用途：把 Storybook 作为组件的可视化事实来源，每个 story 展示一个真实状态，Docs 说明组件契约，而非另写一份平行文档。与设计系统、React 组件工程技能互补。
主要能力：基于 Storybook 8+（保留项目现有 major）与 CSF 3（meta + 具名导出）；使用 Docs/Autodocs 在画布旁生成文档；用 Controls/Args 提供交互式 props；使用项目已有的 a11y、viewport、themes 等 addons。
必要用法：每个公开设计系统组件（或每个被记录的文件夹）一个 stories 文件；覆盖 default、disabled、loading、error、empty 及变体等风险状态；args 需与真实 props 类型对齐，不用假 props；在 preview 中统一放置 theme/router/i18n 的 decorators，避免每个 story 重复样板；title 采用稳定层级（Primitives/、Patterns/、Features/）；优先用 args 而非重复 JSX，仅在需要组合时用 render；用 satisfies Meta<typeof Component> 做 args 类型检查。Docs 中记录用途、何时使用/避免、变体与解剖、无障碍（键盘、roles、必填 labels）、消费的 token、Do/Don't；仅当 autodocs 加 meta description 不够时才用 MDX。
适用场景：编写或审查 stories、记录设计系统、生成组件文档、在 CI 或 UI PR 中运行 a11y 检查、用 viewport 验证移动端与桌面端、用 theme 切换明暗主题。
限制：不要擅自迁移 major 或更换 Vite/Webpack，沿用仓库现有配置；不记录未导出的内部组件为公开 API；避免依赖真实网络的 stories，在边界处 mock 数据；视觉回归（如 Chromatic）仅在项目已使用时采用，且 stories 需稳定、不含时间或随机值。反模式包括 KitchenSink 式单 story、文档与 props 脱节、用 README 截图代替 stories、忽略 disabled/loading/error 状态、args 与 TypeScript API 不符。完成标准：被改动组件有类型化 CSF stories、主要状态可由 controls 导航、有 autodocs 或 MDX 说明用途与边界、theme/a11y/viewport 与项目 preview 一致、props 与文档无明显漂移。