git:20260607.5e55862 to git:20260611.9d7f5e4

19 added, 19 removed. Audit A to A.

---

name: fec-storybook-component-doc

- description: Use when setting up or reviewing Storybook component documentation, design-system presentation, isolated component state previews, stories, addons, decorators, MDX docs, component-state interaction checks, visual baselines, or Chromatic. For real-browser cross-page journeys or broader coverage planning, choose the matching testing workflow first; Chinese triggers include Storybook, 组件文档, Design System, 视觉回归.

+ description: Use when setting up or reviewing Storybook component documentation, design-system presentation, isolated component state previews, stories, addons, decorators, MDX docs, component-state interaction checks, visual baselines, or Chromatic. For real-browser cross-page journeys or broader coverage planning, choose the matching testing workflow first; Chinese triggers include Storybook, component documentation, Design System, visual regression.

---

- # Storybook 组件文档化

+ # Storybook component documentation

## Purpose

- 为 UI 组件建立文档化、设计系统展示和隔离状态预览环境；交互与视觉测试只覆盖 Storybook 场景内的组件状态。

+ Establish documentation, design system display and isolated state preview environment for UI components; interaction and visual testing only cover component states within the Storybook scene.

## Procedure

- 1. 初始化或识别现有 Storybook 配置，沿用项目框架适配器、stories glob、主题和构建命令。

- 2. 每个组件的 Story 覆盖默认态、主要变体、尺寸、语义 tone、disabled、loading、error、empty、selected、invalid 和关键边缘状态。

- 3. 依赖 Router、Store、i18n、ThemeProvider 的组件用 decorators 包裹，不在 Story 中复制应用入口。

- 4. 复杂组件用 MDX 补充使用说明、Props、slots/children、variant 矩阵、状态示例、可访问性要求和源码展示。

- 5. 需要自动化时接入 interaction tests、addon-a11y、Chromatic 或 Storybook Test Runner；这些能力服务于组件文档和设计系统展示，不承接跨页业务旅程。

- 6. 设计系统组件应记录 token 来源、Tailwind/class 变体、暗色模式、响应式尺寸和不支持的组合，避免消费者靠猜测拼装。

+ 1. Initialize or identify an existing Storybook configuration, inheriting the project framework adapter, stories globs, themes, and build commands.

+ 2. Each component's Story covers default state, main variant, size, semantic tone, disabled, loading, error, empty, selected, invalid and key edge states.

+ 3. Components that rely on Router, Store, i18n, and ThemeProvider are wrapped with decorators and do not copy the application entry in Story.

+ 4. Use MDX to supplement complex components with usage instructions, Props, slots/children, variant matrices, status examples, accessibility requirements and source code display.

+ 5. When automation is required, connect interaction tests, addon-a11y, Chromatic or Storybook Test Runner; these capabilities serve component documentation and design system display and do not undertake cross-page business journeys.

+ 6. Design system components should record token sources, Tailwind/class variants, dark modes, responsive sizes, and unsupported combinations to avoid consumers guessing at assembly.

- ## 详细参考

+ ## Detailed reference

- - 需要 `main.ts`、`preview.ts`、stories、decorators、MDX、交互测试和视觉回归示例时，加载 [references/story-patterns.md](references/story-patterns.md)。

+ - Load [references/story-patterns.md](references/story-patterns.md) when you need `main.ts`, `preview.ts`, stories, decorators, MDX, interaction tests and visual regression examples.

## Constraints

- - Story 需随组件 prop 变更同步更新。

- - Provider 依赖必须通过 decorator 补齐。

- - Storybook 构建产物 `storybook-static/` 不应提交到 Git。

- - Storybook 用于开发和组件文档，不替代生产页面 SEO。

- - Storybook 视觉基线用于组件状态；跨页面截图和真实路由流程分流到 E2E workflow。

- - 大型组件库需控制 stories glob 和 addon 开销。

- - 不用 Storybook 隐藏组件 API 问题；若变体组合爆炸，应先收敛组件职责或拆分组件。

+ - Story needs to be updated synchronously with component prop changes.

+ - Provider dependencies must be completed through decorators.

+ - Storybook build product `storybook-static/` should not be committed to Git.

+ - Storybook is used for development and component documentation and is not a replacement for production page SEO.

+ - Storybook visual baseline for component state; cross-page screenshots and real routing processes are offloaded to E2E workflow.

+ - Large component libraries need to control stories glob and addon overhead.

+ - Don’t use Storybook to hide component API issues; if variant combinations explode, you should first converge component responsibilities or split components.

## Expected Output

- 可交互的组件文档和设计系统展示站点，每个组件状态都有隔离预览，Props 表格可生成，关键 Storybook 场景有可选 play 测试或视觉回归基线。

+ Interactive component documentation and design system showcase site with isolated previews of each component state, Props tables to generate, and key Storybook scenes with optional play testing or visual regression baselines.