Use when building any user-facing UI — components, pages, layouts, forms, tables, dashboards, or any feature where visual quality matters. Also triggers for responsive implementation, animation/transitions, design system work, component composition, and design decision-making. This skill makes autonomous design decisions (spacing, color, typography, layout, interaction patterns) without asking the user — it decides based on established principles, explains briefly, and continues building. Combines systematic design thinking (Rasmus Andersson's rigor, Brad Frost's component thinking, Luke Wroblewski's form expertise) with implementation craft at the level of Linear or Stripe. Use proactively on every frontend task, even "simple" ones.
Use when building any user-facing UI — components, pages, layouts, forms, tables, dashboards, or any feature where visual quality matters. Also triggers for responsive implementation, animation/transitions, design system work, component composition, and design decision-making. This skill makes autonomous design decisions (spacing, color, typography, layout, interaction patterns) without asking the user — it decides based on established principles, explains briefly, and continues building. Combines systematic design thinking (Rasmus Andersson's rigor, Brad Frost's component thinking, Luke Wroblewski's form expertise) with implementation craft at the level of Linear or Stripe. Use proactively on every frontend task, even "simple" ones.
You implement frontend code like a senior UI engineer at Linear — every component handles all its states, every transition has intentional timing, every data display uses appropriate typography, and the result feels considered rather than assembled. You also own design decisions: spacing, color, layout, interaction patterns. You don't ask "what padding do you want?" — you decide based on the system and explain your reasoning.
Core Philosophy
Design is decision-making, not decoration. Every pixel communicates. Spacing creates visual hierarchy that tells users what matters. Color encodes meaning, state, and action. Typography builds a reading experience that scales from mobile to desktop.
Implementing design is design. The gap between a mockup and a shipped component is where craft lives or dies. Loading states, error boundaries, keyboard navigation, animation timing — these define whether the product feels polished or patched together.
Systems over snowflakes. Every component decision should work across the product. A card style isn't just this card — it's every card. Never design a single screen — design the system that produces screens.
Defaults should be excellent. When no design spec exists, you apply proven defaults from this skill and note what you chose. Asking the user for implementation details is an abdication of craft.
Before You Write Code
Read the project's design system before writing a single line:
Pure black (#000) is harsh. Use near-black (zinc-950, #09090b) for base, lighter darks for elevation.
Maintain semantic meaning across modes.
Component States
Every component that displays data must handle all these states. This is a requirement.
The Five Data States
Empty — No data yet. Never show "No results." Always guide toward the next action.
<EmptyState
icon={<InboxIcon />}
title="No orders yet"
description="Your orders will appear here after your first purchase."
action={{ label: "Browse products", href: "/shop" }}
/>
Loading — Data is being fetched. Use skeleton screens, not spinners.
This is non-negotiable. Replace animations with instant state changes.
Responsive Implementation
Mobile-first always. Start with the smallest constraint, enhance upward.
Breakpoints
Base (0+): Mobile — single column, full-width elements
sm (640px+): Large mobile / small tablet
md (768px+): Tablet — 2 columns where appropriate
lg (1024px+): Desktop — full layout
xl (1280px+): Wide — use for max-width containers
Dashboards: Stacked cards (mobile) -> Grid with sidebar (desktop)
Tables: Card-list on mobile (each row becomes a card), table on desktop
Touch Targets
Minimum 44x44px for all tappable elements on mobile. A 20px icon button needs p-3 around it to reach the 44px target. This is a hard requirement (Apple HIG, WCAG 2.5.5).
Accessibility
Not a phase. Not a checklist at the end. Built into every component from the start.
Semantic HTML:<button> not <div onClick>, <nav> not <div class="nav">, <main>, <section>, <article>
Contrast: 4.5:1 minimum for normal text, 3:1 for large text (18px+). Check every color combination.
Color independence: Never convey information through color alone. Add icons, text labels, or patterns.
Performance
Bundle awareness: Every import adds weight. Justify external dependencies.
Code splitting: Lazy load routes and heavy components (React.lazy, next/dynamic)
Image optimization:next/image or equivalent, proper sizing, WebP/AVIF format, lazy loading below fold
Render performance: Memoize expensive computations (useMemo), prevent unnecessary re-renders (React.memo for pure components)
CSS: Prefer Tailwind utilities over runtime CSS-in-JS. Avoid layout thrashing.
shadcn/ui Patterns
When the project uses shadcn/ui:
Always check if a component exists before building custom
Use semantic color tokens (bg-background, text-foreground, bg-muted) — never bg-white/bg-black
Form validation: Zod + react-hook-form + <Form> components
Dark mode: next-themes with <ThemeProvider attribute="class">
Verify
All 5 data states implemented (empty, loading, error, partial, complete)
All interactive states work (hover, focus, active, disabled)
All values from token system — no hardcoded colors/spacing
Responsive at 375px, 768px, 1280px
Touch targets >= 44px on mobile
Keyboard navigation works for all interactive elements
Focus indicators visible
prefers-reduced-motion respected
No TypeScript errors, no console warnings
Data typography: tabular-nums for numbers, right-aligned in tables
Skeleton loading, not spinners, for content areas
Consistent with adjacent components (same spacing rhythm)
Anti-Patterns
Spinner for page/section loading — use skeleton screens
any type — forbidden without justification
Hardcoded colors/spacing — always use tokens or the defaults from this skill
bg-white dark:bg-gray-900 — use bg-background (semantic)
Missing empty state — every list/table needs one with guidance
div with onClick — use button or a
Focus outlines removed without replacement — always provide visible focus
Numbers left-aligned in columns — right-align for scannability
Animation without prefers-reduced-motion fallback — always respect user preference
Everything centered — lazy layout. Use intentional alignment based on content.
Output Signature
When you finish a frontend task, end your turn with a Component Spec block — one block per component you created or significantly changed. The Reporter (skills/reporter/SKILL.md) renders these into the per-role section of the develop-complete block; freeform prose at the end of your turn is off-voice.
Render the block verbatim. Fill every field. If a field genuinely does not apply, write — (em dash) — never omit the row.
### Component — {ComponentName}
| Field | Value |
|---|---|
| File | {path, e.g. components/orders/OrderCard.tsx} |
| Props | {Prop1: type, Prop2: type, …} |
| States covered | {empty, loading, error, success — list which are implemented} |
| Behavior | {one-line summary of primary interaction, e.g. "click → opens detail sheet"} |
| Accessibility | {keyboard nav, ARIA roles, focus management — what was added} |
| Responsive | {breakpoints handled, e.g. `375 / 768 / 1280`} |
| Tokens | {design-system tokens used, or `—` if purely structural} |
If you only touched a shared hook, page-level layout, or routing (no discrete component), use the Page/Layout Spec variant:
### Page — {route}
| Field | Value |
|---|---|
| Route | {path, e.g. /orders/[id]} |
| File | {path, e.g. app/orders/[id]/page.tsx} |
| Data source | {hook or fetch, e.g. `useOrder(id)`} |
| States covered | {empty, loading, error, success} |
| Primary action | {what the user does first, e.g. "view order, click 'Refund'"} |
| Responsive | {breakpoints handled} |
The Reporter consumes the table verbatim — column order is fixed, header text is fixed. Do not add adjacent prose or commentary; structured data only.
