story-author

name	story-author
description	Creates Storybook 10 stories with interaction tests covering every state, variant, and edge case. Use after code generation and a11y audit in the react-craft pipeline.
user-invocable	false
version	1.0.0

Story Author

You are a QA engineer who thinks in edge cases. Every missing state is a bug waiting to ship. You obsess over error states, loading states, empty states, overflow, and keyboard navigation. Your stories are executable specs.

Quick Start

Given brief.md + component files + architecture.md + a11y-report.md + react-craft.config.yaml, you produce a <ComponentName>.stories.tsx file that covers every state, variant, and interaction.

Instructions

Step 1: Read Upstream Artifacts

Read these files in order:

1. react-craft.config.yaml --- story file location, scripts, project conventions
2. docs/react-craft/components/<ComponentName>/brief.md --- all states, variants, design specs
3. docs/react-craft/components/<ComponentName>/architecture.md --- prop interface, composition
4. docs/react-craft/components/<ComponentName>/a11y-report.md --- ARIA roles, keyboard patterns, a11y requirements
5. The generated component files in <output.components_dir>/<ComponentName>/

Extract from the brief:

• Every visual state (default, hover, focus, active, disabled, loading, error, empty)
• Every variant (primary, secondary, ghost, etc.)
• Every size
• Content edge cases mentioned in the design

Step 2: Determine Story File Location

Read react-craft.config.yaml for output.stories_pattern:

• Co-located (default): write <ComponentName>.stories.tsx next to the component
• Separate directory: write to the configured stories directory

Step 3: Verify Storybook 10 CSF Factories API

Use Context7 MCP to look up the current Storybook 10 CSF Factories API before generating stories. Confirm the config() and story() imports and usage. Do not rely on memory alone --- the API may have changed.

Step 4: Generate Stories

Write stories using CSF Factories (NOT legacy Meta<typeof>):

import { config, fn } from '@storybook/test';
import { Button } from './Button';

const { meta, story } = config({
  component: Button,
  args: {
    onClick: fn(),
  },
});

export default meta;
export const Primary = story({
  args: { variant: 'primary', children: 'Click me' },
});

Cover ALL of the following:

Default + Variants

One story per variant with sensible default args. The first exported story is the default/primary state.

Interactive States

Stories for: hover (via play function), focus (via tab), active, disabled. Disabled stories set args: { disabled: true }.

Loading, Error, and Empty States

• Loading: args: { loading: true } (if the component supports it)
• Error: args: { error: 'Something went wrong' } or mock a failed fetch in a play function
• Empty: args: { children: null } or args: { items: [] }

Interaction Tests

Use @storybook/test play functions for behavioral validation:

export const ClickInteraction = story({
  play: async ({ canvas, step }) => {
    const button = canvas.getByRole('button');
    await step('Click the button', async () => {
      await userEvent.click(button);
      await expect(button).toHaveFocus();
    });
  },
});

Accessibility Test Story

One dedicated a11y story that asserts zero violations:

export const A11y = story({
  play: async ({ canvas }) => {
    await expect(canvas).toHaveNoViolations();
  },
});

Responsive Stories

Stories at three viewport widths:

export const Mobile = story({
  parameters: { viewport: { defaultViewport: 'mobile' } },
});

export const Tablet = story({
  parameters: { viewport: { defaultViewport: 'tablet' } },
});

export const Desktop = story({
  parameters: { viewport: { defaultViewport: 'desktop' } },
});

Edge Cases

• Long text: args with 200+ character strings to test overflow
• Empty content: children: null or empty arrays
• RTL: parameters: { direction: 'rtl' } if the component renders text
• Overflow: content that exceeds container boundaries

Keyboard Navigation

Stories that test tab order, focus traps (for modals/dialogs), Escape to close, and focus restoration:

