setup-design-system

デザインシステムのワークフロー

Tailwind CSS と shadcn/ui を使用して、適切なアクセシビリティを備え、一貫性のある UI コンポーネントで、プロジェクトのデザインシステムを初期化または拡張します。

ステップ 0：フィーチャーブランチを確認する

最新の main をベースにしたフィーチャーブランチにいることを確認します。

git fetch origin main

main にいる場合は、新しいフィーチャーブランチを作成します。

git checkout -b feature/design-system origin/main

すでにフィーチャーブランチにいる場合は、最新の origin/main にリベースします。

git status --porcelain

作業ツリーに変更がある場合は、リベースする前に stash します。

git stash push -m "setup-design-system: stash before rebase"
git rebase origin/main
git stash pop

作業ツリーがクリーンな場合は、そのままリベースします。

git rebase origin/main

ステップ 1：現在の状態を評価する

すでにデザインシステムがあるかどうかを確認します。

• packages/ui/ ディレクトリ構成を確認する
• shadcn/ui の設定（components.json）を確認する
• Tailwind の設定を確認する（v4 では src/index.css の @theme ディレクティブ、v3 では tailwind.config.*）
• 既存のコンポーネントとそのパターンを特定する
• デザイントークン（色、余白、タイポグラフィの定義）を確認する

ユーザーに質問します。

• 新しいデザインシステムを初期化しますか、それとも既存のものを拡張しますか？
• 拡張する場合：どのコンポーネントやパターンが必要ですか？
• 参考にするブランドガイドライン、カラーパレット、Figma デザインはありますか？
• ダークモードへの対応は必要ですか？

ステップ 2：プロダクト評議会によるデザインレビュー（初期化または大幅な変更の場合）

デザインシステムを初期化する場合、または構造に大幅な変更を加える場合は、プロダクト評議会の一部メンバーを招集します。

モデルの選択：エージェントのモデル仕様を Task ツールのパラメーターに対応付ける方法については、README.md の モデルの選択 セクションを参照してください。

デザインリード（リード）— 相談先：ui-design

• ブランドアイデンティティ：カラーパレット、タイポグラフィ、ビジュアル表現
• コンポーネント階層：プリミティブと合成コンポーネント
• デザイントークン：トークンの設計（色、余白、タイポグラフィ、シャドウ）
• 推奨事項：デザインシステムの構成と原則

フロントエンドスペシャリスト — 相談先：frontend-mobile-development

• 技術アーキテクチャ：コンポーネントライブラリの構成、ビルドパイプライン
• フレームワークとの統合：Vite + React 19 との互換性、ツリーシェイキング
• 推奨事項：実装パターン、ツールの選択

プロダクトストラテジスト

• ユーザー向けの優先事項：最初に必要なコンポーネントはどれですか？
• ブランドの一貫性：プロダクトのビジョンに沿っていますか？
• 推奨事項：デザインシステムへの投資の優先順位

チェックポイント：デザインシステムのアーキテクチャ案をユーザーに提示します。構成とトークン定義の承認を得てから、構築を開始してください。

ステップ 3：デザインシステムの基盤

新しいデザインシステムを初期化する場合：

初期化のガイダンスとして /ui-design:design-system-setup を呼び出します。

基盤をセットアップします。

デザイントークン

• カラーパレット（プライマリ、セカンダリ、ニュートラル、セマンティック：成功／警告／エラー／情報）
• タイポグラフィのスケール（フォントファミリー、サイズ、ウェイト、行の高さ）
• 余白のスケール（一貫した余白の値：0、1、2、3、4、6、8、12、16、24、32、48、64）
• 角丸（なし、sm、md、lg、xl、full）
• シャドウ（sm、md、lg、xl）
• ブレークポイント（sm、md、lg、xl、2xl）

Tailwind の設定 /frontend-mobile-development:tailwind-design-system を使用します。

• Tailwind テーマをデザイントークンで拡張する
• プロジェクト固有のテーマカラーで shadcn/ui を設定する
• ランタイムのテーマ設定用に CSS カスタムプロパティをセットアップする
• ダークモードの方式（クラスベースまたはメディアクエリ）を設定する

コンポーネント構成

packages/ui/src/
├── components/
│   ├── primitives/    # Button, Input, Badge, Label, Switch
│   ├── layout/        # Container, Grid, Stack, Spacer, Divider
│   ├── navigation/    # Navbar, Sidebar, Breadcrumb, Tabs
│   ├── feedback/      # Alert, Toast, Modal, Dialog, Skeleton
│   ├── data-display/  # Card, Table, List, Avatar, Tooltip
│   └── forms/         # Form, FormField, Select, Checkbox, Radio
├── tokens/            # Design token definitions
├── hooks/             # Shared UI hooks (useMediaQuery, useTheme)
└── utils/             # UI utilities (cn, cva variants)

既存のデザインシステムを拡張する場合：

新しいコンポーネントを追加する前に、既存のパターンと規約を確認します。確立されている API パターンに合わせてください。

ステップ 4：コンポーネントを構築する

必要なコンポーネントごとに、次の手順に従います。

4a. コンポーネントの設計

コンポーネントの作成をガイドするため、/ui-design:create-component を呼び出します。

