Skip to main content
skill CX Codex

frontend-ui-design — Claude Code skill: UI and installation

frontend-ui-design — a skill for planning frontend UI components, architecture, responsive behavior, accessibility, and state management decisions.

MIT 122 installs ★ 3 updated 2026-03-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Pixel-Process-UG/superkit-agents --skill frontend-ui-design -a claude-code
Open on GitHub

What frontend-ui-design does

This skill gives an agent a staged way to build frontend interfaces. It starts by asking about the page or component, framework, existing design system, target devices, WCAG needs, and data requirements. It then compares Atomic Design, compound components, hooks, and container/presenter patterns.

The guide covers mobile-first breakpoints, media queries versus container queries, fluid type with clamp(), semantic HTML, ARIA, keyboard access, and screen reader checks. Its state-management table includes useState, useReducer, Context, Zustand, Jotai, TanStack Query, SWR, React Hook Form, and Formik. After discovery and architecture selection, the agent is told to pause for confirmation.

Accessibility is framed around WCAG 2.1 AA, including focus behavior, contrast, and logical tab order. In Claude Code, installation places the skill at ~/.claude/skills/frontend-ui-design/SKILL.md; the workflow should not move past architecture selection before that choice is confirmed.

What it helps with

  • plan a component architecture
  • choose a pattern for a reusable component library
  • define responsive behavior across device sizes
  • check a UI against WCAG 2.1 AA
  • select state management for shared or server data

Example prompts for the agent

  • Use the frontend UI skill to plan this settings page, ask the discovery questions first, then stop after proposing the component architecture.
  • Compare useState, Context, and Zustand for the state in these components, and explain which option fits.
  • Review this interface for semantic HTML, keyboard navigation, and WCAG 2.1 AA requirements.

How to install frontend-ui-design

1Skills CLI (Vercel)

npx skills add Pixel-Process-UG/superkit-agents --skill frontend-ui-design -a claude-code

2Manually: put the files in place

~/.claude/skills/frontend-ui-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/frontend-ui-design/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about frontend-ui-design

How do I install frontend-ui-design in Claude Code?

Run npx skills add Pixel-Process-UG/superkit-agents --skill frontend-ui-design -a claude-code, then check ~/.claude/skills/frontend-ui-design/SKILL.md.

What does frontend-ui-design do?

It guides UI component planning, architecture choices, responsive behavior, accessibility checks, and state-management selection. The workflow pauses for confirmation after discovery and after choosing the architecture.

Which architecture patterns does it cover?

It compares Atomic Design, compound components, hooks, and container/presenter. The choice is tied to component complexity, reused logic, layout flexibility, and testing needs.

Source text

SKILL.md · MIT
---
name: frontend-ui-design
description: "Use when designing UI components, creating component architectures, implementing responsive layouts, setting up design systems, or selecting state management solutions for frontend applications"
---

# 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 screen reader semantics | Use semantic HTML elements |
| `outline: none` without replacement | Keyboard users cannot see focus | Replace with visible focus style |
| Fixed font sizes (px) | Cannot scale with user preferences | Use `rem` and `clamp()` |
| Prop drilling through 4+ levels | Maintenance nightmare | Use Context or state library |
| Fetching in useEffect + useState | No caching, no dedup, race conditions | Use TanStack Query or SWR |
| Premature memoization | Adds complexity without measured benefit | Profile first, optimize measured bottlenecks |
| Desktop-first responsive design | Mobile experience is an afterthought | Start mobile-first, add complexity up |
| Color as sole information carrier | Inaccessible to colorblind users | Add icons, patterns, or text labels |
| No loading/error states | Users see blank screens or cryptic errors | Design loading, error, and empty states |

## Anti-Rationalization Guards

- **Do NOT** skip accessibility — WCAG 2.1 AA is the minimum, not optional
- **Do NOT** use `<div>` with onClick instead of semantic elements
- **Do NOT** skip keyboard navigation testing
- **Do NOT** choose state management before understanding the actual need
- **Do NOT** skip the discovery phase — understand constraints first
- **Do NOT** optimize performance without measuring first

## Integration Points

| Skill | Relationship |
|-------|-------------|
| `api-design` | Upstream: API response shapes inform component data needs |
| `spec-writing` | Upstream: specs define component behavioral requirements |
| `planning` | Downstream: component designs become implementation tasks |
| `test-driven-development` | Downstream: component spec drives test-first implementation |
| `senior-frontend` | Parallel: specialist knowledge for React/Next.js specifics |
| `ui-ux-pro-max` | Upstream: UX design informs component requirements |
| `ui-design-system` | Parallel: design system tokens feed component styling |
| `performance-optimization` | Downstream: profile and optimize after implementation |

## Verification Gate

Before claiming the UI design is complete:

1. VERIFY component architecture pattern is explicitly chosen with rationale
2. VERIFY responsive behavior is defined for all target breakpoints
3. VERIFY accessibility requirements are specified (WCAG level, keyboard, color contrast)
4. VERIFY state management approach is selected based on actual needs
5. VERIFY loading, error, and empty states are designed
6. VERIFY the user has approved the component specification

## Skill Type

**Flexible** — Adapt component patterns, responsive strategy, and state management to project framework and constraints while preserving accessibility requirements and the discovery-first approach.

© Pixel-Process-UG · MIT · Pixel-Process-UG/superkit-agents

Similar skills

All skills for Frontend and UI →

From the same set3

Project sponsors

Companies that keep this analytics open