AI Coding (MCP) – Once UI

About

Once UI is an agent-first design system that empowers indie creators to build high-quality, responsive apps — without wrestling with complexity. Designed for AI-native workflows, it turns abstract intent into concrete interfaces with minimal syntax.

Agent harness (recommended for codegen)

For writing UI code, use the harness — not full doc pages. Bootstrap plus one task bundle is about 45–50KB, read in two or three steps.

Artifact	URL	When to load
Manifest	/ai/manifest.json	Entry point — lists all harness files, and in imports every entry point (/data, /code, /media, /mdx, /next, /config) with its exports
Compact rules	/ai/rules.compact.md	Always, before any UI task (~7KB)
Component catalog	/ai/catalog.json	Pick components by purpose; also lists the icon names
Task index	/ai/tasks/index.json	Match user intent → a task id (pricing, dashboard…)
Task bundle	/ai/bundles/pricing.json	One file per task: the task, every component slice it names, their types, mixins and gotchas
Component slice	/ai/components/Grid.json	Only for a component the bundle doesn't have — one file per component, with its types and importFrom when it is not on the package root
Tokens	/ai/tokens.json	Design tokens, mixins and layout shorthands
Functions	/ai/functions.json	The hooks and helpers (useHotkeys, defineConfig, createMdxComponents, the OG route handlers) with their signatures and types
Spec	/ai/spec.json	Everything above in one 131KB file, for tooling. Agents don't need it
Gold example	/ai/examples/*.tsx	Mimic structure for the task type
Pro blocks	/ai/examples/blocks/manifest.json	Production-quality composition references
Gotchas	/ai/gotchas.json	When using Background, Card, RevealFx, Fade, and for the behaviour fixed in 2.1 (Toast, NumberInput, Select, ContextMenu)

npm imports (version-pinned):

Bash

npm install @once-ui-system/core
npx once-ui-init-agent   # writes AGENTS.md, CLAUDE.md and a Cursor rule in your app (one-time)

Tsx

// Conceptual — read in your agent environment
// @once-ui-system/core/ai/manifest.json
// @once-ui-system/core/ai/rules.compact.md
// @once-ui-system/core/ai/bundles/pricing.json

Machine-readable discovery: onceUi field in @once-ui-system/core package.json.

Workflow:

Load rules.compact.md and catalog.json
Resolve intent → pick a task from tasks/index.json and read its bundle (e.g. bundles/pricing.json). Read everything you need in one step: an agent re-sends every file it has read on each later turn
Fetch a component slice only for a component the bundle doesn't have
Read the gold example for structure; for production fidelity, read matching Pro blocks from examples/blocks/manifest.json
Generate code
Validate: npx once-ui-validate-ai-code path/to/file.tsx (in a Next.js app it also checks that LayoutProvider comes from @once-ui-system/core/next)

MCP Server (exploratory docs)

For how does X work? questions, agents can pull docs through Context7's MCP server.

To configure it:

Open mcp_config.json in File / Preferences / Settings / Plugins
Add the following configuration:

Json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

Restart your IDE
Run: get-library-docs /once-ui-system/core

Use Context7 for exploration. Use the harness for codegen.

Syntax advantage

Compared to Tailwind + shadcn, Once UI yields more compact output, with cleaner, more natural syntax — semantic Row/Column, token props, and purpose-built components.

That compactness only pays off when agents load the harness and follow the rules — especially layout shorthands (fill, center), surface recipes, and component appropriateness (Card is interactive-only).