Skip to main content
Token Schema Standards

Token Schema Standards

Create token schemas that AI can reliably parse and transform. Consistent, well-structured tokens make it easier for AI to generate valid design-to-code outputs whilst maintaining your semantic system.

How to

  1. Define schema structure

    Establish a clear token hierarchy (primitives → semantics → component tokens). Document the structure in JSON Schema or similar format.

  2. Make relationships explicit

    Show how tokens reference each other. Document which tokens are aliases, which are computed, and what the transformation rules are.

  3. Include usage metadata

    Add context to tokens: valid contexts (marketing vs product), platform availability (web/iOS/Android), deprecation status, and accessibility requirements.

  4. Standardise naming patterns

    Use predictable naming that AI can parse: category.property.variant.state rather than arbitrary strings. Document the naming grammar.

    • For example: color.surface.primary.default (clear hierarchy) rather than btnBg (arbitrary)

  5. Provide transformation rules

    Document how tokens transform across platforms, themes, or modes. Make these rules explicit so AI can apply them correctly.

  6. Version your schema

    Treat your token schema as an API. Version it, document breaking changes, and maintain backwards compatibility where possible.