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.

Overview

📚 Storybook

Develop and test React components in isolation with interactive controls and documentation.

🎨 Chromatic

Automated visual regression testing that catches unintended UI changes before they ship.

♿ Accessibility

Built-in a11y addon for WCAG compliance checking on every component.

🔄 CI Integration

Seamless GitHub Actions integration for automated testing on every PR.

Quick Start

Running Storybook

# Start Storybook development server
npm run storybook

# Opens at http://localhost:6006

Building Static Storybook

storybook-static/

# Build for deployment
npm run build-storybook

Running Chromatic

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

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

Storybook Configuration

Project Structure

Stories are co-located with their components:

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

Path Aliases

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

.storybook/main.ts

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
}

Installed Addons

Addon	Purpose
@storybook/addon-essentials	Docs, controls, actions, viewport, backgrounds
@storybook/addon-interactions	Testing component interactions
@storybook/addon-a11y	Accessibility testing

Writing Stories

Basic Story Structure

TypeScript

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.',
  },
}

Multiple Variants

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.',
  },
}

Render Function

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>
  ),
}

Story Best Practices

Story Naming

Use descriptive story names that reflect the component state being demonstrated. For example: WithLongContent, Disabled, Loading, WithError.

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

Existing Stories

The project includes stories for these components:

Component	File	Stories
Alert	Alert.stories.tsx	Error, Success, Info, LongContent
RoleBadge	RoleBadge.stories.tsx	Member, Volunteer, TeamManager, TeamAdmin, Admin, SuperAdmin, AllRoles

Chromatic Visual Testing

Setup

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

How Chromatic Works

1. Build

Chromatic builds your Storybook and captures screenshots of every story.

2. Compare

Screenshots are compared against baselines to detect visual changes.

3. Review

Changes are flagged for review in the Chromatic dashboard.

4. Approve

Accept intentional changes or flag regressions for fixing.

CI/CD Integration

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

fetch-depth: 0

The fetch-depth: 0 option is required for Chromatic to detect which stories have changed and optimize the build.

Accessibility Testing

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

Features

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

Using the A11y Panel

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

Common A11y Issues

Issue	Solution
Missing alt text	Add alt attribute to images
Low contrast	Adjust color combinations for 4.5:1 ratio
Missing labels	Add aria-label or visible labels
Focus indicators	Ensure visible :focus styles
Heading hierarchy	Use sequential heading levels (h1 → h2 → h3)

Available Scripts

Script	Description
npm run storybook	Start dev server on port 6006
npm run build-storybook	Build static Storybook
npm run chromatic	Run visual regression tests (loads .env, forwards extra flags)

Troubleshooting

Path Alias Errors

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

Component Not Rendering

Note

React components in Storybook cannot use Astro-specific APIs like Astro.locals or content collections. Mock these dependencies or create simplified story versions.

Chromatic Build Failures

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

Missing Stories

Ensure your story files:

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

Best Practices

✅ DO

• 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

• 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

Related Resources

E2E Testing

End-to-end testing with Playwright

Project Documentation

Detailed Storybook guide

Storybook Docs

Official Storybook documentation

Chromatic Docs

Official Chromatic documentation

Summary

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!