io.github.mlolahqPublished by GitHub account mlolahqv1.15.2Updated Nov 11, 2026
Mlola UI components, tokens and design rules for coding agents, with a markup checker
Mlola UI gives coding agents the component library's rules, components and tokens, checks written markup, and can render small interfaces in the conversation.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.mlolahq%2Fmlola-ui/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"mlola-ui": {
"type": "http",
"url": "https://ui.mlola.com/mcp"
}
}
}The Mlola UI source-copy CLI. It writes components, blocks, pages, and templates into your project, rewrites their imports to fit it, and installs the Mlola packages they import with your package manager. Framework-free: the copied markup works in any language that can emit HTML, and React sources use only React.
The library's contract is generated from its own stylesheet, so a model reading it cannot invent a class or attribute that does not exist.
init writes mlola.config.json, the engine stylesheet, and the instructions
your coding agents read (see below), and installs @mlola-ui/engine. It fits
the project it finds: files go where the @/ alias in tsconfig.json points,
or into src/ when there is one. Without an alias, as in a new Vite app, it
sets "imports": "relative" and the copied files import each other by
relative path, so nothing needs setting up first. In a Next.js project it
prints the root layout that imports the stylesheet, sets the theme on
<html> and loads every theme's fonts.
add resolves the dependency graph (a page pulls its blocks, a block pulls its
components), copies only what you asked for, and installs the packages the
copied code imports that package.json does not declare yet. Pass
--no-install to only print the command. doctor checks the project against
the registry: packages the installed items import, the engine import, the
theme attribute on <html>, the themes' fonts the project never loads, and
files changed since they were added.
Tailwind can stay in the project. The engine places Mlola's layers above Tailwind's preflight in either import order.
check reads source. audit opens the page: a desktop and a phone, light
and dark, in the project's own Playwright (npm install -D playwright; the
CLI ships no browser). It reports text cut off or running out of its card, a
control over another element's text, fields in a row that do not line up,
sideways scroll, images that did not load, a menu or dialog past the
window's edge, text below the contrast floor and errors the page threw:
--interact also presses what opens (menus, dialogs, tabs) and checks each
state; it presses the page's real buttons, so it is off unless asked for.
These are the audits Mlola runs over its own components.
check runs the same check as the MCP server's check_markup over every
HTML, JSX, TSX, Vue, Svelte, Astro and CSS file in the project (or the paths
you name), and reports each issue with its line and fix:
It ends with the drift: how many different colors and spacing values were
typed by hand instead of read from the tokens, and which ones most. It works
in any project, so it can measure one before it uses Mlola. In a Mlola
project it leaves out what the CLI installed (--all takes the copied markup
in; Mlola's own stylesheets, the built theme among them, are held by the
library's gates and never checked); where
Tailwind, UnoCSS or Windi is installed it leaves utility classes alone and
counts only the values typed into them (bg-[#fafafa], p-[13px]).
It exits 1 when it finds an error (with --strict, a warning too), and on
GitHub Actions each issue is also an annotation on the pull request:
migrate makes the changes a machine can make without guessing, and lists
the rest with the line and what to do. Mlola installs a component at the
same file shadcn/ui did (components/ui/button.tsx), so imports stay as
they are. It reads by default; --write makes the changes.
It rewrites props written out as literals (variant="destructive" becomes
variant="danger", a Badge's variant becomes its tone), moves sonner
and the older use-toast to Mlola's toast (toast.error becomes
toast.danger), switch to toggle, and the lucide-react glyphs Mlola
has to @mlola-ui/icons, in the file's own import style. It leaves a value
computed at runtime, a cva() helper and a component whose API differs
(Dialog, Select, Dropdown Menu…) to you, naming the attributes or the
component that replace each one.
init (or agents, in an existing project) tells the project's coding agents
that its UI is Mlola:
mlola.agents.md: the design guide, with the project setup (the theme on
<html>, every theme's fonts), what each layout primitive does, every
class, data-* value and token, and the rules for new UI;AGENTS.md: a short section between markers pointing at the guide (merged,
never overwritten), and CLAUDE.md importing it for Claude Code;.mcp.json (and .cursor/ or .vscode/ when the project uses them): the
Mlola MCP server;.claude/settings.json: a hook that runs mlola-ui check --hook on each
file Claude Code edits and hands what it finds back to the agent
(--no-hooks leaves it out);.github/workflows/mlola-check.yml, with --ci only: the check on every
pull request.npx mlola-ui mcp is that server. It answers from the registry bundled with
this CLI, offline: get_design_rules, search_components, get_component,
get_tokens, check_markup (classes and tokens that do not exist, with the
closest that do; wrong data-* values and React props; a control's class on
an element that cannot be operated; buttons, links, fields and images with no
name; utility classes; and in style attributes, <style> blocks and
utility classes, the colors, spacing, type sizes, radii, shadows, durations
and layers typed by hand, and faded text, each with its line and fix),
get_render_catalog, check_render and render_ui (Mlola Render, below),
audit_page, add_components and init_project. For Claude Code
without init:
It is started by your agent and talks over stdio, so run by hand it prints one
line and waits. The same tools, minus the two that write, answer at
https://ui.mlola.com/mcp for agents that cannot run a command (with
get_install_command, which also gives the CDN link and script for a page with
no build step), and the server
is listed in the MCP Registry as io.github.mlolahq/mlola-ui. See
https://ui.mlola.com/docs/agents for Cursor, VS Code, Codex and chat apps.
When an agent should show interface instead of writing code for it (a form
in a chat, a status card in an agent's app), it composes
A2UI v0.9 messages from the Mlola Render catalog: free
components and named values, never a color or a class. The check holds them
to the catalog and to what makes a surface usable (a name on every field, one
root, no loops, headings in order, values in range) and answers in A2UI's
VALIDATION_FAILED shape, so the agent fixes its own messages:
The MCP tools are get_render_catalog, check_render and render_ui. In a
chat that shows MCP Apps, render_ui draws the surface in the conversation
(its view is the resource ui://mlola/render), and what the person presses
comes back to the agent as their next message, with A2UI's action. The A2UI
catalog is mlola-ui/render/catalog and
https://ui.mlola.com/a2ui/catalog/v1.
With a model you call yourself, mlola-ui/render/ai is what goes around the
call: the system prompt, a reader for what the model answers (as it streams,
and however it wrapped the JSON), and the loop that hands a refused reply
back with its errors. Mlola never calls a model and holds no key:
renderSystemPrompt, renderTool, createRenderReader, readRenderReply,
checkRenderReply and renderRepairPrompt are the parts, for a stream, a
tool call or a loop of your own. npx mlola-ui render prompt prints the
prompt for a server in another language.
To draw surfaces yourself: npx mlola-ui add render-surface in React, or
@mlola-ui/behavior/render on a page without a framework. See
https://ui.mlola.com/docs/render.
Pro components, blocks, pages and templates are not in this package. With a license, create a token at https://ui.mlola.com/account, then:
add fetches Pro items and their Pro dependencies from the service, checks
every file against its integrity hash, and writes them like any other item.
Free dependencies still come from this package. Pro stylesheets land in
styles/mlola-pro/, gathered by styles/mlola-pro.css: import it once, after
the engine stylesheet. mlola-pro.agents.md at the project root lists every
Pro class and attribute for coding agents; point your AGENTS.md at it. In CI, set MLOLA_PRO_TOKEN instead of logging in. The
token is stored in ~/.config/mlola-ui/credentials.json, readable by you only.
Aliases and targets live in mlola.config.json:
The CLI works from an npm tarball with no repository checkout; the packed installation is tested in CI.
MIT licensed. Part of Mlola UI.
Source: packages/cli/README.md at commit 952f4b8
Mlola design rules
The rules for building UI with Mlola: compose first, color by role, measure with the scales, shared state words, touch and focus; the project setup (the theme on <html>, every theme's fonts); and what each layout primitive does. Read once before writing UI.
Takes no parameters.
Search Mlola components
Find components, blocks, pages and templates by what they do (for example 'date range', 'chat input', 'pricing'). Returns name, tier (free or Mlola Pro) and a one-line description.
kindtierqueryHow to use a Mlola component
Everything needed to use one item: import, every prop with fixed values (variant, tone, size, side…) and its default, the classes it styles and the data-* values each reacts to, dependencies and the install command. Set include_source to read a free component's source.
namerequiredinclude_sourceMlola design tokens
The --ml-* tokens grouped by purpose (planes and ink, color roles, spacing, type, density, shape, depth, motion, layers…). Filter with a group name or part of a token name.
groupCheck markup against the Mlola contract
Checks HTML or JSX: classes and --ml-* tokens that do not exist (with the closest that do), variant classes, data-* values and React props a component does not take, a control's class on an element that cannot be operated (ml-button on a div), buttons, links, fields and images with no name, utility classes, misuse of data-theme or data-mode, and in style attributes, <style> blocks and utility classes (bg-[#fafafa]) what is typed by hand instead of read from a token: colors, spacing, type sizes, radii, shadows, durations, layers, overridden theme tokens and text faded with opacity. Each issue names its line and the fix. Run it on markup you wrote before finishing: pass the whole page or file, <style> blocks included, not an excerpt, since it only checks what it is given.
markuprequiredMlola Render catalog
The components an agent may compose at runtime with Mlola Render, as A2UI v0.9 messages: each component's props and allowed values, how surfaces, data binding and actions work, and complete examples. Read once before composing a surface. format "schema" returns the A2UI catalog (JSON Schema) instead.
formatCheck Mlola Render messages
Checks A2UI messages (createSurface, updateComponents, updateDataModel, deleteSurface) against the Mlola Render catalog before they render: components and props that do not exist, values a component does not offer, colors or styles set by hand, fields and controls without a name, a missing root, children that do not exist or form a loop, headings that skip a level, values outside a range. Each error names its JSON Pointer path and the fix. Pass every message of the surface: one object, an array, or JSON Lines.
messagesrequiredShow Mlola Render UI
Shows an interface in the conversation: a form, a status card, a table of results. Pass A2UI messages composed from the Mlola Render catalog (read get_render_catalog first); they are checked, and drawn with Mlola components where the host shows MCP Apps. When the person presses a button, their next message carries the A2UI action with what they entered. Where the host shows no apps, this answers with the check's report.
messagesrequiredHow to install Mlola components
How to set Mlola up: the commands to run in a project to add components, blocks, pages or templates (with the license step for Mlola Pro items), and the stylesheet link and script for a page with no build step. Leave names out for the setup alone.
names100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
npx mlola-ui initnpx mlola-ui add button sheet hero-split landingnpx mlola-ui doctornpx mlola-ui audit localhost:3000/settingsnpx mlola-ui audit page.html --themes all # a file, in every themenpx mlola-ui audit localhost:3000 --shots .audit # and a screenshot per viewnpx mlola-ui check # the whole projectnpx mlola-ui check src --json # one folder, every issue as data# .github/workflows/ui.ymlname: UIon: pull_requestjobs: mlola: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npx -y mlola-ui@latest check srcnpx mlola-ui migrate # what would change, and what needs a personnpx mlola-ui migrate --write # make the changesnpx mlola-ui add button badge toast --overwrite # the command it printsclaude mcp add mlola --scope project -- npx -y mlola-ui mcpnpx mlola-ui render catalog # what an agent may composenpx mlola-ui render check ui.json # an array, one message, or JSON Linesimport { validateRender } from "mlola-ui/render";import rules from "mlola-ui/render/rules" with { type: "json" };
const { valid, errors } = validateRender(messages, rules);import { composeRender } from "mlola-ui/render/ai";
const { valid, messages, turns } = await composeRender({ rules, request: "A form to book a table for tonight", generate: ({ system, messages }) => callYourModel(system, messages), // answers with the model's text});npx mlola-ui login mlp_…npx mlola-ui add conversation bot{ "aliases": { "components": "@/components/ui", "blocks": "@/components/blocks", "pages": "@/app/pages", "templates": "@/app/templates" }}