File format spec

§8

Text

On this page3 sections

8.1 Content and growth
8.2 TextStyle
8.3 Default text fill

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

8.1 Content and growth

content is a string (always literal), a binding to a string variable, or (feature text/runs) an array of spans { text: string, style?: TextStyle, href?: string, fill?: Color }. A span's style applies on top of the node's style; its fill (a solid color or a color binding) paints that span instead of the node's fill, and its href links that span. Paragraph fields (align, valign) are read from the node's style only. Spans are a delta sequence (they map onto Y.Text attributes), not offsets. Writers SHOULD merge adjacent spans with equal attributes and SHOULD write a plain string when every span would be equal.
grow: "auto" — both dimensions come from the content (single line unless the content has line breaks); w/h are ignored and SHOULD be omitted. "fixed-width" — w is used and text wraps; h comes from the content. "fixed" — both are used; overflow is clipped by an ancestor's clip only.

Keywords:

MUST

MUST NOT

SHOULD

MAY

set in small mono caps wherever they are normative

8.2 TextStyle

Field	Type	Meaning (absent = the reader's default)
`font`	string \| Ref	Family name.
`size`	Num > 0	px.
`weight`	Num 1–1000
`italic`	boolean
`lineHeight`	Num ≥ 0 (multiplier of `size`) \| `{ px: n }`	Absent = the font's default line height.
`letterSpacing`	Num	px.
`align`	`left` `center` `right` `justify`
`valign`	`top` `middle` `bottom`
`decoration`	(`"underline"` \| `"strike"`)[] (unique)
`case`	`upper` `lower` `title`	Render-time transform (also applied when measuring); `content` keeps what was typed. Absent = as typed. `title` capitalises the first letter of each word.
`features`	record 4-char OpenType tag → boolean \| number
`href`	string	Link.
`typography`	Ref	Binds a `typography` variable (feature `tokens/composite`): its fields apply first, inline fields override them.

font

Type string | Ref

Meaning (absent = the reader's default) Family name.

size

Type Num > 0

Meaning (absent = the reader's default) px.

weight

Type Num 1–1000

Meaning (absent = the reader's default)

italic

Type boolean

Meaning (absent = the reader's default)

lineHeight

Type Num ≥ 0 (multiplier of size) | { px: n }

Meaning (absent = the reader's default) Absent = the font's default line height.

letterSpacing

Type Num

Meaning (absent = the reader's default) px.

align

Type left center right justify

Meaning (absent = the reader's default)

valign

Type top middle bottom

Meaning (absent = the reader's default)

decoration

Type ("underline" | "strike")[] (unique)

Meaning (absent = the reader's default)

case

Type upper lower title

Meaning (absent = the reader's default) Render-time transform (also applied when measuring); content keeps what was typed. Absent = as typed. title capitalises the first letter of each word.

features

Type record 4-char OpenType tag → boolean | number

Meaning (absent = the reader's default)

href

Type string

Meaning (absent = the reader's default) Link.

typography

Type Ref

Meaning (absent = the reader's default) Binds a typography variable (feature tokens/composite): its fields apply first, inline fields override them.

8.3 Default text fill

A text node without fill paints with the color variable text/default when the document declares it, otherwise opaque black (#000000). Text is never invisible by omission. An explicit fill: [] (or only invisible paints) is honored and linted (TEXT_INVISIBLE).