Agent Storybook

Storybook Skill

Expert in Storybook for Angular 21+ - component-driven development, visual testing, and living design system documentation.

When to Use This Skill

Use this skill when:

• Creating or updating component stories
• Setting up Storybook for a project
• Creating design system documentation stories
• Visual testing and accessibility testing
• Troubleshooting Storybook issues
• Configuring Storybook addons
• Writing component documentation

Core Principles

Component-Driven Development

• Build components in isolation before integrating into app
• Test all component states and variants
• Document component API (inputs, outputs, methods)
• Use Storybook as the single source of truth for UI components

Story Best Practices

• One story file per component (.stories.ts)
• Export multiple story variants showing different states
• Use descriptive story names (Primary, Disabled, Loading, Error, etc.)
• Include all edge cases and states
• Add accessibility testing to every story

Project Structure

Standard Storybook Setup

apps/frontend/
├── .storybook/
│   ├── main.ts          # Main configuration
│   ├── preview.ts       # Global decorators & parameters
│   └── manager.ts       # UI customization (optional)
├── src/
│   └── app/
│       ├── components/
│       │   └── button/
│       │       ├── button.component.ts
│       │       └── button.stories.ts
│       └── pages/
│           └── home/
│               ├── home.component.ts
│               └── home.stories.ts

Story Naming Convention

Hierarchical Structure

Use / separator for organization:

Components:

• Components/Button - Basic button
• Components/Forms/Input - Nested form input
• Components/Cards/TaskCard - Card components

Pages:

• Pages/Home - Page-level story
• Pages/Auth/Login - Nested page

Design System:

• Design System/Colors - Color palette
• Design System/Typography - Font styles
• Design System/Spacing - Spacing tokens

Examples:

• Examples/Forms/LoginForm - Complete form example
• Examples/Layouts/Dashboard - Layout example

Story Template (Angular 21+ Standalone)

Basic Component Story

import type { Meta, StoryObj } from '@storybook/angular';
import { ButtonComponent } from './button.component';

const meta: Meta<ButtonComponent> = {
  title: 'Components/Button',
  component: ButtonComponent,
  tags: ['autodocs'], // Automatic documentation
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger'],
      description: 'Button visual style',
    },
    size: {
      control: 'select',
      options: ['small', 'medium', 'large'],
    },
    disabled: {
      control: 'boolean',
    },
    loading: {
      control: 'boolean',
    },
  },
};

export default meta;
type Story = StoryObj<ButtonComponent>;

// Primary state
export const Primary: Story = {
  args: {
    label: 'Click me',
    variant: 'primary',
    size: 'medium',
  },
};

// Secondary state
export const Secondary: Story = {
  args: {
    label: 'Click me',
    variant: 'secondary',
  },
};

// Disabled state
export const Disabled: Story = {
  args: {
    label: 'Click me',
    disabled: true,
  },
};

// Loading state
export const Loading: Story = {
  args: {
    label: 'Please wait...',
    loading: true,
  },
};

// All sizes comparison
export const AllSizes: Story = {
  render: (args) => ({
    props: args,
    template: `
      <div style="display: flex; gap: 1rem; align-items: center;">
        <app-button size="small" [label]="label"></app-button>
        <app-button size="medium" [label]="label"></app-button>
        <app-button size="large" [label]="label"></app-button>
      </div>
    `,
  }),
  args: {
    label: 'Click me',
  },
};

Component with Services/Dependencies

import type { Meta, StoryObj } from '@storybook/angular';
import { applicationConfig } from '@storybook/angular';
import { provideHttpClient } from '@angular/common/http';
import { TaskCardComponent } from './task-card.component';

const meta: Meta<TaskCardComponent> = {
  title: 'Components/Cards/TaskCard',
  component: TaskCardComponent,
  tags: ['autodocs'],
  decorators: [
    applicationConfig({
      providers: [
        provideHttpClient(),
        // Add other providers here
      ],
    }),
  ],
};

