The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Mlola UI listing page.
A framework-free design system with a machine-readable contract.
The engine emits plain CSS and DTCG JSON with no runtime dependency, interaction behavior ships as a standard DOM module, and React is one supported consumption path — source-copied components — rather than a requirement. Mlola does not ship a utility framework or outsource its identity to a styling, animation, primitive, or icon runtime.
The contract is generated from the stylesheet and audited, so a model cannot
invent a class or attribute that does not exist.
contract.json lists every class and
the data-* / aria-* attributes the CSS reacts to, and
agents.md is generated from the same
source. Both are checked in CI, so the guide can never describe a library that
is not there.
Your coding agent knows it too. npx mlola-ui init writes the guide and an
AGENTS.md section into the project, and npx mlola-ui mcp is an MCP server
that Claude Code, Cursor, Codex and VS Code can ask: which component fits,
which token to read, whether the markup it just wrote is right. Agents that
cannot run a command, such as a chat app, use the same server at
https://ui.mlola.com/mcp. It is listed in the MCP Registry as
io.github.mlolahq/mlola-ui. See
Coding agents.
A theme is a coherent transformation across eight expression channels:
Component anatomy, semantics, keyboard behavior, accessible names, and state contracts remain invariant. Accessibility and user preferences always take precedence over expression.
Canonical themes:
graphite, default) — neutral, crisp, quiet, and product-firstatelier) — editorial, warm, tactile, and measuredmachined) — compact, angular, exact, and dampedaerogel) — light, luminous, elastic, and translucentnordic) — organic, airy, earthy, and gently roundedActivate a theme with native attributes:
Accessibility is a projection applied at every stage, not a channel the vector can trade away. See the architecture, the theme methodology, and the quality contract.
Source is four ordered layers, each built from the one below:
Button, Card, Tabs).Hero, Navbar, Pricing tiers).Landing, Pricing,
Dashboard).The open-source core is MIT: the engine, tokens, behavior, motion, scene, icons, the free components and the CLI. Mlola Pro adds the AI, code, canvas, editor, workflow and chart components, plus blocks, pages and templates. Pro is a one-time commercial license and is not in this distribution; see ui.mlola.com/pricing.
Every item is source-owned through the CLI. See component anatomy.
@mlola-ui/engine — generated static CSS, spring easings, and theme metadata@mlola-ui/behavior — framework-free interaction runtime and shared decision logic@mlola-ui/motion — native kinetic primitives and the spring integrator@mlola-ui/scene — optional lightweight spatial presentation@mlola-ui/icons — Mlola Glyph DNA icon catalog@mlola-ui/registry — validated source metadata and snapshotmlola-ui — source-copy CLIComponents, blocks, and templates are source-owned through the CLI. React
components vendor their own small runtime helpers and share pure decisions with
the framework-free runtime through @mlola-ui/behavior/logic, so the two paths
cannot drift.
Then import styles/mlola/index.css once and set data-theme="graphite" on the
root element. init installs the engine and add the packages each component
imports; files go where your @/ alias points, or into src/. Next.js and Vite
both work as created, with or without Tailwind.
The CLI installs the open-source components. With a Mlola Pro license, create a token at ui.mlola.com/account, then:
The public repository, mlolahq/mlola-ui,
is exported from the main repository, where code generation and the full audit
suite run; its generated stylesheets, tokens and registry are their output.
See MIRROR.md there.
The repository rejects shipped Tailwind, clsx, tailwind-merge, CVA, Lucide, Radix, transitions.dev, and external motion runtimes. Development-only verification tools are not shipped to consumers.
See CONTRIBUTING.md, the changelog, and the 0.3 to 1.0 migration guide.