write-ui

write-ui

Write the UI for the project. The UI core is pure data transformation: it takes the application state and returns a view-spec, lays it out, and resolves hits, all as data. The renderer sits at the edge and consumes the positioned view-spec. Read first:

• the project's view-spec reference (the widget vocabulary, data shapes, event format, layout model, hit-testing). This is the concrete spec; this skill is the recipe for authoring against it.
• the project's design-language reference (the principles, the token system, the component template, the state design every view must cover, and the design-review checklist).
• the project's token catalog (spacing, type, color, depth, motion). The vocabulary the view-spec references; never inline a raw value.
• skills/shared/references/architecture.md for the Functional Core / Imperative Shell split. The whole UI core lives in its pure core.
• design-ui (sibling), the design-first recipe that produces the surface's design spec before this recipe implements it. Implement against the design spec; do not re-decide the design here.

Where UI code lives

The whole UI core is pure functions under the UI module. None do IO, hold an atom, read a clock, call native, or transact. Input arrives as data from the shell; the view-spec leaves as data for the shell to render. If you reach for a side effect in this module, the design is wrong: move the effect to the shell and keep the decision here.

The contract: view-spec is description, not instruction

The view-spec is the UI's intermediate representation. It describes what the UI is right now; it never tells the renderer how to draw. Hold to this:

• Every widget is a plain map with a type and type-specific keys. No functions, no closures, no objects. A view-spec is serializable data: printable, diffable, testable, scriptable.
• Events are data, not callbacks. Handlers are vectors of action data under an :on key. Late-binding values the UI cannot know yet use placeholder keys; the shell substitutes them when the event fires.
• Re-derive the whole tree from the root each frame. No component-local state, no subtree subscriptions. All UI logic lives in one entry point; given the same state it returns the same view-spec.
• Persistent structures, deliberately. Build the new view-spec by transforming the old state's data, so unchanged subtrees stay identical objects. The renderer's diff exploits this structural sharing; a rebuild that copies unchanged subtrees defeats it.