shadcn

shadcnスキルの概要

shadcnスキルは何のためのものか

shadcnスキルは、AIアシスタントが実際のshadcn/uiプロジェクト内で正しく作業できるようにするためのものです。コンポーネントを見つける、適切なCLIでインストールする、既存のプリミティブを組み合わせて画面を構成する、そしてプリセットやコンポーネントファミリーごとのよくあるAPIミスを避ける、といった作業に向いています。単に「ボタンを生成して」で終わらず、components.json、インストール済みのregistry item、使っているテンプレート、さらにbaseとradixの違いまで踏まえた出力が欲しいときに特に有効です。

このshadcnスキルを使うべき人

特に相性がいいのは、次のような人たちです。

• すでにshadcn/uiを使っている開発者
• presetやregistry中心のUIワークフローを導入しているチーム
• AIにフォーム、ダイアログ、設定ページ、ダッシュボード、テーマ対応の追加やリファクタを任せたい人
• JSXを書く前に、アシスタントにプロジェクト文脈を確認してほしい人

逆に、shadcn/ui、components.json、shadcn CLIを使っていないなら、このスキルはやや用途特化すぎるはずです。

実際に解決したい仕事

ユーザーが欲しいのは、単なるリポジトリ要約ではありません。求めているのは、アシスタントが次のことをできることです。

1. プロジェクトのshadcn構成を見抜く
2. 新規実装をでっち上げる前に既存コンポーネントを選ぶ
3. 正しいCLIコマンドとドキュメントにあるflagだけを使う
4. ライブラリ推奨のパターンでUIを組み立てる
5. triggerの組み方の違い、group wrapperの不足、フォームバリデーション接続ミスのような地味な破綻を避ける

ここが、普通のUIプロンプトよりもshadcnスキルが価値を出せるポイントです。

汎用プロンプトと比べてshadcnが違う点

差が出るのは、かなり実務的なところです。

• npx shadcn@latest info --jsonで取得するプロジェクト文脈から始める
• カスタム実装より前にsearch、view、docsを重視する
• rules/composition.md、rules/forms.md、rules/styling.md、rules/base-vs-radix.mdのようなファイルからプロジェクトルールを取り込んでいる
• 単なるコンポーネント断片ではなく、themeやpreset切り替えまでカバーする
• registry検索やインストールのワークフロー向けにMCPの案内も含んでいる

要するに、shadcnスキルは「Reactを書く」ためのものというより、「このshadcn構成に合った正しいReactを書く」ためのものです。

導入前に知っておきたい制約

このスキルを前提に進める前に、次の制約は押さえておいてください。

• shadcn CLIをプロジェクトのpackage runner経由で使えることを前提にしている: npx、pnpm dlx、bunx --bun
• 使えるのはドキュメント化されたCLI flagの範囲内で、flagの捏造は明確に非推奨
• 良い出力の多くは、有効なcomponents.jsonがあることに依存する
• APIの細部はpresetやbase/radixで変わるので、サンプルの流用を鵜呑みにすると壊れやすい

shadcnスキルの使い方

shadcnスキルの導入前提

まずはディレクトリ標準のインストール手順でAI環境にスキルを追加し、そのうえで実際にshadcn構成を持っている、またはこれから持たせる予定のリポジトリで使ってください。実務上は、スキルの導入コマンドそのものよりも、リポジトリ側の条件のほうが重要です。アシスタントがプロジェクトファイルにアクセスでき、shadcn CLIコマンドを実行できる状態である必要があります。

対象プロジェクト内で重要になる実行コマンドは次のとおりです。

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

プロジェクトのpackage managerに合わせて、必要ならpnpm dlx shadcn@latestやbunx --bun shadcn@latestに置き換えてください。

出力を頼む前に、まず読むべきファイル

shadcnスキルを速く正確に使うなら、だいたい次の順で確認すると効率的です。

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

この順番が機能する理由は次のとおりです。

• SKILL.mdで発火条件とワークフロー全体をつかめる
• cli.mdで、推測ベースのコマンドやflagを防げる
• rules/配下には、汎用コード生成がやりがちなミスがまとまっている
• customization.mdは、生のTailwind色指定ではなくthemeに強いスタイリングが必要なときに重要
• mcp.mdは、shell実行よりMCP経由でregistryを見られる環境なら特に効いてくる

shadcnタスクは毎回プロジェクト調査から始める

最初の一手として最も効果が高いのは、これです。

npx shadcn@latest info --json

これで、コンポーネントやプロジェクト構成を含む、現在の設定状況をアシスタントが把握できます。特に役立つのは次の点です。

• components.jsonの有無を確認する
• インストール済みコンポーネントを特定する
• 妥当なコード選択に影響するセットアップ差分を検出する
• package runnerを確認し、誤ったコマンド例を避ける

