assembling-components

コンポーネントの組み立て

目的

このスキルは、AI Design Components スキルの出力を本番環境対応のアプリケーションに変換します。汎用的な組み立てパターンでは得られない、トークンシステム、コンポーネントパターン、スキルチェーンのワークフローに関するライブラリ固有のコンテキストを提供します。このスキルは、トークンの統合を検証し、適切な足場を生成して、コンポーネントを正しく連携させます。

使用するタイミング

次の場合に、このスキルを有効にします。

• スキルチェーンのワークフロー（テーマ設定 → レイアウト → ダッシュボード → データ可視化 → フィードバック）を完了するとき
• React/Vite、Next.js、FastAPI、Flask、Rust/Axum 用の新しいプロジェクトの足場を生成するとき
• 生成されたすべての CSS がハードコードされた値ではなく、デザイントークンを使用していることを検証するとき
• バレルエクスポートを作成し、コンポーネントのインポートを正しく連携させるとき
• 複数のスキルのコンポーネントを統合アプリケーションに組み立てるとき
• 統合に関する問題（エントリーポイントの欠落、インポートの破損、テーマが切り替わらないなど）をデバッグするとき
• 生成されたコードを本番環境へのデプロイに備えるとき

スキルチェーンのコンテキスト

このスキルは、すべての AI Design Components スキルの出力を理解します。

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ theming-         │────▶│ designing-       │────▶│ creating-        │
│ components       │     │ layouts          │     │ dashboards       │
└──────────────────┘     └──────────────────┘     └──────────────────┘
        │                        │                        │
        ▼                        ▼                        ▼
    tokens.css               Layout.tsx             Dashboard.tsx
    theme-provider.tsx       Header.tsx             KPICard.tsx
        │                        │                        │
        └────────────────────────┴────────────────────────┘
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │ visualizing-data     │
                    │ providing-feedback   │
                    └──────────────────────┘
                                 │
                                 ▼
                         DonutChart.tsx
                         Toast.tsx, Spinner.tsx
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │ ASSEMBLING-          │
                    │ COMPONENTS           │
                    │ (THIS SKILL)         │
                    └──────────────────────┘
                                 │
                                 ▼
                       WORKING COMPONENT SYSTEM

スキルごとの期待される出力

スキル	主な出力	トークンの依存関係
theming-components	tokens.css、theme-provider.tsx	基盤
designing-layouts	Layout.tsx、Header.tsx、Sidebar.tsx	--spacing-、--color-border-
creating-dashboards	Dashboard.tsx、KPICard.tsx	すべてのレイアウト + チャートトークン
visualizing-data	チャートコンポーネント、凡例	--chart-color-、--font-size-
building-forms	フォーム入力、検証	--spacing-、--radius-、--color-error
building-tables	テーブル、ページネーション	--color-、--spacing-
providing-feedback	Toast、Spinner、EmptyState	--color-success/error/warning

トークンの検証

検証スクリプトの実行（トークンを使用しない実行）

# Basic validation
python scripts/validate_tokens.py src/styles

# Strict mode with fix suggestions
python scripts/validate_tokens.py src --strict --fix-suggestions

# JSON output for CI/CD
python scripts/validate_tokens.py src --json

トークンの命名規則

/* Colors - semantic naming */
--color-primary: #FA582D;          /* Brand primary */
--color-success: #00CC66;          /* Positive states */
--color-warning: #FFCB06;          /* Caution states */
--color-error: #C84727;            /* Error states */
--color-info: #00C0E8;             /* Informational */

--color-bg-primary: #FFFFFF;       /* Main background */
--color-bg-secondary: #F8FAFC;     /* Elevated surfaces */
--color-text-primary: #1E293B;     /* Body text */
--color-text-secondary: #64748B;   /* Muted text */

/* Spacing - 4px base unit */
--spacing-xs: 0.25rem;   /* 4px */
--spacing-sm: 0.5rem;    /* 8px */
--spacing-md: 1rem;      /* 16px */
--spacing-lg: 1.5rem;    /* 24px */
--spacing-xl: 2rem;      /* 32px */

