# Component Library

> Scaffold component library structure with Storybook and documentation

- Skill: `majiayu000/component-library-4` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/component-library-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/component-library-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/component-library-4

---


# Component Library Scaffolding

I'll help you set up a complete component library with Storybook, testing, documentation, and build configuration.

Arguments: `$ARGUMENTS` - library type or framework (e.g., "react", "vue", "web-components", "storybook")

## Strategic Planning Process

<think>
Component library setup requires careful consideration:

1. **Framework Selection**
   - React, Vue, Angular, Svelte, Web Components?
   - TypeScript or JavaScript?
   - What's the target environment? (browser, Node.js, both)
   - Design system or utility components?

2. **Build & Distribution**
   - How will components be bundled? (Rollup, Vite, esbuild)
   - What formats? (ESM, CJS, UMD)
   - Tree-shaking support needed?
   - CSS bundling strategy
   - Type definitions generation

3. **Documentation & Development**
   - Storybook for component showcase
   - Documentation site (Docusaurus, VitePress, etc.)
   - Live playground/examples
   - Design tokens documentation
   - Accessibility guidelines

4. **Quality Assurance**
   - Unit testing (Jest, Vitest)
   - Visual regression testing (Chromatic)
   - Accessibility testing (axe, jest-axe)
   - Build validation
   - Bundle size tracking

5. **Publishing Strategy**
   - npm package setup
   - Versioning strategy (semantic versioning)
   - Changelog generation
   - CI/CD for releases
</think>

## Phase 1: Project Detection & Setup

**MANDATORY FIRST STEPS:**
1. Detect existing project or create new structure
2. Identify framework and build tool preferences
3. Determine component library scope
4. Check for existing Storybook installation

Let me analyze your project:

```bash
# Detect framework and setup
echo "=== Component Library Setup Analysis ==="

# Check for existing framework
FRAMEWORK=""
if grep -q "\"react\"" package.json 2>/dev/null; then
    FRAMEWORK="React"
    echo "Detected: React"
elif grep -q "\"vue\"" package.json 2>/dev/null; then
    FRAMEWORK="Vue"
    echo "Detected: Vue"
elif grep -q "@angular/core" package.json 2>/dev/null; then
    FRAMEWORK="Angular"
    echo "Detected: Angular"
elif grep -q "\"svelte\"" package.json 2>/dev/null; then
    FRAMEWORK="Svelte"
    echo "Detected: Svelte"
else
    echo "No framework detected - will set up for your choice"
fi

# Check for TypeScript
if [ -f "tsconfig.json" ]; then
    echo "TypeScript: ✓"
else
    echo "TypeScript: ✗"
fi

# Check for Storybook
if [ -d ".storybook" ]; then
    echo "Storybook: Already installed"
    ls -la .storybook/
else
    echo "Storybook: Not installed (will configure)"
fi

# Check for build tools
if [ -f "vite.config.js" ] || [ -f "vite.config.ts" ]; then
    echo "Build tool: Vite"
elif [ -f "rollup.config.js" ]; then
    echo "Build tool: Rollup"
elif [ -f "webpack.config.js" ]; then
    echo "Build tool: Webpack"
else
    echo "Build tool: None detected (will configure)"
fi

# Check for existing components
if [ -d "src/components" ]; then
    echo ""
    echo "Existing components:"
    find src/components -type f -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" 2>/dev/null | head -10
fi
```

## Phase 2: Component Library Structure

I'll create a comprehensive component library structure:

**Directory Structure:**
```
component-library/
├── src/
│   ├── components/          # Component source files
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   ├── Button.stories.tsx
│   │   │   ├── Button.module.css
│   │   │   └── index.ts
│   │   ├── Input/
│   │   │   ├── Input.tsx
│   │   │   ├── Input.test.tsx
│   │   │   ├── Input.stories.tsx
│   │   │   └── index.ts
│   │   └── index.ts         # Main exports
│   ├── hooks/               # Shared React hooks
│   ├── utils/               # Utility functions
│   ├── types/               # TypeScript types
│   └── index.ts             # Library entry point
├── .storybook/              # Storybook configuration
│   ├── main.ts
│   ├── preview.ts
│   └── theme.ts
├── docs/                    # Documentation
│   ├── getting-started.md
│   ├── components/
│   └── design-tokens.md
├── dist/                    # Build output
│   ├── esm/                 # ES Modules
│   ├── cjs/                 # CommonJS
│   └── types/               # Type definitions
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── vite.config.ts           # Build configuration
├── vitest.config.ts         # Test configuration
├── .npmignore
└── README.md
```

