@fr0mpy/component-system 2.1.1 → 3.1.0

package/templates/component-recipes/switch.md

@@ -14,14 +14,14 @@ peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center {tokens.radius}
 border-2 border-transparent shadow-sm transition-colors
 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2
 disabled:cursor-not-allowed disabled:opacity-50
-data-[state=checked]:bg-primary data-[state=unchecked]:bg-muted
+data-checked:bg-primary data-unchecked:bg-muted
 ```
 
 ### Thumb
 ```
 pointer-events-none block h-4 w-4 rounded-full bg-background shadow-lg ring-0
 transition-transform
-data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0
+data-checked:translate-x-4 data-unchecked:translate-x-0
 ```
 
 ### Sizes
@@ -51,7 +51,7 @@ interface SwitchProps {
 ```
 
 ## Do
-- Use Radix Switch for accessibility
+- Use Base UI Switch for accessibility
 - Include focus ring
 - Animate thumb movement smoothly
 - Use semantic colors (primary for checked)
@@ -64,7 +64,7 @@ interface SwitchProps {
 
 ## Example
 ```tsx
-import * as SwitchPrimitive from '@radix-ui/react-switch'
+import { Switch as SwitchPrimitive } from '@base-ui/react/switch'
 import { cn } from '@/lib/utils'
 
 const Switch = ({ className, ...props }) => (
@@ -74,7 +74,7 @@ const Switch = ({ className, ...props }) => (
       'border-2 border-transparent shadow-sm transition-colors',
       'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
       'disabled:cursor-not-allowed disabled:opacity-50',
-      'data-[state=checked]:bg-primary data-[state=unchecked]:bg-muted',
+      'data-checked:bg-primary data-unchecked:bg-muted',
       className
     )}
     {...props}
@@ -82,7 +82,7 @@ const Switch = ({ className, ...props }) => (
     <SwitchPrimitive.Thumb
       className={cn(
         'pointer-events-none block h-4 w-4 rounded-full bg-background shadow-lg ring-0',
-        'transition-transform data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0'
+        'transition-transform data-checked:translate-x-4 data-unchecked:translate-x-0'
       )}
     />
   </SwitchPrimitive.Root>

package/templates/component-recipes/table.md

@@ -32,7 +32,7 @@ w-full caption-bottom text-sm
 ```
 border-b border-border transition-colors
 hover:bg-muted/50
-data-[state=selected]:bg-muted
+data-selected:bg-muted
 ```
 
 ### Head Cell (th)

package/templates/component-recipes/tabs.md

@@ -20,7 +20,7 @@ text-sm font-medium ring-offset-background
 transition-all
 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2
 disabled:pointer-events-none disabled:opacity-50
-data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:{tokens.shadow}
+data-selected:bg-background data-selected:text-foreground data-selected:{tokens.shadow}
 ```
 
 ### Tab Content
@@ -36,7 +36,7 @@ border-b border-border
 
 Tab Trigger:
 border-b-2 border-transparent pb-3 pt-2
-data-[state=active]:border-primary data-[state=active]:text-foreground
+data-selected:border-primary data-selected:text-foreground
 ```
 
 ### Alternative: Pills Style
@@ -46,7 +46,7 @@ flex gap-2
 
 Tab Trigger:
 rounded-full px-4 py-2
-data-[state=active]:bg-primary data-[state=active]:text-primary-foreground
+data-selected:bg-primary data-selected:text-primary-foreground
 ```
 
 ## Props Interface
@@ -78,7 +78,7 @@ interface TabsContentProps {
 ```
 
 ## Do
-- Use Radix Tabs for accessibility
+- Use Base UI Tabs for accessibility
 - Support keyboard navigation (arrow keys)
 - Include focus ring for triggers
 - Use subtle background for active state
@@ -91,7 +91,7 @@ interface TabsContentProps {
 
 ## Example
 ```tsx
-import * as TabsPrimitive from '@radix-ui/react-tabs'
+import { Tabs as TabsPrimitive } from '@base-ui/react/tabs'
 import { cn } from '@/lib/utils'
 
 const Tabs = TabsPrimitive.Root
@@ -113,7 +113,7 @@ const TabsTrigger = ({ className, ...props }) => (
       'text-sm font-medium ring-offset-background transition-all',
       'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
       'disabled:pointer-events-none disabled:opacity-50',
-      'data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+      'data-selected:bg-background data-selected:text-foreground data-selected:shadow-sm',
       className
     )}
     {...props}

package/templates/component-recipes/toast.md

@@ -6,6 +6,17 @@
 - Auto-dismiss with progress indicator (optional)
 - Support variants: default, success, error, warning
 
+## IMPORTANT: Color Token Usage
+
+**NEVER use hardcoded Tailwind colors.** Use semantic tokens only:
+
+| Semantic Token | Purpose |
+|----------------|---------|
+| `bg-success`, `text-success-foreground` | Success notifications |
+| `bg-warning`, `text-warning-foreground` | Warning notifications |
+| `bg-destructive`, `text-destructive-foreground` | Error notifications |
+| `bg-background`, `text-foreground` | Default notifications |
+
 ## Tailwind Classes
 
 ### Viewport (container for all toasts)
@@ -17,26 +28,28 @@ sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-[420px]
 ### Toast
 ```
 group pointer-events-auto relative flex w-full items-center justify-between space-x-2
-overflow-hidden {tokens.radius} border border-border p-4 pr-6 {tokens.shadow}
+overflow-hidden rounded-[USE_CONFIG_RADIUS] border border-border p-4 pr-6 shadow-elevation-sm
 transition-all
 data-[swipe=cancel]:translate-x-0
-data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)]
-data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)]
+data-[swipe=end]:translate-x-[var(--toast-swipe-end-x)]
+data-[swipe=move]:translate-x-[var(--toast-swipe-move-x)]
 data-[swipe=move]:transition-none
-data-[state=open]:animate-in data-[state=closed]:animate-out
+data-open:animate-in data-closed:animate-out
 data-[swipe=end]:animate-out
-data-[state=closed]:fade-out-80
-data-[state=closed]:slide-out-to-right-full
-data-[state=open]:slide-in-from-top-full
-data-[state=open]:sm:slide-in-from-bottom-full
+data-closed:fade-out-80
+data-closed:slide-out-to-right-full
+data-open:slide-in-from-top-full
+data-open:sm:slide-in-from-bottom-full
 ```
 
-### Variants
+**Note:** Replace `rounded-[USE_CONFIG_RADIUS]` with value from `.claude/styling-config.json` → `tokens.radius`
+
+### Variants (Using Semantic Tokens ONLY)
 ```
-default:     bg-background text-foreground
-success:     bg-green-500 text-white border-green-600
+default:     bg-background text-foreground border-border
+success:     bg-success text-success-foreground border-success
 error:       bg-destructive text-destructive-foreground border-destructive
-warning:     bg-yellow-500 text-white border-yellow-600
+warning:     bg-warning text-warning-foreground border-warning
 ```
 
 ### Title
@@ -51,24 +64,19 @@ text-sm opacity-90
 
 ### Action Button
 ```
-inline-flex h-8 shrink-0 items-center justify-center {tokens.radius}
-border border-border bg-transparent px-3 text-sm font-medium
+inline-flex h-8 shrink-0 items-center justify-center rounded-[USE_CONFIG_RADIUS]
+border border-border bg-transparent px-3 text-sm font-medium cursor-pointer
 transition-colors hover:bg-secondary
-focus:outline-none focus:ring-1 focus:ring-ring
+focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-primary
 disabled:pointer-events-none disabled:opacity-50
-group-[.destructive]:border-muted/40 group-[.destructive]:hover:border-destructive/30
-group-[.destructive]:hover:bg-destructive group-[.destructive]:hover:text-destructive-foreground
-group-[.destructive]:focus:ring-destructive
 ```
 
 ### Close Button
 ```
-absolute right-1 top-1 rounded-md p-1 text-foreground/50
+absolute right-1 top-1 rounded-md p-1 text-foreground/50 cursor-pointer
 opacity-0 transition-opacity hover:text-foreground
-focus:opacity-100 focus:outline-none focus:ring-1
+focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-1
 group-hover:opacity-100
-group-[.destructive]:text-red-300 group-[.destructive]:hover:text-red-50
-group-[.destructive]:focus:ring-red-400 group-[.destructive]:focus:ring-offset-red-600
 ```
 
 ## Props Interface
@@ -98,21 +106,25 @@ function useToast(): {
 ```
 
 ## Do
+- Use semantic color tokens ONLY (bg-success, bg-warning, bg-destructive)
+- Read `.claude/styling-config.json` for radius value
+- Include `cursor-pointer` on action and close buttons
+- Use `focus-visible:` not `focus:` for keyboard accessibility
 - Use a toast provider at app root
 - Support swipe-to-dismiss on mobile
-- Include close button
-- Use appropriate variant for context
 - Limit visible toasts (3-5 max)
 
 ## Don't
-- Hardcode colors
+- Use hardcoded colors (bg-green-500, bg-yellow-500, #XXXXXX)
+- Use non-semantic Tailwind colors
+- Use `focus:` instead of `focus-visible:`
+- Forget `cursor-pointer` on interactive elements
 - Skip auto-dismiss (except for errors)
-- Use for critical information (use Alert)
-- Stack too many toasts
+- Use for critical information (use Alert instead)
 
 ## Example
 ```tsx
-import * as ToastPrimitives from '@radix-ui/react-toast'
+import { Toast as ToastPrimitives } from '@base-ui/react/toast'
 import { X } from 'lucide-react'
 import { cn } from '@/lib/utils'
 
@@ -129,27 +141,29 @@ const ToastViewport = ({ className, ...props }) => (
   />
 )
 
+// Using semantic tokens - NO hardcoded colors!
 const toastVariants = {
   default: 'bg-background text-foreground border-border',
-  success: 'bg-green-500 text-white border-green-600',
+  success: 'bg-success text-success-foreground border-success',
   error: 'bg-destructive text-destructive-foreground border-destructive',
-  warning: 'bg-yellow-500 text-white border-yellow-600',
+  warning: 'bg-warning text-warning-foreground border-warning',
 }
 
 const Toast = ({ className, variant = 'default', ...props }) => (
   <ToastPrimitives.Root
     className={cn(
       'group pointer-events-auto relative flex w-full items-center justify-between space-x-2',
-      'overflow-hidden rounded-lg border p-4 pr-6 shadow-lg transition-all',
+      // Replace rounded-lg with your config's tokens.radius
+      'overflow-hidden rounded-lg border p-4 pr-6 shadow-elevation-sm transition-all',
       'data-[swipe=cancel]:translate-x-0',
-      'data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)]',
-      'data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)]',
+      'data-[swipe=end]:translate-x-[var(--toast-swipe-end-x)]',
+      'data-[swipe=move]:translate-x-[var(--toast-swipe-move-x)]',
       'data-[swipe=move]:transition-none',
-      'data-[state=open]:animate-in data-[state=closed]:animate-out',
-      'data-[swipe=end]:animate-out data-[state=closed]:fade-out-80',
-      'data-[state=closed]:slide-out-to-right-full',
-      'data-[state=open]:slide-in-from-top-full',
-      'data-[state=open]:sm:slide-in-from-bottom-full',
+      'data-open:animate-in data-closed:animate-out',
+      'data-[swipe=end]:animate-out data-closed:fade-out-80',
+      'data-closed:slide-out-to-right-full',
+      'data-open:slide-in-from-top-full',
+      'data-open:sm:slide-in-from-bottom-full',
       toastVariants[variant],
       className
     )}
@@ -160,9 +174,9 @@ const Toast = ({ className, variant = 'default', ...props }) => (
 const ToastAction = ({ className, ...props }) => (
   <ToastPrimitives.Action
     className={cn(
-      'inline-flex h-8 shrink-0 items-center justify-center rounded-md',
+      'inline-flex h-8 shrink-0 items-center justify-center rounded-md cursor-pointer',
       'border bg-transparent px-3 text-sm font-medium',
-      'hover:bg-secondary focus:outline-none focus:ring-1',
+      'hover:bg-secondary focus-visible:outline-none focus-visible:ring-1',
       className
     )}
     {...props}
@@ -172,9 +186,9 @@ const ToastAction = ({ className, ...props }) => (
 const ToastClose = ({ className, ...props }) => (
   <ToastPrimitives.Close
     className={cn(
-      'absolute right-1 top-1 rounded-md p-1 text-foreground/50',
+      'absolute right-1 top-1 rounded-md p-1 text-foreground/50 cursor-pointer',
       'opacity-0 transition-opacity hover:text-foreground',
-      'focus:opacity-100 focus:outline-none group-hover:opacity-100',
+      'focus-visible:opacity-100 focus-visible:outline-none group-hover:opacity-100',
       className
     )}
     {...props}

package/templates/component-recipes/toggle-group.md

@@ -90,7 +90,7 @@ interface ToggleGroupMultipleProps {
 ```
 
 ## Do
-- Use Radix ToggleGroup primitive
+- Use Base UI ToggleGroup primitive
 - Clearly indicate selected state
 - Support keyboard navigation
 - Include proper ARIA attributes
@@ -104,7 +104,7 @@ interface ToggleGroupMultipleProps {
 
 ## Example
 ```tsx
-import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group'
+import { ToggleGroup as ToggleGroupPrimitive } from '@base-ui/react/toggle-group'
 import { cn } from '@/lib/utils'
 
 const ToggleGroup = ({ className, variant = 'default', size = 'md', ...props }) => (
@@ -134,12 +134,12 @@ const ToggleGroupItem = ({ className, variant = 'default', size = 'md', ...props
       'disabled:pointer-events-none disabled:opacity-50',
       variant === 'default' && [
         'text-muted-foreground hover:bg-background/50 hover:text-foreground',
-        'data-[state=on]:bg-background data-[state=on]:text-foreground data-[state=on]:shadow-sm',
+        'data-pressed:bg-background data-pressed:text-foreground data-pressed:shadow-sm',
       ],
       variant === 'outline' && [
         'border-r border-border last:border-r-0',
         'text-muted-foreground hover:bg-muted hover:text-foreground',
-        'data-[state=on]:bg-muted data-[state=on]:text-foreground',
+        'data-pressed:bg-muted data-pressed:text-foreground',
       ],
       toggleGroupItemSizes[size],
       className

package/templates/component-recipes/tooltip.md

@@ -12,7 +12,7 @@
 ```
 z-50 overflow-hidden {tokens.radius} bg-foreground px-3 py-1.5 text-xs text-background
 animate-in fade-in-0 zoom-in-95
-data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95
+data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95
 data-[side=bottom]:slide-in-from-top-2
 data-[side=left]:slide-in-from-right-2
 data-[side=right]:slide-in-from-left-2
@@ -47,7 +47,7 @@ interface TooltipProps {
 - Skip delay on hover when moving between tooltips
 
 ## Do
-- Use Radix Tooltip for accessibility
+- Use Base UI Tooltip for accessibility
 - Include enter/exit animations
 - Support arrow pointing to trigger
 - Use inverted colors (dark bg, light text) for contrast
@@ -60,7 +60,7 @@ interface TooltipProps {
 
 ## Example
 ```tsx
-import * as TooltipPrimitive from '@radix-ui/react-tooltip'
+import { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip'
 import { cn } from '@/lib/utils'
 
 const TooltipProvider = TooltipPrimitive.Provider
@@ -75,7 +75,7 @@ const TooltipContent = ({ className, sideOffset = 4, ...props }) => (
     className={cn(
       'z-50 overflow-hidden rounded-md bg-foreground px-3 py-1.5 text-xs text-background',
       'animate-in fade-in-0 zoom-in-95',
-      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+      'data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95',
       'data-[side=bottom]:slide-in-from-top-2',
       'data-[side=left]:slide-in-from-right-2',
       'data-[side=right]:slide-in-from-left-2',
@@ -97,7 +97,7 @@ const TooltipArrow = ({ className, ...props }) => (
 const SimpleTooltip = ({ content, side = 'top', delayDuration = 200, children }) => (
   <TooltipProvider>
     <Tooltip delayDuration={delayDuration}>
-      <TooltipTrigger asChild>{children}</TooltipTrigger>
+      <TooltipTrigger render={children}>{children}</TooltipTrigger>
       <TooltipContent side={side}>
         {content}
         <TooltipArrow />

package/templates/mcp/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}

package/templates/playwright/playwright.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: [
+    ['list'],
+    ['html', { outputFolder: 'test-results/reports', open: 'never' }],
+  ],
+  outputDir: 'test-results/screenshots',
+  use: {
+    baseURL: 'http://localhost:5173',
+    screenshot: 'only-on-failure',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    port: 5173,
+    reuseExistingServer: true,
+    timeout: 30000,
+  },
+});

package/templates/playwright/tests/components.spec.ts

@@ -0,0 +1,104 @@
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Discover components from Gallery.tsx
+const galleryPath = path.resolve(__dirname, '..', 'Gallery.tsx');
+const galleryContent = fs.readFileSync(galleryPath, 'utf-8');
+const componentNames = [...galleryContent.matchAll(/name:\s*"([^"]+)"/g)].map(
+  (m) => m[1]
+);
+
+test.describe('Component Harness', () => {
+  test('gallery loads', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('nav')).toBeVisible();
+    await expect(page.locator('main')).toBeVisible();
+  });
+
+  for (const name of componentNames) {
+    test.describe(name, () => {
+      test.beforeEach(async ({ page }) => {
+        await page.goto('/');
+        // Click the sidebar button matching the component name
+        const sidebarButton = page.locator('nav button', {
+          hasText: new RegExp(`^${name}$`, 'i'),
+        });
+        await sidebarButton.click();
+        // Wait for preview area to update
+        await page.waitForTimeout(300);
+      });
+
+      test('renders without console errors', async ({ page }) => {
+        const errors: string[] = [];
+        page.on('console', (msg) => {
+          if (msg.type() === 'error') errors.push(msg.text());
+        });
+
+        // Re-navigate to capture console from fresh load
+        await page.goto('/');
+        const sidebarButton = page.locator('nav button', {
+          hasText: new RegExp(`^${name}$`, 'i'),
+        });
+        await sidebarButton.click();
+        await page.waitForTimeout(500);
+
+        // Verify preview area has content
+        const previewArea = page.locator('main');
+        await expect(previewArea).not.toBeEmpty();
+
+        // Check no console errors
+        expect(errors).toHaveLength(0);
+      });
+
+      test('screenshot', async ({ page }) => {
+        const previewArea = page.locator('main');
+        await previewArea.screenshot({
+          path: `test-results/screenshots/${name}.png`,
+        });
+      });
+
+      test('accessibility', async ({ page }) => {
+        const results = await new AxeBuilder({ page })
+          .include('main')
+          .disableRules([
+            'color-contrast', // Often fails in component previews due to isolated context
+          ])
+          .analyze();
+
+        const violations = results.violations.map((v) => ({
+          id: v.id,
+          impact: v.impact,
+          description: v.description,
+          nodes: v.nodes.length,
+        }));
+
+        // Fail on serious or critical violations
+        const critical = violations.filter(
+          (v) => v.impact === 'critical' || v.impact === 'serious'
+        );
+        expect(
+          critical,
+          `${name} has ${critical.length} serious a11y violation(s): ${JSON.stringify(critical, null, 2)}`
+        ).toHaveLength(0);
+      });
+
+      test('responsive - mobile', async ({ page }) => {
+        await page.setViewportSize({ width: 375, height: 667 });
+        await page.goto('/');
+        const sidebarButton = page.locator('nav button', {
+          hasText: new RegExp(`^${name}$`, 'i'),
+        });
+        await sidebarButton.click();
+        await page.waitForTimeout(300);
+
+        // Check for horizontal overflow
+        const hasOverflow = await page.evaluate(() => {
+          return document.documentElement.scrollWidth > document.documentElement.clientWidth;
+        });
+        expect(hasOverflow, `${name} overflows at mobile width (375px)`).toBe(false);
+      });
+    });
+  }
+});

package/templates/skills/react-patterns.md

@@ -0,0 +1,141 @@
+---
+description: USE WHEN creating, modifying, or reviewing React components, hooks, state management, or effect patterns. Enforces Rules of Hooks and correct state/effect usage.
+---
+
+# React Patterns
+
+Apply when creating, modifying, or reviewing React components.
+
+## Rules of Hooks (CRITICAL)
+
+Hooks must be called in the **same order** every render. Violating this crashes the app.
+
+### Never Do
+
+```tsx
+// ❌ Hook in callback/render prop
+const demos = [{
+  render: () => {
+    const [state, setState] = useState()  // CRASHES
+    return <Component />
+  }
+}]
+
+// ❌ Hook after conditional return
+if (loading) return <Spinner />
+const [data, setData] = useState()  // CRASHES
+
+// ❌ Hook in condition
+if (userId) {
+  const [user, setUser] = useState()  // CRASHES
+}
+
+// ❌ Hook in loop
+items.map(item => {
+  const [selected, setSelected] = useState()  // CRASHES
+})
+```
+
+### Always Do
+
+```tsx
+// ✅ Extract to separate component
+const CheckboxDemo = () => {
+  const [checked, setChecked] = useState(false)
+  return <Checkbox checked={checked} onChange={setChecked} />
+}
+
+// ✅ Hooks before any returns
+const [data, setData] = useState()
+const [loading, setLoading] = useState(true)
+if (loading) return <Spinner />
+
+// ✅ Condition inside hook, not hook inside condition
+useEffect(() => {
+  if (userId) fetchUser(userId)
+}, [userId])
+```
+
+## State Updates
+
+```tsx
+// ❌ Stale state - only increments once
+setCount(count + 1)
+setCount(count + 1)
+
+// ✅ Functional update - increments twice
+setCount(prev => prev + 1)
+setCount(prev => prev + 1)
+```
+
+## Dependencies
+
+```tsx
+// ❌ Missing dependency - stale closure
+useEffect(() => {
+  doSomething(value)
+}, [])
+
+// ✅ All dependencies listed
+useEffect(() => {
+  doSomething(value)
+}, [value])
+```
+
+## Component Galleries
+
+When building component showcases:
+
+| Pattern | Wrong | Right |
+|---------|-------|-------|
+| Stateful demo | Hook in render prop | Separate `*Demo` component |
+| Context consumer | Render alone | Wrap in provider |
+| Controlled input | Internal state | Props from wrapper |
+
+```tsx
+// ❌ Wrong - hook in render function
+const components = [{
+  name: "Checkbox",
+  render: () => {
+    const [checked, setChecked] = useState(false)
+    return <Checkbox checked={checked} />
+  }
+}]
+
+// ✅ Right - separate component
+const CheckboxDemo = () => {
+  const [checked, setChecked] = useState(false)
+  return <Checkbox checked={checked} onChange={setChecked} />
+}
+
+const components = [{
+  name: "Checkbox",
+  render: () => <CheckboxDemo />
+}]
+```
+
+## Cleanup
+
+```tsx
+// ❌ Memory leak
+useEffect(() => {
+  const id = setInterval(tick, 1000)
+}, [])
+
+// ✅ Cleanup on unmount
+useEffect(() => {
+  const id = setInterval(tick, 1000)
+  return () => clearInterval(id)
+}, [])
+```
+
+## Checklist
+
+Before delivering React code:
+
+- [ ] No hooks in callbacks, loops, conditions, or render props
+- [ ] No hooks after conditional returns
+- [ ] All `useEffect`/`useCallback`/`useMemo` deps included
+- [ ] Functional state updates when depending on previous state
+- [ ] Context consumers wrapped in their providers
+- [ ] Effects return cleanup functions where needed