Samsen Internal Framework

This is Samsen's internal framework content for Toolchain. It is read-only reference material.

Storybook Integration

Role in the Workflow

Storybook serves as the visual development and testing environment for design system components. In the Samsen workflow, it provides:

• Component isolation — View and interact with components outside the full application context
• Visual regression testing — Catch unintended visual changes before they ship
• Documentation — Living documentation that's always in sync with the code
• Figma bridge — Connect Figma designs to their code implementations

Component Story Format (CSF3)

Storybook's current standard format (CSF3) defines stories as objects:

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

const meta: Meta<typeof Button> = {
  component: Button,
  tags: ['autodocs'],
};

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

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

export const Compact: Story = {
  args: {
    variant: 'primary',
    label: 'Click me',
    size: 'compact',
  },
};

CSF3 benefits for AI-assisted workflows:

• Declarative — Stories are data objects, not imperative rendering code. Easy for AI to generate.
• Type-safe — TypeScript integration ensures stories match component props.
• Autodocs — The autodocs tag generates documentation automatically from stories and prop types.

Visual Regression Testing with Chromatic

Chromatic (by the Storybook team) provides cloud-based visual regression testing:

1. Every PR generates screenshots of all stories
2. Screenshots are compared pixel-by-pixel against the baseline
3. Visual differences are flagged for review
4. Approved changes become the new baseline

This is critical for AI-assisted design because:

• AI-generated component changes can be visually validated automatically
• Designers review visual diffs, not code diffs
• Unintended side effects (a token change that affects 20 components) are caught immediately
• The review workflow aligns with how designers naturally evaluate work — visually

Figma ↔ Storybook Integration

Storybook Connect (Figma Plugin)

Links Figma components to their Storybook stories:

• View the live Storybook story directly in Figma's sidebar
• Navigate from a Figma component to its code implementation
• Verify that the Figma design and code implementation match

Design Tokens Integration

When design tokens flow from Figma → code → Storybook:

1. Figma Variables define the tokens
2. Code consumes tokens as CSS custom properties
3. Storybook renders components with those tokens
4. Changes to tokens in Figma propagate through to Storybook stories

This creates a visual feedback loop: change a token in Figma, see the effect in Storybook.

Storybook and Claude Code

Claude Code can interact with Storybook in several ways:

Generating Stories

"Create Storybook stories for the Card component. Include stories for: default, compact, with image, without image, loading state, and error state."

Claude Code reads the component file, understands its props, and generates appropriate stories with CSF3 format.

Visual Review Workflow

1. Claude Code creates/modifies a component
2. Storybook renders the updated stories
3. Designer reviews in Storybook (or via Chromatic's visual diff)
4. Designer provides feedback: "The compact variant's padding is too tight"
5. Claude Code adjusts
6. Repeat until approved

Testing Integration

"Run the Storybook visual regression tests and tell me if anything changed unexpectedly."

Claude Code can run Chromatic or Percy tests and report results, helping designers catch unintended visual side effects.

MCP and Storybook (Emerging)

The integration between MCP servers and Storybook is an emerging capability area:

• MCP servers could expose Storybook story data to AI tools
• AI could generate stories from Figma components via Figma Console MCP → Storybook
• Visual test results from Chromatic could be fed back through MCP to inform AI iterations

This is an area of active development in the Samsen toolchain.

Implementation Best Practices

• Story per variant — Each meaningful variant gets its own story. AI can generate these systematically.
• Colocate stories — Keep component.stories.tsx next to component.tsx. Makes AI context loading easier.
• Use args over template manipulation — CSF3's args-based approach is cleaner and more AI-friendly.
• Include edge cases — Empty states, long text overflow, error states. These are easy to miss but important to test.
• Document with stories, not prose — A story showing the compact variant is better documentation than a paragraph describing it.

See: ../../research/storybook-guide.md