## Phase 3: Storybook Setup

I'll configure Storybook for component development:

**Install Storybook:**
```bash
# Initialize Storybook (auto-detects framework)
npx storybook@latest init

# Or manual installation for specific framework
npm install --save-dev @storybook/react @storybook/react-vite
npm install --save-dev @storybook/addon-essentials @storybook/addon-a11y
npm install --save-dev @storybook/addon-interactions @storybook/test
```

**Storybook Configuration (.storybook/main.ts):**
```typescript
import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions',
    '@storybook/addon-links',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  docs: {
    autodocs: 'tag',
  },
  staticDirs: ['../public'],
};

export default config;
```

**Storybook Preview (.storybook/preview.ts):**
```typescript
import type { Preview } from '@storybook/react';
import '../src/styles/global.css';

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#1a1a1a' },
      ],
    },
  },
};

export default preview;
```

## Phase 4: Component Templates

I'll create example component templates:

**Button Component (src/components/Button/Button.tsx):**
```typescript
import React from 'react';
import styles from './Button.module.css';

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  /**
   * Button variant
   */
  variant?: 'primary' | 'secondary' | 'outline';
  /**
   * Button size
   */
  size?: 'small' | 'medium' | 'large';
  /**
   * Loading state
   */
  loading?: boolean;
  /**
   * Full width button
   */
  fullWidth?: boolean;
}

/**
 * Primary UI component for user interaction
 */
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  (
    {
      variant = 'primary',
      size = 'medium',
      loading = false,
      fullWidth = false,
      children,
      disabled,
      className,
      ...props
    },
    ref
  ) => {
    const classes = [
      styles.button,
      styles[variant],
      styles[size],
      fullWidth && styles.fullWidth,
      className,
    ]
      .filter(Boolean)
      .join(' ');

    return (
      <button
        ref={ref}
        className={classes}
        disabled={disabled || loading}
        {...props}
      >
        {loading ? <span className={styles.spinner} /> : children}
      </button>
    );
  }
);

Button.displayName = 'Button';
```

**Button Stories (src/components/Button/Button.stories.tsx):**
```typescript
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline'],
    },
    size: {
      control: 'select',
      options: ['small', 'medium', 'large'],
    },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Button',
  },
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    children: 'Button',
  },
};

export const Large: Story = {
  args: {
    size: 'large',
    children: 'Large Button',
  },
};

export const Loading: Story = {
  args: {
    loading: true,
    children: 'Loading...',
  },
};

export const Disabled: Story = {
  args: {
    disabled: true,
    children: 'Disabled',
  },
};
```

**Button Test (src/components/Button/Button.test.tsx):**
```typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { describe, it, expect, vi } from 'vitest';
import { Button } from './Button';

describe('Button', () => {
  it('renders children correctly', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });

  it('applies variant class', () => {
    render(<Button variant="secondary">Button</Button>);
    const button = screen.getByRole('button');
    expect(button).toHaveClass('secondary');
  });

  it('handles click events', async () => {
    const handleClick = vi.fn();
    render(<Button onClick={handleClick}>Click</Button>);

    await userEvent.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it('disables button when loading', () => {
    render(<Button loading>Loading</Button>);
    expect(screen.getByRole('button')).toBeDisabled();
  });

  it('disables button when disabled prop is true', () => {
    render(<Button disabled>Disabled</Button>);
    expect(screen.getByRole('button')).toBeDisabled();
  });
});
```

## Phase 5: Build Configuration

I'll set up build configuration for library distribution:

**Vite Config (vite.config.ts):**
```typescript
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { resolve } from 'path';
import dts from 'vite-plugin-dts';

export default defineConfig({
  plugins: [
    react(),
    dts({
      insertTypesEntry: true,
      include: ['src/**/*'],
      exclude: ['**/*.test.tsx', '**/*.stories.tsx'],
    }),
  ],
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'ComponentLibrary',
      formats: ['es', 'cjs'],
      fileName: (format) => `index.${format === 'es' ? 'mjs' : 'cjs'}`,
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
        assetFileNames: 'assets/[name][extname]',
        chunkFileNames: 'chunks/[name].[hash].js',
      },
    },
    sourcemap: true,
    emptyOutDir: true,
  },
  css: {
    modules: {
      localsConvention: 'camelCase',
    },
  },
});
```

