# Token Alignment Report: Design System ↔ Production

This documents how the Storybook design system tokens map to production's Tailwind config.

## Approach

- **Where tokens match** — production's naming and values adopted directly
- **Where Storybook adds tokens** — added alongside production's existing tokens
- **Where there's a conflict** — flagged below for review

## Colours

### Adopted from production (unchanged)

| Production token | Hex | Notes |
|---|---|---|
| `grey-1` | #f4f3ef | |
| `grey-2` | #D7E1E2 | Matches `sage-200` |
| `grey-3` | #b9c7c9 | Matches `sage-400` |
| `grey-4` | #4c5459 | Matches `sage-800` — default body text |
| `grey-5` | #4c5b6b | Matches `sage-700` |
| `grey-6` | #D9D9D9 | No design system equivalent |
| `grey-7` | #EEEEEE | No design system equivalent |
| `color-1` | #B0610F | Matches `brand-600` |
| `color-1H` | #9e6f42 | No exact DS match (between brand-600 & brand-500) |
| `color-2` | #DCC1A6 | Close to `brand-200` (#EBDAC8) — slightly warmer |
| `color-2H` | #d1b79e | No exact DS match |
| `color-3` | #BA834E | Matches `brand-500` |
| `color-4` | #D0A070 | Matches `brand-400` |
| `color-5` | #F4F3EF | Same as `grey-1` |
| `color-6` | #51301B | Matches `brand-900` |
| `action-orange` | #F89E53 | No DS equivalent — unique to production |
| `success-green` | #76B041 | Different from DS `green-500` (#4A8F4A) |
| `warning-red` | #A41623 | Different from DS `red-600` (#BC2F2F) |

### Design system palettes added alongside

Full 11-shade palettes: `brand`, `sage`, `neutral`, `red`, `amber`, `green`, `blue`

These are available as Tailwind classes: `bg-brand-500`, `text-sage-800`, etc.

### Flagged conflicts — resolved

**Strategy:** Keep both production and DS values. Production names preserved for backward compatibility; DS names are the go-forward standard. New components should use DS token names. Inline comments in `tailwind.config.js` document the mapping.

| Issue | Production | DS equivalent | Resolution |
|---|---|---|---|
| `color-2` vs `brand-200` | #DCC1A6 | #EBDAC8 | Both kept. Warmer production value used in existing templates; DS value for new components. |
| `color-1H` hover | #9e6f42 | — | Kept. Superseded by DS interactive hover states (`brand-700`) as components migrate. |
| `color-2H` hover | #d1b79e | — | Kept. Same approach as `color-1H`. |
| `success-green` vs `green-500` | #76B041 (lime) | #4A8F4A (forest) | Both kept. Visually different; new components use DS `green-*` palette. |
| `warning-red` vs `red-600` | #A41623 (crimson) | #BC2F2F (warm red) | Both kept. New components use DS `red-*` palette. |
| `action-orange` vs `amber-400` | #F89E53 | #ffb833 | Both kept. Production-only orange retained; closest DS equivalent is `amber-400`. |
| `grey-6`, `grey-7` | #D9D9D9, #EEEEEE | ~`neutral-300`, ~`neutral-100` | Both kept. Close but not identical; production values retained for existing usage. |

## Typography

### Font families — aligned
| Production | Design system | Status |
|---|---|---|
| `font-sans` (Montserrat) | `fontFamily.body` | Aligned |
| `font-notoSerifSC` | `fontFamily.display` | Aligned |
| `font-arial` | — | Production only |

### Font sizes — mixed
Production has custom sizes (`xxs`, `1.5xl`, `2.15xl`, `2.3xl`, `3.3xl`) that map to specific Tailwind typography classes. Design system has its own scale (`2xs`–`4xl`). Both are included in the config.

### Typography classes
Production's `.tailwindcss-h1` through `.tailwindcss-h6` classes use hardcoded `#4C5459` text colour. Design system uses MUI Typography variants that reference tokens. Both can coexist — MUI components use the theme, Tailwind templates use the classes.

## Breakpoints — fully aligned

| Name | Value | Source |
|---|---|---|
| `xs` | 0px | Both (MUI default) |
| `sm` | 600px | Both (MUI default) |
| `md` | 960px | Both (MUI v4 default) |
| `lg` | 1280px | Both (MUI default) |
| `xl` | 1536px | Both (MUI v5+ default) |

## Spacing — compatible

Production's custom spacing (5px, 12px, 12.5px, 14px, 15px, 30px) is preserved as `padding` and `margin` extensions. Design system's 4px-base scale is available as standard Tailwind spacing utilities.

## Conclusion

The merged `tailwind.config.js` provides full backward compatibility with production's existing classes while adding the design system's semantic palettes. All 7 flagged colour conflicts have been resolved with a "keep both, document mappings" strategy — production values are preserved for backward compatibility, DS values are the go-forward standard, and inline comments in the Tailwind config document the mapping between them.