design-integration

デザイン統合

概要

プロジェクトのデザインシステムを検出し、全面的に活用し、認められた方法でのみ拡張します。決して逆らわず、見落とさず、すでに提供されているものを作り直さないでください。

基本原則： プロジェクトにデザインシステムがある場合、作成するすべてのコンポーネントで、そのシステムのプリミティブ、トークン、パターンを使用する必要があります。システムがない場合は、コンポーネントを書く前に確立してください。

例外なし。回避策なし。近道なし。

最優先の指示

NEVER REBUILD WHAT THE DESIGN SYSTEM ALREADY PROVIDES

システムに<Dialog>コンポーネントがあれば、それを使用してください。独自のものをでっち上げないでください。スタイルを上書きするコンテナで囲まないでください。バリアント API を使用し、文書化された拡張ポイントを通じてのみ拡張してください。

使用するタイミング

必須となる場合：

• ユーザーインターフェースのある既存のコードベースに取り組むとき
• 確立されたアプリケーションに新しい UI 要素を導入するとき
• プロジェクトのコンポーネントライブラリを拡張するとき
• UI レイヤーを備える新しいプロジェクトを初期化するとき

具体的な該当条件：

• @shadcn/ui、@mui/material、antd、@chakra-uiなど、または同等のパッケージをインポートしている
• 基本レベルのプリミティブを含むcomponents/uiディレクトリがある
• tailwind.config、theme.ts、デザイントークンファイルなどの設定ファイルがある
• システムがないプロジェクトに UI を追加する必要がある

導入プロトコル

BEFORE authoring any UI component:

1. DETECT: What design system governs this project? (see Detection below)
2. STUDY: Read the system's component API for the element you are building
3. ASSESS: Does the system already provide this component?
   - Yes -> Consume it directly. Do NOT recreate it.
   - Partially -> Compose from existing primitives
   - No -> Build it adhering to the system's conventions
4. VALIDATE: Does your component feel native to the system?

Omit any step = fighting the system

検出手順

digraph detect_system {
    rankdir=TB;
    start [label="New project or\nnew component", shape=doublecircle];
    check_deps [label="Inspect package.json\nfor UI frameworks", shape=box];
    known [label="Recognized design\nsystem present?", shape=diamond];
    check_code [label="Search source tree\nfor UI import patterns", shape=box];
    has_custom [label="Internal component\nlibrary found?", shape=diamond];
    check_tokens [label="Look for\ndesign token definitions", shape=box];
    has_tokens [label="Token file\ndetected?", shape=diamond];
    adopt_known [label="ADOPT\nUse the recognized system", shape=box, style=filled, fillcolor="#ccffcc"];
    adopt_internal [label="ADOPT\nFollow internal library conventions", shape=box, style=filled, fillcolor="#ccffcc"];
    bootstrap [label="BOOTSTRAP\nInitialize a design system", shape=box, style=filled, fillcolor="#ccccff"];
    extend_tokens [label="BUILD\non existing token foundation", shape=box, style=filled, fillcolor="#ccffcc"];

    start -> check_deps;
    check_deps -> known;
    known -> adopt_known [label="yes"];
    known -> check_code [label="no"];
    check_code -> has_custom;
    has_custom -> adopt_internal [label="yes\n(components/ui\nor equivalent)"];
    has_custom -> check_tokens [label="no"];
    check_tokens -> has_tokens;
    has_tokens -> extend_tokens [label="yes"];
    has_tokens -> bootstrap [label="no"];
}

フェーズ 1：依存関係を調べる

