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.

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.

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="background-800 foreground-100 border-700">

// Wrong — breaks dark mode and design system
<div className="flex bg-slate-900 text-gray-100 border border-slate-800">

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

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.Left expanded>
    <Panel.Toggle />
  </Panel.Left>
  <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