Getting started

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 lab Claude Code skill routes UI design requests to the right workflow and builds, audits, or fixes UI against the same rules.

Quick start

pnpm add ui-lab-components

Then add your app-owned token layer and import ui-lab-components/styles.css. Follow the Installation guide for the required stylesheet order and a complete working setup.

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.

lab Claude Code skill

Type $lab in Claude Code and describe what you want. The skill picks one of six routes (setup, build, ideate, audit, quickfix, or conform), says which one it chose, and runs it against the MCP registry, so components come from real APIs and examples instead of memory.

See Skill for requirements and what each route does.

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