chore: design system colour tokens, primitives & Storybook

.github/workflows/frontend-chromatic.yml

@@ -0,0 +1,45 @@
+name: Frontend Chromatic
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - frontend/**
+      - .github/workflows/frontend-chromatic.yml
+
+permissions:
+  contents: read
+
+jobs:
+  chromatic:
+    name: Chromatic
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+
+    defaults:
+      run:
+        working-directory: frontend
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: frontend/.nvmrc
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish to Chromatic
+        uses: chromaui/action@v11
+        with:
+          workingDir: frontend
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          exitZeroOnChanges: true
+          exitOnceUploaded: true
+          onlyChanged: true

frontend/.eslintrc.js

@@ -10,6 +10,7 @@ module.exports = {
     'plugin:@typescript-eslint/recommended',
     'plugin:prettier/recommended',
     'plugin:@dword-design/import-alias/recommended',
+    'plugin:storybook/recommended',
   ],
   'globals': {
     '$': true,

frontend/.gitignore

@@ -33,3 +33,6 @@ common/project.js
 # Playwright
 e2e/playwright-report/
 e2e/test-results/
+
+*storybook.log
+storybook-static

frontend/.storybook/main.js

@@ -0,0 +1,62 @@
+const path = require('path')
+
+/** @type { import('storybook').StorybookConfig } */
+const config = {
+  stories: [
+    '../documentation/**/*.mdx',
+    '../documentation/**/*.stories.@(js|jsx|ts|tsx)',
+  ],
+  staticDirs: ['../web'],
+  addons: [
+    '@storybook/addon-webpack5-compiler-swc',
+    '@storybook/addon-docs',
+    '@storybook/addon-a11y',
+  ],
+  framework: {
+    name: '@storybook/react-webpack5',
+    options: {},
+  },
+  swc: () => ({
+    jsc: {
+      transform: {
+        react: {
+          runtime: 'automatic',
+        },
+      },
+      parser: {
+        syntax: 'typescript',
+        tsx: true,
+      },
+    },
+  }),
+  webpackFinal: async (config) => {
+    config.resolve = config.resolve || {}
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      common: path.resolve(__dirname, '../common'),
+      components: path.resolve(__dirname, '../web/components'),
+      project: path.resolve(__dirname, '../web/project'),
+    }
+
+    config.module = config.module || {}
+    config.module.rules = config.module.rules || []
+    config.module.rules.push({
+      test: /\.scss$/,
+      use: [
+        'style-loader',
+        { loader: 'css-loader', options: { importLoaders: 1 } },
+        {
+          loader: 'sass-loader',
+          options: {
+            sassOptions: {
+              silenceDeprecations: ['slash-div'],
+            },
+          },
+        },
+      ],
+    })
+
+    return config
+  },
+}
+module.exports = config

frontend/.storybook/manager-head.html

@@ -0,0 +1,6 @@
+<style>
+  .sidebar-header img {
+    max-width: 28px;
+    max-height: 28px;
+  }
+</style>

frontend/.storybook/manager.js

@@ -0,0 +1,44 @@
+import { addons } from 'storybook/manager-api'
+import { create } from 'storybook/theming'
+
+// Primitive palette — mirrors _primitives.scss
+// Storybook manager runs outside the app, so CSS vars aren't available.
+const slate = {
+  200: '#e0e3e9',
+  300: '#9da4ae',
+  850: '#161d30',
+  900: '#15192b',
+}
+const purple = { 600: '#6837fc' }
+
+addons.setConfig({
+  theme: create({
+    base: 'dark',
+    brandTitle: 'Flagsmith',
+    brandUrl: 'https://flagsmith.com',
+    brandImage: '/static/images/nav-logo.png',
+    brandTarget: '_blank',
+
+    // Sidebar
+    appBg: slate[900],
+    appContentBg: slate[850],
+    appBorderColor: 'rgba(255, 255, 255, 0.1)',
+
+    // Typography
+    fontBase: '"Inter", sans-serif',
+
+    // Toolbar
+    barBg: slate[900],
+    barTextColor: slate[300],
+    barSelectedColor: purple[600],
+
+    // Colours
+    colorPrimary: purple[600],
+    colorSecondary: purple[600],
+
+    // Text
+    textColor: slate[200],
+    textMutedColor: slate[300],
+    textInverseColor: slate[900],
+  }),
+})

frontend/.storybook/preview.js

