Authoring Tokens

File layers in the source example

Facet separates token concerns by file role:

• palette.facet.json — primitive values and scales (color, spacing, typography, shadows)
• themes/light.facet.json, themes/dark.facet.json — semantic alias layer
• brands/<name>.facet.json — brand-level color semantics
• density/compact.facet.json — orthogonal density overrides
• app.resolver.json — mode model across sets and selectors

Practical authoring pattern

Keep shared primitives in palette, map product semantics in theme files, then place variations in brand/density set files.

// themes/light.facet.json (excerpt)
"color": {
  "$type": "color",
  "bg": { "$value": "{color.neutral.50}" },
  "ink": {
    "$value": "{color.text.strong}",
    "$extensions": {
      "com.facet": { "a11y": [{ "pairsWith": "{color.bg}", "minContrast": 4.5, "metric": "WCAG21" }] }
    }
  }
}

// brands/acme.facet.json (excerpt)
"color": {
  "$type": "color",
  "brand": {
    "500": { "$value": { "colorSpace": "oklch", "components": [0.555, 0.205, 268], "hex": "#5865f2" } },
    "600": { "$value": { "colorSpace": "oklch", "components": [0.5, 0.2, 268] },
      "$extensions": { "com.facet": { "derive": { "fn": "oklch.darken", "from": "{color.brand.500}", "by": 0.06 } } } }
  },
  "action": { "$value": "{color.brand.500}" }
}

Reserved key: alias over override order

The compiler resolves each coordinate by merging sets in apply order and applies set inheritance ($extends) where present.

Bootstrap helpers

facet init my-tokens

init writes starter files and prints next steps:

• palette.facet.json
• themes/light.facet.json
• themes/dark.facet.json
• app.resolver.json

Migration helper

facet import <legacy.json> converts legacy Tokens Studio-like shapes to Facet .facet.json:

• value/type become $value/$type
• #hex becomes object color model
• dimension strings like 16px / 0.5rem become { value, unit }
• aliases like {color.brand.500} are preserved

Planned items to track

• The import flow is present as a one-way migration helper.
• The docs note that broader ecosystem parity and parser depth remain roadmap work.