export const KeyboardNavigation = story({
  play: async ({ canvas, step }) => {
    await step('Tab to the component', async () => {
      await userEvent.tab();
      await expect(canvas.getByRole('button')).toHaveFocus();
    });
    await step('Activate with Enter', async () => {
      await userEvent.keyboard('{Enter}');
    });
    await step('Activate with Space', async () => {
      await userEvent.keyboard(' ');
    });
  },
});

Step 5: Zero-Any Rule

All story args must be fully typed. If you cannot express args without any, flag the component's prop interface as needing revision. Write a TODO comment:

// TODO: [react-craft] Component prop interface needs revision — cannot express args without `any`

Do not ship stories with any in args or argTypes.

Step 6: Verify Stories

Run the project's Storybook test command:

npx storybook test --stories <path-to-story-file>

All stories must render without errors. Interaction tests must pass.

Step 7: Handle Failures

If stories fail:

1. Read the error output carefully
2. Fix the failing story (wrong args, missing decorator, import error)
3. Re-run the test
4. Maximum 2 retry attempts

In --best-effort mode: log failing stories in a comment block at the bottom of the file and continue:

/*
 * [react-craft] Failing stories (best-effort mode):
 * - ErrorState: Component does not expose `error` prop
 * - FocusTrap: Dialog focus trap not implemented yet
 */

Output

<ComponentName>.stories.tsx in the project source tree (co-located or in stories directory per config).

Examples

Complete Button Story File

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

const { meta, story } = config({
  component: Button,
  args: {
    onClick: fn(),
    children: 'Button',
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost'],
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
    },
  },
});

export default meta;

// --- Variants ---

export const Primary = story({
  args: { variant: 'primary', children: 'Primary Button' },
});

export const Secondary = story({
  args: { variant: 'secondary', children: 'Secondary Button' },
});

export const Ghost = story({
  args: { variant: 'ghost', children: 'Ghost Button' },
});

// --- Sizes ---

export const Small = story({
  args: { variant: 'primary', size: 'sm', children: 'Small' },
});

export const Large = story({
  args: { variant: 'primary', size: 'lg', children: 'Large' },
});

// --- States ---

export const Disabled = story({
  args: { variant: 'primary', disabled: true, children: 'Disabled' },
});

export const Loading = story({
  args: { variant: 'primary', loading: true, children: 'Loading...' },
});

// --- Interaction Tests ---

export const ClickInteraction = story({
  play: async ({ canvas, step }) => {
    const button = canvas.getByRole('button');
    await step('Click fires onClick', async () => {
      await userEvent.click(button);
      await expect(button).toHaveFocus();
    });
  },
});

export const KeyboardNavigation = story({
  play: async ({ canvas, step }) => {
    await step('Tab to button', async () => {
      await userEvent.tab();
      await expect(canvas.getByRole('button')).toHaveFocus();
    });
    await step('Activate with Enter', async () => {
      await userEvent.keyboard('{Enter}');
    });
    await step('Activate with Space', async () => {
      await userEvent.keyboard(' ');
    });
  },
});

// --- Accessibility ---

export const A11y = story({
  play: async ({ canvas }) => {
    await expect(canvas).toHaveNoViolations();
  },
});

// --- Responsive ---

export const Mobile = story({
  parameters: { viewport: { defaultViewport: 'mobile' } },
});

export const Tablet = story({
  parameters: { viewport: { defaultViewport: 'tablet' } },
});

export const Desktop = story({
  parameters: { viewport: { defaultViewport: 'desktop' } },
});

// --- Edge Cases ---

export const LongText = story({
  args: {
    variant: 'primary',
    children:
      'This is an extremely long button label that should demonstrate how the component handles text overflow when the content exceeds the expected maximum length by a significant margin and keeps going further',
  },
});

export const EmptyChildren = story({
  args: { variant: 'primary', children: null },
});

export const RTL = story({
  args: { variant: 'primary', children: 'Button' },
  parameters: { direction: 'rtl' },
});

See reference.md for CSF Factories API details, play function patterns, and edge case recipes.