← Toolsjsonui-docThe DOC GEN sub-CLI. Python tool that generates HTML, Markdown, Mermaid diagrams, per-platform test adapters, and Figma-as-HTML from JsonUI screen specs, component specs, test JSON files, and Figma API responses. 13 subcommands across four groups: init / validate / generate / figma. The doc_generate_* MCP tools and the /reference HTML pages on this very site are produced by this binary. The swagger-parsing core that originated here (`document_tools/.../swagger.py`) is now also wired into `jui g api` for the swagger-driven DTO + Domain codegen pipeline.~10 min read
What jsonui-doc isThe fifth of the six sub-CLIs under a single jsonui-cli install. Unlike the platform builders (sjui / kjui / rjui) that turn Layout JSON into native code, jsonui-doc turns specs, test files, and Figma exports into human-readable HTML and Markdown. It is the CLI behind every /reference page, every stakeholder preview link, and every doc_generate_* MCP tool call.
When to reach for itFour recurring scenarios. (1) Publish human-readable mirrors of screen and component specs for stakeholders who do not read JSON. (2) Produce end-to-end test documentation and platform-specific adapter code from a single tests/ tree. (3) Mirror a Figma file as HTML with a sidebar navigation for asynchronous design review. (4) As the backend for MCP doc_generate_* calls — agents delegate here rather than regenerating HTML themselves.
Commands by categoryFour groups totaling 13 subcommands. init and validate lift the spec lifecycle; generate is the largest group and the one day-to-day work lands in; figma covers the two-step 'fetch then images' flow with plan-aware throttling to avoid 429s.initvalidategeneratefigma
init specCreate a new screen spec template under specs/ (or a custom directory).-d <display name> -o <output dir>
init componentCreate a new component spec template under components/ (or a custom directory).-c <category> -d <display name> -o <output dir>
validate specValidate a screen spec JSON file — or a directory of them (since 1.6.25) — against the screen_spec schema and the project's custom rules.(positional: path to .spec.json)
validate componentValidate a component spec JSON file against the component_spec schema.(positional: path to .component.json)
generate htmlGenerate an HTML directory with index from a tests/ tree, auto-discovering specs/, components/, figma/, and -d docs directories.-o <out dir> -d <extra docs dir> -fig <figma dir>
generate mermaidEmit a Mermaid flow diagram from a tests/ tree. Prints to stdout, or writes HTML when -o is set. A step that references another test file resolves to that test's `source.layout` rather than the file name, so a variant file folds into the screen it targets; an unresolvable reference falls back to the basename instead of dropping the edge, and a file name claimed by tests of two different screens is left unresolved.-o <out html>
generate adapterGenerate a platform-specific test adapter (ios / android / web) targeting the project test tree.<platform> -o <out dir> -n <project name>
generate docGenerate markdown (default) or HTML from a single .test.json file.-f <file> -o <out> --format html|markdown
generate specGenerate HTML or Markdown from a screen spec file, or in batch mode from a directory of .spec.json files.<file-or-dir> -o <out> --format html|markdown
generate componentGenerate HTML or Markdown from a component spec file, or in batch mode from a directory of .component.json files.<file-or-dir> -o <out> --format html|markdown
figma fetchFetch a Figma file's JSON via the REST API, optionally downloading fills and vector renders. Supports URL parsing, interactive page selection, and node-id targeting.--url <figma url> --node-ids <id…> --images --plan starter|pro|org|enterprise --depth <n> -o <out> -t <token>
figma imagesDownload images for a previously-fetched Figma JSON file, reusing the plan-aware throttle logic.-k <file key> --plan starter|pro|org|enterprise -t <token>
Figma API throttle (Tier 1)Image downloads use 50 % of each plan's rate limit to leave headroom. On HTTP 429 the CLI honours Retry-After and retries automatically. Enterprise bypasses throttling entirely.
starter (default)10 req/min~12 s
pro15 req/min~8 s
org20 req/min~6 s
enterpriseUnlimitedNo throttle
File layout conventionjsonui-doc auto-discovers specs/, components/, tests/, figma/, and html/. Test files under screens/ and flows/ are picked up for generate html / mermaid, -d directories bring OpenAPI or Markdown in, and images land in figma/images/ with a manifest in figma/images.json. The same tree structure is what the MCP wrappers and test adapters assume.
MCP wiringThe doc_generate_spec / doc_generate_component / doc_generate_html MCP tools are thin wrappers that shell out to this CLI. Anything you can do from the command line works identically when called from an agent — same filesystem conventions, same exit codes, same output.
Live sampleBelow is the spec we used for the Hello World tutorial, and what `jsonui-doc generate spec` produces from it. Both tabs are static snapshots — the JSON view is the literal file contents, the HTML view is a hand-pasted snapshot of a recent CLI run. Run it yourself locally and you'll get the same bytes.View this page live → /learn/hello-world
Keep reading
jsonui-mcp-serverThe MCP tools that wrap jsonui-doc — how agents call the DOC GEN path./tools/mcp
CLI commands referenceFull reference for every jui / sjui / kjui / rjui / jsonui-test / jsonui-doc subcommand./reference/cli-commands