export default meta;
type Story = StoryObj<TaskCardComponent>;

export const Default: Story = {
  args: {
    task: {
      id: '1',
      title: 'Clean bathroom',
      assignee: 'Alex',
      points: 10,
      completed: false,
    },
  },
};

export const Completed: Story = {
  args: {
    task: {
      id: '2',
      title: 'Take out trash',
      assignee: 'Sarah',
      points: 5,
      completed: true,
    },
  },
};

Complex Layout Story

import type { Meta, StoryObj } from '@storybook/angular';
import { HomeComponent } from './home.component';
import { TaskCardComponent } from '../../components/task-card/task-card.component';
import { StatCardComponent } from '../../components/stat-card/stat-card.component';

const meta: Meta<HomeComponent> = {
  title: 'Pages/Home',
  component: HomeComponent,
  tags: ['autodocs'],
  parameters: {
    layout: 'fullscreen', // Use full viewport
  },
  decorators: [
    applicationConfig({
      providers: [
        /* ... */
      ],
    }),
  ],
};

export default meta;
type Story = StoryObj<HomeComponent>;

export const Default: Story = {};

export const WithManyTasks: Story = {
  args: {
    tasks: [
      { id: '1', title: 'Task 1' /* ... */ },
      { id: '2', title: 'Task 2' /* ... */ },
      { id: '3', title: 'Task 3' /* ... */ },
    ],
  },
};

export const EmptyState: Story = {
  args: {
    tasks: [],
  },
};

Modal Component Story

CRITICAL: All modal components MUST have Storybook stories.

Modals require special testing because they have multiple interaction points (backdrop, ESC key, close button) that can fail silently.

import type { Meta, StoryObj } from '@storybook/angular';
import { signal } from '@angular/core';
import { AddChildModal } from './add-child-modal';

const meta: Meta<AddChildModal> = {
  title: 'Components/Modals/AddChildModal',
  component: AddChildModal,
  tags: ['autodocs'],
  argTypes: {
    open: { control: 'boolean' },
  },
  // Decorators for modal positioning
  decorators: [
    (story) => ({
      template: `
        <div style="min-height: 600px; position: relative;">
          <story />
        </div>
      `,
    }),
  ],
};

export default meta;
type Story = StoryObj<AddChildModal>;

// Default: Modal open
export const Default: Story = {
  args: {
    open: true,
  },
};

// Closed state
export const Closed: Story = {
  args: {
    open: false,
  },
  parameters: {
    docs: {
      description: {
        story: 'Modal in closed state (not visible)',
      },
    },
  },
};

// With validation errors
export const WithValidationErrors: Story = {
  args: {
    open: true,
  },
  play: async ({ canvasElement }) => {
    // Simulate invalid form state for visual testing
    const canvas = within(canvasElement);
    const submitButton = await canvas.findByRole('button', { name: /add child/i });
    await userEvent.click(submitButton);
    // Form validation errors should now be visible
  },
};

Modal Story Testing Checklist:

Test these interactions in Storybook:

• Open/Close: Toggle open control
• Close Button: Click X button
• Backdrop Click: Click outside modal
• ESC Key: Press Escape
• Form Validation: Submit empty form
• Loading State: Test submitting state
• Error State: Test error messages
• Accessibility: No violations in a11y addon

Common Modal Story Mistakes:

❌ Wrong: No Storybook story (bugs discovered in production) ✅ Correct: Story created BEFORE integrating into app

❌ Wrong: Only testing open state ✅ Correct: Testing open, closed, loading, error states

❌ Wrong: Not testing close interactions ✅ Correct: Manually test X button, backdrop, ESC in Storybook

See .claude/skills/modal-components/SKILL.md for Modal API usage.

Design System Documentation

Color Palette Story

import type { Meta, StoryObj } from '@storybook/angular';

const meta: Meta = {
  title: 'Design System/Colors',
  tags: ['autodocs'],
};

export default meta;

