sb-setup

sb-setup — 原生优先安装

此技能是一个轻量的 对齐 + 验证 层，不会重新实现引导向导。

引导 — 交由 Storybook 处理

test -d .storybook && grep -q '"storybook"' package.json 2>/dev/null && echo PRESENT || echo NO_STORYBOOK
# NO_STORYBOOK → defer to Storybook's OWN official onboarding. `storybook` is the official npm
# package (@storybook/cli) — not a URL, not bundled or controlled by this skill; the USER runs it.
# This skill ships ZERO runtime dependencies and makes no network calls of its own. See SECURITY.md.
npm create storybook@latest   # installs, then prints follow-up steps for the agent (the official package)
npx storybook skills setup    # 10.6+: the setup prompt to execute (10.4–10.5: `npx storybook ai setup`)

命令名称会随 Storybook 小版本变动 — 当前命令和 10.6 之前的等效命令见 references/storybook-surface.md。

了解原生流程已有的内容

在此基础上添加任何内容之前，请先阅读 references/native-ai-setup-prompt.md — 捕获的原生设置提示词（10.6 起使用 storybook skills setup，此前使用 storybook ai setup）（默认采用 optimized-tests 变体），其中包含 8 条参与规则、8 步计划（发现 → 共享预览 → portals → MSW → 编写 ≤10 个就近放置的 stories + 一个 CssCheck → play 规范 → 批量验证 → 清理）、5 项完成标准，以及原样保留的代码示例。我们的工作不是重做其中任何内容，而是只补充下方文档不足的对齐部分。

然后进行对齐 + 验证（文档不足的部分）

完整的对齐层请加载 references/install-wizard.md（仅当你实际要对新鲜的原生设置进行对齐时才加载 — 回答一次性的“我的 Storybook 配置正确吗？”问题时，不要加载它；以下检查清单已足够）：