@@ -0,0 +1,47 @@
+import '../web/styles/styles.scss'
+
+/** @type { import('storybook').Preview } */
+const preview = {
+  globalTypes: {
+    theme: {
+      description: 'Dark mode toggle',
+      toolbar: {
+        title: 'Theme',
+        icon: 'moon',
+        items: [
+          { value: 'light', title: 'Light', icon: 'sun' },
+          { value: 'dark', title: 'Dark', icon: 'moon' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  initialGlobals: {
+    theme: 'light',
+  },
+  decorators: [
+    (Story, context) => {
+      const theme = context.globals.theme || 'light'
+      const isDark = theme === 'dark'
+
+      document.documentElement.setAttribute(
+        'data-bs-theme',
+        isDark ? 'dark' : 'light',
+      )
+      document.body.classList.toggle('dark', isDark)
+
+      return Story()
+    },
+  ],
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    backgrounds: { disable: true },
+  },
+}
+
+export default preview

frontend/documentation/CategoricalPalette.stories.tsx

@@ -0,0 +1,152 @@
+import React from 'react'
+import type { Meta, StoryObj } from 'storybook'
+
+import './docs.scss'
+import DocPage from './components/DocPage'
+import Swatch from './components/Swatch'
+
+// ---------------------------------------------------------------------------
+// Colour data — inlined to avoid importing Constants (which pulls in the
+// full app dependency tree and breaks Storybook's ESM context).
+// Source of truth: common/constants.ts
+// ---------------------------------------------------------------------------
+
+const TAG_COLOURS = [
+  { hex: '#3d4db6', name: 'Indigo' },
+  { hex: '#ea5a45', name: 'Coral' },
+  { hex: '#c6b215', name: 'Gold' },
+  { hex: '#60bd4e', name: 'Green' },
+  { hex: '#fe5505', name: 'Orange' },
+  { hex: '#1492f4', name: 'Blue' },
+  { hex: '#14c0f4', name: 'Cyan' },
+  { hex: '#c277e0', name: 'Lavender' },
+  { hex: '#039587', name: 'Teal' },
+  { hex: '#344562', name: 'Navy' },
+  { hex: '#ffa500', name: 'Amber' },
+  { hex: '#3cb371', name: 'Mint' },
+  { hex: '#d3d3d3', name: 'Silver' },
+  { hex: '#5D6D7E', name: 'Slate' },
+  { hex: '#641E16', name: 'Maroon' },
+  { hex: '#5B2C6F', name: 'Plum' },
+  { hex: '#D35400', name: 'Burnt Orange' },
+  { hex: '#F08080', name: 'Salmon' },
+  { hex: '#AAC200', name: 'Lime' },
+  { hex: '#DE3163', name: 'Cerise' },
+]
+
+const DEFAULT_TAG_COLOUR = '#dedede'
+
+const PROJECT_COLOURS = [
+  '#906AF6',
+  '#FAE392',
+  '#42D0EB',
+  '#56CCAD',
+  '#FFBE71',
+  '#F57C78',
+]
+
+const FEATURE_HEALTH = {
+  healthyColor: '#60bd4e',
+  unhealthyColor: '#D35400',
+}
+
+const meta: Meta = {
+  parameters: { layout: 'padded' },
+  title: 'Design System/Categorical Palette',
+}
+export default meta
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const TagColours: StoryObj = {
+  name: 'Tag colours',
+  render: () => (
+    <DocPage
+      title='Tag colours'
+      description={
+        <>
+          20 decorative colours users pick from when creating tags. Will be
+          defined in <code>_categorical.scss</code> as CSS custom properties (
+          <code>--color-tag-1</code> through <code>--color-tag-20</code>).
+          Currently in <code>constants.ts</code> pending migration. These are
+          NOT semantic tokens &mdash; they are categorical identifiers that need
+          to be visually distinct from each other.
+        </>
+      }
+    >
+      <div className='cat-grid'>
+        {TAG_COLOURS.map(({ hex, name }) => (
+          <Swatch key={hex} colour={hex} label={`${name}\n${hex}`} />
+        ))}
+      </div>
+      <p className='cat-note'>
+        Default tag colour: <code>{DEFAULT_TAG_COLOUR}</code>
+      </p>
+    </DocPage>
+  ),
+}
+
+export const ProjectColours: StoryObj = {
+  name: 'Project colours',
+  render: () => (
+    <DocPage
+      title='Project colours'
+      description={
+        <>
+          6 colours assigned by index for project avatar badges. Will be defined
+          in <code>_categorical.scss</code> as <code>--color-project-1</code>{' '}
+          through <code>--color-project-6</code>. Currently in{' '}
+          <code>constants.ts</code> pending migration. Decorative &mdash; not
+          tied to any UI role or theme.
+        </>
+      }
+    >
+      <div className='cat-grid'>
+        {PROJECT_COLOURS.map((colour: string, i: number) => (
+          <Swatch key={colour} colour={colour} label={`[${i}] ${colour}`} />
+        ))}
+      </div>
+    </DocPage>
+  ),
+}
+
+export const FeatureHealthColours: StoryObj = {
+  name: 'Feature health colours',
+  render: () => (
+    <DocPage
+      title='Feature health colours'
+      description={
+        <>
+          Status colours for feature health indicators. Currently hardcoded in{' '}
+          <code>common/constants.ts</code> as{' '}
+          <code>Constants.featureHealth</code>. These should migrate to semantic
+          feedback tokens: <code>var(--color-success-default)</code> and{' '}
+          <code>var(--color-warning-default)</code>.
+        </>
+      }
+    >
+      <div className='cat-health-row'>
+        <div className='cat-health-item'>
+          <Swatch colour={FEATURE_HEALTH.healthyColor} size={32} />
+          <div>
+            <strong>Healthy</strong>
+            <div className='cat-health-item__migration'>
+              Should use <code>var(--color-success-default)</code>
+            </div>
+          </div>
+        </div>
+        <div className='cat-health-item'>
+          <Swatch colour={FEATURE_HEALTH.unhealthyColor} size={32} />
+          <div>
+            <strong>Unhealthy</strong>
+            <div className='cat-health-item__migration'>
+              Should use <code>var(--color-warning-default)</code>
+            </div>
+          </div>
+        </div>
+      </div>
+    </DocPage>
+  ),
+}