# Token registry

Master reference of all design tokens. Updated by the token-architect agent
whenever tokens are created or modified. Other agents reference this to find
the correct token for any design property.

## How to use this file

- **token-architect**: Update this file whenever you create/modify tokens
- **component-builder**: Reference this file to find the correct token for any CSS property
- **story-writer**: Reference this file to document which tokens a component uses

## Primitives

### Colours

**Brand (warm gold/copper)** — `tokens/primitives/colours.json`
| Token path | Value | Description |
|-----------|-------|-------------|
| color.brand.50 | #FEF9F5 | Lightest warm tint — warm section backgrounds |
| color.brand.100 | #F7ECDF | Light warm — hover backgrounds |
| color.brand.200 | #EBDAC8 | Warm light — secondary backgrounds |
| color.brand.300 | #D8C3B5 | Warm beige (swatch) — surface warmth |
| color.brand.400 | #D0A070 | Mid gold (swatch) — secondary interactive |
| color.brand.500 | #BA834E | **Base brand** (swatch) — primary CTA |
| color.brand.600 | #B0610F | Rich copper (swatch) — hover, brand links |
| color.brand.700 | #8B4E0D | Deep copper — active states |
| color.brand.800 | #6B3C13 | Dark brown — bold accents |
| color.brand.900 | #51301B | Chocolate (swatch) — deep emphasis |
| color.brand.950 | #251913 | Espresso (swatch) — darkest brand |

**Sage (cool grey-green)** — `tokens/primitives/colours.json`
| Token path | Value | Description |
|-----------|-------|-------------|
| color.sage.50 | #F2F5F6 | Lightest sage — cool backgrounds |
| color.sage.100 | #E3EAEB | Light sage — hover states |
| color.sage.200 | #D7E1E2 | (swatch) — light cool surface |
| color.sage.300 | #C8D4D6 | Mid-light sage — dividers |
| color.sage.400 | #B9C7C9 | (swatch) — mid sage |
| color.sage.500 | #8EA2A7 | Base sage — secondary content |
| color.sage.600 | #687D84 | Dark sage — secondary text |
| color.sage.700 | #4C5B6B | (swatch) — secondary buttons |
| color.sage.800 | #4C5459 | (swatch) — supplementary text |
| color.sage.900 | #343C40 | Very dark sage |
| color.sage.950 | #1E2528 | Near-black cool |

**Neutral (true grey)** — `tokens/primitives/colours.json`
| Token path | Value | Description |
|-----------|-------|-------------|
| color.neutral.50-950 | #FAFAFA–#0A0A0B | Full grey scale for text, borders, UI |
| color.neutral.800 | #2C2E35 | (swatch) — **Primary text colour** |

**Feedback hues** — `tokens/primitives/colours.json`
| Token path | Value | Description |
|-----------|-------|-------------|
| color.red.50-950 | #FEF2F2–#3D0E0E | Error/destructive states |
| color.amber.50-950 | #FFF9EB–#331F00 | Warning/caution states |
| color.green.50-950 | #F0F7F0–#0F2A0F | Success/positive states |
| color.blue.50-950 | #EFF6FF–#172554 | Info/informational states |

**Standalone** — `tokens/primitives/colours.json`
| Token path | Value | Description |
|-----------|-------|-------------|
| color.white | #FFFFFF | Pure white |
| color.black | #000000 | Pure black (use sparingly) |

### Typography

`tokens/primitives/typography.json`
| Token path | Value | Description |
|-----------|-------|-------------|
| fontFamily.body | Montserrat, ... | Primary body/UI font |
| fontFamily.display | Noto Serif SC, ... | Display/heading serif |
| fontFamily.mono | JetBrains Mono, ... | Monospace |
| fontSize.xs–4xl | 0.75rem–3rem | Desktop font size scale |
| fontSize.mobile.display | 1.75rem | 28px mobile display |
| fontSize.mobile.h1 | 1.5rem | 24px mobile H1 |
| fontSize.mobile.h2 | 1.25rem | 20px mobile H2 |
| fontSize.mobile.h3 | 1.125rem | 18px mobile H3 |
| fontWeight.regular–bold | 400–700 | Weight scale |
| lineHeight.tight–relaxed | 1.25–1.75 | Leading scale |
| letterSpacing.tighter–widest | -0.02em–0.08em | Tracking scale |

### Spacing

`tokens/primitives/spacing.json`
| Token path | Value | Description |
|-----------|-------|-------------|
| spacing.0-5–20 | 2px–80px | 4px-based spacing scale |
| borderRadius.none–full | 0px–9999px | Radius scale |

### Effects

`tokens/primitives/effects.json`
| Token path | Value | Description |
|-----------|-------|-------------|
| shadow.sm–xl | CSS box-shadow strings | Elevation shadows |
| opacity.disabled | 0.4 | Disabled elements |
| opacity.hover | 0.08 | Hover overlay tint |
| opacity.overlay | 0.5 | Modal backdrop |

## Semantic tokens

### Colour semantics

