Building Component Library React

We built this skill so you don't have to reinvent the wheel every time a design system is needed. You're an engineer. You know the drill: copy a Button from one repo, paste it into another, tweak the props, break the types, and spend three days fighting Vite config. We analyzed how top engineering teams structure reusable UI frameworks, and we distilled that into a skill that scaffolds the architecture, configures the build pipeline, and enforces documentation standards out of the box.

The Copy-Paste Graveyard of Your UI Library

Your component library is a copy-paste graveyard. You have a Button in packages/ui, a Button in packages/dashboard, and a Button in packages/mobile-web that all look slightly different because the CSS variables drifted. You're spending hours manually updating package.json exports, fighting with Rollup externalization, and writing Storybook stories that rot the moment a prop changes. The result is a library that works on your machine but breaks when a consumer installs it, because peer dependencies are missing, tree-shaking is dead, and the barrel export is a circular reference nightmare.

This isn't just annoyance; it's architectural decay. When you're building a component library, the boundary between your library and the consumer app is fragile. Every time you change a prop type, you risk breaking downstream apps. Every time you update a theme, you risk visual regressions. Without a disciplined structure, your library becomes a liability, not an asset. You're essentially maintaining multiple versions of the truth, and the truth is always slightly broken.

The Hidden Cost of a Broken Build Pipeline

Every hour spent fixing a build config is an hour not spent shipping features. If your library has 50 components and you change a theme variable, you're manually regenerating docs and hoping the snapshots pass. That's how regressions sneak into production. A broken export map means your consumers get Module not found errors at runtime, and support tickets pile up. You're also missing out on modern tooling like automatic documentation generation ^[4], which saves teams from writing stale READMEs.

The cost compounds. A team we observed spending 15 hours a week on library maintenance could have shipped three major features if that time was redirected. That's $15,000/month in wasted engineering salary for a single library. And that's just the direct cost. The indirect cost is design drift. When the library is hard to update, designers stop trusting it. They start building custom components in the app, bypassing the library entirely. Now you have two codebases to maintain, and the library is just a graveyard of unused code.

If you're also building a design system, the stakes are even higher. A design system is a product, and products need reliable tooling. Without it, you're just writing CSS in the dark.

How a Fintech Team Scaled from One Button to a Design System

Imagine a team building a design system for a fintech app. They start with a simple Button component. By week two, they have Button, ButtonGroup, and IconButton. They need theming. They look at how Carbon for IBM Products handles this with dedicated theme add-ons ^[6]. They decide to use CSS variables for theming. They set up Storybook. They use Storybook 9 to track test coverage automatically ^[8], realizing 30% of their components have no tests. They refactor to use CSF3 with composeStories for testing ^[8]. They configure Vite for library mode, using Oxc for minification. They scaffold the structure. This is exactly what the skill does.

The team didn't start with a perfect setup. They started with a mess. They copied components, broke the build, and spent days debugging. Then they realized they needed a better way. They looked at how Open Sesame Gemini structures their Material Design library ^[1]. They saw how Material UI handles recipes and integration ^[7]. They decided to template their best practices. This is the approach the skill encodes. You don't have to figure it out. You just install and ship.

If you're building a Tailwind component kit, you might think CSS-in-JS is the way. But if you're building a library that needs to be framework-agnostic or support multiple styling solutions, you need a solid foundation. The skill gives you that foundation.

What Changes When the Library Is Locked Down

Once this skill is installed, you have a production-ready foundation. The scaffold-lib.sh script generates the directory structure, package.json with modern exports, and installs dependencies. Vite is configured with Oxc minification, Rollup externalization, and CSS code splitting. Storybook is set up with CSF3, interactions, and theme preview decorators. Tests use Vitest + React Testing Library with composeStories for snapshot testing. A validator script checks exports, barrel files, and naming conventions. References guide you on optimization and architecture.

You can focus on building components, not fighting the build system. The library becomes a reliable contract. Consumers can install it, and it just works. The exports map is correct. The types are correct. The docs are up to date. The tests pass. The theme works. You can sleep at night.

This is what a React app from scratch should feel like, but for your library. You get the same level of confidence, but for your reusable UI.

What's in the Building Component Library React Skill

• skill.md — Orchestrator guide defining the component library architecture, build pipeline, and testing workflow. References all templates, scripts, validators, and reference docs.
• templates/vite-lib.config.ts — Production-grade Vite library configuration with Oxc minification, rollup externalization, CSS code splitting, and path aliases.
• templates/storybook.config.ts — Storybook main configuration for React-Vite, including essentials, interactions, and theme preview decorators.
• templates/Button.stories.tsx — CSF3-compliant story template demonstrating tags (!test, !dev), typed args, and render functions for isolated component documentation.
• templates/Button.test.tsx — Vitest + React Testing Library test suite using composeStories for snapshot and interaction testing, mirroring Storybook's portable stories pattern.
• scripts/scaffold-lib.sh — Executable shell script that scaffolds the library directory structure, generates package.json with modern exports, and installs dependencies.
• validators/validate-exports.sh — Programmatic validator that checks package.json exports field, barrel exports in index.ts, and story file naming conventions. Exits non-zero on failure.
• references/storybook-csf3-and-testing.md — Canonical reference on Storybook CSF3 tags, composeStories API, Vitest integration, and snapshot testing patterns extracted from official docs.
• references/vite-library-build-optimization.md — Canonical reference on Vite library mode build config, minifier selection (Oxc/Terser), terserOptions, and deep import pre-bundling strategies.
• references/react-component-library-architecture.md — Architectural best practices for React libraries: modular feature-based structure, CSS variable theming, accessibility standards, and tree-shaking optimization.

Install and Ship

Stop guessing the config. Start shipping. Upgrade to Pro to install.