storybook（Storybook 组件文档）

Storybook

Commands

Default action: When asked to "run Storybook" or "open Storybook" without further qualification, run pnpm storybook:start.

Commands may vary — always check package.json scripts to confirm what pnpm storybook:start actually invokes before running.

Before writing stories — explore the project first

Before creating or modifying stories, read the Storybook configuration to understand:

• Which addons are active in .storybook/main.ts
• How the Angular preview is configured in .storybook/preview.ts — understand which global providers, decorators, and imports are available to all stories without explicit declaration
• The glob pattern for story discovery (e.g. src/**/*.stories.ts) — new story files must match this pattern to be picked up by Storybook
• Whether a custom theme or decorator is applied globally — match the existing decorator style when writing new stories

Also explore the component under test to understand its input() signals (or @Input() bindings), output events, required providers, and any Angular CDK dependencies before writing the story.

Story format

All stories use Component Story Format 3 (CSF3) with Angular-specific meta configuration.

• Use title to place the component in the correct sidebar category — follow the existing naming hierarchy used by other stories in the project
• Provide meaningful args defaults in meta so every story starts with a usable state
• Each named export is a separate story — name exports descriptively (e.g. Disabled, WithError, Loading, Empty)
• Prefer args over hardcoded render templates unless the variation cannot be expressed through inputs alone

Standalone component requirements

All Angular components should be standalone. When writing stories, do not use NgModule declarations — import the component directly via the component field in meta. If the component depends on other standalone components, directives, or pipes that are not already declared in its own imports array, supply them via moduleMetadata in the story:

const meta: Meta<MyComponent> = {
    component: MyComponent,
    decorators: [
        moduleMetadata({
            imports: [IconComponent],
        }),
    ],
};

Workflow notes

• Run pnpm storybook:start and visually verify new stories in the browser before committing
• Cover key visual states in separate named stories (e.g. Disabled, Loading, Error) rather than relying on controls alone
• Run pnpm storybook:build to confirm the static build succeeds before merging — build failures can hide story configuration errors that the dev server silently tolerates
• Run pnpm lint after writing stories — eslint-plugin-storybook enforces story file conventions