What is UI Lab

UI Lab is a React component library where design quality is enforced, not hoped for. Components are built on React Aria and Tailwind v4, with a token system that makes correct usage the path of least resistance.

The AI-native angle: an MCP server lets agents query live component APIs, semantic color recommendations, and curated patterns — so AI-generated UI code is design-system-compliant by default, not by accident.

The problem it solves

AI-generated UIs tend toward visual mediocrity. Hallucinated props, arbitrary hex colors, Tailwind utility names that don't exist in the design system, no enforced color hierarchy. The result is code that runs but looks like it was assembled without taste.

UI Lab makes correct usage machine-readable. The MCP server returns one recommended color per semantic intent — not options, one WCAG-verified answer. It returns real component APIs, not invented prop names. The /design Claude Code skill audits code for violations and substitutes correct tokens mechanically.

Four levels of abstraction

Components — 40+ primitives built with React Aria. Compound patterns (Panel.Sidebar, List.Item, Menu.Item) that compose naturally and share state through context. This is the atomic layer everything else builds from.

Patterns — 15 curated UI compositions as copy-paste TSX. Media objects, stat blocks, empty states, labeled form fields, data table rows, inline alerts. Proven patterns you'd otherwise re-implement across every project.

Elements — multi-component UI blocks for specific domains. The free Foundation package gives you header, sidebar, and page shells. Paid packages add AI chat interfaces ($59.99) and documentation components — scroll-synced TOC, article navigation, copy buttons ($49.99).

Sections & Starters — five full-width landing page sections (Hero, Features, CTA, Pricing, Testimonials) and eight project templates — free framework starters (Next.js, Vite, Tauri, Astro) and complete paid applications (documentation site, CRM, blog, productivity app at $49.99 each).

Quick start

npx ui-lab init

Or manually:

pnpm add ui-lab-components

// Root layout (app/layout.tsx or main.tsx)
import 'ui-lab-components/styles.css';

import { Button, Group, Panel } from 'ui-lab-components';

<Panel>
  <Panel.Header>Settings</Panel.Header>
  <Panel.Content>
    <Group>
      <Button>Save</Button>
      <Button variant="ghost">Cancel</Button>
    </Group>
  </Panel.Content>
</Panel>

For step-by-step setup, see the Installation guide.

The design system

UI Lab uses OKLCH — a perceptually-uniform color space that scales correctly across lightness and generates accessible palettes programmatically. Dark mode is automatic: the token direction reverses, no dark: prefixes needed. The same class works in both modes.

Seven semantic color families with enforced shade ranges:

// Correct — works in light and dark mode automatically
<div className="bg-background-800 text-foreground-100 border border-background-700">

// Wrong — breaks dark mode and design system
<div className="bg-white text-gray-900 border-gray-200">

See the Colors reference for the full token documentation.

AI-native tooling

This is where UI Lab differs from every other component library.

MCP server (ui-lab-mcp)

The MCP server gives AI agents 12 tools that cover the full design workflow:

• Component discovery — search_components, get_component return real prop APIs with design guidance, not documentation summaries
• Design decisions — get_semantic_color returns one WCAG-verified color recommendation per component intent, no guessing
• Pattern & element discovery — search_patterns, get_inspiration, get_variation_code — agents find existing patterns before building from scratch
• Landing blocks — search_sections, get_section for Hero, Features, CTA, Pricing, Testimonials
• Theme setup — get_theme_setup with provider code, toggle component, and FOUC prevention

Every tool response injects the design rules: seven color families, enforced shade ranges, and a blocklist of forbidden patterns — arbitrary hex values, Tailwind defaults like bg-white and bg-zinc-*, shadow utilities, gradient classes.

Setup takes two minutes. See the MCP installation guide.

/design Claude Code skill

The /design skill routes to four sub-agents based on intent:

• design-ideator — structured design brief process for new UI
• design-auditor — detects violations: wrong shade ranges, arbitrary colors, incorrect sub-component usage
• design-refactorer — mechanical substitution of violations for correct tokens using live MCP data
• pattern-explorer — discovers existing patterns before building new ones

The auditor enforces hard rules. bg-white → bg-background-950. text-gray-900 → text-foreground-300. shadow-md → removed. Violations are corrected in the tool response, not flagged for a human to fix later.

See Agent workflows for usage examples.

Composing components

Components are built to combine. Compound sub-components share state through context without prop drilling:

<Panel>
  <Panel.Sidebar defaultOpen side="left">
    <Panel.Toggle />
  </Panel.Sidebar>
  <Panel.Content>
    <List>
      {items.map(item => (
        <List.Item key={item.id} value={item.id}>
          <List.Media>{item.icon}</List.Media>
          {item.label}
          <List.Desc>{item.description}</List.Desc>
        </List.Item>
      ))}
    </List>
  </Panel.Content>
</Panel>

List exposes an imperative ref (focusNext, focusPrev, selectHighlighted) that Select, Menu, and Command use internally. You can wire the same keyboard handling into your own components.

Next steps

• Browse Components — full library reference with live examples
• Explore Elements — multi-component UI blocks
• Installation guide — manual setup, Tailwind v4 config
• MCP server setup — connect Claude, Cursor, or any MCP-compatible agent
• GitHub — source, issues, releases