ここを飛ばすと、shadcnスキルはかなり汎用プロンプト寄りになってしまいます。

ざっくりした依頼を、強いshadcnプロンプトに変える

弱いプロンプト:

Build me a profile dialog with shadcn.

より良いプロンプト:

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

これが強い理由は次のとおりです。

• まずプロジェクト調査を強制できる
• preset依存の挙動を指定できる
• iconやstylingの制約を明示できる
• 依存コンポーネント不足時に、実装前の導入手順を要求できる

カスタムコードの前にsearchとdocsを使う

質の高いshadcnワークフローは、次の流れです。

1. registryから既存コンポーネントを探す
2. docsとexampleを確認する
3. 足りないものだけ追加する
4. そのうえで画面を組み立てる

実用的なコマンド例:

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

これは特に、フォーム、オーバーレイ、ナビゲーション、empty stateで重要です。これらは場当たり的なdiv構造よりも、ライブラリの定石パターンを優先するようルール化されているためです。

既存の構成部品を組み合わせて画面を作る

shadcnスキルが最も力を発揮するのは、巨大な独自UIを一発で作らせるときではなく、既存部品の組み合わせを任せるときです。良いタスクの切り方としては、たとえば次のようなものがあります。

• 「settings page = Tabs + Card + form controls」
• 「dashboard = Sidebar + Card + Chart + Table」
• 「empty state = Empty component, not a custom centered div」
• 「callout = Alert, not hand-rolled border boxes」

これは、スキルが想定する基本方針そのものです。まず既存コンポーネントを使い、必要になったときだけvariantやwrapperで調整します。

baseとradixの違いを必ず尊重する

shadcn導入時につまずきやすい大きな原因のひとつが、「どのshadcn例も相互に置き換え可能」と思い込むことです。実際にはそうではありません。

このスキルには、baseとradixの違いに関する明示的なガイドがあります。主な論点は次のとおりです。

• asChildとrenderの違い
• trigger compositionの違い
• 一部のbase専用ケースでのnativeButton={false}
• Select、ToggleGroup、Slider、AccordionなどのコンポーネントAPI差分

プロンプトに利用中の構成が書かれていないなら、npx shadcn@latest infoから判別するようアシスタントに指示してください。

テーマを壊さないスタイリング指針を使う

UI Design用途でshadcnを使うなら、固定のTailwindカラーよりも、semantic tokenとCSS variableベースのtheme設計を使ったほうが結果が安定します。

推奨されるのは、たとえば次のような指定です。

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

逆に、安易に次へ寄せるのは避けたいところです。

• bg-red-500
• text-gray-400
• 大量の手書きdark:上書き

これは、customization.mdで説明されているとおり、コンポーネントがCSS variableを継承する前提だからです。アシスタントがsemantic tokenを使えば、light/dark themeやpresetをまたいでも設計が破綻しにくくなります。

フォームはshadcn流で扱う

evalsやrulesを見ると、フォーム品質はかなり重視されています。shadcnで質の高いフォームにするには、たいてい次の点が重要です。

• 生の積み重ねdivではなく、用意されたfield layout patternを使う
• invalid状態をdata-invalidとaria-invalidで明示する
• 独立したオン/オフ設定にはSwitchを使う
• ルールで求められている場面では、space-y-*よりgap-*を優先する

バリデーションを含む作業なら、その点をプロンプトで明示してください。そこを言わないと、見た目だけそれらしいがライブラリ整合性の低いフォームを生成するアシスタントは少なくありません。

エディタが対応していればMCPを使う

利用環境がMCP対応なら、registryまわりの操作でshadcnスキルの信頼性はさらに上がります。mcp.mdには、次のようなツール利用がまとまっています。

• project registriesの一覧取得
• registry itemの検索
• item詳細やファイル内容の閲覧
• exampleの取得
• itemのインストール

これは、CLI出力だけに頼らず、会話しながらregistryを探索したい場合に便利です。ただし、プロジェクト設定の把握という意味ではinfo --jsonの代わりにはなりません。

shadcn活用のための実用プロンプトテンプレート

より質の高い出力が欲しいなら、次のテンプレートが使えます。

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

shadcnスキル FAQ

このshadcnスキルはコンポーネントのインストール専用ですか？

いいえ。shadcn install系の作業も守備範囲ですが、スキルの対象はもっと広いです。プロジェクト調査、registry検索、コンポーネントの組み立て、theme対応、デバッグ、preset切り替え、API整合性を保ったリファクタまで含まれます。

shadcnスキルは初心者向けですか？

はい。ただし、Reactとpackage managerの基本にある程度慣れていることが前提です。このスキルは、アシスタントを正しいコマンドやルールへ誘導することで、推測に頼る部分を減らしてくれます。一方で、React、Tailwind、デザインシステムをゼロから学びたい人向けの総合入門としてはあまり親切ではありません。