依存関係	システム	方針
@radix-ui/*、class-variance-authority	shadcn/ui	shadcn のファイルおよびバリアントの規約に従う
@mui/material、@emotion/react	Material UI	Material Design の仕様に従う
antd	Ant Design	Ant のコンポーネントパターンに従う
@chakra-ui/react	Chakra UI	Chakra のテーマ設定とスタイルプロパティに従う
@headlessui/react	Headless UI	Tailwind と組み合わせてスタイルを設定する
@mantine/core	Mantine	Mantine のフックおよびコンポーネントパターンに従う
primereact、primevue	PrimeReact/PrimeVue	Prime のテーマ設定とテンプレートシステムに従う

フェーズ 2：内部コンポーネントを探す

次を確認します：

• components/ui/ディレクトリ（一般的な shadcn/ui の構成）
• components/common/またはcomponents/shared/
• コンポーネントディレクトリからのバレル再エクスポート
• Storybook のストーリー（.stories.tsx）

フェーズ 3：デザイントークンを特定する

次を検索します：

• tailwind.config.js/ts（Tailwind CSS のテーマカスタマイズ）
• theme.tsまたはtheme.js（カスタムテーマオブジェクト）
• :rootまたは[data-theme]で定義された CSS カスタムプロパティ
• tokens/またはdesign-tokens/ディレクトリ
• styles/variables.cssまたはstyles/tokens.css

採用：既存システム内での運用

共通原則

1. コンポーネント API をそのまま使用します。 インラインで上書きするラッパー要素を追加しないでください。
2. システムのバリアント機構を使用します。 variant="danger"が用意されている場合は、色を手動で上書きせず、それを使用してください。
3. システムのサイズ指定プロパティを使用します。 size="sm"を受け付ける場合は、カスタム CSS で上書きしないでください。
4. システムで定められた拡張ポイントを通じて拡張します。 CSS の詳細度を競う方法は使わないでください。
5. システムのディレクトリ規約に従います。 プリミティブがcomponents/ui/にある場合、新しいものもそこに配置してください。

shadcn/ui

Radix UI と Tailwind CSS を基盤に構築された、コピーしてカスタマイズできるコンポーネントです。

規約：

• プリミティブはcomponents/ui/に配置する（基礎となる構成要素）
• アプリケーションコンポーネントはcomponents/に配置する（プリミティブを組み合わせて構成）
• クラス文字列の結合にはcn()ヘルパーを使用する
• バリアントの定義にはclass-variance-authorityのcva()を使用する
• すべてのスタイル設定に Tailwind ユーティリティクラスを使用する

不足しているコンポーネントの追加：

npx shadcn@latest add [component-name]

カスタムコンポーネントの構成：

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Badge } from "@/components/ui/badge"

export function ProjectCard({ project }) {
  return (
    <Card>
      <CardHeader><CardTitle>{project.title}</CardTitle></CardHeader>
      <CardContent>
        <Badge variant={project.live ? "default" : "secondary"}>
          {project.live ? "Live" : "Draft"}
        </Badge>
      </CardContent>
    </Card>
  )
}

禁止事項：

• 生の CSS ファイルで shadcn のスタイルを上書きする
• shadcn がすでに提供しているコンポーネントを作り直す
• shadcn コンポーネントと併用して Tailwind 以外のスタイル設定を適用する
• 条件付きクラスの構成でcn()ヘルパーを無視する

Material UI

規約：

• theme.ts の createTheme() でテーマを定義します
• コンポーネントは @mui/material からインポートします
• sx プロパティまたは styled() API でスタイルを設定します
• theme.components でグローバルなオーバーライドを設定します

テーマの拡張：

const theme = createTheme({
  palette: { primary: { main: '#0d9488' } },
  components: {
    MuiButton: {
      defaultProps: { disableElevation: true },
      styleOverrides: { root: { textTransform: 'none', borderRadius: 8 } },
    },
  },
});

Ant Design

規約：

• コンポーネントは antd からインポートします
• ConfigProvider とトークンシステムでテーマを設定します
• グローバルトークンは theme.token、コンポーネントごとのトークンは theme.components で設定します

禁止事項： .ant-* CSS クラスを直接オーバーライドしたり、Ant を競合するコンポーネントライブラリと併用したりしないでください。

Tailwind CSS（コンポーネントライブラリなしの単独利用）

コンポーネントフレームワークを併用せずに Tailwind を使う場合：

1. tailwind.config を調べて、カスタムテーマの拡張を確認します
2. それらの値のみを使用し、任意の値は使いません
3. コードベース内にある既存のクラスパターンを再現します

拡張：既存システムへの追加

システムに必要なコンポーネントがない場合：

作成前のチェックリスト

1. システムのドキュメントを検索します。別の名前で存在している可能性があります
2. 既存のプリミティブを組み合わせて作成できるか判断します
3. コミュニティのプラグインや拡張機能を探します

システム内での新規コンポーネントの作成

システムの規範に合わせます：

1. 命名 — システムの命名パターン（PascalCase のコンポーネント、kebab-case のファイルなど）に従います
2. API — システムのプロパティの規約（variant + size、cva、sx など）に従います
3. スタイル設定 — 同じスタイル設定の仕組み（Tailwind + cn()、sx プロパティ、トークン参照）を使用します
4. トークン — システムのトークン値を参照し、生のリテラル値は使いません
5. アクセシビリティ — システムのアクセシビリティパターン（ARIA 属性、キーボード操作、フォーカス管理）を再現します

ブートストラップ：システムが存在しない場合

プロジェクトの規模	推奨事項
プロトタイプ／MVP	Tailwind CSS + shadcn/ui
小規模チーム、個性的なブランド	Tailwind CSS + ヘッドレスプリミティブ（Radix/Headless UI）
エンタープライズ／大規模組織	Material UI または Ant Design（機能が充実し、設計方針が明確）
デザイン重視／エージェンシー業務	Tailwind CSS + 専用コンポーネントライブラリ

ブートストラップの最小手順

1. CSS フレームワークをインストールします（ほとんどのケースでは Tailwind を推奨）
2. デザイントークンを定義します（godmode:ux-patterns design-tokens.md のテンプレートを活用します）
3. 基盤となるコンポーネントを作成します（最低限、Button、Input、Card、Badge）
4. テーマ設定を構成します（CSS カスタムプロパティまたは Tailwind 設定）

クイックスタートのブートストラップ（Tailwind + shadcn/ui）

npx tailwindcss init -p
npx shadcn@latest init
npx shadcn@latest add button input card badge dialog toast

その後、tailwind.config.ts をプロジェクト固有のトークン値でカスタマイズします。

既存のコードベースでのトークンの発見

トークンが文書化されていないプロジェクトに参加する場合：

トークンのカテゴリ	確認場所
色	CSS 変数、Tailwind 設定、テーマファイル、最も頻繁に使われている hex/rgb 値
タイポグラフィ	フォントのインポート、CSS のフォント宣言、Tailwind 設定のフォントセクション
余白	スタイルシート全体で最も頻繁に使われている padding/margin/gap の値
角丸	コンポーネントのスタイルで最もよく使われている border-radius の値
影	最もよく使われている box-shadow 宣言

発見の手順：

1. すべてのスタイルファイルを対象に CSS カスタムプロパティ（--）を検索します
2. tailwind.config を調べて、theme.extend のカスタマイズを確認します
3. theme.ts または theme.js のエクスポートを確認します
4. 何も見つからない場合は、最もよく使われているコンポーネントを 5～10 個調査し、繰り返し使われている値をトークンとして記録します

認知の罠

正当化	真実
「システムにはこのコンポーネントがありません」	プリミティブから組み立てるか、規約に沿って拡張してください。システムを迂回してはいけません。
「API を学ぶより、生の CSS を書くほうが速いです」	今日だけは速くても、いつまでも一貫性がなくなります。システムを学ぶことに投資してください。
「あとでシステムに組み込みます」	その「あと」は決して来ません。システムの外にあるコンポーネントは、触れるものすべてに悪影響を及ぼします。
「システムの API は制約が厳しすぎます」	API は設計上、一貫性を保つためのものです。その範囲内で対応するか、適切に拡張してください。
「2つのシステムを組み合わせれば、両方の良いところを活かせます」	2つのシステムを組み合わせると、両方の悪いところが現れます。スタイルが競合し、バンドルサイズが倍増します。
「これは一度限りのコンポーネントなので、問題ありません」	一度限りのコンポーネントは増えていきます。正しく構築しなければ、技術的負債になります。
「このプロパティだけを上書きします」	1つの上書きが20個に増えます。システムのテーマ機能を使ってください。

ガードレール -- HALT

• !important を使ってシステムのスタイルを上書きする
• 1つのプロジェクトで異なる2つのコンポーネントフレームワークを混在させる
• システムにすでに用意されているコンポーネントを作り直す
• システムのテーマ設定やトークンの方式を無視する
• システムのコンポーネントがあるのに、生の HTML 要素を使う
• components/ui/ と並べて components/custom/ を作成する
• Tailwind のプロジェクトに単独の CSS ファイルを追加する
• システムにパレットがあるのに、16進数のカラーコードをハードコードする
• UI ライブラリがすでにあるのに、2つ目をインストールする

このリストにある項目が1つでも該当する場合は、HALT。既存のシステムを活用してください。

統合

前提知識：

• godmode:ux-patterns -- デザインの参考情報を提供します。このスキルでは、システム固有の実装を扱います

関連スキル：

• godmode:ui-engineering -- デザインシステムの範囲内で機能する実装パターン
• godmode:project-bootstrap -- プロジェクトのセットアップ時にデザインシステムを初期化します