/* Typography */
--font-size-xs: 0.75rem;   /* 12px */
--font-size-sm: 0.875rem;  /* 14px */
--font-size-base: 1rem;    /* 16px */
--font-size-lg: 1.125rem;  /* 18px */

/* Component sizes */
--icon-size-sm: 1rem;      /* 16px */
--icon-size-md: 1.5rem;    /* 24px */
--radius-sm: 4px;
--radius-md: 8px;
--shadow-sm: 0 1px 2px rgba(0,0,0,0.05);

検証ルール

トークンを必ず使用（エラー）	修正例
色	#FA582D → var(--color-primary)
余白（≥4px）	16px → var(--spacing-md)
フォントサイズ	14px → var(--font-size-sm)

トークンの使用を推奨（警告）	修正例
角丸	8px → var(--radius-md)
影	0 4px... → var(--shadow-md)
Z-index（≥100）	1000 → var(--z-dropdown)

フレームワークの選択

React/TypeScript

次の場合は Vite + React を選択します。

• シングルページアプリケーションを構築する場合
• 軽量で高速な開発ビルドが必要な場合
• 設定を最大限に制御したい場合
• サーバーサイドレンダリングが不要な場合

次の場合は Next.js 14/15 を選択します。

• サーバーサイドレンダリングまたは静的生成が必要な場合
• API ルートを備えたフルスタックアプリケーションを構築する場合
• SEO が重要な場合
• React Server Components を使用する場合

Python

次の場合は FastAPI を選択します。

• 最新の非同期 API を構築する場合
• OpenAPI ドキュメントの自動生成が必要な場合
• 高いパフォーマンスが必要な場合
• 検証に Pydantic を使用する場合

次の場合は Flask を選択します。

• よりシンプルで柔軟なセットアップが必要な場合
• Flask エコシステムに慣れている場合
• テンプレートレンダリング（Jinja2）を使用する場合
• 小規模なアプリケーションの場合

Rust

次の場合は Axum を選択します。

• 最新の Tower ベースのアーキテクチャを使用する場合
• 型安全なエクストラクターが必要な場合
• 非同期処理を優先する設計の場合
• エコシステムの成長を重視する場合

次の場合は Actix Web を選択します。

• 最大限のパフォーマンスが必要な場合
• ユースケースでアクターモデルの利点を活用できる場合
• より成熟したエコシステムが必要な場合

実装方法

1. トークンの統合を検証する

組み立ての前に、すべての CSS がトークンを使用していることを確認します。

python scripts/validate_tokens.py <component-directory>

続行する前に、違反をすべて修正してください。

2. プロジェクトの足場を生成する

React/Vite:

// src/main.tsx - Entry point
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ThemeProvider } from '@/context/theme-provider'
import App from './App'
import './styles/tokens.css'   // FIRST - token definitions
import './styles/globals.css'  // SECOND - global resets

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ThemeProvider>
      <App />
    </ThemeProvider>
  </StrictMode>,
)

index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{PROJECT_TITLE}}</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

3. コンポーネントを連携させる

テーマプロバイダー:

// src/context/theme-provider.tsx
import { createContext, useContext, useEffect, useState } from 'react'

type Theme = 'light' | 'dark' | 'system'

const ThemeContext = createContext<{
  theme: Theme
  setTheme: (theme: Theme) => void
} | undefined>(undefined)

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('system')

  useEffect(() => {
    const root = document.documentElement
    const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
      ? 'dark' : 'light'
    root.setAttribute('data-theme', theme === 'system' ? systemTheme : theme)
    localStorage.setItem('theme', theme)
  }, [theme])

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export const useTheme = () => {
  const context = useContext(ThemeContext)
  if (!context) throw new Error('useTheme must be used within ThemeProvider')
  return context
}

バレルエクスポート:

// src/components/ui/index.ts
export { Button } from './button'
export { Card } from './card'

// src/components/features/dashboard/index.ts
export { KPICard } from './kpi-card'
export { DonutChart } from './donut-chart'
export { Dashboard } from './dashboard'

4. ビルドシステムを設定する

vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"]
}

スキル間の統合

テーマ設定コンポーネントの使用

