Frontend UI engineering
Builds UI components and pages on the project's design system: composition, simple state, WCAG 2.1 AA, mobile-first layouts, loading, empty and error states, no generic AI look. Use when building or changing a user-facing interface.
frontend-ui-engineering- Author
- Addy Osmani
- Source
- addyosmani/agent-skills/skills/frontend-ui-engineering @ 8c99fa3
- License
- MIT · Copyright (c) 2025 Addy Osmani
About this skill
What it does
The skill sets the standard for building or changing user-facing UI, with examples in React and Tailwind. Components live next to their tests and stories, are composed rather than configured through props, and split into a data container and a presentational part. State goes to the simplest place that works: local, lifted, context, URL, server state (React Query, SWR), and a global store only for complex shared state.
On design it asks for the project's own tokens and spacing scale, a strict heading hierarchy and 4.5:1 text contrast. A table lists the "AI aesthetic" to avoid: purple everywhere, heavy gradients, maximum rounding, oversized padding, stock card grids. When the product needs its own visual direction, the agent studies two or three reference screens, writes a short design contract (the screen's job, primary action, states, patterns to reject) and rebuilds the structure with the product's components, never copying another product's branding.
Accessibility targets WCAG 2.1 AA: keyboard access, labels, focus management in dialogs, WAI-ARIA patterns for menus, dialogs and tabs. Layouts are mobile-first and checked at 320, 768, 1024 and 1440 px, with loading, empty and error states. Checks use the project's own test, type-check and lint commands; the agent installs nothing extra and says what it could not run. The folder holds only SKILL.md and the licence; the accessibility checklist it mentions (../../references/accessibility-checklist.md) is not included.
When to use it, and when not
Use it to build or change components, pages, layouts, interactivity and state, or to fix a visual or UX issue, whenever the result should not look generated.
It is for construction. The examples are React; with another framework, take the rules rather than the code. Auditing an existing interface against WCAG 2.2 is a separate job (see below).
How to run it
The install command below puts SKILL.md and the licence in place. The agent picks the skill up by its description when UI work comes up; to call it yourself:
- Claude Code:
/frontend-ui-engineering, or ask for the skill by name. - Codex:
$frontend-ui-engineering. - Cursor: type
/in the Agent chat and pickfrontend-ui-engineering.
Example: /frontend-ui-engineering Build the settings page with our existing Button and Input components. Handle loading, empty and error states.
How it differs from similar skills
Accessibility audit and fixes (WCAG 2.2) from the same pack audits an interface that already exists with axe-core and pa11y and sends new UI work back here: one builds, the other audits. UI polish pass polishes a working UI without redesigning it, with before-and-after screenshots at 390 and 1440 px; this skill shapes components, state and structure from the start. Browser testing with Chrome DevTools MCP checks the result in a real browser. Distinctive frontend design invents a visual identity from the product's subject — palette, type, layout — while this skill builds on the project's design system and reference screens. Implement a Figma design in code builds UI from a Figma frame with 1:1 visual parity. React composition patterns expands this skill's "composition over configuration" rule into eight React rules with code examples.
Install
Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.
curl -fsSL --create-dirs -o ~/.claude/skills/frontend-ui-engineering/SKILL.md https://anymodel.org/en/skills/addy-osmani/frontend-ui-engineering/SKILL.md -o ~/.claude/skills/frontend-ui-engineering/LICENSE https://anymodel.org/en/skills/addy-osmani/frontend-ui-engineering/LICENSE
curl -fsSL --create-dirs -o ~/.agents/skills/frontend-ui-engineering/SKILL.md https://anymodel.org/en/skills/addy-osmani/frontend-ui-engineering/SKILL.md -o ~/.agents/skills/frontend-ui-engineering/LICENSE https://anymodel.org/en/skills/addy-osmani/frontend-ui-engineering/LICENSE
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.claude\skills\frontend-ui-engineering" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/frontend-ui-engineering/$f" -UseBasicParsing -OutFile $p }foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.agents\skills\frontend-ui-engineering" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/frontend-ui-engineering/$f" -UseBasicParsing -OutFile $p }Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/addy-osmani/frontend-ui-engineering/SKILL.md
SKILL.md
Frontend UI Engineering
Overview
Build production-quality user interfaces that are accessible, performant, and visually polished. The goal is UI that looks like it was built by a design-aware engineer at a top company — not like it was generated by an AI. This means real design system adherence, proper accessibility, thoughtful interaction patterns, and no generic "AI aesthetic."
When to Use
- Building new UI components or pages
- Modifying existing user-facing interfaces
- Implementing responsive layouts
- Adding interactivity or state management
- Fixing visual or UX issues
Verify With What the Project Has
Run the project's own test, type-check, or lint commands. Don't install a framework, test runner, or type checker just to check your work; if the project has none, review the code against the Verification list and say what you could not run.
Component Architecture
File Structure
Colocate everything related to a component:
src/components/
TaskList/
TaskList.tsx # Component implementation
TaskList.test.tsx # Tests
TaskList.stories.tsx # Storybook stories (if using)
use-task-list.ts # Custom hook (if complex state)
types.ts # Component-specific types (if needed)
Component Patterns
Prefer composition over configuration:
// Good: Composable
<Card>
<CardHeader>
<CardTitle>Tasks</CardTitle>
</CardHeader>
<CardBody>
<TaskList tasks={tasks} />
</CardBody>
</Card>
// Avoid: Over-configured
<Card
title="Tasks"
headerVariant="large"
bodyPadding="md"
content={<TaskList tasks={tasks} />}
/>
Keep components focused:
// Good: Does one thing
export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
return (
<li className="flex items-center gap-3 p-3">
<Checkbox checked={task.done} onChange={() => onToggle(task.id)} />
<span className={task.done ? 'line-through text-muted' : ''}>{task.title}</span>
<Button variant="ghost" size="sm" onClick={() => onDelete(task.id)}>
<TrashIcon />
</Button>
</li>
);
}
Separate data fetching from presentation:
// Container: handles data
export function TaskListContainer() {
const { tasks, isLoading, error, refetch, toggleTask, deleteTask } = useTasks();
if (isLoading) return <TaskListSkeleton />;
if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />;
if (tasks.length === 0) return <EmptyState message="No tasks yet" />;
return <TaskList tasks={tasks} onToggle={toggleTask} onDelete={deleteTask} />;
}
// Presentation: handles rendering
export function TaskList({ tasks, onToggle, onDelete }: { tasks: Task[] } & Pick<TaskItemProps, 'onToggle' | 'onDelete'>) {
return (
<ul role="list" className="divide-y">
{tasks.map(task => <TaskItem key={task.id} task={task} onToggle={onToggle} onDelete={onDelete} />)}
</ul>
);
}
State Management
Choose the simplest approach that works:
Local state (useState) → Component-specific UI state
Lifted state → Shared between 2-3 sibling components
Context → Theme, auth, locale (read-heavy, write-rare)
URL state (searchParams) → Filters, pagination, shareable UI state
Server state (React Query, SWR) → Remote data with caching
Global store (Zustand, Redux) → Complex client state shared app-wide
Avoid prop drilling deeper than 3 levels. If you're passing props through components that don't use them, introduce context or restructure the component tree.
Design System Adherence
Reference-led UI quality
When the product needs a distinct visual direction, collect evidence before choosing a layout:
- Search a trusted reference catalogue or use references supplied by the product team.
- Study two or three relevant screens. Record decisions about hierarchy, density, navigation, controls, responsive behavior, and interaction states.
- Turn those decisions into a short design contract before implementation. Name the screen's job, primary action, required states, responsive rules, and patterns to reject.
- Rebuild the useful structure in the product's own components, tokens, content, and visual language. Never copy another product's branding, proprietary text, imagery, or exact layout.
Use references as evidence, not as templates. If references are unavailable, document the assumptions and verify the result against the product's existing design system.
Avoid the AI Aesthetic
AI-generated UI has recognizable patterns. Avoid all of them:
| AI Default | Why It Is a Problem | Production Quality |
|---|---|---|
| Purple/indigo everything | Models default to visually "safe" palettes, making every app look identical | Use the project's actual color palette |
| Excessive gradients | Gradients add visual noise and clash with most design systems | Flat or subtle gradients matching the design system |
| Rounded everything (rounded-2xl) | Maximum rounding signals "friendly" but ignores the hierarchy of corner radii in real designs | Consistent border-radius from the design system |
| Generic hero sections | Template-driven layout with no connection to the actual content or user need | Content-first layouts |
| Lorem ipsum-style copy | Placeholder text hides layout problems that real content reveals (length, wrapping, overflow) | Realistic placeholder content |
| Oversized padding everywhere | Equal generous padding destroys visual hierarchy and wastes screen space | Consistent spacing scale |
| Stock card grids | Uniform grids are a layout shortcut that ignores information priority and scanning patterns | Purpose-driven layouts |
| Shadow-heavy design | Layered shadows add depth that competes with content and slows rendering on low-end devices | Subtle or no shadows unless the design system specifies |
Spacing and Layout
Use a consistent spacing scale. Don't invent values:
/* Use the scale: 0.25rem increments (or whatever the project uses) */
/* Good */ padding: 1rem; /* 16px */
/* Good */ gap: 0.75rem; /* 12px */
/* Bad */ padding: 13px; /* Not on any scale */
/* Bad */ margin-top: 2.3rem; /* Not on any scale */
Typography
Respect the type hierarchy:
h1 → Page title (one per page)
h2 → Section title
h3 → Subsection title
body → Default text
small → Secondary/helper text
Don't skip heading levels. Don't use heading styles for non-heading content.
Color
- Use semantic color tokens:
text-primary,bg-surface,border-default— not raw hex values - Ensure sufficient contrast (4.5:1 for normal text, 3:1 for large text)
- Don't rely solely on color to convey information (use icons, text, or patterns too)
Accessibility (WCAG 2.1 AA)
Every component must meet these standards:
For menus, dialogs, tabs, listboxes and comboboxes, follow the WAI-ARIA APG pattern exactly.
Keyboard Navigation
// Every interactive element must be keyboard accessible
<button onClick={handleClick}>Click me</button> // ✓ Focusable by default
<div onClick={handleClick}>Click me</div> // ✗ Not focusable
<div role="button" tabIndex={0} onClick={handleClick} // ✓ But prefer <button>
onKeyDown={e => {
if (e.key === 'Enter') handleClick();
if (e.key === ' ') e.preventDefault();
}}
onKeyUp={e => {
if (e.key === ' ') handleClick();
}}>
Click me
</div>
ARIA Labels
// Label interactive elements that lack visible text
<button aria-label="Close dialog"><XIcon /></button>
// Label form inputs
<label htmlFor="email">Email</label>
<input id="email" type="email" />
// Or use aria-label when no visible label exists
<input aria-label="Search tasks" type="search" />
Focus Management
// Move focus when content changes
function Dialog({ isOpen, onClose }: DialogProps) {
const closeRef = useRef<HTMLButtonElement>(null);
useEffect(() => {
if (isOpen) closeRef.current?.focus();
}, [isOpen]);
// Trap focus inside dialog when open
return (
<dialog open={isOpen}>
<button ref={closeRef} onClick={onClose}>Close</button>
{/* dialog content */}
</dialog>
);
}
Meaningful Empty and Error States
// Don't show blank screens
function TaskList({ tasks, onCreateTask }: { tasks: Task[]; onCreateTask: () => void }) {
if (tasks.length === 0) {
return (
<div role="status" className="text-center py-12">
<TasksEmptyIcon className="mx-auto h-12 w-12 text-muted" />
<h3 className="mt-2 text-sm font-medium">No tasks</h3>
<p className="mt-1 text-sm text-muted">Get started by creating a new task.</p>
<Button className="mt-4" onClick={onCreateTask}>Create Task</Button>
</div>
);
}
return <ul role="list">...</ul>;
}
Responsive Design
Design for mobile first, then expand:
// Tailwind: mobile-first responsive
<div className="
grid grid-cols-1 /* Mobile: single column */
sm:grid-cols-2 /* Small: 2 columns */
lg:grid-cols-3 /* Large: 3 columns */
gap-4
">
Test at these breakpoints: 320px, 768px, 1024px, 1440px.
Loading and Transitions
// Skeleton loading (not spinners for content)
function TaskListSkeleton() {
return (
<div className="space-y-3" role="status" aria-busy="true" aria-label="Loading tasks">
{Array.from({ length: 3 }).map((_, i) => (
<div key={i} className="h-12 bg-muted animate-pulse rounded" />
))}
</div>
);
}
// Optimistic updates for perceived speed
function useToggleTask() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: toggleTask,
onMutate: async (taskId) => {
await queryClient.cancelQueries({ queryKey: ['tasks'] });
const previous = queryClient.getQueryData(['tasks']);
queryClient.setQueryData(['tasks'], (old: Task[]) =>
old.map(t => t.id === taskId ? { ...t, done: !t.done } : t)
);
return { previous };
},
onError: (_err, _taskId, context) => {
queryClient.setQueryData(['tasks'], context?.previous);
},
});
}
See Also
For detailed accessibility requirements and testing tools, see ../../references/accessibility-checklist.md.
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
| "We'll make it responsive later" | Retrofitting responsive design is 3x harder than building it from the start. |
| "The design isn't final, so I'll skip styling" | Use the design system defaults. Unstyled UI creates a broken first impression for reviewers. |
| "This is just a prototype" | Prototypes become production code. Build the foundation right. |
| "The AI aesthetic is fine for now" | It signals low quality. Use the project's actual design system from the start. |
Red Flags
- Components with more than 200 lines (split them)
- Inline styles or arbitrary pixel values
- Missing error states, loading states, or empty states
- No keyboard navigation testing
- Color as the sole indicator of state (red/green without text or icons)
- Generic "AI look" (purple gradients, oversized cards, stock layouts)
Verification
After building UI, check what you can with the project's own tooling, and review the rest against this list. Don't add dependencies or install toolchains only to verify; say which checks you couldn't run.
- Component renders without console errors
- All interactive elements are keyboard accessible (Tab through the page)
- Screen reader can convey the page's content and structure
- Responsive: works at 320px, 768px, 1024px, 1440px
- Loading, empty, error, success, and permission states handled when applicable
- Follows the project's design system (spacing, colors, typography)
- The rendered result passes a final UI-specific finish-gate review
- No accessibility warnings in dev tools or axe-core
Connect through AnyModel API
This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.
AnyModel