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>

bootstrap.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+# FA Design System — Bootstrap Script
+# Run this once after cloning/copying the project scaffold to set everything up.
+
+set -e
+
+echo "╔══════════════════════════════════════════════╗"
+echo "║  FA Design System — Project Bootstrap        ║"
+echo "╚══════════════════════════════════════════════╝"
+echo ""
+
+# ─── 1. Install dependencies ─────────────────────────────────────────────────
+echo "📦 Installing dependencies..."
+npm install
+
+# ─── 2. Initialise Storybook (if not already configured) ─────────────────────
+echo ""
+echo "📖 Checking Storybook setup..."
+if [ ! -d ".storybook" ]; then
+  echo "  .storybook config not found. Creating configuration..."
+  mkdir -p .storybook
+  cat > .storybook/main.ts << 'MAINEOF'
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  addons: [
+    '@storybook/addon-essentials',
+  ],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+  docs: {
+    autodocs: 'tag',
+  },
+  viteFinal: async (config) => {
+    return config;
+  },
+};
+
+export default config;
+MAINEOF
+  cat > .storybook/preview.tsx << 'PREVEOF'
+import React from 'react';
+import type { Preview } from '@storybook/react';
+import { ThemeProvider } from '@mui/material/styles';
+import CssBaseline from '@mui/material/CssBaseline';
+import { theme } from '../src/theme';
+
+const preview: Preview = {
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={theme}>
+        <CssBaseline />
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;
+PREVEOF
+  echo "  ✓ .storybook config created."
+else
+  echo "  .storybook config found. Skipping."
+fi
+
+# ─── 3. Build initial token output ───────────────────────────────────────────
+echo ""
+echo "🎨 Building placeholder token output..."
+mkdir -p src/theme/generated
+mkdir -p tokens/export
+# Style Dictionary needs at least one source file to build
+if [ ! -f "tokens/primitives/colours.json" ]; then
+  echo '{}' > tokens/primitives/colours.json
+  echo '{}' > tokens/primitives/typography.json
+  echo '{}' > tokens/primitives/spacing.json
+  echo '{}' > tokens/primitives/effects.json
+  echo '{}' > tokens/semantic/colours.json
+  echo '{}' > tokens/semantic/typography.json
+  echo '{}' > tokens/semantic/spacing.json
+  echo "  Created empty token placeholder files."
+fi
+
+# ─── 4. TypeScript check ─────────────────────────────────────────────────────
+echo ""
+echo "🔍 Running TypeScript check..."
+npx tsc --noEmit 2>/dev/null && echo "  ✓ TypeScript OK" || echo "  ⚠ TypeScript errors (expected before tokens are created)"
+
+# ─── 5. Git init ─────────────────────────────────────────────────────────────
+echo ""
+if [ ! -d ".git" ]; then
+  echo "🔧 Initialising git repository..."
+  git init
+  git add -A
+  git commit -m "Initial scaffold: FA Design System project structure"
+  echo "  ✓ Git initialised with initial commit"
+else
+  echo "🔧 Git already initialised."
+fi
+
+# ─── 6. Summary ──────────────────────────────────────────────────────────────
+echo ""
+echo "╔══════════════════════════════════════════════╗"
+echo "║  ✓ Bootstrap complete!                       ║"
+echo "╚══════════════════════════════════════════════╝"
+echo ""
+echo "Next steps:"
+echo ""
+echo "  1. SET UP FIGMA MCP:"
+echo "     claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp"
+echo "     Then restart Claude Code and authenticate via /mcp"
+echo ""
+echo "  2. START CLAUDE CODE:"
+echo "     cd $(pwd)"
+echo "     claude"
+echo ""
+echo "  3. CHECK STATUS:"
+echo "     /status"
+echo ""
+echo "  4. CREATE YOUR TOKENS:"
+echo "     /create-tokens [provide brand colours, fonts, and context]"
+echo ""
+echo "  5. START STORYBOOK (in a separate terminal):"
+echo "     npm run storybook"
+echo ""
+echo "  6. BUILD YOUR FIRST ATOM:"
+echo "     /build-atom Button"
+echo ""