sb-wrappers — composition primitives, not hand-rolled grids

Don't hand-roll grid markup. Scaffold a typed wrapper.

Load only what the task needs (these are two large refs — don't pull both for one wrapper):

• references/wrapper-library.md — the per-wrapper API. Load it before authoring any wrapper story, to get the props/args of the one you picked.
• references/composition-patterns.md — the five composition patterns (A/B, role, status grid, page, motion). Load it only for a Compare / multi-pattern / layered build. Do NOT load it for a single StateGrid / ProjectInventory / DesignSystemHealth scaffold — the library ref alone covers that.

Pick the wrapper from intent

User says	Wrapper	Tier
"compare two designs" / "side-by-side"	ABCanvas	1
"every state on one canvas"	StateGrid	1
"every role" / "permission UI"	StateGrid with role as the varied prop (only if the app is role-gated)	1
"track this decision"	TrackedDecision + DecisionsDashboard	2
"the full flow" / "ordered sequence"	StoryStrip / StorySet	2
"shader / WebGL / 3D / keyframe motion"	ShaderCanvas / R3FCanvas / MotionStage	3
"token source of truth" / "DS health" / "inventory"	TokensCanvas / DesignSystemHealth / ProjectInventory	4
"icon coverage" / "which icons / what sizes / where is an icon used"	IconMatrix	4
"whole-app route map" / "journey map"	AppFlowGraph / JourneyGraph	flow

When in the flow (which wrapper, which step)

Wrappers split by what feeds them. The data wrappers render a prior step's JSON — scaffold and use them AFTER that step has run, or they render empty. The component/story wrappers you reach for while writing a story. Suggest the matching wrapper as the next step once its input exists.

Reach for it…	Wrapper(s)	Needs (run first)
after sb-inventory	ProjectInventory, TokenMatrix (Colors foundation — value · mapping · adoption; leave the health prop off)	.storybook/project-inventory.json
after sb-inventory (usage graph)	ComponentUsage, UsageExplorer	.storybook/component-pages.json (build-component-pages.py / refresh-usage.sh)
after sb-health	DesignSystemHealth	.storybook/design-system-health.json (TokensCanvas auto-discovers — no step)
after sb-flows	AppFlowGraph, JourneyGraph	.storybook/flows.json
building Foundations/Icons	IconMatrix	nothing — scans /src live; pass library + resolve
writing a component story (sb-stories)	StateGrid (all states), StateMatrix (variants × states)	the component
composing existing stories	StorySet (by tag/id), StoryStrip (ordered)	stories already written
iteration (Compare / decide)	ABCanvas, TrackedDecision + DecisionsDashboard	—

Don't scaffold a data wrapper before its step has produced the JSON — scaffold-wrapper.sh prints the generating script for each as a reminder.

States scattered across many stories → consolidate into ONE matrix. When a component's states are spread over separate stories (a story per state — hard to scan, easy to drift), collapse them into a single StateGrid (all states) or StateMatrix (variants × states) so every state is reviewable on one canvas. This is the canonical fix for "the Detection header/list states are scattered — make a concise states view".

Real-usage overlay. StateGrid / StateMatrix take an optional usage prop — usage={usageJson.components.<Name>} (from .storybook/component-usage.json) badges each variant/state with its real call-site count and strikes through declared-but-unused ones (×0 unused). Add it as a flat story in the component's existing CSF, never a new file (a new file makes a new sidebar folder). For colours/type use TokenUsageGrid (reads project-inventory.json tokens.map); for the per-component table, UsageSection embeds into each Docs page via preview.ts docs.page — see sb-inventory.

Scaffold

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 is always copied alongside (the shared icon language) and a barrel index.ts is emitted. Wrappers nest: TrackedDecision → ABCanvas → ShaderCanvas → Hero.

View design

All wrappers follow CONTEXT.md §wrapper-view-design — no emoji, the shared Icon set, and an injectable icons prop on the map wrappers. When you add/edit a wrapper, keep that contract.

Next

Compose your Compare/Flow story, then sb-stories gate (validate-stories.sh).