File format spec

§3

Value types

Status

Stable (format version 1.0.0, frozen 2026-10). Backward compatible within 1.x (§16.4). Supersedes the draft v0.1, kept as a historical record; 0.1 files open through the 0.1 → 1.0 migration (§16.2).

Schema

https://getkimo.design/schema/kimo-1.0.json (JSON Schema draft 2020-12), generated into packages/core-schema/schema/kimo-1.0.schema.json. The 0.1 schema stays published at …/kimo-0.1.json (schema/kimo-0.1.schema.json, frozen).

Reference

@kimo/core-schema (packages/core-schema). Where this document and the implementation disagree, that is a bug in one of them; file an issue.

Plan of record

docs/teardown.md §10. Every place where this spec resolves an ambiguity in, or deviates from, that section is listed in §20.

License

MIT

Name	Grammar / shape	Notes
Id	`^[A-Za-z0-9]{6,24}$`	Node id; never contains `/` or `:`. Unique per document (it is the key in `nodes`). Kimo generates 10-character base62 ids. Importers keep matching ids and re-key others.
Alias	`^[A-Za-z][A-Za-z0-9_-]{0,31}$`	Import alias (§11).
QId	`Id` or `alias:Id`	A local node, or a node of the library imported as `alias`.
IdPath	QIds joined by `/`	One segment per instance boundary (§9.5). Override keys are id paths only, never names.
Name	`^[^\s:$][^\s:]{0,127}$`	Variable and theme-axis names: no whitespace, no `:` (reserved for library namespaces), not starting with `$`. `/` and `.` are allowed (`text/default`, `color.surface`).
Axis key	`Name` or `alias:Name`	Key of a theme pin or of a `when` condition.
Order key	`^[0-9A-Za-z]{1,64}$`	Fractional index. Writers SHOULD generate keys with random jitter so concurrent inserts rarely collide.
Ref (binding)	`{ "$ref": "name" }` or `{ "$ref": "alias:name" }`	Exactly one member. A binding is the only way to reference a variable: a plain string is always literal (`"$49/mo"` is text).
Num	number or Ref
Hex color	`^#([0-9A-Fa-f]{3}\|[0-9A-Fa-f]{6}\|[0-9A-Fa-f]{8})$`	sRGB `#RGB`, `#RRGGBB`, `#RRGGBBAA`. `#RGBA` is not allowed.
OKLCH color	`{ "space": "oklch", "l": 0–1, "c": ≥0, "h": [0,360), "alpha"?: 0–1 }`	`alpha` defaults to 1.
Display-P3 color	`{ "space": "display-p3", "r": 0–1, "g": 0–1, "b": 0–1, "alpha"?: 0–1 }`	`alpha` defaults to 1.
Color	hex, OKLCH, Display-P3, or Ref
BlendMode	`normal`, `darken`, `multiply`, `color-burn`, `linear-burn`, `lighten`, `screen`, `color-dodge`, `linear-dodge`, `overlay`, `soft-light`, `hard-light`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`	Paints and shadows. Editor labels: `linear-burn` is "Plus darker", `linear-dodge` is "Plus lighter".
LayerBlendMode	BlendMode or `pass-through`	Node `blend` (§5.3).
Relative path	`^\.{1,2}/(?:[^\\/\s]+/)*[^\\/\s]+$`	`./x` or `../x`; no scheme, no absolute path, no backslash.
Asset reference	`^\./assets/[0-9a-f]{16}\.[a-z0-9]{1,8}$`	First 16 lowercase hex digits of the file's SHA-256, plus extension.
Meta key	`^[a-z][a-z0-9-]*(\.[A-Za-z0-9_-]+)+$`	Namespaced extension key, e.g. `kimo.export.tag`.
Prop name	`^[A-Za-z_][A-Za-z0-9_]{0,63}$`	Declared component property (usable as a React prop).

Grammar / shape ^[A-Za-z0-9]{6,24}$

Notes Node id; never contains / or :. Unique per document (it is the key in nodes). Kimo generates 10-character base62 ids. Importers keep matching ids and re-key others.

Alias

Grammar / shape ^[A-Za-z][A-Za-z0-9_-]{0,31}$

Notes Import alias (§11).

QId

Grammar / shape Id or alias:Id

Notes A local node, or a node of the library imported as alias.

IdPath

Grammar / shape QIds joined by /

Notes One segment per instance boundary (§9.5). Override keys are id paths only, never names.

Name

Grammar / shape ^[^\s:$][^\s:]{0,127}$

Notes Variable and theme-axis names: no whitespace, no : (reserved for library namespaces), not starting with $. / and . are allowed (text/default, color.surface).

Axis key

Grammar / shape Name or alias:Name

Notes Key of a theme pin or of a when condition.

Order key

Grammar / shape ^[0-9A-Za-z]{1,64}$

Notes Fractional index. Writers SHOULD generate keys with random jitter so concurrent inserts rarely collide.

Ref (binding)

Grammar / shape { "$ref": "name" } or { "$ref": "alias:name" }

Notes Exactly one member. A binding is the only way to reference a variable: a plain string is always literal ("$49/mo" is text).

Num

Grammar / shape number or Ref

Notes

Hex color

Grammar / shape ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$

Notes sRGB #RGB, #RRGGBB, #RRGGBBAA. #RGBA is not allowed.

OKLCH color

Grammar / shape { "space": "oklch", "l": 0–1, "c": ≥0, "h": [0,360), "alpha"?: 0–1 }

Notes alpha defaults to 1.

Display-P3 color

Grammar / shape { "space": "display-p3", "r": 0–1, "g": 0–1, "b": 0–1, "alpha"?: 0–1 }

Notes alpha defaults to 1.

Color

Grammar / shape hex, OKLCH, Display-P3, or Ref

Notes

BlendMode

Grammar / shape normal, darken, multiply, color-burn, linear-burn, lighten, screen, color-dodge, linear-dodge, overlay, soft-light, hard-light, difference, exclusion, hue, saturation, color, luminosity

Notes Paints and shadows. Editor labels: linear-burn is "Plus darker", linear-dodge is "Plus lighter".

LayerBlendMode

Grammar / shape BlendMode or pass-through

Notes Node blend (§5.3).

Relative path

Grammar / shape ^\.{1,2}/(?:[^\\/\s]+/)*[^\\/\s]+$

Notes ./x or ../x; no scheme, no absolute path, no backslash.

Asset reference

Grammar / shape ^\./assets/[0-9a-f]{16}\.[a-z0-9]{1,8}$

Notes First 16 lowercase hex digits of the file's SHA-256, plus extension.

Meta key

Grammar / shape ^[a-z][a-z0-9-]*(\.[A-Za-z0-9_-]+)+$

Notes Namespaced extension key, e.g. kimo.export.tag.

Prop name

Grammar / shape ^[A-Za-z_][A-Za-z0-9_]{0,63}$

Notes Declared component property (usable as a React prop).

Numbers MUST be finite. Colors are specified in their own space; renderers and exporters map them deterministically, gamut-mapping out-of-gamut values with the CSS Color 4 algorithm, and CSS emitters SHOULD write the original oklch() / color(display-p3 …) value.

Keywords:

MUST

MUST NOT

SHOULD

MAY

set in small mono caps wherever they are normative