Home Work About Field Notes Contact
Back to work AI Architecture

Design token architecture
for LLMs

Design tokens are the most machine-legible part of a design system — but most token architectures were designed exclusively for human workflows. Re-architecting token hierarchies with LLM interpretation in mind unlocks a new class of AI capability: systems that can reason about design decisions, not just execute them.

Scope Token Architecture
Context AI · LLM Integration
Category AI Architecture
Focus Tokens · Semantics · Reasoning
CORE TOKENS SEMANTIC TOKENS LLM LAYER #0A0A0A #F7C948 16px spacing 1rem type 0.25rem radius color.background.base color.accent.primary spacing.component.md typography.body.base radius.surface.sm LLM processing layer Reason Generate Validate TOKEN ARCHITECTURE · SEMANTIC LAYER · LLM REASONING · DESIGN SYSTEM
Objective

Tokens as a shared language between humans and AI

The goal was to re-architect token hierarchies so that LLMs could reliably interpret design intent — not just token values — enabling AI tools to reason about visual relationships, generate contextually correct UI, and validate design decisions against system rules.

This built directly on the existing three-tier token architecture (core → semantic → component) but extended it with a new layer of machine-readable context.

Challenges & Goals

Tokens weren't designed for AI reasoning

  • Semantic token names carried implicit human meaning that LLMs couldn't reliably infer
  • No formal relationships between tokens — LLMs couldn't understand which tokens were related or why
  • Token documentation existed as prose, not structured data LLMs could query or reason over
  • AI tools defaulted to hardcoded values when token names were ambiguous, breaking the system
  • No mechanism for LLMs to validate generated token usage against system intent
  • Token hierarchies designed for CSS cascade, not for AI traversal or reasoning
Solutions

A token layer built for machine reasoning

  • Extended semantic tokens with structured intent descriptors — machine-readable annotations explaining purpose, relationships, and constraints
  • Formalised token relationship graphs connecting related tokens across tiers and categories
  • Created a token manifest: a structured, queryable document of all tokens, their values, intent, and usage rules
  • Developed token validation rules LLMs can reference to check generated token usage for correctness
  • Built a token-to-component mapping layer so LLMs understand which tokens belong to which components
  • Defined a simplified token vocabulary for AI context windows — optimised for prompt length and reasoning accuracy
Process

Extending the existing architecture

1

Token Audit Through an AI Lens

Re-examined the existing three-tier token architecture to identify where LLMs were failing to interpret intent correctly — focusing on ambiguous names, missing relationships, and undocumented constraints.

2

Intent Annotation Schema

Designed a lightweight annotation schema for semantic tokens — adding purpose, usage context, and constraint fields without disrupting existing token workflows.

3

Token Manifest

Built a machine-readable token manifest in structured JSON, covering all tokens with values, tier, category, intent, and relationship data.

4

LLM Testing

Ran iterative tests measuring how accurately LLMs could apply tokens in generated UI with and without the new manifest and annotations — tracking error rates and token hallucination.

5

Integration & Documentation

Integrated the manifest into AI tooling workflows and published guidance on FreeStyle for teams using AI assistants with the design system.

Results & Impact

Tokens that AI can reason about

🎯

Reduced Token Hallucination

Structured intent annotations and the token manifest significantly reduced cases where AI tools invented token names or defaulted to hardcoded values.

🧠

AI That Understands Intent

LLMs could reason about visual relationships and design decisions — not just apply values — enabling more sophisticated AI-assisted UI generation.

📊

Queryable Token Knowledge

The token manifest gave AI tools a reliable, structured source of truth — queryable at generation time for any token's purpose, value, or constraints.

🔗

Design–Code Coherence

Token-to-component mappings ensured AI-generated code referenced the right tokens in the right contexts, maintaining system integrity.

Want to talk through this work?

Get in touch →