Variables and themes

"variables": {
  "surface": { "type": "color", "value": [ { "value": "#FFFFFF", "when": { "mode": "light" } },
                                           { "value": { "$ref": "ink-900" }, "when": { "mode": "dark" } } ],
               "group": "color.surface", "description": "Page background" }
}

Plain values by type: color → Color; number → Num; string → string | Ref; boolean → boolean | Ref; typography → a TextStyle without typography, or Ref; shadow → a shadow Effect or an array of them, or Ref; dimension → { value: number, unit: "px" } (px only in 0.x and 1.x), or Ref. A value that is a binding is an alias; an alias MUST name a variable of the same type.

A binding MUST name an existing variable (VARIABLE_MISSING); alias:name names a variable of an imported library, which is never copied into the consumer. The bound variable's type MUST fit the property:

themes declares axes, each with its values; the first value is the default. A node's theme pins axes for its subtree; keys are axis keys (alias:axis for a library's axis) and values MUST be declared values of that axis (THEME_AXIS_UNKNOWN, THEME_VALUE_UNKNOWN). The same applies to when keys and values.

1. Effective theme of a node. Start from the defaults: the first value of every local axis, and for every loaded imported library alias, the first value of each of its axes under the key alias:axis. Walk from the root to the node along its placement path (parent links, which include instance placement and at nodes), so instances inherit from where they sit. At each node with theme, overwrite only the named axes. For nodes inside an expanded instance the placement path is the expanded one (§9.8 rules 2 and 4).
2. Library axes are namespaced alias:axis and default from the library.
3. Variable value. A plain value applies under every theme. For a themed value, an entry matches when every axis named in its when equals the effective value of that axis; axes it does not name are ignored (partial when is allowed). Entries without when, or with when: {}, are fallbacks only and never candidates. Among matching entries the last one in list order wins (no specificity ranking).
4. No candidate. Use the fallback entry — the last entry without when (or with when: {}) — if there is one, otherwise the first entry. In both cases emit the lint THEME_NO_MATCH(variable, effectiveTheme).
5. Aliases resolve recursively with cycle detection: a cycle is the error VARIABLE_CYCLE.
6. Library variables ({ "$ref": "alias:name" }) resolve inside the library: a when key axis of the library reads the consumer's effective value of alias:axis, or the library's default for that axis. Paste-without-import copies the variables, with a "use existing" / "add renamed" choice.