Storybook & Chromatic

The astro-basics project uses Storybook for interactive component development and Chromatic for automated visual regression testing. Together, they provide a complete solution for testing and documenting React components.

# Start Storybook development server
npm run storybook

# Opens at http://localhost:6006

# Build for deployment
npm run build-storybook

# Run visual regression tests (loads .env automatically)
npm run chromatic

# Override token for one-off runs
CHROMATIC_PROJECT_TOKEN=<your-token> npm run chromatic

Stories are co-located with their components:

src/components/react/
├── Alert.tsx
├── Alert.stories.tsx      # Story file
├── RoleBadge.tsx
└── RoleBadge.stories.tsx  # Story file

Storybook is configured to support the project’s # path aliases:

viteFinal: async (config) => {
  config.resolve.alias = {
    '#components': new URL('../src/components', import.meta.url).pathname,
    '#utils': new URL('../src/utils', import.meta.url).pathname,
    '#libs': new URL('../src/libs', import.meta.url).pathname,
    '#types': new URL('../src/types', import.meta.url).pathname,
    '#constants': new URL('../src/constants', import.meta.url).pathname,
  }
  return config
}

import type { Meta, StoryObj } from '@storybook/react'
import Alert from './Alert'

const meta = {
  title: 'Components/Alert',
  component: Alert,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    type: {
      control: { type: 'select' },
      options: ['error', 'success', 'info'],
      description: 'The visual style of the alert',
    },
  },
} satisfies Meta<typeof Alert>

export default meta
type Story = StoryObj<typeof meta>

export const Error: Story = {
  args: {
    type: 'error',
    children: 'This is an error message.',
  },
}

export const Success: Story = {
  args: {
    type: 'success',
    children: 'Operation completed successfully!',
  },
}

export const Info: Story = {
  args: {
    type: 'info',
    children: 'Here is some helpful information.',
  },
}

export const LongContent: Story = {
  args: {
    type: 'info',
    children: 'This is a longer message that demonstrates how the component handles more content.',
  },
}

export const AllVariants: Story = {
  render: () => (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
      <Alert type="error">Error alert</Alert>
      <Alert type="success">Success alert</Alert>
      <Alert type="info">Info alert</Alert>
    </div>
  ),
}

Essential patterns:

1. Use satisfies Meta<typeof Component> for type safety
2. Add tags: ['autodocs'] for automatic documentation
3. Define argTypes for interactive controls
4. Create multiple stories for different states
5. Use layout: 'centered' for most components

The project includes stories for these components:

1. Create a Chromatic account at chromatic.com

2. Link your repository and create a new project

3. Copy your project token from the Chromatic dashboard

4. Add the token to .env (loaded automatically):

   CHROMATIC_PROJECT_TOKEN=<your-token>

5. Run Chromatic (extra flags forwarded):

   npm run chromatic

Add Chromatic to your GitHub Actions workflow:

name: Chromatic

on:
  push:
    branches: [primary]
  pull_request:
    branches: [primary]

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          exitZeroOnChanges: true

The @storybook/addon-a11y addon provides automated accessibility checks:

• WCAG 2.1 Level AA compliance checking
• axe-core powered analysis
• Real-time feedback in Storybook UI
• Violation highlighting on components

1. Open Storybook (npm run storybook)
2. Navigate to any story
3. Click the “Accessibility” tab in the addon panel
4. Review violations, passes, and incomplete checks

If you see errors like Cannot find module '#utils/...':

1. Verify .storybook/main.ts has correct alias configuration
2. Ensure paths match tsconfig.json settings
3. Restart Storybook after config changes

1. Verify CHROMATIC_PROJECT_TOKEN is set
2. Test local build: npm run build-storybook
3. Check for build errors in the output
4. Review Chromatic dashboard for specific failures

Ensure your story files:

• Are named *.stories.tsx or *.stories.ts
• Are located in src/components/react/
• Export a default meta object

• Co-locate stories with components
• Write stories for all variants and states
• Use autodocs for automatic documentation
• Test accessibility before merging
• Review Chromatic changes carefully
• Keep stories simple and focused

// ✅ Good - focused, typed, documented
const meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary'],
    },
  },
} satisfies Meta<typeof Button>

• Don’t skip accessibility checks - Fix violations before merging
• Don’t auto-accept Chromatic changes - Always review visually
• Don’t use Astro APIs in React components for stories
• Don’t forget to update stories when component APIs change

The Storybook and Chromatic setup provides:

• 📚 Interactive development with hot reload and controls
• 🎨 Visual regression testing catching UI changes automatically
• ♿ Accessibility testing ensuring WCAG compliance
• 📝 Auto-generated docs from component props
• 🔄 CI/CD integration for automated testing on PRs

Key Takeaway: Write stories for all component variants, review Chromatic changes before merging, and fix accessibility violations early!