Skill

addyosmani/agent-skills46.4k

frontend-ui-engineering

Builds production-quality UIs. Use when building or modifying user-facing interfaces. Use when creating components, implementing layouts, managing state, or when the output needs to look and feel production-quality rather than AI-generated.

Copy install command View source

Quick install

Copy first, validate next

$npx clawhub@latest install frontend-ui-engineering

GitHub

Download SKILL.md or inspect the source before installing.

Step 1

Copy the install command

Copy the command or download SKILL.md, then add it to your AI coding environment.

Step 2

Check source and behavior

Open the source repo and confirm the skill behavior, scope, and fit for the task.

Step 3

Overview

# 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

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:**

```tsx

// Good: Composable

<Card>

Validate with a real task

Run one small real task before keeping it in your long-term workflow.

<CardTitle>Tasks</CardTitle>

</CardHeader>

</CardBody>

</Card>

// Avoid: Over-configured

<Card

title="Tasks"

headerVariant="large"

bodyPadding="md"

content={<TaskList tasks={tasks} />}

/>

```

**Keep components focused:**

```tsx

// Good: Does one thing

export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {

return (

<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)}>

</Button>

</li>

);

}

```

**Separate data fetching from presentation:**

```tsx

// Container: handles data

export function TaskListContainer() {

const { tasks, isLoading, error } = 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} />;

}

// Presentation: handles rendering

export function TaskList({ tasks }: { tasks: Task[] }) {

return (

{tasks.map(task => <TaskItem key={task.id} task={task} />)}

</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

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:

```css

/* 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:

```tsx

// Every interactive element must be keyboard accessible

<button onClick={handleClick}>Click me</button> // ✓ Focusable by default

<div onClick={handleClick}>Click me</div> // ✗ Not focusable

onKeyDown={e => {

if (e.key === 'Enter') handleClick();

if (e.key === ' ') e.preventDefault();

}}

onKeyUp={e => {

if (e.key === ' ') handleClick();

}}>

Click me

</div>

```

ARIA Labels

```tsx

// Label interactive elements that lack visible text

// Label form inputs

<label htmlFor="email">Email</label>

// Or use aria-label when no visible label exists

```

Focus Management

```tsx

// 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 (

<button ref={closeRef} onClick={onClose}>Close</button>

{/* dialog content */}

</dialog>

);

}

```

Meaningful Empty and Error States

```tsx

// Don't show blank screens

function TaskList({ tasks }: { tasks: Task[] }) {

if (tasks.length === 0) {

return (

<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:

```tsx

// 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

```tsx

// Skeleton loading (not spinners for content)

function TaskListSkeleton() {

return (

{Array.from({ length: 3 }).map((_, i) => (

))}

</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);

},

});

}

```

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:

[ ] 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, error, and empty states all handled
[ ] Follows the project's design system (spacing, colors, typography)
[ ] No accessibility warnings in dev tools or axe-core

api-and-interface-design

Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.

browser-testing-with-devtools

Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured.

ci-cd-and-automation

Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.

code-review-and-quality

Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch.

frontend-ui-engineering

Copy first, validate next

Copy the install command

Check source and behavior

Overview

Overview

When to Use

Component Architecture

File Structure

Component Patterns

Validate with a real task

State Management

Design System Adherence

Avoid the AI Aesthetic

Spacing and Layout

Typography

Color

Accessibility (WCAG 2.1 AA)

Keyboard Navigation

ARIA Labels

Focus Management

Meaningful Empty and Error States

Responsive Design

Loading and Transitions

See Also

Common Rationalizations

Red Flags

Verification

Browse skill packs

Read the install guide

Explore more skills