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 ステップの計画（検出 → 共有プレビュー → ポータル → MSW → 同じ場所に配置するストーリーを 10 個以下と 1 つの 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 のネイティブな事実を真実の情報源として使用します（プロバイダーツリーと from、ルート CSS の仕組み（JS インポートと index.html の <link> のどちらか）、ポータルのターゲット ID、ネットワーク／MSW の対象範囲）。以下の 3 つの 箇条書きはこのファイルに基づいています。エントリを手作業で読み直して導き出すのではなく、ファイルと照合してください。
• viteFinal — Storybook で使えないプラグインを削除し、エイリアスは維持します。
• プロバイダーデコレーター — ストーリーをアプリの Router／Theme／Query プロバイダーでラップします（runtime.json.providers を参照）。 クラスベースのダークテーマ（<html> の .dark を切り替え、CSS 変数から色を取得するテーマ）の場合、デコレーターだけでは 不十分です。.storybook/preview-head.html でキャンバスのルートもテーマ設定します（html, body, .sb-show-main { background: var(--color-background) } + html.dark { color-scheme: dark }）。そうしないと、centered ストーリーでは白い背景に 暗い帯が細く表示され、padded／fullscreen ストーリーでは白い枠が表示されます。（スニペットは install-wizard.md の項目 9 を参照。）
• bare-OKLCH／shadcn チャネルトークンのブリッジ — プロジェクトの :root に shadcn の --background／--card／…の名前で チャンネル値のみのトリプレット（oklch() ラッパーなしの --background: 0.99 0.003 234）が宣言され、iframe に届く --color-* 名前空間が存在しない場合、ラッパーの --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 に保存され、レビュー担当者やエージェントがストーリーに Controls がないと判断してしまいます。sb-stories の argTypes が表示されるのは Controls パネルです。つまり、これによって作成した内容を 確認できるようになります。（スニペットは install-wizard.md を参照。）
• テーマ切り替え（テーマを使うプロジェクト）— @storybook/addon-themes を接続し、globalTypes.theme を独自実装しないでください。 実行時情報の検出でテーマ機構（next-themes、クラスベースの .dark、または data-theme）が見つかった場合は、withThemeByClassName を 登録し、ツールバーで、キャンバスルートのテーマ設定（項目 9）と bare-OKLCH の --color-* ブリッジ（項目 11）がすでに参照している 同じ .dark クラスを切り替えるようにします。1 回の切り替えですべてのサーフェスの見た目が変わり、ラッパーの getComputedStyle による再読み込みも切り替え時に実行されます。これがないと、テーマを使うアプリを開いてもテーマコントロールがまったく表示されず （レビュー担当者が手作業で追加することになります。この問題を解消します）、テーマを切り替えられません。サーフェス同士の表示確認が必要な場合に限り、 @storybook/addon-backgrounds を追加します。スニペットは install-wizard.md の項目 12 を参照してください。
• アクセシビリティ機能はすでにインストール済みです。再追加せず、確認してください。 ネイティブの storybook init には @storybook/addon-a11y（コントラストを含む、ストーリーごとの axe）が含まれており、上記のパネル表示設定によって Accessibility パネルも 表示されます。package.json に含まれていることと、パネルが表示されることを確認してください。実行時のアクセシビリティ／コントラスト検査は axe の 担当なので、DesignSystemHealth の検査は静的（生の 16 進数値／未定義／孤立／スケールの欠落）にとどめます。axe と補完し合うものであり、 再実装ではありません。
• ドキュメントページの構成 — preview.tsx で parameters.docs.page を設定し、標準の autodocs ブロックに UsageSection ブロックを 上部付近に配置します。これにより、すべてのコンポーネントと Foundations/Colors／ Typography の Docs が、プレイグラウンドの前に「このアプリでの実際の使い方」を示すステータス帯を表示して開きます。使用状況の JSON は遅延読み込みされ、 ファイルが存在するまでは何も表示されないため、セットアップ時に接続しても安全です。（手順と順序は install-wizard.md のフェーズ 4 を参照。）
• 既存の構成を活用 — storySort.order、タイトルの分類体系、ファイル配置をスキャンして既存の構成に合わせます。 確立済みのリポジトリに新しい規約を押し付けないでください。
• ネイティブプロンプトのプレビュー方針を採用（install-wizard.md の項目 7～9）：アプリ自体が読み取る決定性の設定を、グローバルな beforeEach（MockDate と、アプリが読み取る localStorage キーのみ）で固定します。init が生成した preview.tsx は上書きせず、 Edit します。CSS が実際に読み込まれたことを証明する getComputedStyle チェックとして、CssCheck ストーリーを必ず 1 つだけ 出力します（これがないと、気づかれないまま失敗するケースが最も多くなります）。また、クラスベースのダークテーマではキャンバスルートを テーマ設定します（上記の項目 9）。