export const Primary: StoryObj = {
  render: () => ({
    template: `
      <div style="display: grid; gap: 1rem;">
        <div style="display: flex; align-items: center; gap: 1rem;">
          <div style="width: 100px; height: 100px; background: var(--color-primary); border-radius: 8px;"></div>
          <div>
            <h3>Primary</h3>
            <p>--color-primary: #6366F1</p>
          </div>
        </div>
        <div style="display: flex; align-items: center; gap: 1rem;">
          <div style="width: 100px; height: 100px; background: var(--color-secondary); border-radius: 8px;"></div>
          <div>
            <h3>Secondary</h3>
            <p>--color-secondary: #EC4899</p>
          </div>
        </div>
        <!-- Add more colors -->
      </div>
    `,
  }),
};

export const AllColors: StoryObj = {
  render: () => ({
    template: `
      <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 1rem;">
        <div style="background: var(--color-primary); padding: 2rem; border-radius: 8px; color: white;">
          <div style="font-weight: bold;">Primary</div>
          <div style="font-size: 0.875rem;">#6366F1</div>
        </div>
        <div style="background: var(--color-secondary); padding: 2rem; border-radius: 8px; color: white;">
          <div style="font-weight: bold;">Secondary</div>
          <div style="font-size: 0.875rem;">#EC4899</div>
        </div>
        <!-- Add all design system colors -->
      </div>
    `,
  }),
};

Typography Story

export const Typography: StoryObj = {
  render: () => ({
    template: `
      <div style="font-family: var(--font-body);">
        <h1 style="font-family: var(--font-heading); font-size: 48px; font-weight: 700;">
          Heading 1 - Fredoka
        </h1>
        <h2 style="font-family: var(--font-heading); font-size: 36px; font-weight: 600;">
          Heading 2 - Fredoka
        </h2>
        <p style="font-size: 16px;">
          Body text - Outfit Regular
        </p>
        <p style="font-size: 16px; font-weight: 600;">
          Body text - Outfit Semibold
        </p>
      </div>
    `,
  }),
};

Storybook Configuration

Main Configuration (main.ts)

import type { StorybookConfig } from '@storybook/angular';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions',
    '@storybook/addon-links',
  ],
  framework: {
    name: '@storybook/angular',
    options: {},
  },
  docs: {
    autodocs: 'tag', // Generate docs for components with 'autodocs' tag
  },
};

export default config;

Preview Configuration (preview.ts)

import type { Preview } from '@storybook/angular';
import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';

setCompodocJson(docJson);

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#F8F9FF' },
        { name: 'dark', value: '#1E293B' },
        { name: 'white', value: '#FFFFFF' },
      ],
    },
    viewport: {
      viewports: {
        mobile: {
          name: 'Mobile',
          styles: { width: '375px', height: '667px' },
          type: 'mobile',
        },
        tablet: {
          name: 'Tablet',
          styles: { width: '768px', height: '1024px' },
          type: 'tablet',
        },
        desktop: {
          name: 'Desktop',
          styles: { width: '1440px', height: '900px' },
          type: 'desktop',
        },
      },
    },
  },
};

export default preview;

Essential Addons

@storybook/addon-essentials

Includes: Controls, Actions, Viewport, Backgrounds, Toolbars, Measure, Outline

Usage:

• Controls - Interactive component props
• Actions - Log component events (@Output)
• Viewport - Test responsive behavior
• Backgrounds - Test on different backgrounds

@storybook/addon-a11y

Accessibility testing with axe-core

Usage:

export const MyComponent: Story = {
  parameters: {
    a11y: {
      config: {
        rules: [
          {
            id: 'color-contrast',
            enabled: true,
          },
        ],
      },
    },
  },
};

Check for:

• Color contrast (WCAG AA: 4.5:1 for text, 3:1 for UI)
• ARIA labels
• Keyboard navigation
• Focus indicators
• Semantic HTML

@storybook/addon-interactions

Test user interactions