**Package.json Configuration:**
```json
{
  "name": "@your-org/component-library",
  "version": "1.0.0",
  "description": "A React component library",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./styles": "./dist/style.css"
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "test": "vitest",
    "test:ui": "vitest --ui",
    "lint": "eslint src --ext ts,tsx",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@storybook/react": "^7.6.0",
    "@storybook/react-vite": "^7.6.0",
    "@testing-library/react": "^14.0.0",
    "@testing-library/user-event": "^14.0.0",
    "@types/react": "^18.2.0",
    "@vitejs/plugin-react": "^4.2.0",
    "typescript": "^5.3.0",
    "vite": "^5.0.0",
    "vite-plugin-dts": "^3.7.0",
    "vitest": "^1.0.0"
  }
}
```

**TypeScript Configuration (tsconfig.json):**
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,

    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",

    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,

    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "**/*.stories.tsx", "**/*.test.tsx"]
}
```

## Phase 6: Documentation Setup

I'll create comprehensive documentation:

**README.md:**
```markdown
# Component Library

A modern React component library built with TypeScript, Storybook, and Vite.

## Installation

```bash
npm install @your-org/component-library
# or
yarn add @your-org/component-library
```

## Usage

```tsx
import { Button } from '@your-org/component-library';
import '@your-org/component-library/styles';

function App() {
  return (
    <Button variant="primary" size="large">
      Click me
    </Button>
  );
}
```

## Components

- **Button** - Versatile button component with variants and sizes
- **Input** - Form input with validation support
- **Card** - Container component for content
- [See full component list in Storybook]

## Development

```bash
# Install dependencies
npm install

# Start Storybook
npm run storybook

# Run tests
npm test

# Build library
npm run build
```

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT
```

**Getting Started Guide (docs/getting-started.md):**
```markdown
# Getting Started

## Installation

Install the component library in your React project:

```bash
npm install @your-org/component-library
```

## Basic Setup

Import components and styles:

```tsx
import { Button, Input, Card } from '@your-org/component-library';
import '@your-org/component-library/styles';
```

## TypeScript Support

The library is written in TypeScript and includes type definitions:

```tsx
import type { ButtonProps } from '@your-org/component-library';

const MyButton: React.FC<{ onClick: () => void }> = ({ onClick }) => {
  return <Button variant="primary" onClick={onClick}>Click</Button>;
};
```

## Theming

Customize component styles with CSS variables:

```css
:root {
  --primary-color: #007bff;
  --secondary-color: #6c757d;
  --border-radius: 4px;
}
```

## Next Steps