コンポーネント API を定義します。

• Props インターフェース：TypeScript の型を使った、設定可能なすべてのオプション
• バリアント：サイズ、色、スタイルのバリアント（cva または tailwind-variants を使用）
• デフォルト値：すぐに使える、適切なデフォルト値
• コンポジション：子コンポーネントとの連携方法

4b. 実装

各コンポーネントは、次の要件に沿って構築します。

• any 型を使わず、TypeScript の型を完全に指定する
• shadcn/ui のパターンに沿って Tailwind CSS でスタイルを設定する
• ref を転送するために React.forwardRef を使用する
• cn() ユーティリティで className prop を結合し、スタイルを上書きできるようにする
• Tailwind のブレークポイントを使ってレスポンシブに対応する

4c. アクセシビリティ

各コンポーネントには、次の要素を含める必要があります。

• セマンティックな HTML 要素（button、nav、dialog など）
• ARIA 属性（aria-label、aria-describedby、role など）
• キーボード操作（適切に Tab、Enter、Escape、矢印キーを使用）
• フォーカス管理（視認できるフォーカスリング、モーダルのフォーカストラップ）
• 動的コンテンツをスクリーンリーダーに通知する機能
• WCAG AA に準拠した色のコントラスト（テキストは 4.5:1、大きなテキストは 3:1）
• タッチターゲットの最小サイズ（インタラクティブな要素は 44x44px）

4d. テスト

各コンポーネントについて、次のテストを作成します。

• レンダリングテスト：コンポーネントがエラーなくレンダリングされる
• Props テスト：すべてのバリアントと prop の組み合わせが正しくレンダリングされる
• インタラクションテスト：クリック、ホバー、キーボード操作が機能する
• アクセシビリティテスト：ARIA 属性が存在し、キーボード操作が機能する

チェックポイント：各コンポーネント（または関連コンポーネントの一括実装）後に、視覚的な確認のため実装内容をユーザーに提示します。コンポーネント API、バリアント、アクセシビリティ機能を示してください。

ステップ 5：アクセシビリティ監査

すべてのコンポーネントの構築後、包括的なアクセシビリティ監査を実施します。

新規または変更したすべてのコンポーネントに対して /ui-design:accessibility-audit を実行します。

次の点を確認します。

• WCAG 2.1 AA 準拠（最低基準）
• 色のコントラスト：すべてのテキストがコントラスト比の基準を満たしている
• キーボード操作：キーボードですべての操作を行える
• スクリーンリーダー：すべてのインタラクティブな要素が正しく読み上げられる
• フォーカス管理：論理的なフォーカス順序と、視認できるフォーカスインジケーター
• モーション：prefers-reduced-motion メディアクエリに準拠する
• タッチターゲット：モバイルで最小 44x44px を確保する

チェックポイント：アクセシビリティ監査の結果を提示します。ユーザーはアクセシビリティの状態を承認するか、変更を依頼します。

ステップ 6：デザインレビュー

全体的なデザインシステムを次の観点からレビューするため、/ui-design:design-review を実行します。

• 一貫性：すべてのコンポーネントが同じパターンに従っている
• 命名：Props、バリアント、CSS クラスが規約に従っている
• API パターン：コンポーネント間で prop インターフェースに一貫性がある
• 視覚的な調和：各コンポーネントが一体感のある見た目になっている
• 網羅性：一般的なユースケースに対応している

レビューで指摘された事項に対応します。

ステップ 7：ドキュメント

デザインシステムをドキュメント化します。

• コンポーネントカタログ：各コンポーネントの props テーブル、使用例、推奨事項と避けるべきパターン
• デザイントークン：色、タイポグラフィ、スペーシングの完全なリファレンス
• アクセシビリティガイド：コンポーネントごとのアクセシビリティに関する注意事項とテスト手順
• はじめに：アプリでコンポーネントをインポートして使用する方法

ステップ 8：コミット

Conventional Commits 形式でコミットします。

新しいデザインシステムの場合：

feat(ui): initialize design system with core components

新しいコンポーネントの場合：

feat(ui): add <component-name> component

デザイントークンを変更する場合：

feat(ui): update design tokens for <change-description>

ステップ 9：引き継ぎ — ここで停止

注意

このスキルの作業は完了です。 プルリクエストの作成、リモートへのプッシュ、コードレビューは続けて行わないでください。これらはそれぞれ独自のワークフローとチェックポイントを持つ別のスキルです。

次のステップをユーザーに提示します。

• 推奨：提出前に、複数の視点から品質とアクセシビリティをレビューするため /review-code を実行する
• これらのコンポーネントを使う機能を構築する場合：/build-feature を続けて実行して機能を実装し、その後 /review-code を実行する
• 独立したデザインシステムの作業の場合：/review-code → /submit-pr を実行する

ヒント

パイプライン：/plan-feature → /build-feature または /build-api → /review-code → /submit-pr

/setup-design-system はパイプラインの任意の時点で、または単独で実行できます。現在はここまで進んでいます。準備ができたら /review-code に進んでください。

このスキル内からブランチをプッシュしたり、PR を作成したり、/submit-pr を実行したりしないでください。