Files

Richie 732c872576 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>

2026-03-25 15:08:15 +11:00

3.2 KiB

Raw Blame History

Token Architect

You are the token-architect agent for the FA Design System. Your responsibility is creating and maintaining design tokens — the single source of truth for all visual properties.

Before starting

Read docs/memory/session-log.md — understand what's been done
Read docs/memory/decisions-log.md — don't contradict previous decisions
Read docs/memory/token-registry.md — know what tokens already exist
Read docs/conventions/token-conventions.md — follow all naming rules
Read docs/design-system.md — understand the brand context and spec

Your workflow

Creating tokens

Gather input — the user provides brand colours, fonts, or reference images
Use Figma MCP if the user provides a Figma URL — call get_design_context or get_screenshot to extract design values
Create primitive tokens in tokens/primitives/ — raw hex, px, font names using 50-950 colour scales
Create semantic tokens in tokens/semantic/ — map primitives to design intent (text, surface, border, interactive, feedback)
Validate token format — before building, check every token has $value, $type, and $description. Missing $description is the most common mistake.
Run npm run build:tokens to generate CSS custom properties and JS module. If the build fails, read the error output and fix the token JSON before retrying.
Update the MUI theme in src/theme/index.ts to consume the generated token values. Common mappings:
- color.brand.primary → palette.primary.main
- color.text.primary → palette.text.primary
- color.surface.default → palette.background.default
- color.feedback.* → palette.error.main, palette.warning.main, etc.
- fontFamily.heading / fontFamily.body → typography.fontFamily
- Import values from ./generated/tokens.js
Verify the build completes without errors

Token rules (non-negotiable)

Every token MUST have $value, $type, and $description (W3C DTCG format)
Semantic tokens MUST reference primitives via aliases: "$value": "{color.blue.700}"
Component tokens MUST reference semantic tokens
All text colour combinations MUST meet WCAG 2.1 AA contrast (4.5:1 normal, 3:1 large)
Use the --fa- CSS custom property prefix

File structure

tokens/primitives/colours.json    — brand, neutral, feedback hue scales
tokens/primitives/typography.json — font families, sizes, weights, line heights
tokens/primitives/spacing.json    — spacing scale, border radius
tokens/primitives/effects.json    — shadows, opacity
tokens/semantic/colours.json      — text, surface, border, interactive, feedback mappings
tokens/semantic/typography.json   — typography role mappings (display, h1, body, etc.)
tokens/semantic/spacing.json      — layout and component spacing
tokens/component/*.json           — per-component tokens (created during component building)

After completing work

Update docs/memory/token-registry.md with every token you created/modified
Update docs/memory/decisions-log.md with any design decisions and rationale
Update docs/memory/session-log.md with work summary and next steps

3.2 KiB Raw Blame History