Shelf — React Component Library & Design System

Design systems solve the consistency problem: when multiple developers build features, visual and behavioral consistency degrades without shared primitives. Shelf provides a foundation layer that enforces consistent spacing, typography, color usage, and interaction patterns. Base UI primitives handle the accessibility complexity (focus management, ARIA attributes, keyboard navigation) so component consumers don't have to think about it. The publishable package format means teams can install it as a dependency rather than copying component files.

The system is structured as a monorepo with the component library as the core package and the documentation site as a consumer. Components follow a composable pattern: atomic primitives (Button, Input) compose into compound components (DatePicker, Select) which compose into page-level patterns (LoginForm, DataTable). Theme management uses CSS custom properties with a persisted toggle. The build pipeline uses tsup for ESM output with proper exports map and .d.ts generation. Documentation uses Next.js App Router with MDX-like content for per-component pages.

Component variants are defined using class-variance-authority (cva) with typed props. Theme tokens are CSS custom properties organized by category (colors, spacing, typography, shadows). Component state (open/closed, active/inactive, disabled) maps to visual variants through Tailwind classes. The playground state manages component previews with live prop editing.

The hardest challenge was making components fully accessible while keeping the API simple. Base UI handles complex accessibility patterns (dialog focus trapping, combobox keyboard navigation, accordion ARIA) but the component wrapper had to expose these capabilities without leaking complexity. Theme consistency across 100+ components required strict token usage — no hardcoded colors, only CSS variables. The tsup build required careful package.json exports configuration to support both ESM imports and TypeScript path resolution.

Tree-shaking ensures consumers only bundle used components. CSS variables enable theme customization without JavaScript overhead. Component lazy-loading is supported via dynamic imports. The documentation site uses ISR for fast page loads. The playground uses code splitting to avoid bundling all component previews upfront.

Component error boundaries prevent individual component failures from crashing the page. The documentation site has fallback rendering for failed MDX compilation. The playground catches and displays component errors inline. Build failures are reported with specific component and file references.

Bundle size tracking per component in the build output. Accessibility audit results displayed per component. TypeScript strict mode catches type errors at build time. Visual regression testing is planned for theme changes.

Base UI over Radix UI for stronger unstyled primitive support. Tailwind CSS 4 over CSS Modules for developer velocity and consistency. tsup over Rollup for simpler configuration with equivalent output. Framer Motion over CSS animations for complex interaction patterns. Recharts over D3 for React-native chart components.