Token Schema JSON

What This Is

Everyone gives AI their token files. Nobody gives AI the rules for what makes a valid token. This schema is the missing piece.

It defines:

• Valid categories (color, space, size, radius, font, shadow, motion)
• Valid properties per category
• Valid intents and modifiers
• The naming pattern with examples
• What’s invalid (so AI knows what NOT to generate)

Why You Need It

Without a schema, Claude invents tokens like color.backgroundPrimary or button-bg-color. With it, Claude follows your exact convention every time.

How to Use

1. Download token-schema.json
2. Place it in .design-system/ in your project root
3. Reference it from your CLAUDE.md: @.design-system/token-schema.json
4. Customize the categories, properties, and intents to match your system

The Schema

{
  "categories": ["color", "space", "size", "radius", "font", "shadow", "motion"],
  "properties": {
    "color": ["bg", "fg", "border", "outline", "shadow"],
    "space": ["gap", "padding", "margin", "inset"],
    "size": ["icon", "avatar", "input", "touch"],
    "radius": ["sm", "md", "lg", "full"],
    "font": ["size", "weight", "line-height", "letter-spacing"],
    "shadow": ["sm", "md", "lg", "inner"],
    "motion": ["duration", "easing"]
  },
  "intents": ["primary", "secondary", "danger", "success", "warning", "muted", "inverse", "disabled"],
  "modifiers": ["default", "hover", "active", "disabled", "focus", "subtle"],
  "naming": "{category}.{property}.{intent}.{modifier?}",
  "examples": {
    "valid": [
      "color.bg.primary",
      "color.fg.danger",
      "space.gap.md",
      "color.border.muted.hover",
      "radius.md",
      "shadow.lg"
    ],
    "invalid": [
      "red-500",
      "bg-primary",
      "color.background.main",
      "colorBgPrimary",
      "button-bg-color"
    ]
  },
  "themes": ["light", "dark", "high-contrast"],
  "primitive_format": "{category}.{scale}",
  "primitive_examples": ["color.gray.100", "color.blue.500", "space.4", "radius.md"]
}