• 首先进行运行时发现 — ${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/discover-runtime.py . --out .storybook/runtime.json → .storybook/runtime.json：将原生 Step-1 事实作为真实依据（provider 树 + from、根 CSS 机制（JS import 还是 index.html <link>）、portal 目标 id、网络/MSW 范围）。下面的三个要点都来自此文件——请对照它进行验证，不要手动阅读入口文件重新推导。
• viteFinal — 移除 Storybook 无法使用的插件；保留别名。
• provider 装饰器 — 用应用的 Router/Theme/Query provider 包裹 stories（来源于 runtime.json.providers）。 对于基于 class 的深色主题（在 <html> 上切换 .dark，颜色来自 CSS 变量），仅有装饰器还不够：还要在 .storybook/preview-head.html 中为画布根节点设置主题（html, body, .sb-show-main { background: var(--color-background) } + html.dark { color-scheme: dark }），否则 centered stories 会在白色背景中显示一小条深色区域，而 padded/fullscreen stories 则会出现白色边框。（代码片段见 install-wizard.md 第 9 项。）
• bare-OKLCH / shadcn-channel 令牌桥接 — 对于 :root 声明了裸通道三元组（--background: 0.99 0.003 234，没有 oklch() 包装）的项目，这些变量使用 shadcn 的 --background/--card/… 命名，且没有 --color-* 命名空间传入 iframe；此时包装器的 --color-* 外观引用会解析为空，导致所有表面都失去样式（OKLCH 设计系统中“首次运行看起来坏了”的首要原因）。检测条件为（以 css-vars 为主、值为通道三元组、没有 --color-background），并自动将 --color-* → oklch(var(--bare)) 桥接映射同时写入 .storybook/preview-head.html 中的两种模式——位置和机制与上文的画布根节点主题设置相同。方案和检测方法见 install-wizard.md 第 11 项。
• MCP 接线 — 检测 @storybook/addon-mcp 和 .mcp.json；若存在则接线。
• 默认显示面板 — 写入 .storybook/manager.ts，配置 addons.setConfig({ showPanel: true, panelPosition: 'bottom' })，让 Controls / Actions / Accessibility 面板默认显示。Storybook 不会生成 manager.ts；若没有该文件，一次意外按下 A 键（或拖动分隔线将面板关闭）就会把“面板隐藏”状态保存在 localStorage 中，评审者/Agent 会以为 stories 没有 Controls。Controls 面板会显示 sb-stories 的 argTypes，因此这能让相关创作工作清晰可见。（代码片段见 install-wizard.md。）
• 主题切换（带主题的项目）——接入 @storybook/addon-themes，不要手动实现 globalTypes.theme。 如果运行时发现检测到主题机制（next-themes、基于 class 的 .dark 或 data-theme），请注册 withThemeByClassName，让工具栏切换同一个 .dark class，画布根节点主题设置（第 9 项）和 bare-OKLCH --color-* 桥接（第 11 项）都依赖它——切换一次即可为所有表面换肤，而且包装器会在切换时重新读取实时的 getComputedStyle。如果没有它，带主题的应用打开后会完全没有主题控件（评审者最后只能手动添加——此处正是要解决的问题）。只有在需要检查表面叠加效果时才添加 @storybook/addon-backgrounds。代码片段见 install-wizard.md 第 12 项。
• 无障碍功能已安装——确认即可，不要重复添加。 原生 storybook init 会捆绑 @storybook/addon-a11y（每个 story 都会运行 axe，包括对比度检查）；上文的默认显示面板设置会显示其 Accessibility 面板。请确认它已列在 package.json 中且面板可见——运行时无障碍/对比度检查由 axe 负责，因此 DesignSystemHealth 的检查应保持为静态检查（原始 hex 值 / 未定义 / 孤立项 / 比例间距缺失），与 axe 互补，而不是重新实现它的功能。
• 文档页面组合 — 在 preview.tsx 中设置 parameters.docs.page，采用标准 autodocs 区块，并将 UsageSection 区块放在靠前的位置，这样每个组件以及 Foundations/Colors / Typography 的 Docs 页面都会先显示“本应用中的真实用法”状态栏，再显示 playground。它会延迟读取 usage JSON 文件（文件存在前不渲染内容），因此可在设置阶段安全接入。（方案和顺序见 install-wizard.md 第 4 阶段。）
• 沿用现有结构 — 扫描并匹配 storySort.order、标题分类和文件位置；不要给已建立规范的代码库强加新约定。
• 沿用原生提示词中的预览规范（install-wizard.md 第 7–9 项）：在全局 beforeEach 中固定应用自身读取的确定性条件（MockDate + 仅应用会读取的 localStorage 键）；对 init 生成的 preview.tsx 进行编辑，不要覆盖它；仅生成一个 CssCheck story（通过 getComputedStyle 证明 CSS 确实已加载——否则这是首要的隐蔽故障）；并为基于 class 的深色主题设置画布根节点主题（上文第 9 项）。

**关于发现：**原生提示词要求“使用 Glob/Grep/Read 进行发现，不要用 shell”。我们的 inventory-project.sh/extract-*.sh/discover-runtime.py 链本身就是这种缓存式发现——它 只运行一次，并写入 JSON（project-inventory · flows · component-states · prop-shapes · page-patterns · runtime），之后你再用 Read 读取，而不是每次调用都重新 grep。绝不要通过 shell 扫描重新推导脚本已写入 .storybook/*.json 的内容——请引用 JSON 字段。

决定所有内容存放在哪里（ASK — 不要把文件散落在仓库中）

此工具包写入的所有内容都放在 .storybook/ 下（参见 CONTEXT.md STORAGE MAP），让客户端仓库保持整洁。唯一需要 决定的是 stories 的存放位置——你必须询问用户，因为把 Foo.stories.tsx 写在每个组件旁边会让文件散落在你可能无权管理的 src/ 中（这是一次真实演示中的疏漏）。使用 AskUserQuestion（Claude）/request_user_input（Codex），如果没有可用的阻塞式 工具，则提供编号列表——绝不要擅自决定：

应该把 stories 保存在哪里？（其他所有内容都已放在 .storybook/ 下。）

1. .storybook/stories/ （默认 — 推荐用于审计 / 客户项目 / 杂乱的仓库） — 保持 src/ 不变；整个审计内容都集中在一个可删除的文件夹中。
2. 与组件同目录 — src/**/<Name>.stories.tsx （主动选择 — 适用于你会长期维护的项目） — 这是 Storybook 的常见约定；stories 会随组件一起移动。
3. 自定义文件夹 （由你指定 — 仍集中在一个位置；配置到 main.ts 中）。

.storybook/stories/ 是默认位置：如果用户没有选择，或这显然是客户项目 / 杂乱的 仓库，就选择它——绝不要擅自把 stories 放在组件同目录（我们正是要避免文件散落）。然后配置 main.ts 中的 stories 以匹配（.storybook/stories/ → 添加相对于 .storybook/ 的 './stories/**/*.stories.@(tsx|ts)'； 自定义路径 → 添加对应的 glob；保留 @/ 别名，让 stories 可以正常导入； 注意，开发服务器不会实时重新加载在 .storybook/ 下新增的 story 文件——添加后需重启）， 并在 .storybook/audit/status.md 中记录选择，格式为 storiesLocation: isolated|colocated|PATH。 sb-stories 和 sb-hub 会读取该记录，不会再次询问。

**已经有 Storybook？**仍然必须询问——如果因为项目中已有 Storybook 而跳过 sb-setup， 首次运行 sb-stories 时会改为询问（它会拒绝把 story 写入未经确认的位置）。请预先确定一次， 避免文件散落。

下一步

Storybook 准备就绪后，运行 sb-inventory，在编写 stories 之前识别真实内容与敷衍内容。