import { within, userEvent } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

export const ClickButton: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');

    await userEvent.click(button);
    await expect(button).toHaveClass('clicked');
  },
};

Component Development Workflow

Step 1: Create Component

# Generate component
cd apps/frontend
ng generate component components/button --standalone

Step 2: Create Story

# Create story file
touch src/app/components/button/button.stories.ts

Step 3: Develop in Storybook

# Run Storybook
npm run storybook

# Storybook opens at localhost:6006
# Hot reload automatically updates as you code

Step 4: Test All States

Create stories for:

• Default state
• All variants (primary, secondary, danger, etc.)
• All sizes (small, medium, large)
• Disabled state
• Loading state
• Error state
• Empty state (if applicable)
• With long text / edge cases

Step 5: Accessibility Check

• Use a11y addon (bottom panel)
• Check all violations
• Fix color contrast issues
• Add ARIA labels
• Test keyboard navigation

Step 6: Visual Review

• Test on all viewports (mobile, tablet, desktop)
• Test on all backgrounds (light, dark, white)
• Check hover states
• Check focus states
• Check animations

Step 7: Integration

Once component is complete in Storybook:

• Import into parent component
• Use in actual app
• E2E test in real context

Common Commands

Development

# Start Storybook dev server
npm run storybook

# Build static Storybook
npm run build-storybook

# Generate Compodoc documentation
npm run storybook:docs

# Run both Compodoc and Storybook
npm run storybook:docs && npm run storybook

Story Creation

# Create new story file
touch src/app/components/my-component/my-component.stories.ts

# Follow naming convention: {component-name}.stories.ts

Troubleshooting

Issue: Component not rendering

Solution:

• Check that component is standalone or imported in moduleMetadata
• Check that all dependencies are provided (services, HTTP client)
• Check console for errors

Issue: Styles not loading

Solution:

• Import global styles in preview.ts
• Check component styleUrls path
• Ensure CSS variables are defined

Issue: Compodoc failing

Solution:

# Regenerate documentation
npm run storybook:docs

# Check for TypeScript errors
npm run type-check

Issue: Hot reload not working

Solution:

• Restart Storybook
• Clear browser cache
• Check for conflicting ports

Best Practices Checklist

Every Component Story Should Have:

• Multiple story variants (Default, Disabled, Loading, etc.)
• All input combinations tested
• Accessibility testing enabled (a11y addon)
• Proper argTypes with descriptions
• Tags: ['autodocs'] for automatic documentation
• JSDoc comments on @Input() and @Output()

Every Design System Story Should Have:

• Visual representation
• Code examples
• Usage guidelines
• Do's and Don'ts (optional)

Story Organization:

• Hierarchical naming (Components/, Pages/, Design System/)
• Alphabetical ordering within categories
• Consistent naming convention

Integration with CI/CD

Build Storybook in CI

# GitHub Actions example
- name: Build Storybook
  run: |
    cd apps/frontend
    npm run storybook:docs
    npm run build-storybook

Deploy Storybook

# Build static version
npm run build-storybook

# Deploy to static hosting (Netlify, Vercel, GitHub Pages)
# Output directory: storybook-static/

Visual Regression Testing

Consider adding:

• Chromatic (visual testing platform)
• Percy (visual review)
• Storybook test runner

Success Criteria

After implementing this skill:

• ✅ All components have corresponding stories
• ✅ Design system fully documented
• ✅ Accessibility testing on every component
• ✅ Visual regression testing enabled
• ✅ Developers can create stories in < 5 minutes
• ✅ Storybook deployed for team collaboration

References

Official Documentation

• Storybook for Angular
• Writing Stories
• Essential Addons
• Accessibility Addon

Angular-Specific

• Angular Standalone Components
• Angular Signals
• Angular OnPush Change Detection

Related Skills

Use together with:

• frontend skill - Angular 21+ component development
• frontend-design skill - UI design principles
• ux-design skill - User experience patterns