Richie
1baa55c417
- Configure Vite library mode to export MUI theme as plain JS - Add tsconfig.build.json for declaration generation - Add package.json exports for theme, Tailwind config, and tokens - Create src/index.ts as library entry point - Document token alignment between design system and production including colour mapping, flagged conflicts, and breakpoint alignment Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3.9 KiB
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 for review
| Issue | Detail |
|---|---|
color-2 vs brand-200 |
Production: #DCC1A6, DS: #EBDAC8. Close but not identical. Production has a slightly warmer/darker tint. |
color-1H hover |
Production: #9e6f42. No exact DS equivalent. Falls between brand-500 and brand-600. |
color-2H hover |
Production: #d1b79e. No exact DS equivalent. |
success-green vs green-500 |
Production: #76B041 (lime-ish), DS: #4A8F4A (forest green). Visually different. |
warning-red vs red-600 |
Production: #A41623 (dark crimson), DS: #BC2F2F (warmer red). Different hue and value. |
action-orange |
#F89E53 — exists only in production. No amber/orange equivalent in DS. |
grey-6, grey-7 |
Exist only in production. Not mapped to DS neutral scale. |
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. The flagged colour conflicts are minor and can be resolved when production adopts the design system tokens directly.