FuneralArranger/docs/token-alignment-report.md

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.