UX reference

A sourdough starter for your project's visual language. The AI consults this when it's about to write CSS, JSX styles, or any UI markup that needs a colour / size / spacing decision. Without this, the AI invents — and invented values drift the design system fast.

Tokens (the source of truth)

Where the real tokens live: {app/globals.css / tailwind.config.ts / src/styles/tokens.css — be specific to your project}.

This file is the reference document for what's defined and why. When values change, change them in the tokens file, not here — and refresh this doc when meaningful new tokens land.

Colour

Document each token with: name, value, when to use it, when NOT to use it.

--magenta:   #ff2e88   primary accent · CTAs · key highlights
--cyan:      #00e5ff   secondary accent · info / hover states
--green:     #00ff88   success / free / live
--amber:     #ffc107   warning / draft / coming-soon
--bg-0:      #0c0a07   base background (darkest)
--bg-1:      #1a1612   card / panel background
--bg-2:      #2a2522   elevated panel / inline code background
--fg-0:      #ffffff   primary text on dark
--fg-1:      #e8e2d6   body text on dark
--fg-2:      #aea798   muted body text
--fg-3:      #6a635c   labels / metadata / least-emphasis
--border-0:  rgba(255,255,255,0.06)   subtle dividers
--border-1:  rgba(255,255,255,0.12)   card borders / inputs

Rules:

• Never write a hex code inline. If you need a new colour, add it as a token first.
• Translucent overlays use rgba(...) with one of the base RGB triplets (e.g. rgba(255,46,136,0.06) for a magenta glow).
• Contrast: every text/background pair has to clear WCAG 1.4.3 AA (4.5:1 for body, 3:1 for large text). legibility_review flags violations.

Typography

--sans:    'Inter', -apple-system, sans-serif    body copy
--mono:    'JetBrains Mono', 'SF Mono', monospace  code, eyebrow labels, badges
--pixel:   'VT323', monospace                     pixel-art accents only

Sizes used:

Rules:

• Don't introduce a new size. If you need a smaller body, use 14px; bigger, use 16px. Anything beyond that is bug shape.
• legibility_review caps font-size proliferation at 4 distinct sub-14px sizes — go beyond and the page reads as inconsistent.
• Line-height: 1.6 for body, 1.4 for headings, 1.55 for tight contexts. Never below 1.4 (unitless) without a specific reason.

Spacing

4-point grid. Every margin / padding / gap snaps to a multiple of 4.

4   tight       — icon-to-text spacing inside a button
8   inline      — gap between badges
12  small       — eyebrow-to-heading gap
16  card        — card padding (small)
20  card-md     — card padding (medium)
24  default     — paragraph gap
32  section-sm  — between subsections
40  section     — between major sections
56  section-lg  — section top padding
96  hero        — between hero and first section

Rules:

• Never use a value that doesn't snap to 4. The 4-point grid is what makes the page feel designed rather than vibe-coded.
• brand_consistency flags spacing values outside the grid as L4 sourdough drift.

Radius + shadow

--radius-sm:  6px    inputs, badges
--radius:     8px    cards, buttons
--radius-lg:  12px   panels

Shadows: subtle. 0 0 24px rgba(255,46,136,0.12) for a focused magenta glow; 0 4px 12px rgba(0,0,0,0.20) for elevated panels. Never multi-layered drop shadows — they read as 2014.

When the AI is about to write CSS / styles

Ask:

• Colour? → pick from the palette above. If nothing fits, ADD a token, don't inline a hex.
• Size? → pick from the typography table. If you need a new size, ask first — it's a system change.
• Spacing? → snap to the 4-point grid.
• Radius? → use a token.
• Shadow? → use the subtle pattern, or none.

If the AI proposes inline style={{ color: '#ff6699' }}, that's a violation — call it out and tell it to use the token.

How to feed this starter

Add to it when:

• You add a new token to the source file. Document it here (when to use, when not to).
• You catch the AI inventing a value. Add a rule that would have prevented it.
• You retire a token. Note the deprecation here AND in the source file.

Remove from it when:

• A token is genuinely removed.
• A rule turns out to be wrong (and the alternative is now the rule).

Companion starters

• brand-voice — the verbal equivalent of this document (tone, conventions, AI tells to avoid)
• ux-audit-playbook — what to check on every page before shipping
• project-starter — the parent shape this slots into