┌─────────────────────────────────────────────────────┐
│  1. Isolation                                       │
│     Develop components outside the consuming app    │
│     → Storybook / Ladle / Histoire                  │
├─────────────────────────────────────────────────────┤
│  2. Hot reload                                      │
│     Change code → see result in under 200ms          │
│     → Vite-backed Storybook, Ladle                  │
├─────────────────────────────────────────────────────┤
│  3. Documentation                                   │
│     Every component has a page with API, examples,  │
│     do/don't, and a live playground                  │
│     → Storybook Docs, Docusaurus, custom MDX        │
├─────────────────────────────────────────────────────┤
│  4. Testing                                         │
│     Unit, visual regression, interaction, a11y      │
│     → Vitest, Chromatic, Testing Library, axe-core  │
├─────────────────────────────────────────────────────┤
│  5. Review                                          │
│     Designer + engineer see the component in a PR   │
│     → Chromatic, Storybook deploys                  │
├─────────────────────────────────────────────────────┤
│  6. Publish                                         │
│     Merge → versioned package on registry           │
│     → Changesets, semantic-release, npm              │
└─────────────────────────────────────────────────────┘

# Initialize in an existing project
npx storybook@latest init

# Or with explicit Vite builder
npx storybook@latest init --builder vite

// src/components/Button/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  tags: ['autodocs'],           // auto-generates docs page
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost'],
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
  },
};
export default meta;

type Story = StoryObj<typeof Button>;

// Each export = one story
export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Click me',
  },
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    children: 'Cancel',
  },
};

export const Loading: Story = {
  args: {
    variant: 'primary',
    children: 'Saving...',
    isLoading: true,
  },
};

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions',
    '@storybook/addon-designs',
  ],
  framework: '@storybook/react-vite',
};
export default config;

// Button.stories.tsx
import { expect, fn, userEvent, within } from '@storybook/test';

export const ClickTest: Story = {
  args: {
    onClick: fn(),       // mock function
    children: 'Submit',
  },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button', { name: /submit/i });

    // Verify initial state
    await expect(button).toBeEnabled();

    // Click and verify
    await userEvent.click(button);
    await expect(args.onClick).toHaveBeenCalledOnce();
  },
};

# Run all interaction tests headlessly
npx test-storybook --ci

# Install
npm i -D chromatic

# Run (typically in CI)
npx chromatic --project-token=<token>

# .github/workflows/chromatic.yml
name: Chromatic
on: pull_request

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0            # Chromatic needs full git history
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          exitOnceUploaded: true     # don't block CI; status check handles it

Developer pushes PR
    │
    ▼
CI runs Chromatic ──► screenshots every story
    │
    ▼
Chromatic diffs against baseline
    │
    ├── No changes ──► ✅ PR check passes
    │
    └── Changes detected ──► 🟡 PR check pending
                                │
                                ▼
                          Designer / reviewer opens Chromatic
                          Reviews visual diffs side-by-side
                                │
                                ├── Accepts ──► ✅ new baseline, PR check passes
                                └── Denies  ──► ❌ developer fixes

{/* src/components/Button/Button.mdx */}
import { Meta, Story, Canvas, Controls, ArgTypes } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button

Buttons trigger actions. Use `variant` to set visual weight.

## Do / Don't

- ✅ Use `primary` for the main action on a page
- ✅ Use `ghost` for tertiary actions
- ❌ Don't put two `primary` buttons side by side
- ❌ Don't use a button when a link is semantically correct

## Playground

<Canvas of={ButtonStories.Primary} />
<Controls of={ButtonStories.Primary} />

## All Variants

<ArgTypes of={ButtonStories} />

docs/
├── getting-started.mdx
├── design-principles.mdx
├── components/
│   ├── button.mdx          ← embeds live Storybook via iframe
│   ├── modal.mdx
│   └── table.mdx
├── tokens/
│   ├── color.mdx
│   └── spacing.mdx
└── migration/
    ├── v2-to-v3.mdx
    └── codemods.mdx

## Live Example

