Getting started

Examples

Real .kimo documents to open in Kimo, point an agent at, export, or use as fixtures. Every file is generated by scripts/build-examples.ts from typed @kimo/editor-state ops, so the set is reproducible and stays valid as the format evolves:

2 min read

·

Kimo 1.0 · format 1.0

On this page2 sections

Try the merge driver
Use the library

bun run build:examples   # rebuild every .kimo and preview.png
bun run check:examples   # CI: files on disk match the build, and `kimo validate --strict` passes

All of them pass kimo validate --strict (no errors and no warnings, libraries loaded). The thumbnails are rendered headless with the same CanvasKit renderer and Yoga layout as the canvas.

Example	What it shows
`landing-page/`	A marketing page built entirely with auto layout: nested row/column frames, `fill`/`fit` sizing, `between`/`center` distribution, per-side strokes, gradients, shadows, Lucide icons, color/number variables.
`mobile-app/`	Three 390×844 screens for a habit tracker. Local components with declared props (`text`, `boolean`), instances with `args`, `set` overrides (icon swap, active tab), absolute positioning inside a flex parent, radial/linear gradients.
`dashboard/`	An analytics dashboard with components and derived variants (`Button/Secondary`, `Badge/Warning`, `NavItem/Active` are instances marked as components), an `instance` prop that swaps a nested badge, and variables over two theme axes: `mode` (light, dark) × `density` (comfortable, compact). The dashboard is itself a component; the board shows it as authored and as an instance pinned to dark + compact.
`design-system/`	A library (`meta.library: true`, `kimo-ds.lib.kimo`): color, radius and space tokens, composite `typography` and `shadow` tokens (feature `tokens/composite`), buttons (primary + secondary/danger variants), an input with text and boolean props, a badge, and a card with two slots (`content`, `actions` with suggested components).
`library-consumer/`	A settings page that imports the design system as `ds` (`"imports": {"ds": "../design-system/kimo-ds.lib.kimo"}`): `ds:` instances, slot content placed with `at`, bindings to `ds:` variables, and a theme pin on the library's own axis (`"ds:mode": "dark"`).
`merge-demo/`	`base.kimo`, `ours.kimo` and `theirs.kimo` for the semantic merge driver: both sides change the price (a true conflict); ours adds a feature line, theirs renames the plan and recolors the button (clean changes).

landing-page/

What it shows A marketing page built entirely with auto layout: nested row/column frames, fill/fit sizing, between/center distribution, per-side strokes, gradients, shadows, Lucide icons, color/number variables.

mobile-app/

What it shows Three 390×844 screens for a habit tracker. Local components with declared props (text, boolean), instances with args, set overrides (icon swap, active tab), absolute positioning inside a flex parent, radial/linear gradients.

dashboard/

What it shows An analytics dashboard with components and derived variants (Button/Secondary, Badge/Warning, NavItem/Active are instances marked as components), an instance prop that swaps a nested badge, and variables over two theme axes: mode (light, dark) × density (comfortable, compact). The dashboard is itself a component; the board shows it as authored and as an instance pinned to dark + compact.

design-system/

What it shows A library (meta.library: true, kimo-ds.lib.kimo): color, radius and space tokens, composite typography and shadow tokens (feature tokens/composite), buttons (primary + secondary/danger variants), an input with text and boolean props, a badge, and a card with two slots (content, actions with suggested components).

library-consumer/

What it shows A settings page that imports the design system as ds ("imports": {"ds": "../design-system/kimo-ds.lib.kimo"}): ds: instances, slot content placed with at, bindings to ds: variables, and a theme pin on the library's own axis ("ds:mode": "dark").

merge-demo/

What it shows base.kimo, ours.kimo and theirs.kimo for the semantic merge driver: both sides change the price (a true conflict); ours adds a feature line, theirs renames the plan and recolors the button (clean changes).

Try the merge driver

cd examples/merge-demo
cp ours.kimo /tmp/merged.kimo
bunx kimo merge base.kimo /tmp/merged.kimo theirs.kimo
# kimo merge: merged.kimo: 3 changes applied, 1 conflict stored. Open the file in Kimo to resolve them.
# exit code 1 = merged with stored conflicts
bunx kimo validate /tmp/merged.kimo     # valid (1 warning): CONFLICT_OPEN until it is resolved

The merged file holds ours for the conflicting price plus a conflicts table (spec §21); Kimo opens it on the Conflicts panel. As a git merge driver:

git config merge.kimo.driver "kimo merge %O %A %B %P"
echo '*.kimo merge=kimo diff=kimo' >> .gitattributes

Use the library

Libraries are linked by relative path and loaded read-only when the consumer opens. Validate the consumer with its library next to it (the CLI follows imports automatically):

bunx kimo validate --strict examples/library-consumer/settings.kimo

Agents can open any of these through the MCP server (kimo mcp --headless from the repo root) and read them with kimo_get_state / kimo_query.