- Browse components in [Storybook](http://localhost:6006)
- Read component documentation
- Check out examples
```

## Token Optimization

**Status:** ✅ Fully Optimized (Phase 2 Batch 4B, 2026-01-27)

**Target:** 70-85% reduction (4,000-6,000 → 800-1,500 tokens)

### Optimization Strategies

**1. Template-Based Scaffolding (80% savings)**
```typescript
// Cache structure in .claude/cache/component_library/
{
  "framework_templates": {
    "react": {
      "button": "prebuilt template",
      "input": "prebuilt template",
      "card": "prebuilt template"
    },
    "vue": { /* ... */ },
    "angular": { /* ... */ }
  },
  "directory_structure": {
    "react": ["src/components", "src/hooks", "src/utils", ".storybook"],
    // ...
  }
}
```

**Before (4,000+ tokens):**
```bash
# Detect framework
grep -r "react" package.json
# Read package.json
cat package.json
# Read tsconfig.json
cat tsconfig.json
# Check for Storybook
ls -la .storybook/
cat .storybook/main.ts
# Check existing components
find src/components -type f
cat src/components/Button/Button.tsx
# ... many more reads
```

**After (800 tokens):**
```bash
# Single framework detection with cached template
if grep -q "\"react\"" package.json 2>/dev/null; then
  # Use cached React template - no reads needed
  TEMPLATE="react"
elif grep -q "\"vue\"" package.json 2>/dev/null; then
  TEMPLATE="vue"
fi

# Apply template directly - no verification reads
```

**2. Framework Detection Cache (90% savings)**
- Detect framework ONCE, cache the result
- All subsequent operations use cached framework choice
- No repeated package.json reads

**Before (2,000 tokens):**
```bash
# Phase 1: Detect framework
cat package.json | grep "react"
# Phase 2: Detect framework again
cat package.json | grep "react"
# Phase 3: Detect framework yet again
cat package.json | grep "react"
```

**After (200 tokens):**
```bash
# Detect once, use cache
FRAMEWORK=$(grep -q "\"react\"" package.json && echo "react" || echo "vue")
# Store in .claude/cache/component_library/config.json
# All subsequent operations: read cache
```

**3. Batch File Generation (75% savings)**
- Generate ALL component files in ONE pass
- Use Write tool for multiple files sequentially
- NO verification reads after generation

**Before (3,000+ tokens):**
```bash
# Generate Button.tsx
cat > Button.tsx << 'EOF'
...
EOF
# Read back to verify
cat Button.tsx

# Generate Button.test.tsx
cat > Button.test.tsx << 'EOF'
...
EOF
# Read back to verify
cat Button.test.tsx

# Generate Button.stories.tsx
# ... repeat for EVERY file
```

**After (750 tokens):**
```bash
# Generate all Button files in sequence - NO reads
# Write tool: Button.tsx
# Write tool: Button.test.tsx
# Write tool: Button.stories.tsx
# Write tool: Button.module.css
# Write tool: index.ts
# Trust template generation - no verification needed
```

**4. No Verification Reads (85% savings)**
- Trust template generation
- Skip reading back generated files
- Only report what was created

**Before (5,000+ tokens):**
```bash
# Generate component
cat > Button.tsx << 'EOF'
...
EOF

# Verify it was created correctly
cat Button.tsx  # 1,000+ tokens

# Generate story
cat > Button.stories.tsx << 'EOF'
...
EOF

# Verify story
cat Button.stories.tsx  # 1,000+ tokens
```

**After (750 tokens):**
```bash
# Generate all files - NO verification
# Report: "✓ Created Button.tsx (component)"
# Report: "✓ Created Button.stories.tsx (story)"
# Report: "✓ Created Button.test.tsx (test)"
# NO reads - trust the templates
```

**5. Cached Storybook Config (80% savings)**
- Pre-cached Storybook configurations for each framework
- NO reads of Storybook documentation
- Direct template application

**Cache structure:**
```json
{
  "storybook_configs": {
    "react": {
      "main.ts": "prebuilt config",
      "preview.ts": "prebuilt config",
      "dependencies": ["@storybook/react", "@storybook/react-vite"]
    },
    "vue": { /* ... */ }
  }
}
```

**Before (3,000+ tokens):**
```bash
# Check Storybook docs
cat .storybook/main.ts
cat .storybook/preview.ts
# Read examples
cat examples/storybook-config.ts
# Generate configuration
```

**After (600 tokens):**
```bash
# Use cached template directly
# .claude/cache/component_library/storybook_react_main.ts
# Apply without reads
```

### Token Usage Breakdown

**Baseline (Unoptimized): 4,000-6,000 tokens**
- Framework detection: 500 tokens (repeated reads)
- Existing file analysis: 2,000 tokens (read all components)
- Template generation: 1,500 tokens (verbose explanations)
- Verification reads: 1,500 tokens (read back all generated files)
- Configuration setup: 500 tokens (read configs)

**Optimized: 800-1,500 tokens**
- Cached framework detection: 50 tokens (single grep, cache read)
- Skip existing file reads: 0 tokens (use cache or Glob patterns only)
- Batch template generation: 400 tokens (Write tool calls only)
- No verification: 0 tokens (trust templates)
- Cached configs: 100 tokens (apply from cache)
- Status reporting: 250 tokens (concise summary)

**Savings: 70-85% reduction**

### Implementation Patterns

**Pattern 1: Framework Detection with Cache**
```bash
# Check cache first
CACHE_FILE=".claude/cache/component_library/config.json"
if [ -f "$CACHE_FILE" ]; then
  FRAMEWORK=$(jq -r '.framework' "$CACHE_FILE")
else
  # Detect once
  if grep -q "\"react\"" package.json; then
    FRAMEWORK="react"
  elif grep -q "\"vue\"" package.json; then
    FRAMEWORK="vue"
  fi
  # Cache result
  echo "{\"framework\": \"$FRAMEWORK\"}" > "$CACHE_FILE"
fi
```

**Pattern 2: Template Application**
```bash
# Use cached template - NO reads
TEMPLATE_PATH=".claude/cache/component_library/templates/$FRAMEWORK/button.tsx"
if [ -f "$TEMPLATE_PATH" ]; then
  # Apply template directly
  cp "$TEMPLATE_PATH" "src/components/Button/Button.tsx"
else
  # Use embedded template (fallback)
  # Generate from prebuilt structure
fi
```

**Pattern 3: Batch Component Generation**
```typescript
// Generate all component files in one batch
const components = ['Button', 'Input', 'Card'];
const files = ['tsx', 'test.tsx', 'stories.tsx', 'module.css', 'index.ts'];

// Single loop - NO verification reads
for (const component of components) {
  for (const file of files) {
    // Write tool call
    // NO Read tool call after
  }
}

// Report creation summary
console.log(`✓ Created ${components.length} components`);
```

**Pattern 4: Storybook Setup from Cache**
```bash
# Check for cached Storybook config
STORYBOOK_CACHE=".claude/cache/component_library/storybook/$FRAMEWORK"
if [ -d "$STORYBOOK_CACHE" ]; then
  # Copy entire config - NO reads
  cp -r "$STORYBOOK_CACHE/" .storybook/
else
  # Generate from embedded template
  # Use prebuilt config strings
fi
```

### Cache Management

**Cache Structure:**
```plaintext
.claude/cache/component_library/
├── config.json                 # Framework, build tool choices
├── framework_templates.json    # Complete component templates
├── storybook_configs.json      # Storybook configurations
├── component_patterns.json     # Common patterns (Button, Input, etc.)
├── templates/
│   ├── react/
│   │   ├── button.tsx
│   │   ├── button.test.tsx
│   │   ├── button.stories.tsx
│   │   └── button.module.css
│   ├── vue/
│   └── angular/
└── storybook/
    ├── react/
    │   ├── main.ts
    │   └── preview.ts
    └── vue/
```

**Cache Invalidation:**
- Framework change detected: Clear framework cache
- Major version updates: Clear template cache
- User request: Clear all caches

### Progressive Disclosure

**Minimal Initial Response:**
```bash
# Detect framework: React ✓
# Using cached component templates
# Generating component library structure...

✓ Created src/components/Button/
✓ Created src/components/Input/
✓ Created src/components/Card/
✓ Configured Storybook
✓ Set up build with Vite

Ready: npm run storybook
```

**Only if user asks for details:**
- Show file contents
- Explain configuration choices
- Provide customization options

### Error Handling

**Fast-fail patterns:**
```bash
# Check prerequisites FIRST
[ -f "package.json" ] || { echo "No package.json found"; exit 1; }

# Detect framework quickly
FRAMEWORK=""
grep -q "\"react\"" package.json && FRAMEWORK="react"
[ -z "$FRAMEWORK" ] && { echo "No supported framework detected"; exit 1; }

# Continue with cached templates...
```

### Integration with Other Skills

**Synergistic Operations:**
- `/scaffold` - Use for individual components
- `/types-generate` - Generate TypeScript types from schemas
- `/test` - Run component tests after generation
- `/format` - Format generated code
- `/docs` - Enhance documentation

**Token-efficient workflows:**
```bash
# Component library setup (800 tokens)
/component-library react

# Test the library (400 tokens with cache)
/test src/components

# Generate documentation (300 tokens with cache)
/docs --update
```

### Measurement & Validation

**Success Metrics:**
- Token usage: 800-1,500 (target: 70-85% reduction)
- Component generation: <2 seconds
- Cache hit rate: >90%
- User satisfaction: Complete library scaffold in single pass

**Validation Steps:**
1. Framework detected correctly
2. All component files created
3. Storybook configured
4. Build configuration valid
5. Tests runnable

### Common Pitfalls to Avoid

**Anti-patterns (HIGH COST):**
```bash
# ❌ Reading every existing component
find src/components -type f -exec cat {} \;  # 10,000+ tokens

# ❌ Verifying every generated file
for file in src/components/**/*; do cat "$file"; done  # 5,000+ tokens

# ❌ Explaining every configuration detail
# Full explanation of Vite, Storybook, TypeScript...  # 3,000+ tokens

# ❌ Repeated framework detection
grep "react" package.json  # Multiple times = wasted tokens
```

**Optimized patterns (LOW COST):**
```bash
# ✓ Detect framework once, cache it
FRAMEWORK=$(grep -q "\"react\"" package.json && echo "react")

# ✓ Use templates, trust generation
# NO verification reads

# ✓ Concise status reporting
echo "✓ Component library ready: npm run storybook"

# ✓ Progressive disclosure
# Details only if user asks
```

### Real-World Scenarios

**Scenario 1: New React Component Library**
- Baseline: 5,500 tokens (full analysis, generation, verification)
- Optimized: 900 tokens (cached templates, batch generation)
- Savings: 84%

**Scenario 2: Add Storybook to Existing Project**
- Baseline: 4,000 tokens (read existing components, configure Storybook)
- Optimized: 700 tokens (cached config, minimal detection)
- Savings: 82%

**Scenario 3: Generate Multiple Components**
- Baseline: 6,000 tokens (individual generation, verification for each)
- Optimized: 1,200 tokens (batch generation, no verification)
- Savings: 80%

### Expected Results

**Before Optimization:**
- 4,000-6,000 tokens per execution
- Multiple reads of package.json, configs, existing components
- Verification reads for every generated file
- Verbose explanations and documentation

**After Optimization:**
- 800-1,500 tokens per execution
- Single framework detection with cache
- Batch file generation with no verification
- Concise status reporting
- 70-85% token reduction achieved

**Maintained Capabilities:**
- Full component library scaffolding
- Storybook configuration
- Build setup with Vite/Rollup
- Test configuration
- Complete documentation
- Progressive enhancement on request

## Integration Points

**Synergistic Skills:**
- `/scaffold` - General feature scaffolding
- `/types-generate` - Generate TypeScript types
- `/docs` - Documentation management
- `/test` - Run component tests
- `/format` - Format component code

Suggests `/scaffold` when:
- Need to add new components quickly
- Following existing patterns
- Creating feature-specific components

Suggests `/docs` when:
- Need to enhance documentation
- Create API documentation
- Build documentation site

## Framework Support

**React:**
- Component structure with TypeScript
- Storybook with React
- Jest/Vitest testing
- CSS Modules or Styled Components

**Vue:**
- Single File Components
- Storybook for Vue
- Vue Test Utils
- Scoped styles

**Web Components:**
- Custom Elements API
- Lit or Stencil
- Framework-agnostic approach
- Shadow DOM styling

**Svelte:**
- Svelte components
- Storybook for Svelte
- Svelte Testing Library
- Component-scoped styles

## Expected Outputs

**Files Created:**
- Complete directory structure
- Example components with stories
- Storybook configuration
- Build configuration (Vite/Rollup)
- Test setup and examples
- Documentation files
- Package.json with scripts
- TypeScript configurations
- README and guides

**Ready to Use:**
- `npm run storybook` - Start component development
- `npm test` - Run tests
- `npm run build` - Build library for distribution
- `npm publish` - Publish to npm (after setup)

## Safety Mechanisms

**Protection Measures:**
- Create git checkpoint before scaffolding
- Preview structure before creation
- Non-destructive for existing files
- Validate package names
- Check for conflicts

**Validation Steps:**
1. Verify framework compatibility
2. Check TypeScript configuration
3. Validate build outputs
4. Test Storybook startup
5. Verify tests run

## Common Scenarios

**Scenario 1: New Component Library**
- Create complete structure from scratch
- Set up all tooling
- Create example components
- Configure publishing

**Scenario 2: Add to Existing Project**
- Integrate Storybook into existing codebase
- Add missing configurations
- Create component templates
- Set up testing

**Scenario 3: Migrate to Component Library**
- Extract components from application
- Set up build for distribution
- Add Storybook stories
- Configure exports

## Important Notes

**I will NEVER:**
- Overwrite existing components without confirmation
- Add AI attribution to component files
- Break existing build configuration
- Remove existing Storybook setup
- Modify package.json without validation

**Best Practices:**
- Follow framework conventions
- Use semantic versioning
- Document all components
- Include accessibility features
- Provide usage examples

## Credits

**Inspired by:**
- [Shadcn/ui](https://ui.shadcn.com/) - Component library patterns
- [Radix UI](https://www.radix-ui.com/) - Accessible components
- [Chakra UI](https://chakra-ui.com/) - Design system approach
- [Material-UI](https://mui.com/) - Component library architecture
- [Storybook Best Practices](https://storybook.js.org/docs/react/writing-stories/introduction)

This skill helps you quickly scaffold a production-ready component library with all essential tooling configured.