ConceptsWhy JsonUIThe ideas behind the framework: spec-first, one Layout JSON per screen, ViewModel-owned state, hot reload everywhere.
IdeasSmall essays. Each one explains why the framework makes the choice it does. Read in any order.
Why spec-first
The spec is not documentation. It is the contract the design surface, the engineer, and the agent all sign. Every other artifact — Layout JSON, ViewModel base classes, navigation glue, generated tests — descends from it./concepts/why-spec-first
One Layout JSON per screen
The same file drives SwiftUI, Jetpack Compose, and React. Not a lowest-common-denominator intermediate format — the generator emits each platform's idiomatic code. Here is the thinking behind that choice./concepts/one-layout-json
ViewModel-owned state
The Layout has no state. Every mutation — counter increments, form inputs, toggle flips — flows through the ViewModel. Here is why that constraint makes the whole system easier to reason about./concepts/viewmodel-owned-state
Data binding as contract
`@{variable}` is how a layout JSON names a field on its ViewModel. What the field holds, how strongly it is type-checked, and whether the widget can write back into it depends on the platform and on the widget — the Layout JSON stays the same across all three./concepts/data-binding
Hot reload everywhere
One JSON edit, three simulators update in under a second. On web the React dev server you already run does it — Next.js dev in the default setup, but any dev server that watches your source tree; iOS and Android both run a Dynamic mode that pulls Layout JSON over the network at runtime. Here is how each platform does it./concepts/hot-reload
Responsive design
One Layout JSON should not look the same on a 5-inch phone, an 11-inch tablet, and a split-screen iPad. The `responsive` block lets a single component swap attribute values per size class — without forking the layout file. Here is how the resolver picks which set of values wins, what the generator emits per platform, when responsive is the wrong tool — and the `home@regular.json` variant files that swap the whole tree when it is./concepts/responsive-design
Screen composition
Three ways to put one Layout JSON inside another: `include` lets the codegen inline a sub-layout under the same ViewModel; `TabView.tabs[].include` runs multiple layouts under one parent VM; `Embed` hosts a sub-screen with its own ViewModel. The choice changes how state, lifecycle, and navigation work — pick the wrong one and you fight the framework. Here is the trade-off and the decision rule./concepts/screen-composition
Screen identity and navigation assertion
A test should be able to say 'we are on the my-page screen' without knowing a single element inside it. That needs one shared answer to 'what is a screen, and what is it called' — used by layouts, specs, tests, generated code and the transition diagram alike. Here is that answer, and the runtime marker that makes it checkable./concepts/screen-identity
Implementation contract check
Docs (spec / swagger / DB models) are the source of truth for what gets generated. `jsonui-doc check` verifies that the real running implementation still matches those docs — schema by schema, endpoint by endpoint. Here is the design and how to read the reports./concepts/implementation-contract-check
DB schema check (docs/db ⇔ live DB)
Every table under `docs/db/` is a schema-only OpenAPI file describing the real database. The builtin db-schema checker in `jsonui-doc check` compares those files against the live schema — declaration vs declaration, confidence `proof` — so migrations can never drift away from the docs unnoticed. This page covers the file format, exactly what gets compared, and how to wire the check up./concepts/db-schema-check