claude-design-system-architect

# Claude Design System Architect

A design system is the difference between a site that looks bespoke and one that looks like every other AI-generated landing page. This skill builds the token layer and component language that makes everything downstream look intentional — then exports it in the formats your stack actually uses.

Pairs with `claude-landing-composer` (which consumes these tokens to build pages) and `claude-design-critic` (which audits against them).

## Step 1 — Establish the brand inputs

From a brief, an existing site (WebFetch / screenshots), or a few reference sites the user likes:
- **Personality** — 3–5 adjectives (e.g. "warm, editorial, confident, calm"). These drive every later decision.
- **Audience & context** — who uses it, on what device, in what mood.
- **Existing equity** — logo, locked colors, fonts already in use.
- **Anti-references** — what it must NOT look like.

### Defaults & house rules
Unless the brand explicitly overrides:
- **No purple** anywhere in the palette.
- **No emoji** in UI — use an icon set (Lucide / Heroicons) and specify it as a token.
- Lean toward **warm / earth tones** (sand, terracotta, clay) and consider a **dark surface** option.
- Motion is part of the system, not an afterthought.

## Step 2 — Build the tokens

Design each layer deliberately and document the *why*:
- **Color** — a real ramp (50–900) per hue, semantic tokens (`surface`, `text`, `muted`, `accent`, `border`, `success`/`warn`/`danger`), and verified contrast (WCAG AA min for body text). Include a dark mode set. No arbitrary hexes scattered later — everything maps to a token.
- **Type** — a font pairing with rationale, a modular scale (not random px), line-heights and tracking per size, and weights. Prefer characterful, legible pairings over the default system stack that screams "AI made this."
- **Space & layout** — a spacing scale, container widths, grid, breakpoints. Generous, asymmetric whitespace reads premium; cramped uniform padding reads generated.
- **Radius / border / elevation** — a small, consistent set. Shadows that match the brand's weight (soft for warm brands, crisp for technical ones).
- **Motion** — duration + easing tokens, named patterns (entrance, emphasis, transition), and a reduced-motion stance. This is what makes it feel alive.

## Step 3 — Specify components

For the core set (button, input, card, nav, section, badge, modal), specify variants, states (hover/focus/active/disabled), sizing, and accessibility notes — all expressed in the tokens above, never one-off values.

## Step 4 — Export

Produce real files, not prose:
- `tailwind.config` extension (or `@theme` for Tailwind v4) wiring every token.
- `tokens.css` — CSS custom properties (light + dark).
- `design-system.md` — the usage doc: palette with hexes + contrast, type scale, spacing, motion, component specs, and **do/don't** examples that call out the AI-tell patterns to avoid.

## Step 5 — Hand off
End with a one-screen summary and the next move: `claude-landing-composer` to build pages on these tokens, or `claude-design-critic` to retrofit an existing UI onto them.

## What separates premium from generated (bake this in)
- Intentional, restrained palette — not 6 competing accent colors.
- A real type scale and characterful fonts — not default sans at 3 sizes.
- Asymmetric, generous whitespace — not uniform padding everywhere.
- Motion with personality — not the same fade-up on every element.
- One confident accent — not rainbow gradients (and never purple-by-default).

## Guardrails recap
Every value is a token, nothing arbitrary · contrast meets AA · dark mode + reduced-motion included · no purple / no emoji unless the brand demands it · export real config files, not descriptions.