ui-lab.app

Overview

UI Lab is a React component library and design system built for accessible, themeable interfaces. It provides 39 carefully crafted React components built on industry-standard accessibility patterns, paired with a semantic design token system and interactive tooling. The monorepo includes an MCP server for AI-assisted development and a full-featured Next.js documentation site with live previews and an interactive theme configurator.

Component Library

The library provides a complete set of UI components organized into 9 categories:

• Layout — Grid, Flex, Gallery, Divider, Expand, Panel
• Composition — Group, List
• Action — Button, Confirm, Command
• Input — Date, Checkbox, Color, Input, Radio, Select, Slider, Switch, Textarea
• Information — Banner, Badge, Label, Tooltip
• Feedback — Popover, Progress, Toast
• Navigation — Path, Menu, Tabs, Anchor
• Container — Page, Card, Modal, Scroll, Mask, Frame
• Display — Table, Code

Key Features:

• Full Accessibility — Built on React Aria with keyboard navigation, focus management, ARIA attributes, and WCAG compliance
• Compound Components — Complex components designed as composable sub-components (e.g., Card.Header/Body/Footer, Modal.Header/Body/Footer)
• TypeScript Support — Complete type definitions for all components
• CSS Modules + CSS Variables — Styled with CSS Modules using CSS custom properties for theming; no required Tailwind dependency for consumers
• UMD + ES Modules — Available in both Universal Module Definition and ES module formats

Design System & Semantic Tokens

• Semantic Color System — 8 color families (background, foreground, accent, success, danger, warning, info) with shade variations (50–950)
• Component + Intent Mappings — Pre-defined color recommendations for component/intent pairs with complete CSS variable pairings including background, text, border, hover, active, and disabled states
• WCAG Compliance Notes — Accessibility guidance built into the design token system
• Design Tokens Registry — Typed registry providing metadata, patterns, elements, sections, and design tokens
• PostCSS Plugin — Custom PostCSS plugin for processing styles

MCP Integration

The ui-lab-mcp package is a Model Context Protocol server that lets AI coding assistants query the library directly with 12 specialized tools:

• search_components — Natural language component discovery
• get_component — Full API, examples, and design guidance
• get_semantic_color — Color recommendations for component + intent pairs
• get_theme_setup — Complete theme provider setup with FOUC prevention
• search_patterns — Design pattern discovery by use case
• get_pattern — Pattern code and design rationale
• search_elements — Multi-component UI block search
• get_element — Element variations and source code
• search_sections — Landing page section discovery
• get_section — Section variations and source
• get_inspiration — Fuzzy discovery across all categories
• get_variation_code — Source code for specific variations

Compatible with Claude Desktop, Cursor, and any MCP-compatible AI development tool.

Documentation & Interactive Site

A Next.js-powered documentation site featuring:

• Component Browser — Category-organized gallery with live preview thumbnails
• Patterns, Elements, Sections, Starters — Browsable, searchable collection with copy-paste code
• Design System Documentation — Colors, typography, spacing, tokens, CSS variables, and accessibility guidelines
• Interactive Theme Configurator — Real-time component preview with full control over OKLCH colors, typography, spacing, and border radius; exports ready-to-use CSS files
• Dark/Light Mode — Full support with FOUC prevention and device preference detection
• Syntax Highlighting — Code examples with Shiki syntax highlighting
• Live Previews — Real-time rendering of components and patterns

Theme System

• ThemeProvider — Central theme management component
• useTheme & useThemeMode Hooks — Runtime theme access and switching
• generateThemeScript — Prevents flash of unstyled content (FOUC)
• localStorage Persistence — Theme preferences persist across sessions
• Light/Dark Mode — Automatic and manual mode switching

What I learned

Shipping a library with an MCP server alongside it changed how I think about documentation. The MCP forces the registry to be machine-readable in a way that also makes it more structured for humans. The theme system — especially preventing FOUC across server and client renders — required more careful coordination than expected between ThemeProvider, generateThemeScript, and localStorage.

Stack

• UI: React 19.2.4, React Aria 3.14+, TypeScript 5.9+
• Site: Next.js 16.2.0, Tailwind CSS 4.1.11, Shiki 3.17.1+
• Bundling: Vite 5.3.4+, PostCSS 4
• Animations: GSAP 3.12.2+
• Icons: Lucide React
• Package manager: pnpm 10.21.0
• Node.js: >= 18
• Build Tools: Changesets for version management, Knip for unused code detection