Spec Reference

Token file (*.facet.json)

A token file is a tree of groups and tokens.

file := object
object := { property: value }
value := group | token
group := { "name": groupOrToken }

token := { "$value": tokenValue, "$type"?, "$extensions"?, "$description"? }

Token value forms:

• color: { colorSpace, components, alpha?, hex? }
• dimension: { value, unit }
• duration, number, fontFamily, fontWeight, cubicBezier, shadow
• aliases: "{dotted.path}"

com.facet extensions

• derive: build-time computed value (oklch.darken, oklch.lighten, oklch.mix, alpha, contrast.on)
• a11y: contrast constraints per token
• fluid: dimension clamp range { min, max }

Resolver format (*.resolver.json)

{
  "sets": { "core": "palette.facet.json", ... },
  "modifiers": {
    "theme": { "values": ["light", "dark"], "default": "light", "selector": { "light":":root", "dark":".dark" } }
  },
  "apply": [
    { "always": ["core"] },
    { "when": { "theme": "dark" }, "use": ["theme.dark"] }
  ]
}

A permutation is one value per modifier axis. The default coordinate emits base variables; non-default axis values emit diffs only.

Utility/Fx IR

All authoring surfaces normalize to:

{ prop, value, state, at, arbitrary? }

The canonical atom key is derived from that tuple and emitted as a content-hash class.

Guarantees

• contrast checks across every permutation (WCAG21 or APCA)
• switch-safety contract: each permutation resolves identical token paths
• deterministic output for identical input
• zero-runtime styling (CSS vars + atoms)
• RTL construction via logical properties and optional lint checks

Targets and outputs

• CSS tokens/utilities (@layer tokens, @layer utilities)
• Tailwind v4 @theme
• Style Dictionary v4
• React Native, Swift, Kotlin, JS token maps
• Pure DTCG export for default mode
• Figma variable payload (--figma)

Planned / roadmap markers

• Resolver draft modules and parser breadth are explicitly noted as non-final in source notes.
• Production-depth work remains for expanded parser coverage and some ecosystem integrations.