Initial commit: FA 2.0 Design System foundation

Token pipeline (Style Dictionary v4, DTCG format):
- Primitive tokens: colour palettes (brand, sage, neutral, feedback),
  typography (3 font families, 21-variant type scale), spacing (4px grid),
  border radius, shadows, opacity
- Semantic tokens: text, surface, border, interactive, feedback colours;
  typography roles; layout spacing
- Component tokens: Button (4 sizes), Input (2 sizes)
- Generated outputs: CSS custom properties, JS ES6 module, flat JSON

Atoms (3 components):
- Button: contained/soft/outlined/text × primary/secondary, 4 sizes,
  loading state, underline for text variant
- Typography: 21 variants across display/heading/body/label/caption/overline,
  maxLines truncation
- Input: external label, helper text, error/success validation,
  start/end icons, required indicator, 2 sizes, multiline support

Infrastructure:
- MUI v5 theme with full token mapping
- Storybook 8 with autodocs
- Claude Code agents and skills for token/component workflows
- Design system documentation and cross-session memory

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-03-25 15:08:15 +11:00
commit 732c872576
56 changed files with 12690 additions and 0 deletions

View File

@@ -0,0 +1,164 @@
{
"color": {
"$type": "color",
"text": {
"$description": "Semantic text colours — define the hierarchy and intent of text across the UI.",
"primary": {
"$value": "{color.neutral.800}",
"$description": "Primary text — body content, headings. Cool charcoal (#2C2E35) for comfortable extended reading"
},
"secondary": {
"$value": "{color.neutral.600}",
"$description": "Secondary text — helper text, descriptions, metadata, less prominent content"
},
"tertiary": {
"$value": "{color.neutral.500}",
"$description": "Tertiary text — placeholders, timestamps, attribution, meta information"
},
"disabled": {
"$value": "{color.neutral.400}",
"$description": "Disabled text — clearly diminished but still readable for accessibility"
},
"inverse": {
"$value": "{color.white}",
"$description": "Inverse text — white text on dark or coloured backgrounds (buttons, banners)"
},
"brand": {
"$value": "{color.brand.600}",
"$description": "Brand-coloured text — links, inline brand emphasis. Copper tone meets AA on white (4.8:1)"
},
"error": {
"$value": "{color.red.600}",
"$description": "Error text — form validation messages, error descriptions"
},
"success": {
"$value": "{color.green.600}",
"$description": "Success text — confirmation messages, positive feedback"
},
"warning": {
"$value": "{color.amber.700}",
"$description": "Warning text — cautionary messages. Uses amber.700 for WCAG AA compliance on white (5.1:1)"
}
},
"surface": {
"$description": "Background/surface colours for page sections, cards, and containers.",
"default": {
"$value": "{color.white}",
"$description": "Default surface — main page background, card faces"
},
"subtle": {
"$value": "{color.neutral.50}",
"$description": "Subtle surface — slight differentiation from default, alternate row backgrounds"
},
"raised": {
"$value": "{color.white}",
"$description": "Raised surface — cards, elevated containers (distinguished by shadow rather than colour)"
},
"warm": {
"$value": "{color.brand.50}",
"$description": "Warm surface — brand-tinted sections, promotional areas, upsell cards like 'Protect your plan'"
},
"cool": {
"$value": "{color.sage.50}",
"$description": "Cool surface — calming sections, information panels, FAQ backgrounds"
},
"overlay": {
"$value": "#00000080",
"$description": "Overlay surface — modal/dialog backdrop at 50% black"
}
},
"border": {
"$description": "Border colours for containers, inputs, and visual dividers.",
"default": {
"$value": "{color.neutral.200}",
"$description": "Default border — cards, containers, resting input borders"
},
"strong": {
"$value": "{color.neutral.400}",
"$description": "Strong border — emphasis borders, active input borders"
},
"subtle": {
"$value": "{color.neutral.100}",
"$description": "Subtle border — section dividers, soft separators"
},
"brand": {
"$value": "{color.brand.500}",
"$description": "Brand border — focused inputs, selected cards, brand-accented containers"
},
"error": {
"$value": "{color.red.500}",
"$description": "Error border — form fields with validation errors"
},
"success": {
"$value": "{color.green.500}",
"$description": "Success border — validated fields, confirmed selections"
}
},
"interactive": {
"$description": "Colours for interactive elements — buttons, links, form controls.",
"default": {
"$value": "{color.brand.600}",
"$description": "Default interactive — primary button fill, link colour, checkbox accent. Uses brand.600 (copper) for WCAG AA compliance (4.6:1 on white)"
},
"hover": {
"$value": "{color.brand.700}",
"$description": "Hover state — deepened copper on hover for clear visual feedback"
},
"active": {
"$value": "{color.brand.800}",
"$description": "Active/pressed state — dark brown during click/tap"
},
"disabled": {
"$value": "{color.neutral.300}",
"$description": "Disabled interactive — muted grey, no pointer events"
},
"focus": {
"$value": "{color.brand.600}",
"$description": "Focus ring colour — keyboard navigation indicator, 2px outline with 2px offset"
},
"secondary": {
"$value": "{color.sage.700}",
"$description": "Secondary interactive — grey/sage buttons, less prominent actions"
},
"secondary-hover": {
"$value": "{color.sage.800}",
"$description": "Secondary interactive hover — darkened sage on hover"
}
},
"feedback": {
"$description": "System alert and feedback colours. Each type has a strong variant (for text/icons) and a subtle variant (for backgrounds).",
"success": {
"$value": "{color.green.600}",
"$description": "Success — confirmations, completed arrangement steps, booking confirmed"
},
"success-subtle": {
"$value": "{color.green.50}",
"$description": "Success background — success message container fill, completion banners"
},
"warning": {
"$value": "{color.amber.600}",
"$description": "Warning — price change alerts, important notices, bond/insurance prompts"
},
"warning-subtle": {
"$value": "{color.amber.50}",
"$description": "Warning background — warning message container fill, notice banners"
},
"error": {
"$value": "{color.red.600}",
"$description": "Error — form validation failures, system errors, payment issues"
},
"error-subtle": {
"$value": "{color.red.50}",
"$description": "Error background — error message container fill, alert banners"
},
"info": {
"$value": "{color.blue.600}",
"$description": "Info — helpful tips, supplementary information, guidance callouts"
},
"info-subtle": {
"$value": "{color.blue.50}",
"$description": "Info background — info message container fill, tip banners"
}
}
}
}