調査について： ネイティブプロンプトには「シェルではなく、Glob/Grep/Read で調査する」とあります。inventory-project.sh／extract-*.sh／discover-runtime.py の一連の処理こそが、そのキャッシュ済みの調査です。一度だけ実行して JSON（project-inventory・flows・component-states・prop-shapes・page-patterns・runtime）を書き出し、その後はそれを Read します。呼び出しのたびに Grep をやり直すことはありません。スクリプトがすでに .storybook/*.json に書き出した内容を、シェルスキャンで再導出しないでください。JSON のフィールドを参照してください。

すべての保存先を決める（確認する — リポジトリ内に散らばらせない）

このバンドルが書き込むものはすべて .storybook/（CONTEXT.md STORAGE MAP）の下に置き、クライアントのリポジトリをきれいに保ちます。決めるのはストーリーの保存場所だけです。Foo.stories.tsx をすべてのコンポーネントの隣に置くと、所有していないかもしれない src/ にファイルが散らばるため、必ずユーザーに確認してください（実際のデモで起きた失敗です）。AskUserQuestion（Claude）／request_user_input（Codex）を使うか、処理を妨げるツールがない場合は番号付きリストを提示してください。黙って決めてはいけません。

ストーリーはどこに保存しますか？（それ以外はすでに .storybook/ に保存されています。）

1. .storybook/stories/ (デフォルト — 監査／クライアント／雑然としたリポジトリに推奨) — src/ に触れず、監査全体を削除可能な一つのフォルダーにまとめます。
2. コンポーネントと同じ場所 — src/**/<Name>.stories.tsx (任意 — 長期的に所有するプロジェクト向け) — Storybook の一般的な規約で、ストーリーがコンポーネントと一緒に移動します。
3. カスタムフォルダー (場所はユーザーが指定 — 1か所にまとめ、main.ts に設定します)。

デフォルトは .storybook/stories/ です。ユーザーが選ばない場合や、クライアント／雑然としたリポジトリであることが明らかな場合は、これを選んでください。黙ってコンポーネントと同じ場所に置いてはいけません（それを避けるために分離しています）。その後、main.ts の stories を設定して保存場所に合わせます（.storybook/stories/ → .storybook/ からの相対パスとして './stories/**/*.stories.@(tsx|ts)' を追加。カスタムパス → 対応する glob を追加。ストーリーを正しくインポートできるよう @/ エイリアスは維持します。開発サーバーは .storybook/ に追加されたストーリーファイルを自動再読み込みしないため、追加後に再起動してください）。そして、.storybook/audit/status.md に選択を storiesLocation: isolated|colocated|PATH として記録してください。 sb-stories と sb-hub はこの設定を読み込み、再確認しません。

すでに Storybook を使っていますか？ その場合も、ここでの確認は必要です。Storybook が存在するために sb-setup をスキップした場合は、最初の sb-stories の実行時に確認されます（保存場所が未確認の状態ではストーリーを書き込みません）。ファイルを散らばらせないよう、最初に一度だけ決めてください。

次の手順

Storybook が用意できたら、作成を始める前に sb-inventory を実行し、実際の内容と粗雑な内容を見極めてください。