{
  "schemaVersion": "0.1.0",
  "library": "sparkdesign",
  "purpose": "Machine-readable design token ontology for AI agents choosing semantic styling without reading CSS internals first.",
  "axes": {
    "theme": {
      "attribute": "data-theme",
      "intent": "Controls color palette independently from layout density or geometry.",
      "knownValues": [
        "light",
        "dark",
        "light-parchment",
        "dark-parchment"
      ],
      "rules": [
        "Do not infer layout density from data-theme.",
        "Custom themes should define --token-color-* values and rely on theme-base.css mappings.",
        "Components should consume --color-* semantic tokens rather than raw --token-color-* internals."
      ]
    },
    "style": {
      "attribute": "data-style",
      "intent": "Controls spacing, radius, and typography rhythm independently from color.",
      "knownValues": [
        "neutral",
        "compact",
        "soft",
        "sharp",
        "dense"
      ],
      "rules": [
        "Use neutral when no product density preference is known.",
        "Use compact for efficiency-oriented workspaces that need tighter controls without becoming spreadsheet-dense.",
        "Use dense for data-heavy UI where text-sm, line-height, spacing, and radius all need compression.",
        "Use soft for airy, approachable, reading-friendly surfaces with larger radius and more breathing room.",
        "Use sharp when square geometry and mono-like precision are a deliberate product direction."
      ]
    }
  },
  "families": {
    "color.primary": {
      "tokens": [
        "--color-primary",
        "--color-primary-hover",
        "--color-primary-active",
        "--color-primary-bg",
        "--color-primary-bg-hover",
        "--color-primary-border",
        "--color-primary-border-hover",
        "--color-primary-text",
        "--color-primary-text-hover",
        "--color-primary-text-active",
        "--color-text-on-primary"
      ],
      "intent": "Brand and primary action emphasis.",
      "useFor": [
        "Primary action buttons",
        "Selected controls",
        "Active navigation accents",
        "Focused brand emphasis"
      ],
      "avoidFor": [
        "Large page backgrounds",
        "Destructive actions",
        "Neutral metadata",
        "Multiple competing actions in the same group"
      ],
      "agentRules": [
        "Use only one primary action per decision surface.",
        "Use --color-text-on-primary for text placed directly on --color-primary."
      ]
    },
    "color.text": {
      "tokens": [
        "--color-text",
        "--color-text-secondary",
        "--color-text-tertiary",
        "--color-text-quaternary",
        "--color-text-base"
      ],
      "intent": "Readable hierarchy for foreground content.",
      "useFor": [
        "Body copy",
        "Headings",
        "Metadata",
        "Disabled-looking low-emphasis support text"
      ],
      "avoidFor": [
        "Status semantics that need success, warning, error, or info color",
        "Decorative accents"
      ],
      "agentRules": [
        "Use --color-text for primary readable content.",
        "Use secondary and tertiary text only after hierarchy is established."
      ]
    },
    "color.background": {
      "tokens": [
        "--color-bg-base",
        "--color-bg-container",
        "--color-bg-elevated",
        "--color-bg-layout",
        "--color-bg-spotlight",
        "--color-bg-mask",
        "--color-bg-highlight",
        "--color-bg-highlight-hover"
      ],
      "intent": "Page, container, elevation, overlay, and spotlight surfaces.",
      "useFor": [
        "Application background",
        "Cards and panels",
        "Popover and modal surfaces",
        "Overlay masks",
        "Temporary highlight surfaces"
      ],
      "avoidFor": [
        "Text foreground",
        "Status messages without semantic color",
        "Arbitrary decorative blocks"
      ],
      "agentRules": [
        "Use --color-bg-layout for app-level backgrounds.",
        "Use --color-bg-container or --color-bg-base for content surfaces.",
        "Use --color-bg-mask only for modal, drawer, dialog, and popover overlays."
      ]
    },
    "color.border": {
      "tokens": [
        "--color-border",
        "--color-border-secondary",
        "--color-border-tertiary",
        "--color-input",
        "--color-ring"
      ],
      "intent": "Separation, input affordance, and keyboard focus indication.",
      "useFor": [
        "Card and panel boundaries",
        "Dividers",
        "Input borders",
        "Focus rings"
      ],
      "avoidFor": [
        "Primary semantic emphasis",
        "Replacing spacing as the only separator"
      ],
      "agentRules": [
        "Use --color-ring for focus indication.",
        "Prefer border-secondary or border-tertiary for low-emphasis separators."
      ]
    },
    "color.fill": {
      "tokens": [
        "--color-fill",
        "--color-fill-secondary",
        "--color-fill-tertiary",
        "--color-fill-quaternary",
        "--color-fill-disable",
        "--color-accent",
        "--color-muted"
      ],
      "intent": "Subtle non-surface fills for controls, hover areas, muted chips, and disabled states.",
      "useFor": [
        "Hover backgrounds",
        "Secondary controls",
        "Muted chips",
        "Disabled fill areas"
      ],
      "avoidFor": [
        "Primary page background",
        "High-risk status feedback",
        "Readable foreground text"
      ],
      "agentRules": [
        "Use fill tokens to support interaction affordance without adding new brand colors.",
        "Use --color-fill-disable only when disabled semantics are explicit."
      ]
    },
    "color.semantic": {
      "tokens": [
        "--color-link",
        "--color-error",
        "--color-error-hover",
        "--color-error-bg",
        "--color-error-bg-hover",
        "--color-error-border",
        "--color-info",
        "--color-info-hover",
        "--color-info-bg",
        "--color-info-bg-hover",
        "--color-info-border",
        "--color-success",
        "--color-success-hover",
        "--color-success-bg",
        "--color-success-bg-hover",
        "--color-success-border",
        "--color-warning",
        "--color-warning-hover",
        "--color-warning-bg",
        "--color-warning-bg-hover",
        "--color-warning-border"
      ],
      "intent": "Meaningful status communication.",
      "useFor": [
        "Validation errors",
        "Warnings",
        "Success confirmations",
        "Informational callouts",
        "Links"
      ],
      "avoidFor": [
        "Pure decoration",
        "Brand emphasis",
        "Dense rainbow categorization without labels"
      ],
      "agentRules": [
        "Do not rely on color alone; pair semantic color with text or icon labels.",
        "Use background and border companions for Alert-like surfaces."
      ]
    },
    "color.accent": {
      "tokens": [
        "--color-pink",
        "--color-pink-bg",
        "--color-pink-bg-hover",
        "--color-purple",
        "--color-purple-bg",
        "--color-purple-bg-hover",
        "--color-yellow",
        "--color-yellow-bg",
        "--color-yellow-bg-hover",
        "--color-orange",
        "--color-orange-bg",
        "--color-orange-bg-hover",
        "--color-teal",
        "--color-teal-bg",
        "--color-teal-bg-hover",
        "--color-blue",
        "--color-blue-bg",
        "--color-blue-bg-hover",
        "--color-mauve",
        "--color-mauve-bg",
        "--color-mauve-bg-hover",
        "--color-slate",
        "--color-slate-bg",
        "--color-slate-bg-hover",
        "--color-lavender",
        "--color-lavender-bg",
        "--color-lavender-bg-hover",
        "--color-sage",
        "--color-sage-bg",
        "--color-sage-bg-hover"
      ],
      "intent": "Categorical accents for tags, files, generated artifacts, or non-status grouping.",
      "useFor": [
        "Category tags",
        "File type accents",
        "Non-critical visual grouping",
        "Generated artifact previews"
      ],
      "avoidFor": [
        "Primary actions",
        "Error, warning, success, or info status",
        "Long-form text"
      ],
      "agentRules": [
        "Use accents sparingly and label categories explicitly.",
        "Do not invent new accent colors in generated UI."
      ]
    },
    "spacing": {
      "tokens": [
        "--spacing-0",
        "--spacing-px",
        "--spacing-0.5",
        "--spacing-1",
        "--spacing-1.5",
        "--spacing-2",
        "--spacing-2.5",
        "--spacing-3",
        "--spacing-3.5",
        "--spacing-4",
        "--spacing-5",
        "--spacing-6",
        "--spacing-8",
        "--spacing-10",
        "--spacing-12",
        "--spacing-16",
        "--spacing-20",
        "--spacing-24"
      ],
      "intent": "Rhythm and density controlled by data-style.",
      "useFor": [
        "Component padding",
        "Stack gaps",
        "Grid gutters",
        "Inline icon-label spacing"
      ],
      "avoidFor": [
        "One-off pixel nudges",
        "Encoding visual hierarchy only through whitespace",
        "Breaking sibling rhythm without a reason"
      ],
      "agentRules": [
        "Prefer existing Tailwind spacing utilities mapped to Spark tokens.",
        "Use larger spacing for section rhythm and smaller spacing for control internals."
      ]
    },
    "radius": {
      "tokens": [
        "--radius-none",
        "--radius-sm",
        "--radius-md",
        "--radius-lg",
        "--radius-xl",
        "--radius-2xl",
        "--radius-3xl",
        "--radius-full"
      ],
      "intent": "Geometry and softness controlled by data-style.",
      "useFor": [
        "Buttons",
        "Cards",
        "Inputs",
        "Pills",
        "Panels"
      ],
      "avoidFor": [
        "Mixing unrelated radii in a single component",
        "Using full radius for large rectangular panels",
        "Overriding sharp or dense styles with arbitrary rounded values"
      ],
      "agentRules": [
        "Let data-style drive geometry unless a component has a documented exception.",
        "Use --radius-full only for pills, avatars, and circular controls."
      ]
    },
    "typography": {
      "tokens": [
        "--font-size-xs",
        "--font-size-sm",
        "--font-size-base",
        "--font-size-lg",
        "--font-size-xl",
        "--font-size-2xl",
        "--font-size-3xl",
        "--font-size-4xl",
        "--font-size-5xl",
        "--font-size-6xl",
        "--font-size-7xl",
        "--font-size-8xl",
        "--font-size-9xl"
      ],
      "intent": "Readable type hierarchy controlled by data-style.",
      "useFor": [
        "Body text",
        "Labels",
        "Section headings",
        "Display headings"
      ],
      "avoidFor": [
        "Decorative scale jumps without information hierarchy",
        "Tiny text for required content",
        "Long paragraphs above base size without layout reason"
      ],
      "agentRules": [
        "Use base or sm for dense application text.",
        "Use larger sizes to express hierarchy, not decoration."
      ]
    },
    "motion": {
      "tokens": [
        "--motion-duration-fast",
        "--motion-duration-base",
        "--motion-duration-slow",
        "--motion-ease-standard",
        "--motion-ease-emphasized",
        "--motion-ease-out"
      ],
      "intent": "Purposeful feedback and state transition timing.",
      "useFor": [
        "Hover and press feedback",
        "Disclosure transitions",
        "Modal and popover entry/exit",
        "Streaming or generation state changes"
      ],
      "avoidFor": [
        "Purely decorative delay",
        "Animating large layout shifts without user benefit",
        "Long-running loops that distract from task work"
      ],
      "agentRules": [
        "Use fast durations for control feedback.",
        "Use base or slow only for surface transitions that clarify spatial change."
      ]
    }
  },
  "forbiddenPatterns": [
    "Hard-coded hex colors in component className or style props.",
    "Raw rgba overlays when --color-bg-mask or a semantic token exists.",
    "Arbitrary radius values that fight data-style.",
    "One-off spacing values that break sibling rhythm.",
    "Using accent colors to communicate status without labels."
  ]
}