| name | design-system |
| description | デザインシステムの新規構築と既存ルールの強制を行う。トークン設計、コンポーネント設計、
プロジェクトセットアップ、日本語タイポグラフィをガイドする。
「デザインシステムを作りたい」「DS を構築」「コンポーネントライブラリを作る」
「トークンを設計」「デザインシステムに従って」などのリクエストで使用する。
|
Design System Skill
デザインシステムの構築から運用までをガイドするスキル。2 つのモードで動作する。
モード
構築モード
プロジェクトに .design-system/system.md が存在しない場合に適用。
トークン設計 -> 技術選定 -> プロジェクト初期化 -> コンポーネント実装の順にガイドする。
各フェーズの決定事項を .design-system/system.md に記録し、次のフェーズへ進む。
強制モード
プロジェクトに .design-system/system.md が存在する場合に適用。
ファイルに記録されたトークン、パターン、技術スタックに従ってコーディングを強制する。
モード検出
- プロジェクトルートで
.design-system/system.md を探す
- 存在する場合: 読み込んで強制モードへ
- 存在しない場合: ユーザーに確認して構築モードへ
構築モード
Phase 1: UI インベントリ(既存プロダクトがある場合)
既存プロダクトがある場合のみ実施。新規の場合は Phase 2 へ。
- 既存の UI をカテゴリ別に分類する(ボタン、フォーム、ナビゲーション、カード等)
- 同じ役割で見た目が異なる要素(矛盾)を洗い出す
- 使用頻度と重要度でランク付けする
- 統合すべき要素を特定する
出力: 矛盾リストと優先コンポーネントリストをユーザーに提示。
Phase 2: デザイン原則
ユーザーと対話して 3-5 個のデザイン原則を策定する。
質問する内容:
- プロダクトの性格は?(堅実/遊び心/ミニマル/情報密度高め等)
- 対象ユーザーは?(エンジニア/一般消費者/業務担当者等)
- 避けたい印象は?
- 参考にしたい既存のプロダクトやデザインシステムは?
各原則に Do/Don't の具体例を添える。
出力例:
1. 明確さ優先 - 装飾より情報の伝達を優先する
Do: ラベルを省略しない、エラー原因と対処法を両方伝える
Don't: アイコンだけで意味を伝えようとしない
決定内容を .design-system/system.md の Design Principles セクションに記録。
Phase 3: トークン設計
references/token-design.md を参照して以下を決定する。
決定事項:
- カラーパレット(Primitive 色 + Semantic マッピング + ダークモード)
- タイポグラフィスケール(ベースサイズ、比率、日本語フォント)
- スペーシングスケール(4px/8px grid)
- エレベーション(シャドウ 5 段階)
- ブレークポイント
- ボーダー(radius、width)
ユーザーにカラー候補を提示する際は、既存ブランドカラーがあるか確認する。
日本語フォントは references/japanese-typography.md を参照。
出力フォーマット(DTCG JSON):
{
"color": {
"primitive": {
"blue-500": { "$type": "color", "$value": "#3b82f6" }
},
"semantic": {
"primary": { "$type": "color", "$value": "{color.primitive.blue-500}" }
}
}
}
決定内容を .design-system/system.md の Tokens セクションに記録。
Phase 4: 技術スタック選定
references/tech-stack-guide.md を参照し、ユーザーと対話して決定する。
決定事項:
- UI フレームワーク(React / Vue / Svelte / フレームワーク非依存)
- スタイリング(Tailwind CSS v4 / Vanilla Extract / Panda CSS / CSS Modules)
- Headless UI 基盤(Radix UI / React Aria / Ark UI)
- バリアント管理(CVA / Tailwind Variants)
- ビルドツール(tsdown / Vite library mode)
- モノレポツール(pnpm workspaces + Turborepo)
- ドキュメント(Storybook 10)
- テスト(Vitest + Testing Library)
ユーザーの経験や好みに合わせて推奨構成を提案する。
迷った場合のデフォルト推奨: React + Tailwind v4 + Radix UI + CVA + tsdown + pnpm + Turborepo
決定内容を .design-system/system.md の Tech Stack セクションに記録。
Phase 5: プロジェクト初期化
references/project-setup.md を参照してモノレポを構築する。
design-system/
apps/
docs/ # Storybook
packages/
tokens/ # DTCG JSON + Style Dictionary
components/ # UI コンポーネント
icons/ # SVG -> コンポーネント変換
pnpm-workspace.yaml
turbo.json
package.json
各パッケージの初期ファイルを生成:
packages/tokens/: Phase 3 で決定したトークンを DTCG JSON で配置、Style Dictionary 設定packages/components/: Headless UI + バリアント管理のベース設定packages/icons/: SVG 変換パイプラインapps/docs/: Storybook 設定
Phase 6: コンポーネント実装
references/component-patterns.md を参照してコンポーネントを実装する。
推奨実装順:
- 基盤ユーティリティ:
cn() ヘルパー、型定義
- Button(バリアント管理のリファレンス実装)
- Input, TextArea, Select(フォーム要素)
- Card, Badge, Avatar(表示要素)
- Dialog, Popover, Tooltip(オーバーレイ)
- Tabs, Accordion(インタラクティブ)
各コンポーネントの実装時に守ること:
- Headless UI 基盤の振る舞い層とスタイル層を分離する
- バリアントは CVA/Tailwind Variants で型安全に定義する
- HTML ネイティブ属性を透過する(
...rest props)
- ARIA 属性とキーボードナビゲーションを含める
- Storybook ストーリーを同時に作成する
Phase 7: ドキュメント
Storybook のセットアップと拡張:
- Autodocs で Props テーブルを自動生成(
tags: ['autodocs'])
- MDX でガイドラインページを作成(デザイン原則、トークン一覧、使い方)
- a11y addon でアクセシビリティチェックを常時実行
- Interactions addon でインタラクションテストを統合
ドキュメントサイトが必要な場合は Astro Starlight を推奨。
Phase 8: 配布
npm パッケージとしての公開準備:
package.json の exports フィールドで ESM エントリを定義"sideEffects": false で Tree-shaking を有効化- Changesets でバージョニングとリリースノートを管理
- GitHub Actions で CI/CD パイプラインを構築
MCP サーバー化(オプション):
デザインシステムのトークンとコンポーネント情報を MCP 経由で AI エージェントに公開する。
日本企業の先行事例: Spindle MCP, kamii-mcp, MFUI MCP
強制モード
.design-system/system.md が存在する場合、以下のルールを適用する。
トークン準拠
- ハードコードされた色値(
#xxx, rgb())を使わない。トークン経由で参照する
- スペーシングはトークンで定義されたスケール値のみ使用する
- タイポグラフィはトークンで定義されたフォント、サイズ、行間のみ使用する
- system.md に定義されていない値を使う場合はユーザーに確認し、承認後に system.md を更新する
コンポーネントパターン準拠
- system.md で指定された Headless UI ライブラリを基盤にする
- バリアントは指定されたツール(CVA/Tailwind Variants)で管理する
- 新しいコンポーネントは既存パターンに従って実装する
- Compound Components パターンで構成する(props の羅列を避ける)
日本語タイポグラフィ準拠
references/japanese-typography.md と system.md の Japanese Typography セクションに従う:
- 指定フォントファミリを使用する
- 本文の line-height は指定値以上を維持する
- 全角・半角の混在ルールに従う
逸脱時の対応
ルールから逸脱する必要がある場合:
- 逸脱の理由を説明する
- ユーザーの承認を得る
- 承認された場合、system.md に例外として記録する
永続化: .design-system/system.md
構築モードの各フェーズで決定した内容を以下のフォーマットで保存する。
強制モードではこのファイルを読み込んでルールを適用する。
# Design System: [project-name]
## Design Principles
1. [原則名] - [説明]
Do: [具体例]
Don't: [具体例]
## Tokens
### Colors
- primitive: { blue-500: #3b82f6, ... }
- semantic: { primary: blue-500, background: white, ... }
- dark: { background: gray-900, ... }
### Typography
- font-family: "Noto Sans JP", sans-serif
- base-size: 16px
- scale-ratio: 1.25
- sizes: { xs: 10px, sm: 13px, base: 16px, lg: 20px, xl: 25px, 2xl: 31px }
### Spacing
- base: 4px
- scale: [4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80]
### Elevation
- level-0: none
- level-1: 0 1px 2px rgba(0,0,0,0.05)
- level-2: 0 4px 6px rgba(0,0,0,0.07)
- level-3: 0 10px 15px rgba(0,0,0,0.1)
- level-4: 0 20px 25px rgba(0,0,0,0.15)
### Border
- radius: { sm: 4px, md: 8px, lg: 12px, full: 9999px }
### Breakpoints
- sm: 640px, md: 768px, lg: 1024px, xl: 1280px
## Component Patterns
- headless-base: Radix UI
- variant-tool: CVA
- styling: Tailwind CSS v4
- component-style: Compound Components
## Tech Stack
- framework: React
- styling: Tailwind CSS v4
- build: tsdown
- monorepo: pnpm + Turborepo
- docs: Storybook 10
- test: Vitest + Testing Library
- versioning: Changesets
## Japanese Typography
- font: "Noto Sans JP", sans-serif
- line-height-body: 1.7
- line-height-heading: 1.3
- letter-spacing: 0.03em
## Exceptions
(ルールからの逸脱を記録)
References
