Core Concepts

Design data model: *.facet.json

Facet token files are DTCG trees with two node kinds:

• Group: object without $value; may set $type for descendants.
• Token: object with $value, and optional $type and $extensions.

{
  "color": {
    "$type": "color",
    "brand": {
      "500": { "$value": { "colorSpace": "oklch", "components": [0.55, 0.2, 268], "hex": "#5865f2" } }
    },
    "action": { "$value": "{color.brand.500}" }
  }
}

Supported $type shapes

• color: object color model (colorSpace, components, optional hex)
• dimension: { value, unit }
• duration: { value, unit }
• number, fontFamily, fontWeight, cubicBezier, shadow

$type is inherited from the nearest ancestor group when a token does not set it.

Aliases and derivations

• Alias: "$value": "{color.brand.500}"
• Derivation: in $extensions.com.facet.derive

{
  "$value": { "colorSpace": "oklch", "components": [0.49, 0.2, 268] },
  "$extensions": {
    "com.facet": {
      "derive": { "fn": "oklch.darken", "from": "{color.brand.500}", "by": 0.06 }
    }
  }
}

Implemented derive.fn values are:

• oklch.darken, oklch.lighten
• oklch.mix (with, by)
• alpha (by)
• contrast.on

A11y constraints in token data

$extensions.com.facet.a11y declares contrast requirements that are checked in every mode.

"ink": {
  "$value": "{color.text.strong}",
  "$extensions": {
    "com.facet": {
      "a11y": [{ "pairsWith": "{color.bg}", "minContrast": 4.5, "metric": "WCAG21" }]
    }
  }
}

Fluent dimensions (fluid)

$extensions.com.facet.fluid emits clamp(min, fluid, max) for dimensions.

"text": {
  "sm": {
    "$value": { "value": 0.8125, "unit": "rem" },
    "$extensions": { "com.facet": { "fluid": { "min": 0.8125, "max": 0.875 } } }
  }
}

Typed resolution and graph guarantees

The compiler loads sets, merges them, resolves references, then emits concrete values by mode. Unknown references and cycles are rejected.

The typed IR (FIR)

All authoring surfaces eventually become

{ prop: <css-property>, value, state, at }

and are content-hashed before emission.

Planned / deferred notes (from source docs)

• fx() is a typed API contract, but there is no full cross-project TS enforcement story in the current host setup.
• Full parser support for all JSX/Vue/Svelte patterns is documented as deferred production work.