shadcn-tailwind-ui

shadcn + Tailwind UI

共通のコミュニケーション

TW の平易な表現とガイダンスのルールを適用してください。用語は初出時に説明し、ユーザーが選択した新人／入门／熟练／老手のレベルを維持し、どのレベルでも必要な変更やバグを説明してください。ソウルモードと文章モードを使用しても、この基本ルールは無効になりません。

プラグインのランタイム

このスキルをプラグイン、クラウドホスト、またはリモートマシン経由で実行する場合は、開始時にプラグイン実行契約を読み、ホスト固有のコマンドを実行する前に、ホスト、ツール、永続性の確認を適用してください。このスキルの範囲、認可、受け入れ基準を維持してください。

UI に変更を加える前に、shadcn-tailwind-ui ルートで $consult-tavernweave-library を使用し、A0、レスポンシブ／CSS ガイド、候補となるデザイン／モーションの参考資料を読み込んでください。ライブラリやビジュアルの方向性を選択しても、依存関係のインストールや既存設定の上書きが許可されるわけではありません。

既存の React コードベース内での実装作業には、このスキルを使用してください。新しいものを導入する前に、プロジェクトのフレームワーク、パッケージマネージャー、コンポーネントの規約、トークン、インストール済みの shadcn コンポーネントを維持してください。

デザインとレビューには、共通のフロントエンドデザイン品質 基準を使用してください。関連する事例を積極的に調査し、ユーザーの意図に沿った一貫性のある主要デザインを作成し、役立つ場合はビジュアルを使って説明してください。標準の Awwwards 品質基準を適用し、意味のない短いコピーや装飾的な英語テキストを取り除いてください。依頼された範囲内では、採用済みのプロジェクトの方向性を再利用してください。

範囲

• React、Vite、Next.js アプリケーション。
• Radix UI プリミティブを基盤とする shadcn/ui コンポーネント。
• Tailwind CSS ユーティリティ、セマンティックトークン、レスポンシブレイアウト、ダークモード、動きを減らす設定。
• フォーム、ダイアログ、ナビゲーション、テーブル、設定、ダッシュボード、空／エラー／読み込み状態などの製品 UI。

このスキルでは、フォント、画像、キャンバスデザイン、ポスターの生成、サードパーティ製コンポーネントのソースは提供しません。このスキルを再配布する前に、provenance.mdを読んでください。

ワークフロー

1. 変更する前にプロジェクトを調査します。
   • package.json、ロックファイル、components.json、CSS エントリーポイント、既存の UI コンポーネントを読みます。
   • React フレームワーク、Tailwind のメジャーバージョン、パスエイリアス、アイコンライブラリ、フォーム関連の構成、パッケージマネージャーを特定します。
   • 既存のユーザー変更を確認し、設定や生成済みコンポーネントを安易に置き換えないようにします。
2. 現在のシステムを再利用します。
   • 独自のプリミティブを並行して作成するより、インストール済みの shadcn コンポーネントを優先します。
   • セマンティックカラー、間隔、角丸、タイポグラフィ、モーションのトークンを再利用します。
   • 動作や繰り返し使用するバリエーションが必要な場合に限り、コンポーネントをローカルで拡張します。
3. 装飾より先に構造を実装します。
   • セマンティック HTML と論理的な見出し順を使用します。
   • ラベル、説明、エラーとの関連付け、視認できるフォーカス、キーボード操作、安定した読み込み／エラー／空の状態を用意します。
   • フォーカス管理を再実装するのではなく、Radix を基盤とするプリミティブを組み合わせて、ダイアログ、メニュー、タブ、セレクト、ポップオーバーを構成します。
4. モバイルファーストでスタイルを設定します。
   • 最小のサポート対象ビューポートから始め、その後、少数のブレークポイント上書きを追加します。
   • 折り返し、min-w-0、オーバーフローのルール、コンテンツの制約を意図的に使用します。
   • ライト／ダークテーマ、200％ズーム、動きを減らす設定、長いテキスト、タッチターゲットに対応します。
