Design conventions

/design-conventions — generate per-project visual design conventions

Scans the current TypeScript/React project's UI layer and produces .claude/design-conventions.md — a lightweight, project-specific visual design convention reference. rules/typescript.md instructs loading this file first for any UI work, so the design language loads cheaply without re-scanning each session.

Greenfield guard

This skill derives from what exists. If the project has no existing UI at all (no Tailwind config, no token files, no components, no screens), stop and tell the user to ask @frontend-architect first — creating a design language from a blank slate is design work, not derivation. If only config exists (Tailwind config, a chosen component lib, token file stubs) with no implemented screens, seed a minimal stub from that and flag the rest for the architect.

When to run

• First time in a project with existing UI — before any substantial UI work.
• --refresh — when the design system has evolved or a new visual pattern has been established. Merges new patterns into the existing file; preserves hand-edits.
• Prompted by a gap — if you hit a pattern the file doesn't cover while coding, append the rule inline (don't re-run the full scan).

Procedure

1. Confirm context

Verify you're in a TS/React project: check for package.json, a tsconfig.json, and the presence of .ts/.tsx files. If absent, stop and say so.

Check whether .claude/design-conventions.md already exists. If it does and --refresh was not passed, report what's there and ask the user to pass --refresh to merge new patterns.

2. Scan the project's UI layer

Read these artifacts in priority order:

a. Design token / config foundation

• tailwind.config.{ts,js} — custom color palette, spacing scale, type scale, breakpoints, font families, border-radius tokens, shadow scale
• tokens/ or design-tokens/ directory — primitive and semantic token definitions
• CSS custom-property files (variables.css, globals.css, :root blocks)
• theme.{ts,js} or theme/ — if using a component lib (MUI, Chakra, Mantine)

b. Component library / primitives

• package.json — identify which component library is installed (Radix, Mantine, MUI, Chakra, shadcn/ui, etc.) and the styling solution (Tailwind, CSS Modules, styled-components, vanilla-extract)
• components/ui/ or src/ui/ or lib/components/ — base primitive components (Button, Input, Card, Badge, etc.); read 3-4 to understand the token usage pattern

c. Representative screens / pages

• Read 2-3 full page or feature components to observe:
  • Spacing rhythm (gap, padding, margin patterns — are they from a scale?)
  • Layout structure (max-width containers, grid/flex patterns)
  • Typography usage (which text sizes, weights, and colors appear most)
  • Color usage (primary actions, secondary, destructive, surface, text)
  • Component composition patterns (card structures, list items, form layouts)

d. State presentation patterns

• Find one loading state, one empty state, one error state — document how each is presented visually

3. Derive conventions

From what you read, identify the established patterns for each section below. Only document what you actually observed — don't invent from general knowledge. If a section has no established pattern, omit it (leave a brief # TODO: note).

Sections to cover:

1. Stack — styling solution (Tailwind / CSS Modules / CSS-in-JS), component library, key UI deps
2. Color tokens — primary, secondary, destructive, surface, border, and text token names/values
3. Type scale — the sizes and weights in use (e.g. text-sm/base/lg/xl, font-medium/semibold)
4. Spacing rhythm — the spacing values in use; whether a strict scale is followed
5. Layout patterns — max-width container, column grid, common flex/grid structures
6. Border & radius — border-radius values, shadow scale in use
7. Breakpoints — the responsive breakpoints defined and their usage pattern
8. Component primitives — which primitives exist and their expected usage pattern
9. Empty / loading / error states — how each is presented (skeleton, spinner, illustration, etc.)
10. Motion — whether animations/transitions are used; prefers-reduced-motion handling

4. Write the file

Write to .claude/design-conventions.md in the repo root (create .claude/ if needed).

With --refresh: read the existing file first, merge new patterns in, keep existing content that is still valid. Never overwrite hand-edits — look for # NOTE: or # OVERRIDE: markers and preserve them.

File header:

# Design conventions — {project-name}

Derived from codebase scan on {date}. Maintained by `/design-conventions --refresh`.

> **Stack:** {styling solution} · {component library} · {key UI deps}

Then one section per category found. Each section:

• States the rule plainly (imperative)
• Shows the token name or value where it isn't obvious
• Cites the file/pattern it was derived from (e.g. // see tailwind.config.ts)

Keep each section tight — 5-15 lines max. This file is loaded before every UI session; brevity matters more than completeness.

5. Report

Tell the user:

• Path of the written file
• Number of sections covered
• Any areas where you couldn't find an established pattern (and what to do)
• How to view/edit it (it's plain markdown — open in any editor)
• Suggest adding @.claude/design-conventions.md to the project's CLAUDE.md for automatic inclusion (optional; rules/typescript.md reads it on demand without this)

Do not commit the file unless the user asks.

Notes

• This skill writes to the target project repo, not to the addit-harness repo.
• If the project uses a design token system (Style Dictionary, Theo, etc.), prefer reading the token source files directly over the compiled output.
• A file generated by @frontend-architect for a greenfield project is a valid starting point — run /design-conventions --refresh after the first screens are built to extend it with observed patterns.