`tokens/semantic/colours.json`
| Token path | References | Description |
|-----------|-----------|-------------|
| color.text.primary | → neutral.800 | Main body/heading text |
| color.text.secondary | → neutral.600 | Helper text, descriptions |
| color.text.tertiary | → neutral.500 | Placeholders, timestamps |
| color.text.disabled | → neutral.400 | Disabled text |
| color.text.inverse | → white | Text on dark backgrounds |
| color.text.brand | → brand.600 | Links, brand emphasis |
| color.text.error | → red.600 | Error messages |
| color.text.success | → green.600 | Success messages |
| color.text.warning | → amber.700 | Warning messages |
| color.surface.default | → white | Main page background |
| color.surface.subtle | → neutral.50 | Alternate backgrounds |
| color.surface.raised | → white | Cards (with shadow) |
| color.surface.warm | → brand.50 | Warm-tinted sections |
| color.surface.cool | → sage.50 | Cool/calming sections |
| color.surface.overlay | #00000080 | Modal backdrop |
| color.border.default | → neutral.200 | Standard borders |
| color.border.strong | → neutral.400 | Emphasis borders |
| color.border.subtle | → neutral.100 | Soft dividers |
| color.border.brand | → brand.500 | Focused inputs, brand borders |
| color.border.error | → red.500 | Error field borders |
| color.border.success | → green.500 | Success field borders |
| color.interactive.default | → brand.500 | Primary button, links |
| color.interactive.hover | → brand.600 | Hover state |
| color.interactive.active | → brand.700 | Active/pressed state |
| color.interactive.disabled | → neutral.300 | Disabled interactive |
| color.interactive.focus | → brand.500 | Focus ring colour |
| color.interactive.secondary | → sage.700 | Secondary buttons |
| color.interactive.secondary-hover | → sage.800 | Secondary hover |
| color.feedback.success | → green.600 | Success indicator |
| color.feedback.success-subtle | → green.50 | Success background |
| color.feedback.warning | → amber.600 | Warning indicator |
| color.feedback.warning-subtle | → amber.50 | Warning background |
| color.feedback.error | → red.600 | Error indicator |
| color.feedback.error-subtle | → red.50 | Error background |
| color.feedback.info | → blue.600 | Info indicator |
| color.feedback.info-subtle | → blue.50 | Info background |

### Typography semantics

`tokens/semantic/typography.json`
| Token path | References | Description |
|-----------|-----------|-------------|
| typography.display.* | fontSize.3xl, fontFamily.display, bold, tight | Hero display text |
| typography.h1.* | fontSize.2xl, fontFamily.display, bold, tight | Page headings |
| typography.h2.* | fontSize.xl, fontFamily.display, semibold, snug | Section headings |
| typography.h3.* | fontSize.lg, fontFamily.body, semibold, snug | Sub-headings |
| typography.h4.* | fontSize.md, fontFamily.body, semibold, snug | Minor headings |
| typography.bodyLarge.* | fontSize.md, fontFamily.body, regular, relaxed | Lead paragraphs |
| typography.body.* | fontSize.base, fontFamily.body, regular, normal | Default body |
| typography.bodySmall.* | fontSize.sm, fontFamily.body, regular, normal | Helper text |
| typography.caption.* | fontSize.xs, fontFamily.body, regular, snug | Fine print |
| typography.label.* | fontSize.sm, fontFamily.body, medium, normal | Form labels |
| typography.overline.* | fontSize.xs, fontFamily.body, semibold, snug | Section overlines |

### Spacing semantics

`tokens/semantic/spacing.json`
| Token path | References | Description |
|-----------|-----------|-------------|
| spacing.component.xs–lg | → spacing.1–6 | Component internal spacing |
| spacing.layout.gutter | → spacing.4 | Grid gutter (mobile) |
| spacing.layout.gutter-desktop | → spacing.6 | Grid gutter (desktop) |
| spacing.layout.section | → spacing.12 | Page section gap |
| spacing.layout.page | → spacing.16 | Major section gap |
| spacing.layout.page-padding | → spacing.4 | Page horizontal padding (mobile) |
| spacing.layout.page-padding-desktop | → spacing.8 | Page horizontal padding (desktop) |

## Component tokens

`tokens/component/button.json`

### Button — Sizing

| Token path | Value / Reference | Used by | Description |
|-----------|-----------|---------|-------------|
| button.height.xs | 28px | Button | Extra-small height — compact text buttons |
| button.height.sm | 32px | Button | Small height — secondary actions |
| button.height.md | 40px | Button | Medium height — default |
| button.height.lg | 48px | Button | Large height — CTAs, mobile (meets 44px touch target) |
| button.paddingX.xs–lg | → spacing.2–6 (8–24px) | Button | Horizontal padding per size |
| button.paddingY.xs–lg | → spacing.1–3 (4–12px) | Button | Vertical padding per size |
| button.fontSize.xs–lg | → fontSize.xs–base (12–16px) | Button | Font size per size |
| button.iconSize.xs–lg | 14–20px | Button | Icon dimensions per size |
| button.iconGap.xs–lg | → spacing.1–2 (4–8px) | Button | Icon-to-text gap per size |
| button.borderRadius.default | → borderRadius.md (8px) | Button | Button corner radius |