View File

@@ -0,0 +1,22 @@
{
"spacing": {
"component": {
"$type": "dimension",
"$description": "Component-level spacing — internal padding and gaps within components.",
"xs": { "$value": "{spacing.1}", "$description": "4px — tight gaps: icon margins, chip internal padding" },
"sm": { "$value": "{spacing.2}", "$description": "8px — small padding: badge padding, inline element gaps" },
"md": { "$value": "{spacing.4}", "$description": "16px — default padding: button padding, input padding, form field gap" },
"lg": { "$value": "{spacing.6}", "$description": "24px — large padding: card padding (desktop), modal padding" }
},
"layout": {
"$type": "dimension",
"$description": "Layout-level spacing — structural gaps between sections and page elements.",
"gutter": { "$value": "{spacing.4}", "$description": "16px — grid gutter on mobile, card grid gap" },
"gutter-desktop": { "$value": "{spacing.6}", "$description": "24px — grid gutter on desktop" },
"section": { "$value": "{spacing.12}", "$description": "48px — vertical gap between page sections" },
"page": { "$value": "{spacing.16}", "$description": "64px — major page section separation, hero spacing" },
"page-padding": { "$value": "{spacing.4}", "$description": "16px — horizontal page padding on mobile" },
"page-padding-desktop": { "$value": "{spacing.8}", "$description": "32px — horizontal page padding on desktop" }
}
}
}

View File

