color-primary: #60a5fa; --color-primary-hover: #93c5fd; }

```ts
// Button.tsx (styling integration)
const variantStyles = {
  primary: 'bg-[var(--color-primary)] hover:bg-[var(--color-primary-hover)]',
  secondary: 'bg-gray-200 hover:bg-gray-300 dark:bg-gray-700 dark:hover:bg-gray-600',
  ghost: 'bg-transparent hover:bg-gray-100 dark:hover:bg-gray-800',
};

// Apply via className composition
className={cn(
  'rounded-[var(--radius-md)] font-[var(--font-sans)] transition-[var(--transition-base)]',
  variantStyles[variant]
)}

Architecture Decision: CSS variables + token-driven styling enable runtime theming without JavaScript overhead. It also simplifies dark mode, high-contrast, and brand customization.

Step 4: Enforce Accessibility & Testing

Accessibility cannot be retrofitted. Implement ARIA attributes, keyboard navigation, and focus management at the component level. Test behavior, not pixels.

// Modal.tsx (focus trap skeleton)
import { useEffect, useRef } from 'react';

export const Modal = ({ isOpen, onClose, children }: ModalProps) => {
  const trapRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!isOpen || !trapRef.current) return;
    const focusable = trapRef.current.querySelectorAll<HTMLElement>(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    const first = focusable[0];
    const last = focusable[focusable.length - 1];

    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === 'Tab') {
        if (e.shiftKey && document.activeElement === first) {
          e.preventDefault();
          last.focus();
        } else if (!e.shiftKey && document.activeElement === last) {
          e.preventDefault();
          first.focus();
        }
      }
    };

    trapRef.current.addEventListener('keydown', handleKeyDown);
    first?.focus();
    return () => trapRef.current?.removeEventListener('keydown', handleKeyDown);
  }, [isOpen]);

  if (!isOpen) return null;
  return (
    <div ref={trapRef} role="dialog" aria-modal="true" aria-labelledby="modal-title">
      {children}
    </div>
  );
};

Testing Strategy:

• Unit: Test prop variations, conditional rendering, event handlers.
• Integration: Test keyboard navigation, focus management, ARIA state changes.
• Visual: Snapshot only critical layout states; avoid pixel-perfect drift.

Step 5: Package, Version, and Distribute

Treat components as libraries. Use library mode bundlers, enforce tree-shaking, and adopt semantic versioning. Document usage with interactive examples.

Architecture Decision:

• Monorepo: Best for internal teams. Enables shared tooling, atomic commits, and zero-publish friction.
• Published Package: Best for cross-team or external consumption. Requires stricter API stability and changelog discipline.
• Versioning: SemVer for public packages. CalVer or commit-hash tagging for internal monorepos.

Pitfall Guide

1. Over-abstracting too early Building a "generic" component before seeing 3 real use cases leads to leaky abstractions. Wait for pattern recurrence before extracting.

2. Coupling UI to business logic Components should not fetch data, manage auth, or handle routing. Pass data and callbacks. Keep components presentational or behaviorally scoped.

3. Ignoring accessibility from day one Adding aria-* later breaks component contracts. Implement focus management, keyboard navigation, and screen reader announcements during initial development.

4. Prop API sprawl (God Components) When a component accepts 15+ props, it's trying to do too much. Split into compound components or use configuration objects with discriminated unions.

5. Missing documentation & playgrounds Reusability dies without discoverability. Every component needs: props table, usage examples, accessibility notes, and an interactive sandbox.

6. Inconsistent versioning & breaking changes Changing prop types or default behavior without major version bumps breaks consumers. Use deprecation warnings, codemods, and migration guides.

7. Neglecting performance Unmemoized callbacks, unnecessary re-renders, and heavy runtime styling inflate bundle size and hurt TTI. Use React.memo, useCallback, and virtualized lists where applicable.

Production Bundle

Action Checklist

• Audit existing UI for duplication patterns; identify top 5 candidate components
• Define TypeScript prop contracts before implementation; exclude business logic
• Implement compound/slot architecture for complex components
• Extract design tokens to CSS variables; decouple styling from behavior
• Add keyboard navigation, focus traps, and ARIA states during initial build
• Write integration tests for accessibility and state transitions
• Configure library bundler with tree-shaking and peer dependency declarations
• Publish to internal registry or npm with automated changelog and versioning

Decision Matrix

Configuration Template

// package.json
{
  "name": "@acme/ui",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "vite build && tsc --emitDeclarationOnly",
    "lint": "eslint src --ext .ts,.tsx",
    "test": "vitest run",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "typescript": "^5.3.0",
    "vitest": "^1.0.0",
    "eslint": "^8.56.0",
    "prettier": "^3.2.0"
  }
}

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { resolve } from 'path';

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      formats: ['es', 'cjs'],
      fileName: (format) => `index.${format === 'es' ? 'js' : 'cjs'}`,
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
      },
    },
    sourcemap: true,
    emptyOutDir: true,
  },
});

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "declaration": true,
    "declarationDir": "./dist",
    "emitDeclarationOnly": true,
    "outDir": "./dist",
    "strict": true,
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx"]
}

Quick Start Guide

1. Scaffold the library

   npm create vite@latest @acme/ui -- --template react-ts
   cd @acme/ui
   npm install react react-dom --save-peer
   npm install -D vite typescript vitest eslint prettier
   

   Replace vite.config.ts and tsconfig.json with the templates above.

2. Create your first component

   mkdir src/components/Button
   touch src/components/Button/Button.tsx src/components/Button/Button.test.tsx
   

   Implement the component using the API-first + composition pattern. Export from src/index.ts.

3. Add tests & linting

   npx vitest init
   npm run lint
   npm run test
   

   Ensure all tests pass and ESLint reports zero errors. Add @testing-library/react and @testing-library/jest-dom for integration tests.

4. Build & verify

   npm run build
   ls dist/
   # Should output: index.js, index.cjs, index.d.ts, index.js.map
   

   Link locally with npm link or pnpm link to validate tree-shaking and peer dependency resolution.

5. Publish or integrate For internal use, add to your monorepo workspace. For public distribution, configure npm/org scope, set up GitHub Actions for automated publishing, and document migration paths for v1 → v2.

Reusable UI components are not a design system checkbox. They are the foundation of scalable frontend engineering. When built with explicit contracts, compositional architecture, token-driven styling, and accessibility baked into the lifecycle, they compound into faster delivery, lower maintenance, and consistent user experiences. Start small, measure reuse, and treat your component library as production infrastructure.