sb-wrappers

sb-wrappers — 手作りのグリッドではなく、構成プリミティブ

グリッドのマークアップを手作りしないでください。型付きのラッパーをスキャフォールドしてください。

タスクに必要なものだけを読み込んでください（以下は大規模なリファレンスが2つあります。1つのラッパーに両方を読み込まないでください）：

• references/wrapper-library.md — ラッパーごとの API です。選んだラッパーの props/args を確認するため、ラッパーのストーリーを作成する前に読み込んでください。
• references/composition-patterns.md — 5つの構成パターン（A/B、role、status grid、page、motion）です。Compare／複数パターン／レイヤー構成のビルドの場合のみ読み込んでください。 単一の StateGrid／ProjectInventory／DesignSystemHealth をスキャフォールドする場合は読み込まないでください — library ref だけで十分です。

意図に合わせてラッパーを選ぶ

ユーザーの発言	ラッパー	Tier
「2つのデザインを比較」／「横並び」	ABCanvas	1
「すべての状態を1つのキャンバスに」	StateGrid	1
「すべてのロール」／「権限 UI」	StateGrid（アプリにロールによるアクセス制限がある場合のみ、変化させる prop は role）	1
「この決定を追跡」	TrackedDecision + DecisionsDashboard	2
「フロー全体」／「順序付きシーケンス」	StoryStrip / StorySet	2
「シェーダー／WebGL／3D／キーフレームアニメーション」	ShaderCanvas / R3FCanvas / MotionStage	3
「トークンの信頼できる唯一の情報源」／「DS の健全性」／「インベントリ」	TokensCanvas / DesignSystemHealth / ProjectInventory	4
「アイコンの網羅状況」／「どのアイコン／どのサイズ／アイコンはどこで使われているか」	IconMatrix	4
「アプリ全体のルートマップ」／「ジャーニーマップ」	AppFlowGraph / JourneyGraph	flow

フローのどの段階か（どのラッパーを、どのステップで使うか）

ラッパーは何を入力として受け取るかで分かれています。データラッパーは前のステップの JSON を表示します。そのステップの実行後にスキャフォールドして使用してください。先に実行しないと、空の状態で表示されます。コンポーネント／ストーリーラッパーは、ストーリーの作成中に使用します。入力データがそろったら、次のステップとして対応するラッパーを提案してください。

使用する場面…	ラッパー	必要なもの（先に実行）
sb-inventory の後	ProjectInventory、TokenMatrix（Colors foundation — 値・マッピング・採用状況。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 は注意喚起として、それぞれの生成スクリプトを表示します。

複数のストーリーに分散した状態 → 1 つのマトリックスに集約します。 コンポーネントの状態が別々のストーリーに分散している場合（状態ごとにストーリーがあり、確認しにくく、差異が生じやすい場合）は、1 つの StateGrid（すべての状態）または StateMatrix（バリアント × 状態）にまとめ、すべての状態を 1 つのキャンバスで確認できるようにします。これは「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 に従います — 絵文字は使わず、共有の Icon セットを使用し、マップラッパーでは icons prop を注入可能にします。ラッパーを追加／編集する際は、この契約を守ってください。

次のステップ

Compare/Flow ストーリーを構成し、その後 sb-stories のゲート（validate-stories.sh）を実行してください。