Design System — Generate & Audit Visual Systems

When to Use

• Starting a new project that needs a design system
• Auditing an existing codebase for visual consistency
• Before a redesign — understand what you have
• When the UI looks "off" but you can't pinpoint why
• Reviewing PRs that touch styling

When NOT to use: on skyyrose.co the token system already exists and is canon — wordpress-theme/skyyrose-flagship/theme.json plus the per-collection identity in data/logo-registry.json → collections.<slug>. Audit mode applies there; generate mode does not. Generating a parallel token set for a surface that already has one is the single most damaging outcome of this skill. For SkyyRose taste calls (restraint, motion, imagery) use luxury-design-taste; for framework-grounded implementation use frontend-design.

Inputs

Input	Where	If absent
Existing token source	theme.json, tokens.css, design-tokens.css, tailwind.config.*, data/logo-registry.json (collections)	Search first with the census command below. If tokens exist, generate mode is off — switch to audit
The stylesheets to audit	the repo's real CSS/SCSS/TSX, excluding built .min/dist output	Stop — auditing build output reports the compiler's opinion, not the author's
Brand constraints doc	CLAUDE.md, .impeccable.md, docs/brand/*	Stop — an audit with no target palette can only report "it is what it is"
Target contrast level	WCAG 2.2 AA unless the project states higher	Default AA; state that you defaulted

Never proceed on an assumed palette. If you cannot name the intended tokens from a file you read this session, you cannot score drift against them.

How It Works

Mode 1: Generate Design System

Analyzes your codebase and generates a cohesive design system:

1. Scan CSS/Tailwind/styled-components for existing patterns
2. Extract: colors, typography, spacing, border-radius, shadows, breakpoints
3. Research 3 competitor sites for inspiration (via browser MCP)
4. Propose a design token set (JSON + CSS custom properties)
5. Generate DESIGN.md with rationale for each decision
6. Create an interactive HTML preview page (self-contained, no deps)

Output: DESIGN.md + design-tokens.json + design-preview.html

Mode 2: Visual Audit

Scores your UI across 10 dimensions (0-10 each):

1. Color consistency — are you using your palette or random hex values?
2. Typography hierarchy — clear h1 > h2 > h3 > body > caption?
3. Spacing rhythm — consistent scale (4px/8px/16px) or arbitrary?
4. Component consistency — do similar elements look similar?
5. Responsive behavior — fluid or broken at breakpoints?
6. Dark mode — complete or half-done?
7. Animation — purposeful or gratuitous?
8. Accessibility — contrast ratios, focus states, touch targets
9. Information density — cluttered or clean?
10. Polish — hover states, transitions, loading states, empty states

Each dimension gets a score, specific examples, and a fix with exact file:line.

Mode 3: AI Slop Detection

Identifies generic AI-generated design patterns:

- Gratuitous gradients on everything
- Purple-to-blue defaults
- "Glass morphism" cards with no purpose
- Rounded corners on things that shouldn't be rounded
- Excessive animations on scroll
- Generic hero with centered text over stock gradient
- Sans-serif font stack with no personality

Procedure

1. Detect existing tokens before anything else. Run the census (Verification #1). Non-empty result → audit mode; generate mode is disabled.
2. Read the brand-constraints doc and write down the intended palette hexes and font stacks explicitly. This list is what you score against.
3. Score the 10 audit dimensions. Every finding carries file:line and the intended value it deviates from. A score with no file:line is an opinion, not an audit.
4. Measure contrast numerically for each text/background pair you flag (Verification #2). Never assert a ratio you did not compute.
5. Run the slop-detection greps (Verification #3) rather than reading for vibes — the patterns have exact CSS signatures.
6. If the codebase carries a generated-token pipeline, edit the source (the registry's collections entry on SkyyRose), never the generated artifact, then re-run the drift guard (Verification #4).
7. For theme CSS, any accepted fix requires cd wordpress-theme && npm run build — production serves .min.

Verification

Every check states its command, its pass condition, and its evidence scope.

1. Token-source census — does a system already exist?

ls wordpress-theme/skyyrose-flagship/theme.json \
   wordpress-theme/skyyrose-flagship/data/logo-registry.json 2>/dev/null

PASS (audit mode): files listed → a system exists, do not generate a second one. PASS (generate mode): command prints nothing AND tokens.css/tailwind.config.* are also absent. [repo]

2. Palette-drift census — measure, do not eyeball:

grep -rhoE '#[0-9a-fA-F]{6}\b' wordpress-theme/skyyrose-flagship/assets/css/*.css \
  | grep -v '.min.css' | tr 'A-F' 'a-f' | sort | uniq -c | sort -rn | head -8

PASS: the top ranks are declared tokens plus neutrals. Any undeclared hue in the top ranks is a drift finding with a count attached. [repo]

3. Contrast measurement for every pair the audit flags:

python3 -c "
def lum(h):
    r,g,b=[int(h[i:i+2],16)/255 for i in (0,2,4)]
    f=lambda c: c/12.92 if c<=0.03928 else ((c+0.055)/1.055)**2.4
    r,g,b=f(r),f(g),f(b); return 0.2126*r+0.7152*g+0.0722*b
for fg,bg in [('DC143C','0A0A0A'),('B3B3B3','0A0A0A')]:
    l1,l2=sorted((lum(fg),lum(bg)),reverse=True)
    print(fg,bg,f'{(l1+0.05)/(l2+0.05):.2f}:1')
"

PASS: body text ≥ 4.5:1, large text and UI components ≥ 3:1. [repro]

4. Generated-artifact drift guard — proves the generated files still match their source:

rtk proxy pytest tests/collections/ -q

PASS: 24 passed, 1 skipped with zero failures (observed 2026-07-28 [test]). The 1 skip is tests/collections/test_verify_drift.py:17 — excluded in sparse worktrees. A SKIP is not a PASS: that aspect is closed by CI or a full checkout, not by this run. Report it as open, never as green.

5. Slop signature greps (adapt the path to the audited tree):

grep -rnE 'background-clip:\s*text|backdrop-filter:\s*blur|border-(left|right):\s*[2-9]' \
  wordpress-theme/skyyrose-flagship/assets/css/*.css | grep -v '.min.css' | head

PASS: zero hits, or every hit is justified in writing at its file:line. [repo]

Inherited rules: a check that errors or times out produced an artifact, not a pass — re-run it by hand. Before claiming a drift finding is caused by the change under review, run the same census against a pristine tree via git archive HEAD wordpress-theme | tar -x -C <scratch> and diff the contents — never git stash (the stack is shared across worktrees).

Examples

Audit an existing UI (real, this repo; census re-run 2026-09-18, CSS counts 2026-07-28):

$ ls wordpress-theme/skyyrose-flagship/theme.json wordpress-theme/skyyrose-flagship/data/logo-registry.json
wordpress-theme/skyyrose-flagship/data/logo-registry.json
wordpress-theme/skyyrose-flagship/theme.json
$ python -c "import json;print(sorted(json.load(open('wordpress-theme/skyyrose-flagship/data/logo-registry.json'))['collections']))"
['black-rose', 'kids-capsule', 'love-hurts', 'signature']

A token system exists → generate mode is off, audit only. Census then returned 478 #b76e79 · 146 #0a0a0a · 103 #d4af37 · 49 #050505 · 48 #ffffff · 46 #dc143c · 31 #c0c0c0 · 14 #2a2a2a across 52 non-minified stylesheets — top ranks all declared tokens or neutral surface steps, so color-consistency scores high with no drift finding [repo]. The drift guard ran 24 passed, 1 skipped [test].

Generate for a greenfield app (only after check #1 prints nothing):

/design-system generate --style minimal --palette earth-tones

Check for AI slop:

/design-system slop-check

Failure modes

• Generating a parallel token system on top of an existing one. The most damaging outcome; the two systems then fight forever. Check #1 exists to make this impossible — run it first, always.
• Editing a generated artifact. On SkyyRose, design-tokens.css and sot.json are generated from the registry's collections section (see data/collections/README.md). Editing the output means the next regeneration silently reverts your fix. Edit the source.
• Scoring contrast by eye. #DC143C on #0A0A0A reads confident and measures 3.97:1 — below AA. Compute it (check #3).
• Auditing minified output. .min.css is machine-formatted; findings there are noise. Filter with grep -v '.min.css' as every command above does.
• Reading a SKIP as green — test_verify_drift skips in sparse worktrees (bug-257 class: sparse-checkout guards must skip narrowly and be reported, not swallowed). Name who closes it.
• Fail-open audit — no brand doc found, so the audit proceeds against an assumed palette and reports "consistent". Absent input = stop (bug-230, ×6).