Tostada
Try Tostada Join Slack

Token schema

The DesignToken interface lives in src/tokens/types.ts. This is the authoritative shape — anything you read in design-system.json or that survives an importLibrary round-trip uses this type.

The interface

interface DesignToken {
  id:             string             // unique identifier
  name:           string             // display name
  tier:           TokenTier          // 'primitive' | 'semantic' | 'shadcn'
  value:          string             // own raw value (hex, oklch, px, rem…)
  references?:    string             // ID of token referenced in light mode
  darkValue?:     string             // own raw value in dark mode
  darkReferences?: string            // ID of token referenced in dark mode
  description?:   string             // optional description
  group?:         string             // grouping/category for the editor
  usage?:         SemanticUsage      // optional usage guidance
}

type TokenTier = 'primitive' | 'semantic' | 'shadcn'

interface SemanticUsage {
  purpose:    string
  useWhen:    string[]
  avoidWhen:  string[]
  notes?:     string
}

Field reference

Field Required When set
id yes Always. Stable identifier; how other tokens reference this one.
name yes Always. Display name shown in the editor.
tier yes Always. Determines which editor surface the token belongs to.
value yes Always — even for semantic/component tokens that primarily use references, this is the fallback.
references no Set on semantic and component tokens that point at another token in light mode.
darkValue no Set on tokens with a raw dark override (rare — usually use darkReferences).
darkReferences no Set on tokens that should resolve through a different chain in dark mode.
description no Free-form note shown in the editor.
group no Editor grouping for primitives (e.g. "color", "radius", "spacing"). Defaults derived from id prefix when omitted.
usage no Optional structured guidance (purpose + useWhen + avoidWhen + notes).

Tier rules

Tier Typical fields used
primitive id, name, value, group — value is the raw value (hex, rem, px).
semantic id, name, references (light) and optionally darkReferences (dark).
shadcn id (e.g. "--primary"), name, references, darkReferences.

ID conventions

  • Primitives: descriptive, value-anchored — color-blue-500, radius-md, space-4.
  • Semantics: intent-anchored — bg-accent, fg-default, border-focus.
  • component: the literal CSS variable name including dashes — --primary, --background, --ring.

The Semantic editor uses the ID prefix (bg-, fg-, border-) to auto-categorize rows. Names off-pattern fall into "Other".

Resolution algorithm

See light and dark for the resolution chain. In short:

  • Light resolution: follow references until a token without references; return that token's value.
  • Dark resolution: try darkReferences first → fall through to light chain; once a token is reached, prefer darkValue → fall through to value.

In code