Vui Starter
npm

Guides

Building with AI agents

VUI ships an agent-ready usage guide so your AI coding assistant produces consistent, token-driven, accessible UI on the first pass instead of reinventing the design system. This page covers using the theme in your own app.

Which guide do I need?

Two scenarios, two homes. When you're using the theme in your own app(this page), your agent reads the package's AGENT.md. When you're contributing to the theme itself, see Contributing (humans) and its AGENTS.md (agents).

Where the guide lives

The full guide ships inside the npm package at node_modules/@viliha/vui-ui/AGENT.md. The fastest way to wire it up is the ready-made CLAUDE.template.md that comes with the package: copy it to your project root as CLAUDE.md (Claude Code) or AGENTS.md(Cursor, Copilot). It's a one-line @import of AGENT.md, so the rules stay in one place and you never paste them by hand.

wire up the guide (recommended)
# after: npm install @viliha/vui-ui
cp node_modules/@viliha/vui-ui/CLAUDE.template.md ./CLAUDE.md
# or ./AGENTS.md, and your agent reads it automatically

Prefer a self-contained copy over the @import? Copy AGENT.md itself:

or copy the guide verbatim
cp node_modules/@viliha/vui-ui/AGENT.md AGENTS.md

Also on GitHub

The repo carries two companion files: AGENTS.md (rules for agents working in this repo) and CONTRIBUTING.md (for humans contributing to the theme). The package AGENT.md is the one you want for consuming VUI downstream.

How do I connect the VUI MCP server?

Run npx @viliha/vui-ui mcp and register it with your agent. The package ships an MCP server so an assistant can ask VUI direct questions (how do I install it, what components exist, what props a component takes, how the organizations page is built) instead of reading through node_modules and guessing. These docs ship with it as markdown, so it runs over stdio, needs no API key and no network, and answers for whatever version of the package you installed.

register the server
# Claude Code
claude mcp add vui -- npx -y @viliha/vui-ui mcp

# Cursor, Windsurf, or any MCP client (.mcp.json / mcp.json)
{
  "mcpServers": {
    "vui": { "command": "npx", "args": ["-y", "@viliha/vui-ui", "mcp"] }
  }
}

Seven tools come with it:

  • list_guides — every page of this docs site, from Installation to the per-component reference. It ships inside the package as markdown, so it works offline and matches the version you installed.
  • get_guide — one guide in full, as markdown with its code samples.
  • list_components— every export with its import specifier, straight from the package's src/.
  • get_component — the source for one component, or its public API (props and exported types) when the file is large, plus the doc sections that describe it.
  • list_pages— the reference app's pages, layouts and shell components with their routes.
  • get_page — the full source of any of those files, so the agent copies a working page instead of inventing one.
  • search_docs — searches all of it at once: AGENT.md, the README, and every guide. Call it with no query to get the outline.

MCP is an addition, not a replacement

Keep the CLAUDE.md pointer above. It loads the rules every session; the MCP server answers the follow-up questions on demand. They read the same files, so the two never disagree.

What the guide enforces

  • Reuse first. Look for an existing component, layout, variant, or utility before creating anything new, and extend before you build.
  • Tokens only. Never hard-code colors, spacing, radius, shadows, or typography. Read the semantic tokens from theme.css (--background, --foreground, --button-primary, …).
  • Follow the page pattern. SetPageTitle → action header with <Breadcrumbs /> → a single scrolling content region (p-4, gap-4).
  • Datatables use RecordView with a fields array, never hand-rolled HTML tables. Charts use ChartContainer plus Recharts with chart tokens.
  • Accessibility and dark mode are mandatory: keyboard nav, visible focus, ARIA, WCAG AA, and both light and dark driven from tokens (no per-component color overrides).
  • Keep business logic out of the UI, prefer Server Components, and always surface loading, empty, success, and error states.

Package exports vs. reference-app patterns

The package ships the primitives: Button, Input, Select, Dialog, Menu, RecordView, ChartContainer, and theme.css. The app-shell pieces the guide references (SetPageTitle, Breadcrumbs, the sidebar and nav-config, and the AuthCard* auth screens) are reference-app patterns to copy from the backoffice demo rather than package exports. The shipped AGENT.mdmakes this distinction explicit so your agent won't invent imports.