// Import tokens first, components inherit token values
import './styles/tokens.css'

// Use ThemeProvider at root
<ThemeProvider>
  <App />
</ThemeProvider>

ダッシュボードコンポーネントの使用

// Components from creating-dashboards skill
import { Dashboard, KPICard } from '@/components/features/dashboard'

// Wire with data
<Dashboard>
  <KPICard
    label="Total Threats"
    value={1234}
    severity="critical"
    trend={{ value: 15.3, direction: 'up' }}
  />
</Dashboard>

データ可視化の使用

// Charts from visualizing-data skill
import { DonutChart } from '@/components/charts'

// Charts use --chart-color-* tokens automatically
<DonutChart
  data={threatData}
  title="Threats by Severity"
/>

フィードバックコンポーネントの使用

// From providing-feedback skill
import { Toast, Spinner, EmptyState } from '@/components/feedback'

// Wire toast notifications
<ToastProvider>
  <App />
</ToastProvider>

// Use spinner for loading states
{isLoading ? <Spinner /> : <Dashboard />}

統合チェックリスト

納品前に、以下を確認してください。

• トークンファイルが存在する（tokens.css）こと。7つすべてのカテゴリが含まれていること
• トークンのインポート順序が正しいこと（tokens.css → globals.css → components）
• ハードコードされた値がないこと（validate_tokens.py を実行）
• テーマ切り替えが動作すること（data-theme 属性が切り替わる）
• モーションの軽減に対応していること（@media (prefers-reduced-motion)）
• ビルドがエラーなく完了すること
• 型チェックに合格すること（TypeScript がコンパイルされる）
• インポートが解決されること（モジュールの不足がない）
• 各コンポーネントディレクトリにバレルエクスポートがあること

バンドルされたリソース

スクリプト（トークンを読み込まない実行）

• scripts/validate_tokens.py - CSSでデザイントークンが使われていることを検証します
• scripts/generate_scaffold.py - プロジェクトのボイラープレートを生成します
• scripts/check_imports.py - インポートチェーンを検証します
• scripts/generate_exports.py - バレルエクスポートファイルを作成します

スクリプトはコンテキストに読み込まず、直接実行してください。

python scripts/validate_tokens.py demo/examples --fix-suggestions

リファレンス（詳細なパターン）

• references/library-context.md - AI Design Components ライブラリの概要
• references/react-vite-template.md - Vite + React の完全なセットアップ
• references/nextjs-template.md - Next.js 14/15 のパターン
• references/python-fastapi-template.md - FastAPI プロジェクトの構成
• references/rust-axum-template.md - Rust/Axum プロジェクトの構成
• references/token-validation-rules.md - 検証ルールの完全版

サンプル（完全な実装）

• examples/react-dashboard/ - Vite + React の完全なダッシュボード
• examples/nextjs-dashboard/ - Next.js App Router のダッシュボード
• examples/fastapi-dashboard/ - Python FastAPI のダッシュボード
• examples/rust-axum-dashboard/ - Rust Axum のダッシュボード

アセット（テンプレート）

• assets/templates/react/ - React プロジェクトのテンプレート
• assets/templates/python/ - Python プロジェクトのテンプレート
• assets/templates/rust/ - Rust プロジェクトのテンプレート

アプリケーション構築ワークフロー

1. コンポーネントを検証する：生成したすべてのCSSに対して validate_tokens.py を実行します
2. フレームワークを選択する：要件に応じて React/Vite、Next.js、FastAPI、または Rust を選びます
3. スキャフォールディングを生成する：プロジェクト構成と設定を作成します
4. インポートを接続する：エントリーポイント、インポートチェーン、バレルエクスポートを設定します
5. プロバイダーを追加する：ルートに ThemeProvider と ToastProvider を追加します
6. コンポーネントを接続する：機能コンポーネントをインポートして組み合わせます
7. ビルドを設定する：vite.config、tsconfig、package.json を設定します
8. 最終検証を行う：ビルド、型チェック、Lint を実行します
9. ドキュメントを作成する：セットアップと使用方法を記載した README を作成します

ライブラリ固有のパターンと詳細については、references/library-context.md を参照してください。