どんなときshadcnは普通のプロンプトより有利ですか？

shadcnスキルを使うべきなのは、正しさがプロジェクト文脈に強く依存するときです。

• 既存のcomponents.jsonがある
• インストール済みコンポーネントとの整合が必要
• baseとradixの挙動差がある
• ドキュメント化されたCLI flagだけを使いたい
• theme tokenやライブラリのcomposition ruleを守りたい

普通のプロンプトでもそれらしいJSXは出せますが、インストール手順を落としたり、コンポーネントAPIを誤用したりする確率は高くなります。

どんな場合はshadcnスキルを使わないほうがいいですか？

次のケースでは無理に使わなくて大丈夫です。

• プロジェクトがshadcn/uiを使っていない
• 汎用的なHTML/CSSモックだけ欲しい
• 特定のデザインシステムに依存しない回答が欲しい
• アシスタントがファイル確認もコマンド実行もできず、必要な文脈を手動で渡すことも難しい

こうした場合は、より広い用途のfrontendスキルのほうが合うことがあります。

このスキルはshadcn for UI Designの判断にも役立ちますか？

はい。特にcompositionとthemingの判断で役立ちます。再利用しやすいプリミティブ、semantic color token、正しいoverlay pattern、そして一回限りの手作りレイアウトより保守しやすいコンポーネント構造へ、アシスタントを自然に寄せてくれます。

AI出力でshadcn利用が壊れやすいのはどこですか？

典型的な失敗は次のとおりです。

• 未対応のCLI flagを捏造する
• baseとradixでtrigger compositionを取り違える
• 既存registry componentを使わず独自UIを作る
• theme systemと衝突する生の色指定でスタイリングする
• title、group、fallbackのような必須サブコンポーネントを省く

まさにこうした部分を引き締めるために、このスキルがあります。

shadcnスキルをより活かすには

足りない文脈は最初にまとめて渡す

最も効く改善策は、入力の質を上げることです。少なくとも次の情報を含めると効果的です。

• frameworkやtemplate（next、vite、astroなど）
• components.jsonの有無
• わかっていればbaseかradixか
• 現在のicon set
• 対象コンポーネントまたは画面
• install、refactor、bugfixのどれを含む作業か

具体的な文脈が一文あるだけでも、アシスタントが間違ったAPIを選ぶ確率はかなり下がります。

コンポーネント不足の可能性があるなら、コードより先にコマンドを求める

必要なコンポーネントが未導入かもしれないなら、こんなふうに促すと効果的です。

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

こうすると、環境変更と実装を切り分けられるため、結果を信頼しやすくなり、適用もしやすくなります。

壊れやすいコンポーネント種別では、ルール準拠を明示する

フォーム、ダイアログ、dropdown、sheet、drawer、selectのような壊れやすい領域では、rule fileに従うよう明示してください。たとえば次のように書けます。

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

これは重要です。質の低い生成は見た目だけ整っていても、アクセシビリティやcomposition contractを壊していることがよくあります。

デザイン制約を具体化してshadcn利用の精度を上げる

良いUIプロンプトは、単に「モダンにして」で終わりません。たとえば次のような制約を入れてください。

• semantic tokenのみ使用
• 生のpalette utilityは禁止
• dark modeは手動overrideなしで成立させる
• カスタムclassより先に既存variantを使う
• empty state、alert、separator、badge、skeletonはライブラリ既存部品を優先する

こうした指定は、shadcn for UI Designの初回出力品質を実際に大きく押し上げます。

全面書き直しではなく、狙いを絞って修正させる

最初の出力後に、ただ「もう一回」だけを返すのは得策ではありません。代わりに、次のように具体的に指示します。

• 「Refactor this to use installed shadcn components only.」
• 「Make this valid for base, not radix.」
• 「Replace raw color classes with semantic tokens.」
• 「Add the missing title/fallback/group wrappers required by shadcn.」
• 「Show the exact shadcn add commands for anything assumed.」

こうすれば、良い部分を残しながら、壊れやすい箇所だけを的確に直せます。

リポジトリ内の強い根拠と照合して検証する

信頼性を上げるには、出力を次のファイルと照らし合わせて確認するのが近道です。

• コマンドとflagはcli.md
• 構造はrules/composition.md
• API整合性はrules/base-vs-radix.md
• バリデーションとレイアウトはrules/forms.md
• theme安全なstylingはrules/styling.mdとcustomization.md
• 実際に何が「良い出力」かはevals/evals.json

これが、shadcnスキルの出力が単なる汎用UIコードなのか、それともリポジトリに沿った実用的な出力なのかを見極める最短ルートです。