frontend-design

What this skill does

# Frontend Design

## Overview
This skill bridges the gap between visual design and frontend implementation. It produces precise, developer-ready specifications for UI components, responsive layouts, and design systems—including CSS custom properties, layout logic, spacing scales, component states, and interaction behaviors. Whether you are designing a single button component or specifying an entire design system, the output is implementation-ready: exact values, not vague descriptions. This skill is for designing and specifying the frontend; for writing the actual code, pair it with a coding skill.

## When to Use
- Specifying a UI component with all states (default, hover, focus, disabled, error)
- Designing a responsive page layout with breakpoints and grid logic
- Building or extending a design system with tokens, components, and patterns
- Converting a visual design brief into developer-ready CSS specifications
- Defining spacing, typography, and elevation scales for a product
- Designing interactive component behavior (animations, transitions, state changes)

## When NOT to Use
- Backend API design or server-side logic (use `api-designer` skill instead)
- Data engineering, databases, or infrastructure
- Writing actual production code (pair with a coding assistant for implementation)
- Marketing design or print layout
- Mobile native UI (iOS/Android have platform-specific patterns; this skill targets web)

## Quick Reference
| Task | Approach |
|------|----------|
| Spacing scale | 4px base unit: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128 |
| Typography scale | 12, 14, 16 (base), 18, 20, 24, 30, 36, 48, 60, 72px |
| Breakpoints | Mobile: <640px, Tablet: 640–1024px, Desktop: >1024px (adjust for product) |
| Grid | 4-column mobile, 8-column tablet, 12-column desktop; 16–24px gutters |
| Component states | Always spec: default, hover, focus, active, disabled, loading, error |
| Elevation | 3–5 levels: flat, raised (2px), overlay (4–8px), modal (16px), tooltip (24px) |
| Focus ring | 2px offset, 2px width, brand primary color — never remove, only restyle |
| Transition | 150ms ease-out for micro-interactions; 250–300ms for larger state changes |

## Instructions

1. **Define the component or layout scope precisely.** Name the component, its purpose, and where it appears in the product. A "Button" spec covers all button variants across the app; a "Hero Section" spec covers one layout pattern. Clarify scope before specifying—ambiguity at this stage creates implementation inconsistencies later.

2. **Establish the design token foundation first.** Before specifying any component, confirm the token system: color tokens (brand, semantic, neutral scales), spacing scale (4px base unit recommended), typography scale (size, weight, line-height, letter-spacing per level), and border radius values. Components reference tokens, not raw values — this makes theming and design system updates tractable.

3. **Specify every component state.** For interactive components, document all states: default, hover, focus-visible, active/pressed, disabled, loading, and any error or validation states. For each state, specify: background color, text color, border color, shadow, cursor, and transition from previous state. Missing states become inconsistent implementations.

4. **Define layout with explicit grid and spacing logic.** Specify column count, gutter width, and margin at each breakpoint. Name layout regions (header, sidebar, main, footer). Define how the layout collapses across breakpoints — not just "it becomes mobile" but specifically which columns stack, what reorders, and what hides.

5. **Write CSS custom properties for every design token.** Use the `--` prefix convention. Group by category: `--color-brand-primary`, `--spacing-4`, `--font-size-base`, `--radius-md`, `--shadow-md`. Provide the actual values alongside the tokens. This makes the spec immediately usable by developers without translation.

6. **Specify responsive behavior explicitly.** For each breakpoint, document: font sizes, spacing adjustments, layout changes, and component variations (e.g., a desktop mega-menu becoming a mobile drawer). Use `min-width` breakpoints (mobile-first) as the default unless the project already uses a different convention.

7. **Document interaction and animation specs.** For every interactive state transition, specify: duration (ms), easing function, and which properties animate. For complex interactions (modals, drawers, tooltips), specify trigger, entrance animation, exit animation, and focus management behavior.

8. **Produce a component anatomy diagram or structured spec.** Label every sub-element of the component (container, icon, label, badge, etc.) with its token references. This eliminates ambiguity about which part of the spec applies to which element.

## Examples

### Example 1: Button Component Full Specification

**Input:** "Spec a button component for our design system. We have primary, secondary, and ghost variants. Sizes: small, medium, large. Must be accessible. We use a 4px spacing scale and our primary brand color is #2563eb."

**Output:**

#### Design Tokens (establish these first)

```css
/* Color tokens */
--color-brand-primary-500: #2563eb;
--color-brand-primary-600: #1d4ed8;
--color-brand-primary-700: #1e40af;
--color-brand-primary-100: #dbeafe;
--color-neutral-700: #374151;
--color-neutral-800: #1f2937;
--color-white: #ffffff;

/* Spacing */
--spacing-2: 4px;
--spacing-3: 6px;
--spacing-4: 8px;
--spacing-6: 12px;
--spacing-8: 16px;
--spacing-10: 20px;
--spacing-12: 24px;

/* Typography */
--font-size-sm: 14px;
--font-size-base: 16px;
--font-weight-medium: 500;
--line-height-tight: 1.25;

/* Shape */
--radius-md: 6px;

/* Transition */
--transition-fast: 150ms ease-out;
```

#### Size Scale

| Size | Height | Padding (H × V) | Font size | Icon size |
|------|--------|-----------------|-----------|-----------|
| Small (sm) | 32px | 12px × 8px | 14px | 14px |
| Medium (md) | 40px | 16px × 10px | 16px | 16px |
| Large (lg) | 48px | 20px × 12px | 16px | 18px |

#### Variant Specifications

##### Primary Button

| State | Background | Text | Border | Shadow |
|-------|-----------|------|--------|--------|
| Default | `--color-brand-primary-500` | white | none | none |
| Hover | `--color-brand-primary-600` | white | none | none |
| Focus-visible | `--color-brand-primary-500` | white | none | 0 0 0 2px white, 0 0 0 4px `--color-brand-primary-500` |
| Active | `--color-brand-primary-700` | white | none | none |
| Disabled | `--color-brand-primary-200` | `--color-brand-primary-400` | none | none |
| Loading | `--color-brand-primary-500` | transparent | none | none + spinner overlay |

##### Secondary Button

| State | Background | Text | Border |
|-------|-----------|------|--------|
| Default | white | `--color-brand-primary-500` | 1.5px solid `--color-brand-primary-500` |
| Hover | `--color-brand-primary-100` | `--color-brand-primary-600` | 1.5px solid `--color-brand-primary-600` |
| Focus-visible | white | `--color-brand-primary-500` | 1.5px solid + focus ring |
| Disabled | white | `--color-neutral-400` | 1.5px solid `--color-neutral-300` |

##### Ghost Button

| State | Background | Text | Border |
|-------|-----------|------|--------|
| Default | transparent | `--color-neutral-700` | none |
| Hover | `--color-neutral-100` | `--color-neutral-800` | none |
| Focus-visible | transparent | `--color-neutral-700` | focus ring |
| Disabled | transparent | `--color-neutral-400` | none |

#### Interaction Spec
- **Transition:** `background-color var(--transition-fast), border-color var(--transition-fast), box-shadow var(--transition-fast)`
- **Loading state:** Show spinner (16px, white, 1px stroke) centered in button; keep button width fixed; hide label text (or set opacity: 0 to maintain width)
- **Focus ring:** `outline: 2px solid var(--color-brand-primary-500); outline-offset: 2px` — never `outline: none` without replacement

#### Accessibility Requirements
-