shadcn-registry-first

まずは Shadcn レジストリを確認

Darkmatter は @shadcnblocks ブロックレジストリの利用料を支払い、これと無料の @shadcn レジストリの両方を shadcn MCP に接続しています。つまり、一般的な UI の多くの画面要素（ヒーロー、ナビバー、フッター、料金表、機能グリッド、ダッシュボード、ログイン画面、データテーブル）は、すでに本番品質で、アクセシブルかつテーマ設定可能なブロックとして用意されており、1 つのコマンドでインストールできます。まずこれらを使えば、空のファイルから JSX を書くより速く、より良い出力を得られます。

このスキルが解消する典型的な失敗は、エージェントがレジストリにすでにあるヒーローや料金表を、気づかないまま独自に実装してしまうことです。その結果、トークンを浪費し、仕上がりも劣ります。新しいコンポーネントを一から書く前に、レジストリにすでに用意されていないか確認してください。

使用する場面

• 新しいマーケティング／ランディングページのセクションを作成する場合：ヒーロー、機能グリッド、CTA バンド、お客様の声、ロゴ一覧、フッター、料金表。
• アプリの基本レイアウトを作成する場合：ナビバー、サイドバー、ダッシュボードのシェル、設定パネル。
• 一般的なインタラクティブ要素を作成する場合：フォーム、認証画面、データテーブル、コマンドパレット、ファイルアップロード、カレンダー、チャート。
• 既存のコンポーネントを、より洗練されたレジストリのブロックで再スタイリングまたは置き換える場合。
• ユーザーが「X セクションを追加して」「Y ページを作って」「Z コンポーネントが必要」と言い、Z がよく知られた Web UI パターンである場合。

使用しない場面

• コンポーネントが本当にドメイン固有である場合（例：流動性範囲のティックチャート、プロトコル固有のポジションカード）。一般的なレジストリにはないため、できればレジストリのプリミティブを組み合わせて作成してください。
• プロジェクトが React ではない場合、またはレジストリを設定した components.json がない場合。まず確認してください（下記参照）。何も設定されていなければ、このスキルは適用されません。
• 小さな単発の要素（スタイル付きボタン 1 つやラベルなど）で、ブロックをインストールするよりも 1 行書くほうが簡単な場合。
• 新しい画面要素を追加するのではなく、既存のコンポーネントの内部を編集する場合。

ワークフロー

1. レジストリが設定されていることを確認する

shadcn MCP の get_project_registries ツールを使うか、components.json を読み取ります。@shadcnblocks や @shadcn が一覧にあることを確認してください。@shadcnblocks が存在するのに API キーが解決されない場合は、下記の「レジストリへのアクセス」を参照してください。キーが見つからないからといって独自実装に切り替えず、キーを修正してください。

2. 検索し、候補を少なくとも 3 つに絞る

設定済みのレジストリを対象に、必要なパターンを search_items_in_registries で検索します。キーワードではなく、必要な「もの」自体を検索してください。

• search_items_in_registries(registries=["@shadcnblocks"], query="hero dark")
• search_items_in_registries(registries=["@shadcnblocks"], query="pricing toggle")
• search_items_in_registries(registries=["@shadcnblocks"], query="dashboard analytics")

@shadcnblocks は大規模で、ブロックが 1000 個以上あります。「hero」のような検索では、何百件も返されます。「hero split」「hero video」「hero dark」のように条件を加えて絞り込み、説明をざっと確認してください。説明は読みやすく、レイアウト、カラム数、主な機能がわかるように書かれています。

検索結果から、要件を満たす可能性のある、少なくとも 3 つの異なる候補を選んでください。レイアウト、密度、視覚的な強調点が異なるなど、本当のバリエーションを優先し、ほとんど同じブロックを 3 つ選ばないでください。ユーザーに実質的な選択肢を提示するのが目的です。フォントやパレットの候補を複数提案し、黙って決めてしまわないのと同じです。

検索結果は非常に多くなることがあります。1 回の呼び出しで大量のリストが切り詰められて返された場合は、その全体をコンテキストに読み込まないでください。保存したツール出力ファイルに対して Grep/Read を使う explore エージェントに処理を委任するか、検索条件をさらに絞って再実行してください。

3. 候補をそれぞれプレビューする

最終候補に選んだものについて、何を導入するのかを確認します。

• get_item_examples_from_registries — デモとその完全なソースを確認し、実際のマークアップと props を把握します。
• view_items_in_registries — アイテムのファイル、依存関係、レジストリの依存関係（取り込まれる他のコンポーネント）を確認します。

それぞれがプロジェクトのデザインシステム（テーマトークン、フォント、角丸）に適合することを確認します。多くのブロックはデフォルトの shadcn テーマを前提としています。プロジェクトでトークンを上書きしている場合（例：--radius: 0 のターミナルテーマ）、ブロックはそのトークンに合わせて表示されますが、調整が必要なハードコードされた色や角丸がないか確認してください。

4. すべてのバリエーションをインストールする

get_add_command_for_items で追加コマンドを取得し、実行します（通常は bunx shadcn@latest add @shadcnblocks/<name>）。これにより、各コンポーネントがプロジェクトの ui／components エイリアスに書き込まれ、依存関係がインストールされます。バリエーション同士は分離しておきます。名前が明確なファイルや一時ディレクトリにインストールし、入れ替えたり削除したりしても他のバリエーションに影響しないようにしてください。

