Component Demo Skill

This skill guides the creation and maintenance of components and their demo pages in the Protobox component showcase.

When to Use This Skill

Use this skill when:

• Creating new custom components in src/components/
• Creating new custom hooks in src/hooks/
• Updating existing components or hooks
• Planning feature additions that involve reusable components

Component Development Workflow

Phase 1: Planning - Ask About Demo Pages

IMPORTANT: When planning to create a new component or hook, ALWAYS ask the user:

"Would you like me to create a demo page for this [component/hook] in the component showcase?"

Options to present:

1. Yes, create demo page - Create both the component and a showcase demo
2. Yes, standalone demo - Create component and a standalone demo page at /[name]-demo
3. No demo needed - Just create the component/hook

Phase 2: Component Creation

Create the component in the appropriate location:

• Custom components: src/components/[ComponentName].tsx
• Custom hooks: src/hooks/[hookName].tsx
• UI components: Use npx shadcn-ui@latest add [component] for shadcn components

Follow component best practices from src/components/README.md:

• Simple default usage with sensible defaults
• Accept style, className, and native element props
• Use composition for icons (via props, not hardcoded)
• Standard heights: 16px, 20px, 40px
• Support dark mode with Tailwind dark: variants

Phase 3: Demo Page Creation (if requested)

A. For Component Showcase (/components/[name])

1. Create Content Component in src/components/DemoShowcase/[Name]Content.tsx:

   • Extract core demo functionality without page wrappers
   • Remove: min-h-screen, full-page padding, headers, back links
   • Keep: interactive elements, controls, examples
   • Use Card components to organize examples
   • Include usage code examples

2. Register in Demo Registry (src/components/DemoShowcase/demoRegistry.tsx):

   // Add lazy import
   const [Name]Content = lazy(() => import('./[Name]Content'))
   
   // Add to DEMO_REGISTRY array
   {
     id: '[name]',
     label: '[Display Name]',
     section: 'Hooks' | 'Components',
     component: [Name]Content,
     description: 'Brief description',
     path: '/components/[name]',
   }
   

3. Add Route in src/App.tsx:

   // Add lazy import at top
   const [Name]Content = lazy(() => import('./components/DemoShowcase/[Name]Content'))
   
   // Add route inside <Route path="/components"> nested routes
   <Route
     path="[name]"
     element={
       <Suspense fallback={<div>Loading...</div>}>
         <[Name]Content />
       </Suspense>
     }
   />
   

B. For Standalone Demo Page (/[name]-demo)

1. Create Page Component in src/pages/[Name]Demo.tsx:

   • Include full-page wrapper with proper styling
   • Add header with title and description
   • Organize examples using Card components
   • Include code examples showing usage
   • Add back link to home

2. Add Route in src/App.tsx:

   import [Name]Demo from './pages/[Name]Demo'
   
   <Route path="/[name]-demo" Component={[Name]Demo} />
   

Phase 4: Component Updates - Check for Existing Demos

CRITICAL: When updating an existing component or hook, ALWAYS check if demo pages exist:

1. Search for Demo Pages:

   • Check src/components/DemoShowcase/ for [Name]Content.tsx
   • Check src/pages/ for [Name]Demo.tsx
   • Check demoRegistry.tsx for entries

2. If Demo Pages Exist:

   • Update them to reflect new functionality
   • Add examples demonstrating new features
   • Update code examples
   • Test that demos still work correctly

3. Prompt User:

   "I found existing demo pages for this [component/hook]. I'll update them to include the new [feature/changes]."

Demo Content Best Practices

Structure

Organize demo content with clear sections:

<div className="space-y-8">
  {/* Example 1: Basic Usage */}
  <Card className="p-6 space-y-3">
    <div className="flex items-center gap-2">
      <Badge variant="secondary">Basic</Badge>
      <span className="text-xs text-zinc-500 dark:text-zinc-400">
        Configuration details
      </span>
    </div>
    {/* Demo content */}
  </Card>

  {/* More examples... */}

  {/* Code Example */}
  <Card className="p-6 space-y-3 bg-zinc-50 dark:bg-zinc-900">
    <Badge variant="outline">Usage Example</Badge>
    <pre className="text-xs text-zinc-700 dark:text-zinc-300 overflow-x-auto">
      <code>{`// Code example here`}</code>
    </pre>
  </Card>
</div>

Example Categories

Include diverse examples:

1. Basic - Simple default usage
2. Advanced - Complex configurations
3. Interactive - User-controlled examples
4. Variants - Different visual styles or behaviors
5. Edge Cases - Boundary conditions
6. Code Examples - Implementation snippets

Styling

• Use Card components for grouping examples
• Add Badge components for labeling examples
• Include configuration details in muted text
• Support dark mode throughout
• Add visual indicators for interactive elements
• Show state changes clearly

Component Showcase Navigation

The navigation is automatically generated from demoRegistry.tsx:

• Hooks section: Custom React hooks
• Components section: UI components, libraries, demos

Demos are displayed in the order they appear in DEMO_REGISTRY.

Testing Checklist

After creating or updating component demos:

• Navigate to the demo route
• Verify all examples render correctly
• Test interactive elements (buttons, inputs, controls)
• Check dark mode appearance
• Verify code examples are accurate
• Test on different screen sizes
• Check TypeScript compilation
• Verify navigation active state

Examples

Example 1: Creating a New Hook with Demo

User: "Create a useDebounce hook"

Claude:
1. Asks: "Would you like me to create a demo page for this hook in the component showcase?"
2. User selects: "Yes, create demo page"
3. Creates:
   - src/hooks/useDebounce.tsx (the hook)
   - src/components/DemoShowcase/DebounceContent.tsx (demo)
   - Updates demoRegistry.tsx
   - Updates App.tsx with route

Example 2: Updating Existing Component

User: "Add a 'size' prop to the Button component"

Claude:
1. Searches for existing demos
2. Finds: N/A (Button is shadcn component, no custom demo)
3. Updates Button usage examples in existing demos if needed

Example 3: Updating Hook with Demo

User: "Add a 'delay' option to useTypewriter"

Claude:
1. Updates src/hooks/useTypewriter.tsx
2. Searches and finds: src/components/DemoShowcase/TypewriterContent.tsx
3. Announces: "I found the existing TypewriterContent demo. I'll add an example showing the new delay option."
4. Adds new Card with delay example
5. Updates code example to include delay option

File Locations Reference

• Component showcase layout: src/pages/ComponentShowcase.tsx
• Demo registry: src/components/DemoShowcase/demoRegistry.tsx
• Navigation: src/components/DemoShowcase/DemoNavigation.tsx
• Demo content: src/components/DemoShowcase/[Name]Content.tsx
• Standalone demos: src/pages/[Name]Demo.tsx
• Routes: src/App.tsx

Key Principles

1. Always ask - Don't assume whether demos are wanted
2. Always search - Check for existing demos before updating
3. Keep demos updated - When components change, demos should reflect it
4. Provide variety - Show multiple use cases, not just basic usage
5. Make it interactive - Let users experiment with controls
6. Include code - Show implementation examples
7. Support dark mode - Test in both themes
8. Organize clearly - Use consistent structure across demos