Skip to content
Frontend UI Engineering

Frontend UI Engineering Skill

Addy Osmani's skill for building production-quality, accessible, responsive interfaces: component architecture, the simplest workable state, design-system adherence, a list of AI-aesthetic defaults to avoid, WCAG 2.1 AA and a verification checklist.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from addyosmani/agent-skills.

$ npx skills add addyosmani/agent-skills --skill frontend-ui-engineering

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/frontend-ui-engineering/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/addyosmani/agent-skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/frontend-ui-engineering ~/.claude/skills/frontend-ui-engineering

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/frontend-ui-engineering/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Component architecture, file structure and composition patterns
  • State ladder from local state to a global store, prop drilling capped at three levels
  • Named list of AI-aesthetic defaults to avoid, with production alternatives
  • Reference-led design contract before building a new visual direction
  • WCAG 2.1 AA: keyboard navigation, ARIA, focus management, empty and error states
  • Verification checklist using the project's own tooling

Frontend UI Engineering is one of the engineering-practice skills in Addy Osmani's addyosmani/agent-skills collection. The agent uses it whenever it builds or modifies user-facing UI: new components or pages, layouts, interactivity and state, or visual and UX fixes. Its stated aim is UI that looks built by a design-aware engineer rather than generated by a model.

It covers component architecture and file structure with composition patterns, and a ladder for choosing state, from local state up through lifted state, context, URL state and server-state libraries to a global store, with prop drilling capped at three levels. On design it asks the agent to adhere to the project's design system, to study two or three reference screens and write a short design contract before building a distinct visual direction, and to avoid a named list of AI defaults: purple-indigo palettes, heavy gradients, maximum rounding, generic heroes, placeholder copy, oversized padding, stock card grids and heavy shadows. Spacing, type hierarchy and semantic colour tokens with contrast ratios get their own rules.

Accessibility targets WCAG 2.1 AA with keyboard navigation, ARIA labels, focus management and meaningful empty and error states, followed by responsive design and loading and transitions. The skill closes with common rationalizations, red flags and a verification checklist (no console errors, keyboard and screen-reader checks, 320 to 1440 px breakpoints, every state handled, axe-core clean), run with the project's own tooling rather than newly installed dependencies. MIT licensed.

SKILL.md

The instructions your agent loads, as published by Addy Osmani.

SKILL.md
name
frontend-ui-engineering
description
Builds production-quality, accessible, responsive user-facing UIs. Use when building or modifying interfaces and pages, creating components, implementing layouts, meeting WCAG accessibility requirements, managing state, or when the output needs to look and feel production-quality rather than AI-generated.

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](#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:

  1. Search a trusted reference catalogue or use references supplied by the product team.
  2. Study two or three relevant screens. Record decisions about hierarchy, density, navigation, controls, responsive behavior, and interaction states.
  3. 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.
  4. 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 DefaultWhy It Is a ProblemProduction Quality
Purple/indigo everythingModels default to visually "safe" palettes, making every app look identicalUse the project's actual color palette
Excessive gradientsGradients add visual noise and clash with most design systemsFlat or subtle gradients matching the design system
Rounded everything (rounded-2xl)Maximum rounding signals "friendly" but ignores the hierarchy of corner radii in real designsConsistent border-radius from the design system
Generic hero sectionsTemplate-driven layout with no connection to the actual content or user needContent-first layouts
Lorem ipsum-style copyPlaceholder text hides layout problems that real content reveals (length, wrapping, overflow)Realistic placeholder content
Oversized padding everywhereEqual generous padding destroys visual hierarchy and wastes screen spaceConsistent spacing scale
Stock card gridsUniform grids are a layout shortcut that ignores information priority and scanning patternsPurpose-driven layouts
Shadow-heavy designLayered shadows add depth that competes with content and slows rendering on low-end devicesSubtle 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
RationalizationReality
"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
Install

Skill: Anti-Slop Design

by Ferousco-dev

Featured

Stops AI-generated UI from defaulting to purple gradients and templated hero sections by forcing a named design direction first.

155 views 30 copies

Skill: UI/UX Pro Max

by Next Level Builder

New

A searchable UI/UX knowledge base as an agent skill: styles, product palettes, font pairings, 120 UX guidelines, icons, charts and 22 stacks, queried by a local Python script to generate and persist design systems.

Skill: Impeccable

by Paul Bakaus

New

Paul Bakaus' frontend design skill: one entry point with over 20 commands to shape, critique, audit, polish, animate and harden websites, app UI and design systems, guided by product context in PRODUCT.md and DESIGN.md.

New

The official shadcn/ui skill: project-aware rules and CLI workflows for adding, composing, styling and updating shadcn components, applying presets, and turning a DESIGN.md into a themed design system.

Browse all skills →