@@ -0,0 +1,198 @@
{
"typography": {
"$description": "Typography role definitions — 21 variants across 6 categories. Display uses Noto Serif SC (serif, Regular). All other text uses Montserrat. Line-height and letter-spacing use specific values per variant for precise control.",
"displayHero": {
"$description": "Hero display — largest marketing/hero text. Noto Serif SC Regular.",
"fontFamily": { "$value": "{fontFamily.display}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.display.hero}", "$type": "dimension", "$description": "80px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.displayHero}", "$type": "dimension", "$description": "32px mobile" },
"fontWeight": { "$value": "{fontWeight.regular}", "$type": "fontWeight", "$description": "400 — serif carries inherent weight at large sizes" },
"lineHeight": { "$value": 1.05, "$type": "number" },
"letterSpacing": { "$value": "-1.5px", "$type": "dimension" }
},
"display1": {
"$description": "Display level 1 — major marketing headings. Noto Serif SC Regular.",
"fontFamily": { "$value": "{fontFamily.display}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.display.1}", "$type": "dimension", "$description": "64px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.display1}", "$type": "dimension", "$description": "28px mobile" },
"fontWeight": { "$value": "{fontWeight.regular}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.078, "$type": "number" },
"letterSpacing": { "$value": "-1px", "$type": "dimension" }
},
"display2": {
"$description": "Display level 2 — section hero text. Noto Serif SC Regular.",
"fontFamily": { "$value": "{fontFamily.display}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.display.2}", "$type": "dimension", "$description": "52px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.display2}", "$type": "dimension", "$description": "24px mobile" },
"fontWeight": { "$value": "{fontWeight.regular}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.096, "$type": "number" },
"letterSpacing": { "$value": "-0.5px", "$type": "dimension" }
},
"display3": {
"$description": "Display level 3 — prominent section titles. Noto Serif SC Regular.",
"fontFamily": { "$value": "{fontFamily.display}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.display.3}", "$type": "dimension", "$description": "40px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.display3}", "$type": "dimension", "$description": "22px mobile" },
"fontWeight": { "$value": "{fontWeight.regular}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.15, "$type": "number" },
"letterSpacing": { "$value": "-0.25px", "$type": "dimension" }
},
"displaySm": {
"$description": "Display small — smallest display text, pull quotes. Noto Serif SC Regular.",
"fontFamily": { "$value": "{fontFamily.display}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.display.sm}", "$type": "dimension", "$description": "32px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.displaySm}", "$type": "dimension", "$description": "20px mobile" },
"fontWeight": { "$value": "{fontWeight.regular}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.1875, "$type": "number" },
"letterSpacing": { "$value": "0px", "$type": "dimension" }
},
"h1": {
"$description": "Heading 1 — page titles. Montserrat Bold.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.3xl}", "$type": "dimension", "$description": "36px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.h1}", "$type": "dimension", "$description": "26px mobile" },
"fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.194, "$type": "number" },
"letterSpacing": { "$value": "-0.5px", "$type": "dimension" }
},
"h2": {
"$description": "Heading 2 — section titles. Montserrat Bold.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.2xl}", "$type": "dimension", "$description": "30px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.h2}", "$type": "dimension", "$description": "22px mobile" },
"fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.267, "$type": "number" },
"letterSpacing": { "$value": "-0.25px", "$type": "dimension" }
},
"h3": {
"$description": "Heading 3 — sub-section titles. Montserrat Bold.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.xl}", "$type": "dimension", "$description": "24px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.h3}", "$type": "dimension", "$description": "20px mobile" },
"fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.292, "$type": "number" },
"letterSpacing": { "$value": "0px", "$type": "dimension" }
},
"h4": {
"$description": "Heading 4 — minor headings. Montserrat Bold.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.lg}", "$type": "dimension", "$description": "20px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.h4}", "$type": "dimension", "$description": "18px mobile" },
"fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.35, "$type": "number" },
"letterSpacing": { "$value": "0px", "$type": "dimension" }
},
"h5": {
"$description": "Heading 5 — small headings. Montserrat Bold.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.md}", "$type": "dimension", "$description": "18px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.h5}", "$type": "dimension", "$description": "16px mobile" },
"fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.389, "$type": "number" },
"letterSpacing": { "$value": "0px", "$type": "dimension" }
},
"h6": {
"$description": "Heading 6 — smallest heading. Montserrat Bold.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.base}", "$type": "dimension", "$description": "16px desktop" },
"fontSizeMobile": { "$value": "{fontSize.mobile.h6}", "$type": "dimension", "$description": "14px mobile" },
"fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.375, "$type": "number" },
"letterSpacing": { "$value": "0px", "$type": "dimension" }
},
"bodyLg": {
"$description": "Body large — lead paragraphs, introductions. Montserrat Medium.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.md}", "$type": "dimension", "$description": "18px" },
"fontWeight": { "$value": "{fontWeight.medium}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.611, "$type": "number" },
"letterSpacing": { "$value": "0px", "$type": "dimension" }
},
"body": {
"$description": "Body default — main content text. Montserrat Medium.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.base}", "$type": "dimension", "$description": "16px" },
"fontWeight": { "$value": "{fontWeight.medium}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.625, "$type": "number" },
"letterSpacing": { "$value": "0px", "$type": "dimension" }
},
"bodySm": {
"$description": "Body small — helper text, secondary content. Montserrat Medium.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.sm}", "$type": "dimension", "$description": "14px" },
"fontWeight": { "$value": "{fontWeight.medium}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.571, "$type": "number" },
"letterSpacing": { "$value": "0px", "$type": "dimension" }
},
"bodyXs": {
"$description": "Body extra-small — fine print, compact content. Montserrat Medium.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.xs}", "$type": "dimension", "$description": "12px" },
"fontWeight": { "$value": "{fontWeight.medium}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.5, "$type": "number" },
"letterSpacing": { "$value": "0.1px", "$type": "dimension" }
},
"labelLg": {
"$description": "Label large — prominent form labels, section labels. Montserrat Medium.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.base}", "$type": "dimension", "$description": "16px" },
"fontWeight": { "$value": "{fontWeight.medium}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.3125, "$type": "number" },
"letterSpacing": { "$value": "0.1px", "$type": "dimension" }
},
"label": {
"$description": "Label default — form labels, UI text. Montserrat Medium.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.sm}", "$type": "dimension", "$description": "14px" },
"fontWeight": { "$value": "{fontWeight.medium}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.286, "$type": "number" },
"letterSpacing": { "$value": "0.15px", "$type": "dimension" }
},
"labelSm": {
"$description": "Label small — compact labels, tag text. Montserrat Medium.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.xs}", "$type": "dimension", "$description": "12px" },
"fontWeight": { "$value": "{fontWeight.medium}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.333, "$type": "number" },
"letterSpacing": { "$value": "0.2px", "$type": "dimension" }
},
"caption": {
"$description": "Caption default — fine print, timestamps, metadata. Montserrat Regular.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.xs}", "$type": "dimension", "$description": "12px" },
"fontWeight": { "$value": "{fontWeight.regular}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.417, "$type": "number" },
"letterSpacing": { "$value": "0.2px", "$type": "dimension" }
},
"captionSm": {
"$description": "Caption small — compact metadata, footnotes. Montserrat Regular. Min 11px for accessibility.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.2xs}", "$type": "dimension", "$description": "11px — accessibility floor" },
"fontWeight": { "$value": "{fontWeight.regular}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.364, "$type": "number" },
"letterSpacing": { "$value": "0.2px", "$type": "dimension" }
},
"overline": {
"$description": "Overline default — section overlines, category labels. Montserrat SemiBold, uppercase.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.xs}", "$type": "dimension", "$description": "12px" },
"fontWeight": { "$value": "{fontWeight.semibold}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.333, "$type": "number" },
"letterSpacing": { "$value": "1.5px", "$type": "dimension" }
},
"overlineSm": {
"$description": "Overline small — compact section labels, tab overlines. Montserrat SemiBold, uppercase. Min 11px for accessibility.",
"fontFamily": { "$value": "{fontFamily.body}", "$type": "fontFamily" },
"fontSize": { "$value": "{fontSize.2xs}", "$type": "dimension", "$description": "11px — accessibility floor" },
"fontWeight": { "$value": "{fontWeight.semibold}", "$type": "fontWeight" },
"lineHeight": { "$value": 1.273, "$type": "number" },
"letterSpacing": { "$value": "1.5px", "$type": "dimension" }
}
}
}