frontend-ui-design

What this skill does

# Frontend UI Design

## Overview

Guide the design and implementation of frontend user interfaces with consistent architecture, accessibility, responsive behavior, and performance. This skill covers component patterns, design system integration, state management selection, and WCAG compliance — producing components that are testable, accessible, and performant.

**Announce at start:** "I'm using the frontend-ui-design skill to design the UI."

## Phase 1: Discovery

Ask these questions to understand the UI requirements:

| # | Question | What It Determines |
|---|----------|-------------------|
| 1 | What component or page are we building? | Scope and complexity |
| 2 | What framework/library? (React, Vue, Svelte, etc.) | Code patterns |
| 3 | Is there an existing design system or component library? | Constraints |
| 4 | What devices must be supported? (mobile, tablet, desktop) | Responsive strategy |
| 5 | Accessibility requirements? (WCAG level) | A11y standards |
| 6 | What data does this component need? | State management approach |

STOP after discovery — present a summary of constraints and approach before designing.

## Phase 2: Component Architecture Selection

### Architecture Pattern Decision Table

| Pattern | When to Use | When NOT to Use |
|---------|------------|-----------------|
| **Atomic Design** | Building a component library from scratch | Adding one component to existing system |
| **Compound Components** | Multi-part component needing layout flexibility | Simple single-purpose component |
| **Hooks Pattern** | Same logic reused across different UIs | Logic tied to one specific component |
| **Container/Presenter** | Components need isolated testing or multiple data sources | Simple components with minimal logic |

### Atomic Design Levels

| Level | Description | Examples |
|-------|-------------|----------|
| **Atoms** | Smallest building blocks, single purpose | Button, Input, Label, Icon |
| **Molecules** | Groups of atoms functioning together | SearchBar (Input + Button), FormField (Label + Input + Error) |
| **Organisms** | Complex sections composed of molecules | Header (Logo + Nav + SearchBar), ProductCard |
| **Templates** | Page layouts with placeholder content | DashboardLayout, AuthLayout |
| **Pages** | Templates populated with real data | HomePage, SettingsPage |

### Compound Components Example

```tsx
<Select value={selected} onChange={setSelected}>
  <Select.Trigger />
  <Select.Options>
    <Select.Option value="a">Option A</Select.Option>
    <Select.Option value="b">Option B</Select.Option>
  </Select.Options>
</Select>
```

Use when: a component has multiple sub-parts that must coordinate but consumers need layout flexibility.

### Hooks Pattern Example

```tsx
function useDialog() {
  const [isOpen, setIsOpen] = useState(false);
  const open = () => setIsOpen(true);
  const close = () => setIsOpen(false);
  return { isOpen, open, close };
}
```

Use when: the same logic is needed across multiple components with different UI.

STOP after architecture selection — confirm the pattern choice before proceeding.

## Phase 3: Responsive Design

### Mobile-First Breakpoints

| Breakpoint | Target | Min-Width |
|------------|--------|-----------|
| sm | Mobile landscape | 640px |
| md | Tablet | 768px |
| lg | Desktop | 1024px |
| xl | Large desktop | 1280px |
| 2xl | Wide desktop | 1536px |

### Responsive Strategy Decision Table

| Need | Use | Not |
|------|-----|-----|
| Layout changes based on viewport size | Media queries | Container queries |
| Component adapts to parent container size | Container queries | Media queries |
| Text scales smoothly between breakpoints | `clamp()` fluid typography | Fixed font sizes |
| Images adapt to viewport | `srcset` + `sizes` | Single fixed image |

### Fluid Typography

```css
font-size: clamp(1rem, 0.5rem + 1.5vw, 1.5rem);
```

## Phase 4: Accessibility (WCAG 2.1 AA)

### Semantic HTML Decision Table

