# MDMA — Markdown Documents with Mounted Applications > MDMA is an open-source generative UI framework. It extends Markdown with interactive components declared in fenced ```mdma blocks, so an LLM can answer with structured, schema-validated, renderable UI — forms, tables, approval gates — instead of prose or brittle JSON. Because the format is forgiving Markdown rather than strict JSON, small and cheap models emit it reliably. MIT-licensed, built by Mobile Reality. The problem MDMA solves: asking a model for UI as strict JSON fails on small models — one unbalanced brace and the whole payload is unusable, so teams fall back to the largest tier and pay for it on every request. MDMA is Markdown with a schema behind it, which is a shape small models can hold together. How it works: a model writes a document containing ```mdma blocks. The parser turns it into an AST, the validator lint-checks it (17 rules, 6 auto-fix strategies, no LLM required), the runtime holds state, bindings, policy, audit log and PII redaction, and a renderer draws it. Parsing and state are headless, so the same document renders in React, Vue 3 or React Native. Component types (10): form, button, tasklist, table, callout, approval-gate, webhook, chart, thinking, custom. The `custom` type is a stable envelope a host fills with its own components — a model cannot invent `type: timer`, but it can emit `type: custom` with `name: timer` once that variant is registered, so the catalog extends without the spec changing. Reliability: in a cross-format benchmark (1107 generations, each format run from its own published prompt and scored by its own validator, auto-repair off for all of them including MDMA), MDMA rendered every time in 94.4% of scenarios on both a flagship model and an open-weights one — a 0.0pp drop between tiers. The other formats tested dropped 27.8pp and 44.4pp over the same two models. Own model: MobileReality/mdma-gemma4-26b-dsl-unsloth-v1 is a 27B Gemma 4 fine-tune published under Apache 2.0 that reads a compact DSL intent and returns a valid MDMA document. It passes 181/181 committed eval cases. Latest release: 2026-07-27 — Cross-format generative UI benchmark. ## Site - [MDMA home](https://mdma.software): what MDMA is, the component catalog, a live editable demo, the cross-format benchmark and install instructions. - [The MDMA model](https://mdma.software/model): the fine-tuned open-weights model, its DSL, eval results and serving contract. - [Changelog](https://mdma.software/changelog): every release, what shipped in it, and the package versions it published. ## Source and packages - [GitHub repository](https://github.com/MobileReality/mdma): the monorepo — spec, parser, validator, runtime, renderers, prompt pack, CLI, MCP server, evals and benchmarks. - [Model weights on Hugging Face](https://huggingface.co/MobileReality/mdma-gemma4-26b-dsl-unsloth-v1): MobileReality/mdma-gemma4-26b-dsl-unsloth-v1, Apache 2.0, BF16 safetensors. - [@mobile-reality/mdma-parser](https://www.npmjs.com/package/@mobile-reality/mdma-parser): Remark plugin: Markdown → MDMA AST. - [@mobile-reality/mdma-validator](https://www.npmjs.com/package/@mobile-reality/mdma-validator): Static analysis, 17 lint rules, auto-fix. - [@mobile-reality/mdma-runtime](https://www.npmjs.com/package/@mobile-reality/mdma-runtime): State, bindings, audit log, policies. - [@mobile-reality/mdma-renderer-react](https://www.npmjs.com/package/@mobile-reality/mdma-renderer-react): React components for every block type. - [@mobile-reality/mdma-renderer-vue](https://www.npmjs.com/package/@mobile-reality/mdma-renderer-vue): Vue 3 renderer, same API surface as React. - [@mobile-reality/mdma-renderer-react-native](https://www.npmjs.com/package/@mobile-reality/mdma-renderer-react-native): The same documents as native iOS / Android UI. - [@mobile-reality/mdma-agui](https://www.npmjs.com/package/@mobile-reality/mdma-agui): Stream MDMA over AG-UI, route actions back. - [@mobile-reality/mdma-prompt-pack](https://www.npmjs.com/package/@mobile-reality/mdma-prompt-pack): Author, fixer and agent prompts per model. - [@mobile-reality/mdma-attachables-core](https://www.npmjs.com/package/@mobile-reality/mdma-attachables-core): Handlers for the stateful component types. - [@mobile-reality/mdma-spec](https://www.npmjs.com/package/@mobile-reality/mdma-spec): Zod schemas and types for every component. - [@mobile-reality/mdma-cli](https://www.npmjs.com/package/@mobile-reality/mdma-cli): mdma create (prompt builder) and mdma validate. - [@mobile-reality/mdma-mcp](https://www.npmjs.com/package/@mobile-reality/mdma-mcp): Serves the spec, prompts and docs to an LLM. ## Documentation - [Quick start](https://github.com/MobileReality/mdma/blob/main/docs/getting-started/quick-start.md): install, parse a document, render it. - [Key concepts](https://github.com/MobileReality/mdma/blob/main/docs/getting-started/concepts.md): documents, components, bindings, actions. - [Architecture overview](https://github.com/MobileReality/mdma/blob/main/docs/getting-started/architecture.md): how parse, validate, run and render fit together. - [Component catalog](https://github.com/MobileReality/mdma/blob/main/docs/reference/component-catalog.md): the authoritative reference for every component type and its YAML. - [Creating documents](https://github.com/MobileReality/mdma/blob/main/docs/guides/creating-documents.md): authoring MDMA by hand or with an LLM. - [Creating custom attachable handlers](https://github.com/MobileReality/mdma/blob/main/docs/guides/creating-attachables.md): registering your own component behind the `custom` envelope. - [Theming](https://github.com/MobileReality/mdma/blob/main/docs/guides/theming.md): the theme prop, the token shape, and CSS variable overrides. - [Enterprise features](https://github.com/MobileReality/mdma/blob/main/docs/guides/enterprise-features.md): policy engine, PII redaction, tamper-evident audit log. ## Renderers - [React — @mobile-reality/mdma-renderer-react](https://www.npmjs.com/package/@mobile-reality/mdma-renderer-react): The reference renderer. All ten component types, element overrides, custom variants and theming. - [Vue 3 — @mobile-reality/mdma-renderer-vue](https://www.npmjs.com/package/@mobile-reality/mdma-renderer-vue): Same public API, ported to provide/inject and composables. Ships the same styles.css, so a theme is portable. - [React Native — @mobile-reality/mdma-renderer-react-native](https://www.npmjs.com/package/@mobile-reality/mdma-renderer-react-native): Native iOS and Android UI from the same document. Shares the MdmaTheme token shape with the web renderers. ## Optional - [Cross-format benchmark report](https://github.com/MobileReality/mdma/blob/main/benchmarks/genui-formats/results/REPORT.md): full methodology and per-model figures for MDMA against OpenUI Lang, json-render and A2UI. - [Creating blueprints](https://github.com/MobileReality/mdma/blob/main/docs/guides/creating-blueprints.md): packaging a multi-step workflow as a reusable document. - [Mobile Reality](https://themobilereality.com): the team behind MDMA. - [Contributing](https://github.com/MobileReality/mdma/blob/main/CONTRIBUTING.md): how to work on the project. ## FAQ ### What is MDMA? MDMA (Markdown Documents with Mounted Applications) extends Markdown with interactive components defined in fenced mdma code blocks. A regular Markdown file becomes an interactive application with forms, tables, charts, approval gates and more. ### How is MDMA different from raw markdown or a JSON UI contract? Raw Markdown renders as text and a custom JSON UI contract is brittle on smaller models. MDMA is forgiving Markdown that small, cheap models emit reliably, and it is schema-validated so the output is renderable and safe. In a cross-format benchmark, MDMA rendered every time in 94.4% of scenarios on both a flagship model and an open-weights one, a 0.0pp drop between the two tiers. ### Why does MDMA save on tokens? Because MDMA works on small, cheap models such as Gemini Flash and Claude Haiku where strict JSON often breaks. A deterministic validator with 17 lint rules and 6 auto-fix strategies, plus an LLM fixer, keeps the loop cheap — so you don't burn tokens re-asking a large model to repair its own output. ### Which components can MDMA render? Ten types: form, button, tasklist, table, callout, approval-gate, webhook, chart, thinking, and custom. The custom type is a stable envelope your host fills in with its own components, so you can extend the catalog without changing the spec — and an LLM can still author them, because it emits type: custom with a registered name rather than inventing a new type. ### Which frameworks can render MDMA? React, Vue 3 and React Native, via @mobile-reality/mdma-renderer-react, @mobile-reality/mdma-renderer-vue and @mobile-reality/mdma-renderer-react-native. Parsing, state, bindings, policy and audit are headless, so all three share the same core and the same MdmaTheme token shape. ### Which packages does MDMA ship? Twelve packages under @mobile-reality/mdma-*: the spec, parser, validator, runtime and attachables-core, three renderers (React, Vue, React Native), an AG-UI bridge, a prompt-pack, a CLI and an MCP server. ### Can I use MDMA with an agent framework? Yes. @mobile-reality/mdma-agui bridges MDMA and the AG-UI protocol: documents stream in over inline text or a dedicated custom event, user actions (submit, approve, deny, completed checklists, webhook triggers) route back into the agent run, and interrupts let a run pause on an approval gate and resume from the answer. ### Is there a model fine-tuned for MDMA? Yes. MobileReality/mdma-gemma4-26b-dsl-unsloth-v1 is a 27B Gemma 4 fine-tune, published on Hugging Face under Apache 2.0, that reads a compact MDMA-IL DSL intent and returns a valid MDMA document. The LoRA is merged into the base weights, and the model passes all 95 cases in its held-out gate plus the standard author, flows, fixer, guidance and custom-prompt suites. ### Is MDMA open source? Yes. MDMA is MIT-licensed and maintained by Mobile Reality. The source is on GitHub at github.com/MobileReality/mdma. ### Does MDMA work with Claude, GPT and Gemini? Yes. MDMA is model-agnostic: any LLM that can write Markdown can emit MDMA. The prompt-pack ships 36 tuned author-prompt variants across OpenAI, Anthropic, Google, xAI and our own fine-tuned model, so the format works on small, cheap tiers rather than only the largest ones. An MCP server serves the spec, prompts and docs straight to an LLM. ### How do I render MDMA in React? Install @mobile-reality/mdma-renderer-react along with the parser and runtime, parse the markdown to an AST, create a document store, and pass them to the MdmaDocument component. It renders every component type as a live, stateful element. Add a theme prop for light, dark, auto or your own tokens.