5. 実際のプロジェクトで検証します。
   • プロジェクトの型チェック、リンター、テスト、ビルドを、実用上最小の範囲で実行します。
   • キーボードのみでのナビゲーション、フォーカスの復帰、フォームエラー、レスポンシブのブレークポイント、ダークモード、動きを減らす設定を確認します。
   • レンダリングされた DOM と計算済みレイアウトを確認します。ビルドの成功だけでは、UI の動作が正しいとは限りません。

コンポーネントのルール

• アクションには Button を、ナビゲーションにはリンクを使用してください。通常の div 要素にクリック動作を設定しないでください。
• すべての入力にはアクセシブルな名前が必要です。エラーや説明は、それらが属する入力に関連付けてください。
• アイコンのみのコントロールには、アクセシブルなラベルと視認できるフォーカス状態が必要です。
• 破壊的なアクションには、明確な文言と影響に応じた確認が必要です。
• ダイアログには、タイトル、フォーカスの閉じ込め、Escape キーへの対応、トリガーへのフォーカス復帰が必要です。
• 散在する色のリテラルよりも、bg-background、text-foreground、text-muted-foreground などのセマンティックなトークンクラスを優先してください。
• コンパイラーが検出できない、実行時に組み立てる Tailwind クラスの断片は避けてください。完全なクラス名か、明示的なセーフリストを使用してください。
• prefers-reduced-motion を尊重してください。状態を伝える手段として、動きだけに頼ってはいけません。

Tailwind 設定の安全性

プロジェクトに既存の設定がある場合は、それを優先してください。Tailwind のバージョンによって仕様が異なるため、JavaScript／TypeScript の設定と CSS ファーストの @theme カスタマイズのどちらを選ぶか決める前に、インストールされているバージョンの公式ドキュメントを確認してください。

設定ファイルを意図的に使用するプロジェクト向けに、scripts/generate_tailwind_config.py は安全対策を施したヘルパーです。

# Default TypeScript format; dry run prints the proposed file and writes nothing.
python <skill-root>/scripts/generate_tailwind_config.py --framework react --format typescript --colors brand:#2563eb

# ESM JavaScript: tailwind.config.js with export default.
python <skill-root>/scripts/generate_tailwind_config.py --framework nextjs --format esm --write

# CommonJS: tailwind.config.cjs with module.exports; explicitly replace an existing file.
python <skill-root>/scripts/generate_tailwind_config.py --framework nextjs --format commonjs --force

tailwind.config.ts には typescript、tailwind.config.js には esm、tailwind.config.cjs には commonjs を選択してください。プロジェクトの既存のモジュールモードに合わせてください。ジェネレーターに合わせるためだけに package.json を変更しないでください。選択した形式によって、デフォルトの拡張子とエクスポート構文の両方が決まります。上書きできるのは --force を指定した場合のみです。出力された提案を確認し、使用する前にプロジェクト固有のコンテンツパス、プラグイン、トークンを保持してください。

shadcn コンポーネントのインストール

shadcn CLI はプロジェクトを変更する操作として扱ってください。

1. components.json とパッケージマネージャーを確認します。
2. 要求されたコンポーネントがすでに存在するか、ローカルで編集されているかを調べます。
3. プロジェクトに適した CLI のバージョンを固定するか、確認します。
4. 最小限の add コマンドを実行します。デフォルトでは --all を使用しないでください。
5. 生成された差分を確認し、プロジェクトのチェックを実行します。

ユーザーから明示的な許可を得ずに、ローカルで変更されたコンポーネントを上書きしないでください。

参考資料

• react-ui-checklist.md：実装と受け入れのための簡潔なチェックリストです。
• provenance.md：このクリーンな派生物における、ソースとライセンスの境界について説明しています。