# 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 |

### Card

`tokens/component/card.json`

| Token path | Value / Reference | Used by | Description |
|-----------|-----------|---------|-------------|
| card.borderRadius.default | → borderRadius.md (8px) | Card | Card corner radius |
| card.padding.default | → spacing.6 (24px) | Card | Standard card padding (desktop) |
| card.padding.compact | → spacing.4 (16px) | Card | Compact card padding (mobile, tight layouts) |
| card.shadow.default | → shadow.md | Card | Resting elevation — medium shadow |
| card.shadow.hover | → shadow.lg | Card | Hover elevation — interactive cards |
| card.border.default | → color.border.default (#E8E8E8) | Card | Outlined card border colour |
| card.border.selected | → color.border.brand (#BA834E) | Card | Brand border for selected/active cards |
| card.background.default | → color.surface.raised (#FFFFFF) | Card | Card background (raised surface) |
| card.background.hover | → color.surface.subtle (#FAFAFA) | Card | Subtle grey fill on hover for interactive cards |
| card.background.selected | → color.surface.warm (#FEF9F5) | Card | Warm tint for selected cards |

### Badge

`tokens/component/badge.json`

| Token path | Value / Reference | Used by | Description |
|-----------|-----------|---------|-------------|
| badge.height.sm | 22px | Badge | Small badge height |
| badge.height.md | 26px | Badge | Medium badge height (default) |
| badge.paddingX.sm | → spacing.2 (8px) | Badge | Small horizontal padding |
| badge.paddingX.md | → spacing.3 (12px) | Badge | Medium horizontal padding |
| badge.fontSize.sm | → fontSize.2xs (11px) | Badge | Small badge text |
| badge.fontSize.md | → fontSize.xs (12px) | Badge | Medium badge text |
| badge.iconSize.sm | 12px | Badge | Small badge icon |
| badge.iconSize.md | 14px | Badge | Medium badge icon |
| badge.iconGap.default | → spacing.1 (4px) | Badge | Icon-to-text gap |
| badge.borderRadius.default | → borderRadius.full (9999px) | Badge | Pill shape |

### Chip

`tokens/component/chip.json`

| Token path | Value / Reference | Used by | Description |
|-----------|-----------|---------|-------------|
| chip.height.sm | 28px | Chip | Small chip height |
| chip.height.md | 32px | Chip | Medium chip height (default) |
| chip.paddingX.sm | → spacing.2 (8px) | Chip | Small horizontal padding |
| chip.paddingX.md | → spacing.3 (12px) | Chip | Medium horizontal padding |
| chip.fontSize.sm | → fontSize.xs (12px) | Chip | Small chip text |
| chip.fontSize.md | → fontSize.sm (14px) | Chip | Medium chip text |
| chip.iconSize.sm | 16px | Chip | Small chip leading icon |
| chip.iconSize.md | 18px | Chip | Medium chip leading icon |
| chip.deleteIconSize.sm | 14px | Chip | Small chip delete icon |
| chip.deleteIconSize.md | 16px | Chip | Medium chip delete icon |
| chip.iconGap.default | → spacing.1 (4px) | Chip | Icon-to-text gap |
| chip.borderRadius.default | → borderRadius.full (9999px) | Chip | Pill shape |

### Switch

`tokens/component/switch.json`

| Token path | Value / Reference | Used by | Description |
|-----------|-----------|---------|-------------|
| switch.track.width | 44px | Switch | Track width |
| switch.track.height | 24px | Switch | Track height |
| switch.track.borderRadius | → borderRadius.full (9999px) | Switch | Pill shape |
| switch.thumb.size | 18px | Switch | Thumb diameter |

### Radio

`tokens/component/radio.json`

| Token path | Value / Reference | Used by | Description |
|-----------|-----------|---------|-------------|
| radio.size.default | 20px | Radio | Outer circle size |
| radio.dotSize.default | 10px | Radio | Inner selected dot size |

### ProviderCard

`tokens/component/providerCard.json`

| Token path | Value / Reference | Used by | Description |
|-----------|-----------|---------|-------------|
| providerCard.image.height | 180px | ProviderCard | Hero image fixed height |
| providerCard.logo.size | 64px | ProviderCard | Logo width/height — rounded rectangle inside image area |
| providerCard.logo.borderRadius | → borderRadius.md (8px) | ProviderCard | Rounded rectangle corners |
| providerCard.content.padding | → spacing.3 (12px) | ProviderCard | Content area padding |
| providerCard.content.gap | → spacing.1 (4px) | ProviderCard | Gap between content rows |

### VenueCard

`tokens/component/venueCard.json`

| Token path | Value / Reference | Used by | Description |
|-----------|-----------|---------|-------------|
| venueCard.image.height | 180px | VenueCard | Hero image fixed height — matches ProviderCard for list consistency |
| venueCard.content.padding | → spacing.3 (12px) | VenueCard | Content area padding |
| venueCard.content.gap | → spacing.1 (4px) | VenueCard | Gap between content rows |
