onewave-ai/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.