diff --git a/.storybook/preview-head.html b/.storybook/preview-head.html
new file mode 100644
index 0000000..f2662d7
--- /dev/null
+++ b/.storybook/preview-head.html
@@ -0,0 +1,6 @@
+
+
+
diff --git a/docs/token-alignment-report.md b/docs/token-alignment-report.md
index a122af2..8ab238e 100644
--- a/docs/token-alignment-report.md
+++ b/docs/token-alignment-report.md
@@ -39,17 +39,19 @@ Full 11-shade palettes: `brand`, `sage`, `neutral`, `red`, `amber`, `green`, `bl
These are available as Tailwind classes: `bg-brand-500`, `text-sage-800`, etc.
-### Flagged for review
+### Flagged conflicts — resolved
-| 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. |
+**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
@@ -82,4 +84,4 @@ Production's custom spacing (5px, 12px, 12.5px, 14px, 15px, 30px) is preserved a
## 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.
+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.
diff --git a/tailwind.config.js b/tailwind.config.js
index 91fd01a..3bf9d31 100644
--- a/tailwind.config.js
+++ b/tailwind.config.js
@@ -61,25 +61,26 @@ module.exports = {
// Production's colour tokens (preserved for backward compatibility)
// plus design system semantic palettes
colors: {
- // --- Production tokens (unchanged) ---
- 'grey-1': '#f4f3ef',
- 'grey-2': '#D7E1E2',
- 'grey-3': '#b9c7c9',
- 'grey-4': '#4c5459',
- 'grey-5': '#4c5b6b',
- 'grey-6': '#D9D9D9',
- 'grey-7': '#EEEEEE',
- 'warning-red': '#A41623',
- 'color-1': '#B0610F',
- 'color-1H': '#9e6f42',
- 'color-2': '#DCC1A6',
- 'color-2H': '#d1b79e',
- 'color-3': '#BA834E',
- 'color-4': '#D0A070',
- 'color-5': '#F4F3EF',
- 'color-6': '#51301B',
- 'action-orange': '#F89E53',
- 'success-green': '#76B041',
+ // --- Production tokens (preserved for backward compatibility) ---
+ // DS equivalent noted where applicable; new components should use DS names.
+ 'grey-1': '#f4f3ef', // ≈ brand-50 (#fef9f5)
+ 'grey-2': '#D7E1E2', // = sage-200
+ 'grey-3': '#b9c7c9', // = sage-400
+ 'grey-4': '#4c5459', // = sage-800
+ 'grey-5': '#4c5b6b', // = sage-700
+ 'grey-6': '#D9D9D9', // ≈ neutral-300 (#d4d4d4)
+ 'grey-7': '#EEEEEE', // ≈ neutral-100 (#f5f5f5)
+ 'warning-red': '#A41623', // ≈ red-600 (#BC2F2F) — darker crimson vs DS warm red
+ 'color-1': '#B0610F', // = brand-600
+ 'color-1H': '#9e6f42', // No DS match — between brand-500 and brand-600
+ 'color-2': '#DCC1A6', // ≈ brand-200 (#EBDAC8) — warmer/darker than DS
+ 'color-2H': '#d1b79e', // No DS match — production hover state
+ 'color-3': '#BA834E', // = brand-500
+ 'color-4': '#D0A070', // = brand-400
+ 'color-5': '#F4F3EF', // = grey-1
+ 'color-6': '#51301B', // = brand-900
+ 'action-orange': '#F89E53', // ≈ amber-400 (#ffb833) — production only
+ 'success-green': '#76B041', // ≈ green-500 (#4a8f4a) — lime vs DS forest green
// --- Design system palettes (from tokens) ---
...dsTokens.colors,