GuidesHow-to guidesTask-focused walkthroughs that pick up after the Learn track. Each guide is scoped to one workflow.
GuidesTask-shaped guides. Each one walks a single job end to end.
Writing your first spec
A hands-on walk-through of a complete screen_spec.json. We will author a Counter screen from scratch — check your setup, declare state and handlers, then run the validate / generate / build / verify loop that keeps spec and layout in sync. By the end you will have a spec the generator can turn into Layout JSON and a ViewModelBase — plus a clear sense of which files are yours and which are @generated./guides/writing-your-first-spec
Writing layouts
Layout JSON is the single biggest file family you author in a JsonUI project, and a handful of idioms make it much easier to read. The same JSON ships to iOS (SwiftUI / UIKit), Android (Compose / XML), and Web (React) — each platform's generator projects it into native code, but the vocabulary you author in is one. This guide walks the cross-platform essentials: how styles get shared, how sub-layouts are reused via include, how Collection cells and sections work, the @{binding} and visibility story, and the pitfalls every first-time layout author trips over./guides/writing-layouts
Navigation between screens
Navigation in JsonUI is a platform-external contract: the spec declares intent (transitions + onNavigate method), the generator emits a typed callback stub in the Data interface, and every platform's router layer — Route enum, NavigationStack, NavHost, Next.js page.tsx — is hand-written. This guide shows the contract, what the generator actually emits (spoiler: not much), and how to wire the routers yourself on each platform./guides/navigation
Writing screen tests
JsonUI tests are JSON files — same language as your layouts. One file describes a screen or a flow, and a per-platform driver (XCUITest for iOS, Espresso / UI Automator for Android, Playwright for Web) executes it. The CLI is jsonui-test, shipped inside jsonui-cli — there is no `jui test` command. This guide covers the real shape of tests, the action/assert DSL, the drivers, and the invocation flow./guides/testing
Mocking APIs in tests
Test a screen without its backend. jsonui-test generates mock responses from your OpenAPI / Swagger, serves them from a local mock server, and lets each test pick a scenario (success / error / empty) — so the same `.test.json` can drive the happy path and the failure path against deterministic data./guides/api-mock
Adding a new language
One strings.json feeds three different output shapes: a Swift StringManager struct, an Android strings.xml resource tree, and a reactive TypeScript StringManager singleton. There is no standalone `jui localize` command — it is all handled by `jui build`'s resource distribution step. This guide covers the real asymmetries between platforms and the five mechanical steps for adding a new locale./guides/localization
Colors and theming
One colors.json feeds every platform's colour handling: the palette per mode, the generated ColorManager, and — on web — the Tailwind `@theme` block. `jui build` also registers colours for you: a raw hex in a layout is extracted into the palette and the layout is rewritten to reference the name. This page covers what that does, when it helps, and where it stops short of a curated palette./guides/colors
Web framework adapters
Since jsonui-cli 1.6.7, every web-framework-specific string rjui emits — the RSC directive, the Link component wiring, the router import, hook and type — is resolved through an adapter selected by `web_framework` in rjui.config.json. The default is the built-in Next.js adapter, whose output is the historical emit byte for byte. Declaring a custom adapter object retargets the same Layout JSON to any React-family framework — Remix, TanStack Start, and friends — without touching the tool./guides/web-framework-adapters
Building a custom component
Authoring a custom component in JsonUI is a three-layer contract — spec, project whitelist, platform converter — plus a scaffold and a hand-editable component body. This guide walks the full chain using the docs site's own CodeBlock component as the running example, so every file path is one you can open./guides/custom-components
Developer menuiOS · Android
DeveloperMenuContainer is a DEBUG-only wrapper shipped with SwiftJsonUI and KotlinJsonUI. You put it around your app's root content, and in DEBUG builds it exposes two gestures: double-tap opens a sheet listing every screen so you can jump to any one of them; long-press toggles Dynamic Mode, which makes the app hot-reload Layout JSON from a running `jui hotload listen`. In Release builds — or when you pass enabled: false — the container vanishes and your content renders plain. This guide shows how to wire it up on iOS and on Android (ReactJsonUI has no equivalent, so the Web side of your app stays unchanged)./guides/developer-menu
Verifying implementation against docs
Set up `jsonui-doc check` end to end: declare checks in your config, wire up an adapter for whichever backend framework you're using, run the check locally and in CI, and read the resulting HTML page. Includes copy-pasteable snippets for FastAPI, Spring, NestJS, and Rails./guides/verifying-implementation-against-docs
Branch contracts
A screen spec can declare each method's branches as a machine-checkable table. The optional `branchContracts` section keeps those declarations inside a closed vocabulary of names the spec has already declared — so `jsonui-doc validate` can check them, the generated documentation renders them as decision tables, and `jsonui-test` can generate unit tests from them. Available since jsonui-cli 1.6.18; existing specs without the section are untouched./guides/branch-contracts
Branch tests
One branchContracts declaration, three platforms of real-stack unit tests: `jsonui-test generate branch-tests` emits vitest for web, JUnit4 (Robolectric) for Android, and XCTest for iOS from the same branch tables — mocking nothing but the HTTP boundary. This page covers the command, the generated files and who owns them, the harness contract on each platform, the errors that stop generation, and how to trust the result./guides/branch-tests
Unit contracts
The spec declares which unit test cases exist and on which platforms; `jsonui-test generate unit-stubs` writes the missing ones as failing stubs, and `--check` fails when the declared set and the implemented set disagree. The bodies stay hand-written — this mechanism is about the SET, not the code. This page covers the declaration, what the config must supply, the generation contract (append-only, and why that had to be fixed), the three kinds of drift, and the iOS naming rule that decides whether a test runs at all./guides/unit-contracts
Referencing the API canon from a spec
A dataFlow method that declares an `endpoint` is already pointing at an operation in your OpenAPI documents. Since jsonui-cli 1.7.0 it can reference that operation instead of restating it: `"params": "@canonical"` expands to the operation's parameters at build and validate time, and `"returnType": "@canonical.wire"` lifts the schema name its success response carries. Whatever the canon does not describe stays hand-written beside the mark./guides/canonical-marks