Marvelous UI (Free pack and agent plugin)

Marvelous UI is a framework-agnostic UI component library: native Web Components (<mv-*> tags), CSS classes on native HTML (.mv-*) and design tokens (--mv-* CSS variables), with zero runtime dependencies. It works in plain HTML, React 19+, Vue 3, Svelte, Angular and Astro.

This repository holds the Free pack (21 components, MIT License) and its agent plugin: a local MCP server, four focused skills, and hooks that check catalog consultation before supported UI writes. Everything here works on its own, with no account, no license key and no purchase.

Install in Claude Code

/plugin marketplace add marvelous-ui/marvelous-ui
/plugin install marvelous-ui@marvelous-ui

From a terminal: claude plugin marketplace add marvelous-ui/marvelous-ui, then claude plugin install marvelous-ui@marvelous-ui.

Requirements: Node.js 20 or later and npm on the PATH. When Claude Code installs the plugin, it installs the MCP server's two dependencies (@modelcontextprotocol/server 2.0.0 and zod 4.6.5) from package-lock.json, with lifecycle scripts disabled. Restart Claude Code or run /reload-plugins, then ask for UI as usual, for example: "Add a settings dialog with tabs and a toast on save."

What the plugin does

Part	File	Behavior
MCP server marvelous-ui	.mcp.json, mcp/server.mjs	Runs locally over stdio (node ${CLAUDE_PLUGIN_ROOT}/mcp/server.mjs). Tools: search_components, list_components, get_component, get_design_tokens (read only), get_install_bundle (returns files, writes nothing) and install_components (copies the chosen components into a folder of your project). Makes no network request. Its only subprocess is a read-only git log on its own folder, to date the components when that folder is a git checkout.
Skills	skills/*/SKILL.md	Build UI, theme components, troubleshoot integrations, or set up the agent connection. The historical marvelous-ui skill handles UI construction.
Hooks	hooks/hooks.json, hooks/search-first.mjs	Check new and existing UI written through Claude Write/Edit or Codex apply_patch. In a task without a successful search or known-component lookup, the first such write is declined once with a reminder; the retry goes through. The reminder provides an offline catalog fallback. Local records are scoped to the project, session and task, and expire after 24 hours. Arbitrary shell writes are outside this guard.

The plugin collects no data and contacts no server. Privacy policy: https://marvelous-ui.com/legal/privacy.html

Components

Component	Use	Description
Badge	.mv-badge	Pure-CSS badge: 7 variants (soft or solid tints), animatable status dot, icon, remove button, pill/square, 3 sizes, and a counter positioned on the corner of an avatar or icon.
Button	.mv-button	Pure-CSS button on <button> or <a>: 6 variants, 4 sizes, loading state, group.
Checkbox	.mv-checkbox	Native pure-CSS checkbox: a self-drawing (reversible) check mark, indeterminate state, sizes, invalid; also provides the shared .mv-choice and .mv-choice-card layouts (option cards highlighted via :has(:checked)).
Input	.mv-input	Pure-CSS text field: 3 sizes, invalid (aria-invalid / :user-invalid), read-only and file states, plus a group with icons, prefixes/suffixes, inline buttons and a clear button.
Kbd	.mv-kbd	Subtly raised keyboard keys on <kbd>: nested combinations, 3 sizes, a flat variant, adapts inside buttons and tooltips.
Radio	.mv-radio	Pure-CSS native radio button: an inner dot that springs in, sizes, an outline variant, inline or stacked groups, and option cards (plan lists, tiles with a badge).
Select	.mv-select	Styled native <select> (token-colored chevron), progressively enhanced into a customizable select (appearance: base-select): animated list, status dots, icons, descriptions and checkmark, optional “liquid” opening; clean fallback elsewhere.
Separator	.mv-separator	Pure-CSS horizontal or vertical separator: solid, dashed, dotted or faded, with a centered (“or”) or aligned label, on <hr> or <div>.
Switch	.mv-switch	Pure-CSS switch on <input type="checkbox" role="switch">: thumb that slides on a spring and stretches when pressed, icons in the thumb (customizable), sizes, label on the left or right, option card.
Textarea	.mv-textarea	Textarea that grows on its own (field-sizing: content) between a minimum and maximum number of rows, with an optional resize handle, a group with a toolbar and an <mv-char-count> character counter.
Field	.mv-field	Pure-CSS field layout: label (required / optional), help text, an error message that shows up on its own when the control is invalid, vertical, horizontal, responsive and inline orientations, choice cards and fieldset.

Per-component docs: docs/components/. Catalog: docs/COMPONENTS.md. Guides: docs/GUIDE.md, docs/MCP.md. Agents without MCP can read llms.txt.

Without the plugin

git clone https://github.com/marvelous-ui/marvelous-ui.git marvelous-ui
cd marvelous-ui
node scripts/add.mjs dialog tabs toast --out ../my-app/src/marvelous

scripts/add.mjs copies each component with everything it needs (tokens, core helpers, other components) and prints the imports. For Codex or another MCP client, run npm ci in the clone, then node scripts/init-agent.mjs /path/to/your-app or node scripts/init-agent.mjs --plugin: see docs/MCP.md.

The npm CLI npx marvelous-ui-library@latest init installs the same Free pack in a project and connects the detected agents.

Editions

Marvelous UI also has a paid edition, the Pro pack, sold at https://marvelous-ui.com. It is not in this repository: this plugin neither contains nor downloads it, and works fully with the 21 free components.

Versions

This repository is generated from the Marvelous UI release pipeline at each release; it is not edited by hand. Version 1.5.2, see CHANGELOG.md. Pull requests cannot be merged as such: open an issue or write to [email protected].

License

The Free pack is released under the MIT License, see LICENSE. Copyright (c) 2026 Quentin Fankrache EI. Only the Free pack is MIT: the Pro pack and the Exclusive components are sold under the Marvelous UI commercial license, not under MIT.

Trademark

The MIT License covers the code, not the brand: it gives no right to the "Marvelous UI" name or logo. A fork must use a different name and must not present itself as the official Marvelous UI product.

Support: [email protected]