<iframe
  src="https://your-storybook.chromatic.com/?path=/story/button--primary&viewMode=story"
  width="100%"
  height="200"
  style={{ border: 'none' }}
/>

┌──────────────────────────────────────────────────────┐
│  Source (JSON / Figma / Tokens Studio)                │
│                                                      │
│  color.primary.500 = #2563eb                         │
│  spacing.md        = 16                              │
│  font.body.size    = 16                              │
│  shadow.card       = 0 1px 3px rgba(0,0,0,0.12)     │
└──────────────┬───────────────────────────────────────┘
               │  Style Dictionary / token pipeline
               ▼
┌──────────────────────────┐  ┌──────────────────────────┐
│  CSS custom properties   │  │  JS/TS constants          │
│  --color-primary-500     │  │  COLOR_PRIMARY_500        │
│  --spacing-md            │  │  SPACING_MD               │
└──────────────────────────┘  └──────────────────────────┘
┌──────────────────────────┐  ┌──────────────────────────┐
│  iOS (Swift)             │  │  Android (XML/Compose)    │
│  Color.primary500        │  │  colorPrimary500          │
└──────────────────────────┘  └──────────────────────────┘

// tokens/color.json (W3C Design Token format)
{
  "color": {
    "primary": {
      "500": { "$value": "#2563eb", "$type": "color" },
      "600": { "$value": "#1d4ed8", "$type": "color" },
      "700": { "$value": "#1e40af", "$type": "color" }
    },
    "neutral": {
      "100": { "$value": "#f5f5f5", "$type": "color" },
      "900": { "$value": "#171717", "$type": "color" }
    }
  }
}

// style-dictionary.config.mjs
import StyleDictionary from 'style-dictionary';

export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables',
      }],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{
        destination: 'tokens.mjs',
        format: 'javascript/es6',
      }],
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'dist/ios/',
      files: [{
        destination: 'Tokens.swift',
        format: 'ios-swift/class.swift',
        className: 'DesignTokens',
      }],
    },
  },
};

# Generate all platform outputs
npx style-dictionary build

# .github/workflows/tokens.yml
name: Build Tokens
on:
  push:
    paths: ['tokens/**']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx style-dictionary build
      - uses: actions/upload-artifact@v4
        with:
          name: design-tokens
          path: dist/

design-system/
├── packages/
│   ├── tokens/              ← design tokens (published as @acme/tokens)
│   │   ├── tokens/
│   │   ├── style-dictionary.config.mjs
│   │   └── package.json
│   ├── react/               ← React components (published as @acme/ui)
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── vue/                 ← Vue components (published as @acme/ui-vue)
│   │   └── ...
│   └── icons/               ← Icon package (published as @acme/icons)
│       └── ...
├── apps/
│   └── storybook/           ← Storybook app (not published)
├── package.json
├── turbo.json               ← or nx.json
└── .changeset/
    └── config.json

# Developer adds a changeset during PR
npx changeset add

# Prompts:
# Which packages? → @acme/ui
# Bump type? → minor
# Summary? → Add size prop to Avatar component

---
'@acme/ui': minor
---

Add `size` prop to Avatar component. Accepts `sm`, `md`, `lg`.

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - name: Create Release PR or Publish
        uses: changesets/action@v1
        with:
          publish: npm run release    # runs changeset publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

// codemods/rename-variant-prop.js
// Transforms: <Button type="primary" /> → <Button variant="primary" />

export default function transformer(file, api) {
  const j = api.jscodeshift;
  const root = j(file.source);

  root
    .find(j.JSXOpeningElement, { name: { name: 'Button' } })
    .find(j.JSXAttribute, { name: { name: 'type' } })
    .forEach((path) => {
      path.node.name.name = 'variant';
    });

  return root.toSource();
}

# Run across a consuming repo
npx jscodeshift -t codemods/rename-variant-prop.js src/ --extensions=tsx,ts

packages/react/
├── src/
├── codemods/
│   ├── v5-to-v6/
│   │   ├── rename-variant-prop.js
│   │   ├── remove-deprecated-icons.js
│   │   └── __tests__/
│   └── v4-to-v5/
│       └── ...
└── package.json

