reui

This repository (Asymmetric-al/core)

Subordinate to docs/ai/rules/frontend.md, docs/ai/skills/moai-library-shadcn/SKILL.md (generic shadcn rules), and TanStack guides under docs/guides/development/.

Registry (packages/ui/components.json):

• Active style is base-maia (Base UI + Maia). Read the segment before the first - in style to detect the base (base-maia → Base UI).
• @reui is the plain-string registry (free components and c-* examples). Premium blocks/icons need the authenticated object form plus REUI_LICENSE_KEY in git-ignored .env.local — see rules/cli.md. Switch back to the plain form when premium installs are not in progress so contributors without a key can install free items.

Tables:

• Prefer shared DataTableResponsive from @asym/ui/components/shadcn/data-table for standard app tables (see docs/guides/development/tanstack-virtual-foundation.md).
• Use ReUI data-grid when you need ReUI-specific table composition after get_component('data-grid').

Naming: ReUI (@reui, this skill) is unrelated to shadcn-studio /rui (Refine UI) in docs/ai/rules/shadcn-studio-mcp.md.

MCP: reui at https://mcp.reui.io in .mcp.json, .cursor/mcp.json, and .codex/config.toml. The MCP is free; only premium installs need a license key. Never commit REUI_LICENSE_KEY.

Refresh: references/upstream.md.

ReUI for Agents

ReUI is a shadcn-compatible registry. It ships four things you reuse - never redesign:

• components - the 17 ReUI building blocks with real APIs: data-grid, kanban, filters, date-selector, tree, stepper, ... (free)
• examples - free c-* single-pattern use-cases of a component (c-kanban-1); install one and read it to see exact composition
• blocks - premium full-page sections that compose components (data-grid-2, pricing-page-1); Pro or Ultimate license at install
• icons - Motion Icons in 4 styles, static + hover-animated variants; Ultimate license at install

The MCP and this skill are free; only installing premium content needs a license (see rules/registry.md).

Your job: find the right item, install it with the shadcn CLI, read its real API, and adapt by reuse - wire real data and theme it; do not hand-roll or restyle what ReUI already provides. This skill layers on docs/ai/skills/moai-library-shadcn/SKILL.md for generic shadcn rules (spacing, cn(), semantic colors, forms); follow this for everything ReUI-specific.

The core loop (MCP-native)

1. Find - call the ReUI MCP search tool with the user's intent. It returns a ranked, scored list across components/examples/blocks/icons, each with an install command, previewUrl, docsUrl, and componentsUsed. Pass hints (type, component, category, features, free) when you can infer them.
2. Install - run the returned command non-interactively (npx shadcn@latest add @reui/<name> --yes). The CLI resolves deps, aliases, and the base/style from components.json. See cli.md.
3. Read the API (on your base) - first note your base from components.json -> style (this repo uses base-maia → Base UI; radix-nova → Radix UI). For each component an item uses, call get_component(name) and read its inline api (no web fetch); then get_examples(name) to install a worked example and copy its composition - the installed files are already in your base. See components.md.
4. Adapt (reuse-first) - swap demo data for real data, fix icon imports, align tokens. Do not redesign. See adapting.md.

If the ReUI MCP is not configured, fall back to npx shadcn@latest search @reui -q "..." then add - but the MCP gives scored matches + inline APIs; prefer it.

Commands

Run ReUI as explicit slash commands (via the ReUI MCP) or just ask in plain language - both run the same workflow.

Command	Invoke	Does
build	/mcp__reui__build <what>	Compose a page/section/feature from ReUI: plan → install → read API → adapt → craft → audit.
add	/mcp__reui__add <item>	Find & install one component/example/block/icon and wire it in.
fix	/mcp__reui__fix [target]	Diagnose & fix ReUI usage: wrong/undocumented props, base/radix mismatch, missing states, a11y/scroll.
improve	/mcp__reui__improve [target]	Refine + extend existing ReUI UI to a production-exceptional bar (hierarchy, density, states, responsive, motion).

Invocation differs slightly per agent (/mcp__reui__build in Claude Code/Cursor/Windsurf, /mcp.reui.build in VS Code). No command surface? Just describe what you want - this skill drives the identical loop.

When to reach for ReUI vs plain shadcn

Need	Reach for
A full page or section (dashboard, billing, auth, pricing, settings)	compose_page first (plans sections + best blocks), then ReUI blocks
A data table with sorting/filtering/pagination/virtualization	DataTableResponsive in this repo; ReUI data-grid when ReUI-specific composition is required
A drag-and-drop board	the kanban component
Advanced column filtering, date range, tree, stepper, ...	the matching ReUI component
A single generic control already in shadcn (Button, Dialog, Select)	plain shadcn

Detailed references

• rules/registry.md - the four types, the @reui registry, base/radix, free vs premium + license
• rules/workflow.md - the find -> install -> read-API -> adapt loop (most important)
• rules/components.md - the 17 components, the data-grid contract, base vs radix
• rules/adapting.md - reuse-first: preserve the design (no over-customizing), reuse examples + a block's own elements, real data, don't invent APIs
• rules/craft.md - make it exceptional: point of view, hierarchy, density, states, responsive, motion, the bar
• rules/quality.md - security, accessibility, and scroll gates (the done gate)
• rules/styling.md - ReUI extended tokens, theme adaptation, density
• rules/icons.md - portable icons, swapping imports, Motion Icons (static + animated)
• tools.md - the ReUI MCP: golden path, the 19 tools, token rules, result shapes, errors