specsfy-specialist-shadcn-ui

shadcn/ui

Promovaweb の React と Tailwind のインターフェース向けに、このスキルはプリミティブ、components.json、エイリアス、テーマを準備します。画面に CRUD やプロダクトの組み立てが必要な場合は、$specsfy-specialist-reui も併せて読み込んでください。このスキルは、まず無料の ReUI コンポーネントをこの基盤に追加します。

使用する場合

• プロジェクトに components.json や組み込み済みの shadcn コンポーネントがある場合、または shadcn/ui のコンポーネント（Data Table、Sidebar、Dialog、Form、Chart）を明示的に求められた場合に使用します。
• パターン（ダッシュボード、フォーム、オーバーレイ）を組み立てる前に、プロジェクトの shadcn/ui が Base UI、Radix、React Aria のどれを使用しているか特定する場合にも使用します。
• Tailwind のトークンやユーティリティ自体を扱う場合は使用しません。その場合は $specsfy-specialist-tailwind-css と組み合わせてください。
• プロジェクトで異なるビジュアルコンポーネントライブラリ（コピー可能な非 Radix のライブラリ）を使用している場合は使用しません。その場合は $specsfy-specialist-react-ui-components と $specsfy-specialist-ui-design の組み合わせを検討してください。
• Radix プリミティブですでに確保されているアクセシビリティを超える詳細な監査には、$specsfy-specialist-web-accessibility と組み合わせてください。

手順