┌─────────────────────────────────────────────┐
│  Visual regression (Chromatic / Percy)       │  ← catches pixel-level regressions
│  Run per PR; screenshots every story         │
├─────────────────────────────────────────────┤
│  Interaction tests (Storybook play functions)│  ← tests behavior in real browser
│  Click, type, assert — visible in Storybook  │
├─────────────────────────────────────────────┤
│  Accessibility (axe-core + Storybook a11y)   │  ← WCAG violations caught automatically
│  Run per story; fail CI on violations        │
├─────────────────────────────────────────────┤
│  Unit tests (Vitest + Testing Library)       │  ← logic, state, edge cases
│  Fast; run on every change                   │
└─────────────────────────────────────────────┘

// Button.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button } from './Button';

test('calls onClick when clicked', async () => {
  const onClick = vi.fn();
  render(<Button onClick={onClick}>Submit</Button>);

  await userEvent.click(screen.getByRole('button', { name: /submit/i }));
  expect(onClick).toHaveBeenCalledOnce();
});

test('renders as disabled when isLoading', () => {
  render(<Button isLoading>Save</Button>);
  expect(screen.getByRole('button')).toBeDisabled();
});

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('Button has no a11y violations', async () => {
  const { container } = render(<Button>Click</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

// .storybook/test-runner.ts
import { checkA11y, injectAxe } from 'axe-playwright';

export default {
  async preVisit(page) {
    await injectAxe(page);
  },
  async postVisit(page) {
    await checkA11y(page, '#storybook-root', {
      detailedReport: true,
      detailedReportOptions: { html: true },
    });
  },
};

npx test-storybook --ci   # now fails if any story has a11y violations

// eslint-plugin-design-system/rules/no-hardcoded-colors.js
module.exports = {
  meta: {
    type: 'suggestion',
    messages: {
      hardcodedColor: 'Use a design token instead of hard-coded color "{{value}}".',
    },
  },
  create(context) {
    return {
      Property(node) {
        if (
          ['color', 'backgroundColor', 'borderColor'].includes(node.key.name) &&
          node.value.type === 'Literal' &&
          /^#[0-9a-f]{3,8}$/i.test(node.value.value)
        ) {
          context.report({
            node,
            messageId: 'hardcodedColor',
            data: { value: node.value.value },
          });
        }
      },
    };
  },
};

// Base Web Component
import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('ds-button')
export class DsButton extends LitElement {
  @property() variant: 'primary' | 'secondary' = 'primary';
  @property({ type: Boolean }) disabled = false;

  static styles = css`
    :host { display: inline-block; }
    button { /* uses design tokens via CSS custom properties */ }
  `;

  render() {
    return html`
      <button class=${this.variant} ?disabled=${this.disabled}>
        <slot></slot>
      </button>
    `;
  }
}

// React wrapper (auto-generated or manual)
import { createComponent } from '@lit/react';
import { DsButton as DsButtonWC } from '@acme/web-components';

export const Button = createComponent({
  tagName: 'ds-button',
  elementClass: DsButtonWC,
  react: React,
  events: { onClick: 'click' },
});

# .github/workflows/ci.yml
name: Design System CI
on: pull_request

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint
      - run: npm run test              # unit tests (Vitest)
      - run: npm run test:storybook    # interaction tests

  visual-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx storybook build --quiet
      - run: |
          npx concurrently -k -s first -n "SB,TEST" \
            "npx http-server storybook-static -p 6006 --silent" \
            "npx wait-on tcp:6006 && npx test-storybook --ci"

  tokens:
    runs-on: ubuntu-latest
    if: contains(github.event.pull_request.changed_files, 'tokens/')
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx style-dictionary build
      - run: npm run test:tokens       # validate generated output

✅  Lint & Test         — passed
✅  Chromatic           — 3 visual changes accepted by reviewer
✅  Accessibility       — 0 violations
✅  Tokens Build        — skipped (no token changes)