5. 比較用の画面を用意する

必ず、チャットで名前を伝えるだけではなく、ユーザーがバリエーションを並べて実際に表示を確認できるようにします。フォント比較のパターンを参考に、すべてのバリエーションを1つの画面に表示し、それぞれに明確なラベルを付け、同じ代表的なコンテンツを使います。違いはブロック自体だけになるようにしてください。

• ルーティングのある Web アプリ（TanStack Router、Next）：すべてのバリエーションをインポートして縦に並べ、各オプションに見出しを付ける一時ルート（/compare/<feature> など）を追加します。使い捨てであることを明示（// TODO: remove after selection コメントを付ける）し、認証や起動時のゲーティングを回避して表示できるようにしてください。
• コンポーネント／Storybook：各バリエーションを横一列に表示するギャラリーストーリーを作成します。
• 開発サーバーを起動し、ユーザーが利用できるプレビュー URL（この環境の Tailscale 経由の開発 URL など）を渡します。結果を想像してもらうのではなく、実際に確認できるようにしてください。

比較用の画面は、提示する前に問題なくビルドできる必要があります（lsp_diagnostics、check-types、プロジェクトのビルドを実行します）。

6. ユーザーに選んでもらい、選んだものを調整する

ラベル付きのオプションとプレビュー URL を提示し、どれを残すかユーザーに尋ねます。選んでもらったら、次の作業を行います。

• 選んだものを実際のデータとルートに接続し、デモ用のプレースホルダーテキストを削除して、テーマの不一致を解消し、不要な部分を取り除きます。
• 他のバリエーションと一時的な比較用の画面を削除し、コードベースに放置されて劣化しないようにします。

目指すのは、洗練されアクセシブルな構成を出発点に、実際にビルドした選択肢からユーザーに選んでもらうことです。最初に見つけたブロックをそのまま出荷したり、lorem ipsum を残したりすることではありません。

7. 監査する

選んだものを確定して他を削除したら、shadcn MCP の get_audit_checklist を実行して、項目に沿って確認します（インポートが解決すること、依存関係がインストール済みであること、デモデータや比較用のコードが残っていないこと、型に問題がないこと）。続けて、プロジェクト独自のチェック（lsp_diagnostics、check-types、ビルド）も実行します。

レジストリへのアクセス

@shadcnblocks レジストリへのアクセスには、components.json の Authorization ヘッダーに API キーが必要です。darkmatter リポジトリでは、プロジェクトごとに次のように処理します。

• components.json は gitignore されており、解決済みのキーを保持します（または shadcn MCP が環境変数 ${SHADCNBLOCKS_API_KEY} を読み取ります）。
• components.json.template は ${SHADCNBLOCKS_API_KEY} プレースホルダー付きでコミットされています。
• キーはシークレットストアに保存されています（himitsu：himitsu read shadcnblocks-api-key、または SOPS で暗号化されたシークレット）。scripts/setup-components-json.ts がテンプレートにキーを挿入します。

bunx shadcn コマンドを実行する前に

レンダリング済みの components.json が存在し、最新の状態である必要があります。前回のセッションで生成された古いファイルには、期限切れのキーが含まれている可能性があります。必ず最初に次の手順を実行してください。

1. components.json をビルドする：リポジトリのルートで bun scripts/setup-components-json.ts を実行します。これにより、himitsu から現在のキーが読み込まれ、Git の追跡対象外である components.json が書き出されます。この手順を省略すると、401 認証エラーが発生します。
2. アプリのディレクトリに cd する（例：apps/web/）：その後、bunx shadcn@latest add ... を実行します。CLI は、現在の作業ディレクトリにある components.json からレジストリを解決します。モノレポのルートから実行すると失敗します。
3. --overwrite フラグを使用する：ブロックが依存している可能性があるものの、プロジェクトにすでに存在するファイル（utils.ts、button.tsx など）について、既存ファイルを上書きするか尋ねる対話式プロンプトをスキップします。

一般的な実行方法：

# From repo root:
bun scripts/setup-components-json.ts
cd apps/web
bunx shadcn@latest add @shadcnblocks/hero253 --overwrite

レジストリの呼び出しで環境変数の不足や認証エラーが発生した場合は、レジストリを諦めてコンポーネントを手作業で作るのではなく、シークレットストアからキーを設定してください。この設定の暗号化に関する説明と、想定されるシークレットの取り扱い方については、sops-secret-access スキルを参照してください。

画面上で安定した要素は、リポジトリの共通 UI パッケージに移してください（パッケージ名はリポジトリごとに異なります。ADR-0013 を参照してください）。

他のスキルとの関係

• sops-secret-access — 暗号化されたレジストリ設定とキーへの アクセス方法 を説明します。このスキルでは レジストリのコンポーネントを優先すること を扱い、こちらのスキルではプライベートレジストリにアクセスするための仕組みを扱います。
• ui-ux-pro-max — デザインに関する知見（スタイル、配色、レイアウト、アクセシビリティ）を提供します。優れた UI の 設計方法 を決める際に使い、このスキルは、その UI を実現するコンポーネントの 入手元 を決める際に使います。両者を組み合わせて、ui-ux-pro-max でデザインの方向性を決めてから、それに合うブロックをレジストリで検索してください。
• vercel-react-best-practices — インストールしたブロックの周囲や内部に記述する React のパフォーマンスパターンを扱います。