sb-wrappers

sb-wrappers — 组合原语，而不是手写网格

不要手写网格标记。搭建一个类型化包装器。

只加载任务所需的内容（这两份参考文档都很长；单个包装器不要两份都加载）：

• references/wrapper-library.md — 每个包装器的 API。编写任何包装器故事之前，先加载它，了解所选包装器的 props/args。
• references/composition-patterns.md — 五种组合模式（A/B、角色、状态网格、页面、动效）。仅在构建 Compare／多模式／分层内容时加载。 对于单个 StateGrid／ProjectInventory／DesignSystemHealth 搭建，不要加载它——仅靠包装器库参考文档就足够了。

根据意图选择包装器

用户表述	包装器	层级
“比较两个设计”／“并排展示”	ABCanvas	1
“在同一个画布上展示所有状态”	StateGrid	1
“所有角色”／“权限 UI”	StateGrid，将 role 作为变化的 prop（仅当应用按角色控制访问时）	1
“跟踪此决策”	TrackedDecision + DecisionsDashboard	2
“完整流程”／“有序序列”	StoryStrip／StorySet	2
“着色器／WebGL／3D／关键帧动效”	ShaderCanvas／R3FCanvas／MotionStage	3
“令牌的唯一真实来源”／“DS 健康状况”／“清单”	TokensCanvas／DesignSystemHealth／ProjectInventory	4
“图标覆盖情况”／“哪些图标／什么尺寸／图标在哪里使用”	IconMatrix	4
“整个应用的路由图”／“用户旅程图”	AppFlowGraph／JourneyGraph	流程

在流程中的哪个位置（哪个封装器，哪个步骤）

封装器按数据来源划分。数据封装器会渲染上一步的 JSON——请在该步骤运行后再生成并使用，否则渲染结果为空。编写故事时则使用组件/故事封装器。输入数据准备就绪后，将对应的封装器作为下一步建议。

使用场景	封装器	所需内容（先运行）
在 sb-inventory 之后	ProjectInventory、TokenMatrix（Colors foundation — value · mapping · adoption；省略 health prop）	.storybook/project-inventory.json
在 sb-inventory 之后（使用情况图）	ComponentUsage、UsageExplorer	.storybook/component-pages.json（build-component-pages.py / refresh-usage.sh）
在 sb-health 之后	DesignSystemHealth	.storybook/design-system-health.json（TokensCanvas 会自动发现——无需步骤）
在 sb-flows 之后	AppFlowGraph、JourneyGraph	.storybook/flows.json
构建 Foundations/Icons	IconMatrix	无——实时扫描 /src；传入 library + resolve
编写组件故事（sb-stories）	StateGrid（所有状态）、StateMatrix（变体 × 状态）	组件
组合现有故事	StorySet（按标签/ID）、StoryStrip（有序）	已编写的故事
迭代（比较 / 决策）	ABCanvas、TrackedDecision + DecisionsDashboard	—

在对应步骤生成 JSON 之前，不要生成数据封装器——scaffold-wrapper.sh 会打印每个封装器对应的生成脚本，以作提醒。

状态分散在多个故事中 → 整合到一个矩阵中。 当组件的状态分散在不同故事中（每种状态一个故事——难以浏览，也容易出现偏差），将它们合并到一个 StateGrid（所有状态）或 StateMatrix（变体 × 状态）中，以便在同一个画布上检查所有状态。这是解决“Detection 标题/列表状态分散——生成简洁的状态视图”这一问题的标准方法。

真实使用情况叠加层。 StateGrid / StateMatrix 可接收可选的 usage prop—— usage={usageJson.components.<Name>}（来自 .storybook/component-usage.json）会为每个变体/状态标注真实调用点数量，并划掉已声明但未使用的项（×0 unused）。将其添加为组件现有 CSF 中的扁平故事，切勿新建文件（新文件会创建新的侧边栏文件夹）。 对于颜色/字体，使用 TokenUsageGrid（读取 project-inventory.json 的 tokens.map）；对于组件级表格，UsageSection 通过 preview.ts 的 docs.page 嵌入到每个 Docs 页面中——参见 sb-inventory。

生成封装器

CORE=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}   # scaffold-wrapper is shared core
# scaffold-wrapper.sh is a LOCAL bash script that ships INSIDE this skill — it only copies the bundled
# .tsx wrappers into the project's .storybook/. No network, no install, no external code. See SECURITY.md.
"$CORE/scripts/scaffold-wrapper.sh" --tier 1            # CORE
# --tier 2 | 3 | 4 (adds DESIGN-SYSTEM) | --flow (AppFlowGraph+JourneyGraph) | --all
"$CORE/scripts/scaffold-wrapper.sh" ABCanvas StateGrid  # or specific names

icons.tsx 始终会一并复制（共享图标语言），并会生成一个入口文件 index.ts。封装器可以嵌套：TrackedDecision → ABCanvas → ShaderCanvas → Hero。

视图设计

所有封装器都遵循 CONTEXT.md §wrapper-view-design——不使用 emoji，使用共享的 Icon 集合，并在地图封装器上提供可注入的 icons prop。添加或编辑封装器时，请遵守这一约定。

下一步

组合 Compare/Flow 故事，然后运行 sb-stories 门禁（validate-stories.sh）。