File format spec

§13

Feature flags

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

A document MUST list in features every gated construct it uses (FEATURE_NOT_DECLARED otherwise). A property equal to its default never needs its feature.

Feature	Unlocks
`layout/wrap`	`layout.wrap`, `layout.crossGap`
`layout/stretch-baseline`	`layout.align` `"stretch"` and `"baseline"`
`size/min-max`	`min` / `max` in `fit` / `fill` sizes
`text/runs`	`content` as TextSpan[]
`tokens/composite`	variable types `typography`, `shadow`, `dimension`; `style.typography`; `effects` as a binding
`fill/mesh`	`kind: "mesh"` paints
`fill/shader`	`kind: "shader"` paints
`node/script`	`script` nodes
`node/browser`	`browser` nodes
`merge/conflicts`	root `merge` and `conflicts` (stored merge conflicts, §21)

layout/wrap

Unlocks layout.wrap, layout.crossGap

layout/stretch-baseline

Unlocks layout.align "stretch" and "baseline"

size/min-max

Unlocks min / max in fit / fill sizes

text/runs

Unlocks content as TextSpan[]

tokens/composite

Unlocks variable types typography, shadow, dimension; style.typography; effects as a binding

fill/mesh

Unlocks kind: "mesh" paints

fill/shader

Unlocks kind: "shader" paints

node/script

Unlocks script nodes

node/browser

Unlocks browser nodes

merge/conflicts

Unlocks root merge and conflicts (stored merge conflicts, §21)

Feature gates apply wherever the construct appears, including instance props and set overrides. Opaque records (script inputs, shader uniforms, args; Appendix B) hold data, not document constructs, and are never gated. Enum option values are gated as values of the prop's field (an option {dir:"row", wrap:true} for field: "layout" needs layout/wrap). style.typography is gated wherever a TextStyle appears (node style, TextSpan style). A reader that does not support a listed feature MUST open the file read-only (§16.3); validators report it as FEATURE_UNKNOWN (warning). Feature names have the form area/name (^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*$).

Keywords:

MUST

MUST NOT

SHOULD

MAY

set in small mono caps wherever they are normative