tsaru23 design-adopt — OSSフロントエンドデザインの探索と適用
目的
対象プロジェクトのスタックを判定したうえで、shadcn/ui MCP・GitHub(gh CLI)・Claude Design・
Figma MCP・21st.dev Magic MCP・Lovable MCP といった情報源をコストの安い順に使い分けて候補を探し、
ライセンス・保守性・スタック適合を基準に最適なものを選び、既存のデザイントークンに合わせて調整して
適用する。
Step 0 — 対象プロジェクトの判定（必ず最初に実行）
対象ディレクトリの package.json（無ければファイル構成）を読み、次の3系統に分類する。
分類結果をユーザーに1行で伝えてから次に進む。
- A: React + Tailwind あり → shadcn 系がそのまま入る
- B: React あり / Tailwind なし → Tailwind 導入の可否をユーザーに確認してから進む
- 導入する → 系統Aとして扱う
- 導入しない → 系統Cとして扱う（shadcn は使わず、CSS Modules / 素のCSSで実装する）
- C: 素のHTML/CSS、または非Reactフレームワーク → shadcn は使えない。ルート2/3のみ
判定例（イメージ）:
| プロジェクト（例） | スタック | 系統 |
|---|---|---|
~/projects/saas-dashboard（SaaS管理画面系） |
Next 16 + React 19 + Tailwind v4 | A |
~/projects/internal-tool, ~/projects/meeting-notes-app（社内ツール系） |
Next 16 + React 19（Tailwindなし） | B |
~/projects/habit-tracker, ~/projects/study-log（記録アプリ系） |
Vite + React 19 | B |
~/projects/camera-app（カメラ系ツール） |
Vite（Reactなし） | C |
~/projects/landing-page, ~/projects/docs-site（LP系） |
素のHTML/CSS | C |
Step 1 — ルートを選ぶ
サイトの性格で3つに分岐する。ルートによって主に使う情報源が変わる。
| ルート | 対象 | 主な情報源 |
|---|---|---|
| 1 コンポーネント駆動 | 管理画面・SaaS・フォーム/テーブル主体 | shadcn/ui MCP（+ GitHub でテンプレ探索） |
| 2 表現駆動 | LP・ポートフォリオ・ブランドサイト（モーションと余白で見せる） | references/motion-stack.md を先に読む。21st.dev の search（無料・無制限）+ GitHub |
| 3 参照駆動 | 既にFigmaに確定デザインがある | Figma MCP。ただし月20回制限（後述）を厳守 |
ルート2では shadcn/ui MCP はほとんど役に立たない（フォーム部品のカタログであってモーションの
語彙を持たないため）。ルート2だと判定したら、shadcn を探しに行かずに references/motion-stack.md
へ進むこと。
Step 1.5 — 意匠を先に固める（ルート2、および既存デザインを大きく変える場合）
実装に入る前に /design スキル（Claude Design）で .dc.html アートボードを起こし、
レイアウト・タイポスケール・色数をユーザーと合意してから Step 2 に進む。
先にコードを書いてから見た目を議論すると手戻りが大きい。
例: ./design/main.dc.html, ./design/works.dc.html
ルート1で、既存のデザイントークンに沿って部品を足すだけの場合はこの Step を飛ばしてよい。
Step 2 — 情報源の使い分け（コストの安い順に試す）
この順序を守ることがトークンとクォータの節約になる。
| 情報源 | 呼び出し方 | コスト | 役割 |
|---|---|---|---|
| shadcn/ui MCP | get_project_registries → search_items_in_registries → view_items_in_registries → get_add_command_for_items → get_audit_checklist |
無料・無制限 | ルート1の第一候補。実装コンポーネントの取得 |
| GitHub | gh CLI（認証済みのGitHubアカウントで使用・scope: repo/gist/read:org/workflow） |
無料 | OSSテンプレ/実装例の探索、LICENSE確認、star数・最終更新の確認 |
| Claude Design | /design スキル（.dc.html アートボード） |
無料 | Step 1.5 の意匠検討 |
| 21st.dev | 接続済み（Claude Desktop カスタムコネクタ） | search 等は無料・無制限／get_component のみ1日2回 |
ルート2の探索源。意匠のカタログ閲覧に使う |
| Magic UI MCP / daisyUI MCP | 未登録。必要になったら claude mcp add -s user で追加 |
無料・OSS | ルート2の補完（21st.dev で足りないとき） |
| Figma MCP | 接続済み（claude.aiコネクタ） | 月20回のみ | 既存デザインの参照だけ。探索には絶対に使わない |
| Lovable MCP | 未登録 | クレジット消費（無料枠は1日5・月30程度） | 常用しない |
詳細は references/sources.md を参照。
shadcn/ui MCP の注意書き
必ず get_project_registries から始める。 対象プロジェクトに components.json が無い、
またはレジストリが未設定だと後続のツールが失敗する。未設定なら先に
npx shadcn@latest init を実行するかどうかをユーザーに確認すること。
21st.dev の注意書き
get_usage の実測値: tier: free / freeSearchesPerDay: null（無制限）/ freeRetrievalsPerDay: 2。
searchsearch_pickerおよび list/metadata 系はすべて無料・無制限。遠慮なく探索に使う。 ユーザーに候補を見せて選ばせたいときはsearch_picker（インラインのピッカーが出る）- メーターがかかるのは
get_component（コード本体の取得）だけで1日2回。 候補を3つに絞り込んでから呼ぶこと。残量はget_usageで確認できる get_themeが返すテーマCSSは無料。ただしカタログは薄い（実測: 「dark theme」で1件）- 配布形態は shadcn レジストリ。
searchの結果に含まれるinstallCommandはnpx shadcn@latest add "https://21st.dev/r/AUTHOR/NAME?api_key=$API_KEY_21ST"の形なので、 このコマンドをそのまま実行するなら環境変数API_KEY_21STの設定が必要 - 書き込み系（
submit_componentedit_profiledelete_*など）はユーザーに明示的に 頼まれない限り呼ばない
Figma の注意書き
ユーザーのプランは Starter tier / View シートで、get_design_context get_screenshot
get_metadata get_variable_defs などの読み取り系ツールが合計で月20回を共有する。
機能ブロックではなく回数制限。だから「とりあえずFigmaを見る」は禁止で、Figmaに確定デザインが
ある場合に限り、呼ぶ前に何を取得するか決めてから1回で済ませること。
出典: https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/
GitHub の注意書き
GitHub の MCP コネクタは OAuth 未認証のため使えない。gh CLI を使うこと。
以下は実行検証済みのコマンド。
探索（--json license でライセンスも同時に返るので、リポジトリごとに /license を叩かなくてよい）:
gh search repos "portfolio template" --stars=">1000" --sort stars --limit 5 --json fullName,stargazersCount,updatedAt,license,description
ファイル単体の取得（--jq .content は base64 のまま返るので使わない。raw ヘッダを使う）:
gh api repos/OWNER/REPO/contents/PATH -H "Accept: application/vnd.github.raw"
コツと落とし穴:
- クエリは2語程度から始める。 3語以上に絞ると
--starsの閾値と噛み合って0件になりやすい （実測:"portfolio nextjs tailwind" --stars=">300"は0件、"portfolio template" --stars=">1000"は良質な候補が返る） - star数の閾値でノイズを落とす。閾値なしだと0スターのリポジトリばかり返る
- リポジトリ全体を clone せず、必要なファイルだけ取ること（トークン節約）
Step 3 — 選定基準（「最適なものを選ぶ」の中身）
候補を最大3つに絞り、次の軸で比較表を作ってユーザーに提示してから適用に進む。
- スタック適合 — Step 0 の系統に無改造で入るか
- ライセンス — MIT / Apache-2.0 / ISC のみ採用可。GPL系・独自ライセンス・ライセンス表記なしは
不採用。
gh search repos --json licenseの結果で確認する - 依存の重さ — 新規に増える依存パッケージ数。既存の依存で済むものを優先
- 保守性 — star数と最終更新日（1年以上更新なしは減点）
- デザイントークン整合 — 既存の配色・角丸・フォントスケールを壊さないか
軸2で実際に落ちる例は多い。実測した検索結果の上位3件のうち、chetanverma16/react-portfolio-template
はライセンス表記なし、rammcodes/Dopefolio は GPL-3.0 で、いずれも不採用になった。
star数だけで選ばないこと。
Step 4 — 適用
- 系統Aの場合:
get_add_command_for_itemsで得たコマンドをそのまま実行し、最後にget_audit_checklistを必ず走らせる - GitHub由来のコードをコピーする場合: ライセンス表記を保持し、ファイル冒頭に出典URLを コメントで残す
- 既存のデザイントークン（CSS変数 /
tailwind.config/globals.css）に合わせて色・角丸・ タイポを必ず上書き調整する。素のまま貼るとテンプレート臭が出る - 適用後の検証:
webapp-testingスキルまたは/runで実際に起動してスクリーンショットを撮り、 ユーザーに見せる
Step 5 — 出典とライセンスの記録
対象プロジェクト直下に docs/design-sources.md を作成/追記する。記録する項目:
- 日付
- 採用元（URL）
- ライセンス
- 取り込んだファイル
- 変更点
禁止事項
- 特定サイトのロゴ・画像・Lottie/動画アセット・コピー文をそのまま複製しない
- 非公開ソースをリバースエンジニアリングして貼り付けない（minified バンドルの復元を含む）
- GPL系ライセンスのコードを、ライセンス条件を満たさないまま取り込まない
- Figma MCP を「探索目的」で呼ばない（月20回の枠を浪費するため）
- APIキー・トークンの発行や入力は行わない。必要な場合はユーザーに依頼する