1. コンポーネントを追加する前に、フレームワーク、shadcn/ui のバージョン、components.json（インポートエイリアス、スタイル、CSS variables）、設定済みのレジストリを確認します。
2. 使用中のプリミティブ基盤を特定します。まず組み込み済みの shadcn コンポーネントのインポートを調べ、manifest で確認します。@base-ui/react は Base UI、radix-ui または @radix-ui/react-* は Radix、react-aria-components または @react-aria/* は React Aria として分類します。コンポーネントが複数の基盤を使用している場合や、判断材料が足りない場合は、ファイルごとに基盤を記録し、不一致が解消されるまでプリミティブの追加、移行、書き換えを行いません。
3. 同等のコンポーネントがすでに存在する場合の重複や不整合を避けるため、新しいコンポーネントを追加する前に、プロジェクトに組み込まれているコンポーネントとローカルのカスタマイズを監査します。
4. デザインに最も近い見た目ではなく、必要な動作とセマンティクス（モーダルダイアログ、ポップオーバー、サイドシート）に基づいて、特定した基盤のプリミティブを選びます。
5. 必要最小限のコンポーネントを追加し、生成されたコードを1行ずつ確認します。コードはプロジェクトにコピーされ、追加した人が保守することになります。
6. 特定した基盤が提供する roles、aria-*、フォーカス管理、キーボードショートカットを削除せずに、プロジェクトのデザインに合わせてトークン、バリアント（cva）、コンポジションを調整します。
7. ドキュメントに示された標準状態だけでなく、コンポーネントの実際の状態（loading、empty、error、disabled、permission denied）をすべて作成します。
8. コンポーネントの完成とする前に、キーボード操作、フォーカス、レスポンシブ対応、フォームの送信、ライトテーマとダークテーマの両方をテストします。
9. 作成、変更、再利用した各プリミティブまたはブロックについて、ファイル、出所、目的、API、状態、アクセシビリティ、利用者、拡張方法を含めて INTERFACE.md を更新します。

規約

• shadcn/uiを、パッケージ内でバージョン管理される不透明な依存関係として扱わないでください。コピーしたコードはプロジェクトに属するものであり、そこで発生するバグやアクセシビリティ上の逸脱は、ライブラリではなくチームの責任です。
• 特定した基盤固有のAPI、状態属性、コンポジションのみを使用してください。Base UI、Radix、React Ariaは似た契約を公開していますが、インポート、props、属性に互換性はありません。
• 基盤が提供する場合は、ARIAロール、ラベル、フォーカス管理（初期フォーカス、フォーカストラップ、トリガーへのフォーカス復帰）、Escapeキーの動作を維持してください。見た目のカスタマイズによって、これらの動作を取り除いてはいけません。
• テーマトークン（CSS variables）は1か所に集約してください。ブランドカラーの変更やテーマの調整のために、何十ものコンポーネントを個別に編集してはいけません。
• PromovawebのReactプロジェクトでは、shadcn/uiとReUIを併用してください。前者はプリミティブ、後者は無料のプロダクト向けコンポジションを担います。すべての画面はReactコンポーネントのコンポジションであり、単一の巨大なファイルではありません。
• あらゆる機能を「念のため」備えた汎用コンポーネントをインポートするのではなく、実際のユースケース（必要な列、並べ替え、フィルター、選択、ページネーション）に合わせてData Tableを構成してください。
• Sidebarはビューポートに応じて動作し（モバイルでは折りたたむ）、ナビゲーションの密度に配慮し、現在のルートを視覚的にわかりやすく強調してください。
• すべてのフォームをサーバー側でも検証してください（クライアント側の検証はUXのためであり、セキュリティ対策ではありません）。各エラーメッセージは、aria-describedby/labelを使って対応するフィールドに関連付けてください。
• すでにカスタマイズ済みのコンポーネントを更新する際は、新しいregistryのバージョンとローカルのカスタマイズとの差分を比較してからにしてください。安易にaddすると、以前に行ったアクセシビリティの修正が上書きされることがあります。

アンチパターン

• 同じ公開APIを持つという理由で、shadcn/uiのすべての実装がRadixを使っていると思い込むこと。これにより、Base UIやReact Ariaと互換性のないインポートやpropsが持ち込まれます。
• shadcn/uiのDialogをインポートし、「見た目上は冗長」という理由でaria-describedby/タイトルを削除すること。ダイアログの目的に関するスクリーンリーダーの読み上げが損なわれます。
• トークンや中央のvariantを調整する代わりに、スタイルを「修正」するために生成済みコンポーネントのファイルを編集すること。次にコンポーネントを更新する人は、その修正があったことを知らずに失ってしまいます。
• Data Tableをシステム内のあらゆるテーブル向けの単一の汎用コンポーネントとして扱い、理解できなくなるまで条件付きpropsを増やすこと。registryのブロックから、ユースケースごとにテーブルを構成してください。
• クライアント側だけでフォームを検証し（フロントエンドにschemaを置き）、サーバー側では検証を繰り返さないこと。エンドポイントへの直接リクエストはフォームの検証を回避できます。
• 事前に差分を確認せず、カスタマイズ済みのコンポーネントにshadcn addを実行し、ローカルで施したアクセシビリティやビジネス上の調整を気付かないまま失うこと。

検証

• コンポーネントを追加または変更した後、プロジェクトのtypecheck、lint、テスト、buildを実行してください。
• キーボードだけですべてのナビゲーションを操作してください。オーバーレイの開閉、Dialog/Sheet内のフォーカストラップ、開いた要素へのフォーカス復帰を確認してください。
• モバイルとデスクトップ、ライトテーマとダークテーマ、高いズーム倍率、テーブルセルやラベル内の長いコンテンツ／省略表示をテストしてください。
• 画面で実際に使うテーブルの状態（空、読み込み中、エラー、データあり）、グラフ（データなし、データあり）、フォーム（処理中、エラー、成功、値を保持したまま失敗後に再度開く）、sidebar（折りたたみ、展開、アクティブなルート）を確認してください。
• shadcn/ui由来というだけでコンポーネントを「アクセシブル」と宣言しないでください。そう宣言する前に、カスタマイズしたものはすべて上記の確認を完了している必要があります。

関連スキル

• $specsfy-specialist-astro は、React のプリミティブを Astro のアイランドとして使用する際の統合とハイドレーションを担当します。
• $specsfy-specialist-tailwind-css は、コンポーネントのテーマを支えるトークンとユーティリティのシステムを扱います。
• $specsfy-specialist-react は、各 shadcn/ui プリミティブの背後にある React コンポーネントの状態管理ロジック、エフェクト、テストを扱います。
• $specsfy-specialist-typescript は、cva のバリアントとフォームスキーマ（zod + react-hook-form）の型付けを扱います。
• $specsfy-specialist-nextjs は、フォームを Server Action に送信する場合に使用します。サーバーサイドの検証と認可はこのスキルの対象です。
• $specsfy-specialist-react-ui-components と $specsfy-specialist-ui-design は、プロジェクトでより幅広いビジュアルリファレンスのギャラリーや、ページ構成の定義が必要な場合に使用します。
• $specsfy-specialist-web-accessibility は、インストール済みのベースが標準で提供する範囲を超える監査に使用します。
• $specsfy-specialist-application-security は、サーバー上でのフォーム検証と、Server Actions／エンドポイントで公開されるミューテーションの認可に使用します。

shadcn/ui コンポーネントを変更する前に、インストール済みのベースを確認するため、references/primitives.md をお読みください。 registry、ダッシュボードのパターン、Data Table、フォーム、オーバーレイ、チャートについて公式ソースとともに説明している references/standards.md をお読みください。