| Need | Use | NOT |
|------|-----|-----|
| Navigation | `<nav>` | `<div class="nav">` |
| Button action | `<button>` | `<div onClick>` |
| Page sections | `<main>`, `<section>`, `<aside>` | `<div>` |
| Headings | `<h1>`-`<h6>` in order | `<div class="heading">` |
| List of items | `<ul>`, `<ol>` | Nested `<div>`s |
| Form labels | `<label for="...">` | Placeholder text only |

### ARIA Usage Rules

| Rule | When |
|------|------|
| Use semantic HTML first | Always — ARIA is a fallback |
| `aria-label` | Labels for elements without visible text |
| `aria-describedby` | Associates descriptive text with an element |
| `aria-live` | Announces dynamic content changes |
| `aria-expanded` | Toggleable sections (accordions, menus) |
| `role` | Only when no semantic element exists |

### Keyboard Navigation Requirements

- All interactive elements focusable (naturally or `tabindex="0"`)
- Operable via keyboard (Enter, Space, Escape, Arrow keys)
- Visible focus indicator (never `outline: none` without replacement)
- Logical tab order matching visual order
- Focus traps for modals and dialogs

### Color Contrast Requirements

| Element | Minimum Ratio |
|---------|--------------|
| Normal text | 4.5:1 |
| Large text (18px+ or 14px+ bold) | 3:1 |
| UI components | 3:1 against adjacent colors |
| Information conveyed by color | Must also use icons, patterns, or text |

### Screen Reader Testing

Test with at least one screen reader:
- macOS: VoiceOver (built-in)
- Windows: NVDA (free) or JAWS
- Verify: content announced in logical order, form errors associated with inputs, dynamic updates announced

## Phase 5: State Management & Performance

### State Management Decision Table

| State Type | Solution | When |
|------------|----------|------|
| **Local** | `useState`, `useReducer` | State used by one component or direct children |
| **Shared** | Context, Zustand, Jotai | State shared across multiple unrelated components |
| **Server** | TanStack Query, SWR | Data fetched from API, needs caching/revalidation |
| **Form** | React Hook Form, Formik | Complex forms with validation and submission |
| **URL** | Search params, router state | State that should be bookmarkable/shareable |

### Selection Heuristic

1. Start with `useState` — only escalate when you hit a real limitation
2. If prop drilling exceeds 2 levels, consider Context or state library
3. If caching API responses, use a server state library (not Redux for server state)
4. For forms with >3 fields and validation, use a form library

### Performance Optimization Checklist

| Technique | When to Apply |
|-----------|--------------|
| `React.lazy()` + `Suspense` | Route-level code splitting |
| `loading="lazy"` on images | Below-the-fold images |
| Virtualization | Lists with >50 items |
| `useMemo` | Expensive computations |
| `useCallback` | Callbacks passed to memoized children |
| Dynamic `import()` | Conditionally loaded heavy libraries |
| WebP/AVIF images | All image assets |
| Explicit `width`/`height` on images | Prevent layout shift |

### Design System Integration

**Design Tokens** — define foundational values, not hard-coded:

```ts
const tokens = {
  color: { primary: '#2563eb', secondary: '#64748b', error: '#dc2626' },
  spacing: { xs: '0.25rem', sm: '0.5rem', md: '1rem', lg: '1.5rem', xl: '2rem' },
  typography: { fontFamily: { sans: 'Inter, system-ui, sans-serif' } },
};
```

**Component Variants** — consistent variant API:

```tsx
<Button variant="primary" size="md">Save</Button>
<Button variant="outline" size="sm">Cancel</Button>
```

**Theme Support:**
- CSS custom properties for runtime theme switching
- Support light + dark themes at minimum
- Respect `prefers-color-scheme` as default
- Allow user override stored in localStorage

STOP after design — present the full component specification for review.

## Anti-Patterns / Common Mistakes

| Mistake | Why It Is Wrong | What To Do Instead |
|---------|----------------|-------------------|
| `<div onClick>` instead of `<button>` | Not keyboard accessible, no