Knowledge Graph Starter Kit

What This Is

Three JSON files that transform your design system from a collection of files into a connected knowledge base that AI can reason about.

File	Purpose
token-schema.json	What makes a valid token (rules, not just values)
knowledge-graph.json	What connects to what (components, tokens, patterns)
component-intent.json	When to use what (selection logic for AI)

Why Three Files

• Token schema prevents AI from inventing wrong names
• Knowledge graph lets AI answer “what breaks if I change this token?”
• Component intent lets AI pick the right component for the right context

Without these, Claude can list your tokens. With them, Claude can reason about your system.

How to Use

1. Download and unzip the starter kit
2. Create a .design-system/ folder in your project root
3. Place all three files inside
4. Reference from your CLAUDE.md: @.design-system/token-schema.json
5. Customize each file to match your actual system

File 1: knowledge-graph.json

Maps relationships between components, tokens, and contexts:

{
  "components": {
    "Button": {
      "tokens": ["color.bg.primary", "color.fg.inverse", "radius.md", "space.padding.sm"],
      "variants": ["primary", "secondary", "danger", "ghost"],
      "contexts": {
        "alert": "Use danger variant. Never primary.",
        "card": "Use secondary or ghost. Never danger.",
        "nav": "Use ghost variant only.",
        "form": "Use primary for submit, secondary for cancel."
      },
      "depends_on": ["Icon"],
      "used_by": ["Dialog", "Form", "Card", "AlertBanner"]
    },
    "Dialog": {
      "tokens": ["color.bg.surface", "shadow.lg", "radius.lg", "space.padding.lg"],
      "variants": ["default", "destructive", "fullscreen"],
      "contexts": {
        "destructive-action": "Use destructive variant with danger Button.",
        "confirmation": "Use default variant with primary + secondary Buttons.",
        "form": "Use default variant. Include form validation."
      },
      "depends_on": ["Button", "Icon"],
      "used_by": []
    },
    "AlertBanner": {
      "tokens": ["color.bg.{status}", "color.fg.{status}", "color.border.{status}"],
      "variants": ["info", "success", "warning", "danger"],
      "contexts": {
        "page-level": "Full width, below nav. Use for system messages.",
        "section-level": "Constrained width. Use for contextual feedback."
      },
      "depends_on": ["Icon", "Button"],
      "used_by": []
    }
  }
}

File 2: component-intent.json

Tells AI when to pick each component:

{
  "AlertBanner": {
    "use_when": "System-level message that affects the entire page or section",
    "dont_use_when": "Inline validation feedback (use InlineAlert instead)",
    "placement": "Top of page, below nav, full width",
    "required_tokens": ["color.bg.{status}", "color.fg.{status}", "color.border.{status}"],
    "a11y": "role=alert for urgent, role=status for informational"
  },
  "InlineAlert": {
    "use_when": "Contextual feedback within a form or content area",
    "dont_use_when": "Page-level system messages (use AlertBanner instead)",
    "placement": "Inline, near the related content",
    "required_tokens": ["color.bg.{status}.subtle", "color.fg.{status}"],
    "a11y": "aria-live=polite, never role=alert"
  },
  "Dialog": {
    "use_when": "Action requires user confirmation or focused input",
    "dont_use_when": "Content preview or quick glance (use Sheet or Tooltip)",
    "placement": "Centered overlay with backdrop",
    "required_tokens": ["color.bg.surface", "shadow.lg", "radius.lg"],
    "a11y": "Focus trap, ESC to close, aria-modal=true"
  },
  "Sheet": {
    "use_when": "Secondary content or actions that don't need full focus",
    "dont_use_when": "Destructive actions requiring explicit confirmation (use Dialog)",
    "placement": "Slides in from edge (right or bottom)",
    "required_tokens": ["color.bg.surface", "shadow.lg"],
    "a11y": "Focus trap, ESC to close, aria-modal=true"
  },
  "Toast": {
    "use_when": "Non-critical, temporary feedback after an action",
    "dont_use_when": "Errors or warnings that require action (use AlertBanner)",
    "placement": "Bottom-right corner, auto-dismiss after 5s",
    "required_tokens": ["color.bg.surface", "shadow.md", "radius.md"],
    "a11y": "role=status, aria-live=polite, never auto-dismiss errors"
  },
  "Button": {
    "use_when": "User-initiated action (submit, cancel, navigate, toggle)",
    "dont_use_when": "Navigation to a new page (use Link). Decorative element.",
    "placement": "Within forms, cards, dialogs, toolbars",
    "required_tokens": ["color.bg.{intent}", "color.fg.{intent}", "radius.md"],
    "a11y": "Minimum 44x44px touch target, visible focus ring, disabled state announced"
  }
}

File 3: token-schema.json

See the Token Schema JSON template for the full file.

Folder Structure

your-project/
├── CLAUDE.md                    <- References these files via @import
├── .design-system/
│   ├── token-schema.json        <- What's valid
│   ├── knowledge-graph.json     <- What connects to what
│   └── component-intent.json    <- When to use what