Richie
16dcc4de2e
- Add preview-head.html to load Montserrat and Noto Serif SC in Storybook - Document DS equivalents for all 7 flagged production color conflicts - Strategy: keep both values, production names for backward compat, DS names go-forward Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
88 lines
4.5 KiB
Markdown
88 lines
4.5 KiB
Markdown
# 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.
|