ai-component-metadata

AI コンポーネントメタデータジェネレーター

デザインシステムのコンポーネントについて、構造化された AI が利用できるメタデータを生成し、インテリジェントな UI 生成とコンポーネントの使用を可能にします。

クイックスタート

コンポーネントを分析する際は、scripts/generate_metadata.py のメタデータスキーマテンプレートを使用するか、以下の手動プロセスに従ってください。

# Automatic generation (reads component file)
python scripts/generate_metadata.py path/to/Component.tsx

# Or use the template directly
cp assets/metadata-template.tsx your-component-metadata.tsx

コアワークフロー

1. コンポーネントの構造を分析する

以下を特定します。

• コンポーネントの構成（スロット、子要素）
• 使用可能なバリアントと状態
• プロパティとその型
• アクセシビリティ属性

2. メタデータを生成する

以下のスキーマに従ってメタデータを作成します。

export const componentMetadata = {
  component: {
    name: "ComponentName",
    category: "atoms|molecules|organisms",
    description: "Brief description",
    type: "interactive|display|container|input|navigation"
  },
  
  usage: {
    useCases: ["primary-use", "secondary-use"],
    requiredProps: [],
    commonPatterns: [
      {
        name: "pattern-name",
        description: "When to use",
        composition: "JSX example"
      }
    ],
    antiPatterns: [
      {
        scenario: "what-not-to-do",
        reason: "why",
        alternative: "what-instead"
      }
    ]
  },
  
  composition: {
    slots: {},
    nestedComponents: [],
    commonPartners: [],
    parentConstraints: []
  },
  
  behavior: {
    states: [],
    interactions: {},
    responsive: {}
  },
  
  accessibility: {
    role: "ARIA role",
    keyboardSupport: "description",
    screenReader: "behavior",
    focusManagement: "strategy",
    wcag: "AA"
  },
  
  aiHints: {
    priority: "high|medium|low",
    keywords: [],
    context: "when to use"
  }
}

3. メタデータを検証する

• AI 生成タスクでテストします
• Storybook で確認します
• サンプルが実行可能であることを確認します

コンポーネントのカテゴリ

• atoms：基本的な構成要素（Button、Text、Input）
• molecules：単純な組み合わせ（Card、Chip、FormField）
• organisms：複雑なコンポーネント（Header、Table、Form）

高度な機能

複雑なシナリオについては、以下を参照してください。

• ネストされたコンポーネント：NESTED.md
• 統合パターン：INTEGRATION.md
• テスト戦略：TESTING.md

Figma との連携

Figma MCP と組み合わせる場合：

// Figma provides visual context
const figmaContext = await Figma.get_design_context();

// Your metadata provides behavioral context
const componentMetadata = components.Button.metadata;

// AI combines both for complete understanding

ベストプラクティス

1. 実際のサンプルを使用する - 実際に実行できるコードを使用します
2. パターンに焦点を当てる - 一般的な使用パターンを記録します
3. アンチパターンを含める - AI が間違いを避けられるようにします
4. 使用して検証する - 実際の AI 生成でテストします

成功指標

メタデータが効果的であることを示す条件：

• AI がコンポーネントを再作成せず、既存のコンポーネントを使用する
• コンテキストに基づいて適切なバリアントが選択される
• 生成されたコードでもアクセシビリティが維持される
• AI の出力全体でパターンに一貫性がある