skillstore-cli 1.0.0

package/data/shared/framework/skills/ui-generation/references/compound-components.md

@@ -0,0 +1,252 @@
+# Compound Components & Design System Patterns
+
+## Compound Component Pattern (React)
+
+Compound components share implicit state through Context, giving consumers full control over rendering order and structure.
+
+### Core Pattern
+
+```tsx
+import { createContext, useContext, useState, ReactNode } from 'react';
+
+// 1. Shared context
+interface TabsContextValue {
+  activeTab: string;
+  setActiveTab: (id: string) => void;
+}
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+function useTabsContext() {
+  const ctx = useContext(TabsContext);
+  if (!ctx) throw new Error('Tabs compound components must be used within <Tabs>');
+  return ctx;
+}
+
+// 2. Root component owns the state
+interface TabsProps {
+  defaultTab: string;
+  children: ReactNode;
+}
+function Tabs({ defaultTab, children }: TabsProps) {
+  const [activeTab, setActiveTab] = useState(defaultTab);
+  return (
+    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
+      <div role="tablist">{children}</div>
+    </TabsContext.Provider>
+  );
+}
+
+// 3. Child components consume context
+function Tab({ id, children }: { id: string; children: ReactNode }) {
+  const { activeTab, setActiveTab } = useTabsContext();
+  return (
+    <button
+      role="tab"
+      aria-selected={activeTab === id}
+      onClick={() => setActiveTab(id)}
+    >
+      {children}
+    </button>
+  );
+}
+
+function Panel({ id, children }: { id: string; children: ReactNode }) {
+  const { activeTab } = useTabsContext();
+  if (activeTab !== id) return null;
+  return <div role="tabpanel">{children}</div>;
+}
+
+// 4. Attach sub-components for dot notation
+Tabs.Tab = Tab;
+Tabs.Panel = Panel;
+
+// Usage
+<Tabs defaultTab="settings">
+  <Tabs.Tab id="profile">Profile</Tabs.Tab>
+  <Tabs.Tab id="settings">Settings</Tabs.Tab>
+  <Tabs.Panel id="profile">Profile content</Tabs.Panel>
+  <Tabs.Panel id="settings">Settings content</Tabs.Panel>
+</Tabs>
+```
+
+### When to Use Compound Components
+- Components with multiple related pieces (Tabs, Accordion, Select, Menu)
+- Consumer needs flexibility in ordering and wrapping sub-components
+- Shared state should be implicit, not passed via props drilling
+
+---
+
+## Headless UI Libraries
+
+Headless libraries provide behavior and accessibility with zero styling, giving full visual control.
+
+### Comparison
+
+| Library | Framework | Styling Approach | Component Count | Key Strength |
+|---|---|---|---|---|
+| Radix UI | React | Fully unstyled | 30+ primitives | Best accessibility, fine-grained parts |
+| Headless UI | React, Vue | Fully unstyled | ~10 components | Tailwind Labs, tight Tailwind integration |
+| Ark UI | React, Vue, Solid | Fully unstyled | 40+ components | State machine driven (Zag.js), multi-framework |
+
+### Radix UI Usage Pattern
+
+```tsx
+import * as Select from '@radix-ui/react-select';
+
+<Select.Root>
+  <Select.Trigger className="px-4 py-2 border rounded">
+    <Select.Value placeholder="Choose..." />
+    <Select.Icon />
+  </Select.Trigger>
+  <Select.Portal>
+    <Select.Content className="bg-white shadow-lg rounded-md p-1">
+      <Select.Viewport>
+        <Select.Item value="react" className="px-3 py-2 cursor-pointer hover:bg-gray-100 rounded">
+          <Select.ItemText>React</Select.ItemText>
+        </Select.Item>
+        <Select.Item value="vue" className="px-3 py-2 cursor-pointer hover:bg-gray-100 rounded">
+          <Select.ItemText>Vue</Select.ItemText>
+        </Select.Item>
+      </Select.Viewport>
+    </Select.Content>
+  </Select.Portal>
+</Select.Root>
+```
+
+---
+
+## Slot-Based vs Children-Based Composition
+
+### Vue Slots
+
+```vue
+<!-- BaseCard.vue -->
+<template>
+  <div class="card">
+    <header v-if="$slots.header"><slot name="header" /></header>
+    <div class="card-body"><slot /></div>
+    <footer v-if="$slots.footer"><slot name="footer" :count="itemCount" /></footer>
+  </div>
+</template>
+
+<!-- Usage: scoped slot receives data from child -->
+<BaseCard>
+  <template #header>Order Summary</template>
+  <p>Main content here</p>
+  <template #footer="{ count }">{{ count }} items</template>
+</BaseCard>
+```
+
+### React Children Equivalent
+
+```tsx
+// React achieves the same via props or render props
+<Card
+  header={<h3>Order Summary</h3>}
+  footer={(count) => <span>{count} items</span>}
+>
+  <p>Main content here</p>
+</Card>
+```
+
+**Key difference**: Vue slots are a first-class template feature with named/scoped variants. React uses composition through props (ReactNode) or render props (functions). Both achieve the same flexibility — choose based on your framework.
+
+---
+
+## Design System Governance
+
+### Component API Stability
+
+- **Stable**: shipped, documented, covered by semver — breaking changes require a major version
+- **Beta**: functional but API may change — prefix with `Beta` or flag in docs
+- **Deprecated**: still works but scheduled for removal — log console warnings, link to migration guide
+
+### Versioning Policy
+
+1. **Patch** (1.0.x): bug fixes, style tweaks that don't change API
+2. **Minor** (1.x.0): new components, new optional props on existing components
+3. **Major** (x.0.0): removed props, renamed components, changed default behavior
+
+### Deprecation Process
+
+```tsx
+/** @deprecated Use `variant` prop instead. Will be removed in v4.0. */
+interface ButtonProps {
+  /** @deprecated */ type?: 'primary' | 'secondary';
+  variant?: 'primary' | 'secondary';
+}
+
+function Button({ type, variant, ...props }: ButtonProps) {
+  if (type && !variant) {
+    console.warn('[DesignSystem] Button `type` prop is deprecated. Use `variant` instead.');
+    variant = type;
+  }
+  // ...
+}
+```
+
+---
+
+## Token-Driven Theming
+
+### Design Token Format (W3C Draft)
+
+```json
+{
+  "color": {
+    "primary": { "$value": "#2563eb", "$type": "color" },
+    "primary-hover": { "$value": "#1d4ed8", "$type": "color" }
+  },
+  "spacing": {
+    "sm": { "$value": "8px", "$type": "dimension" },
+    "md": { "$value": "16px", "$type": "dimension" },
+    "lg": { "$value": "24px", "$type": "dimension" }
+  }
+}
+```
+
+### CSS Custom Properties Pipeline
+
+```
+tokens.json → Style Dictionary → css/variables.css + tailwind.config.ts
+```
+
+```css
+/* Generated: css/variables.css */
+:root {
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+  --spacing-lg: 24px;
+}
+
+/* Dark theme override */
+[data-theme="dark"] {
+  --color-primary: #60a5fa;
+  --color-primary-hover: #93bbfd;
+}
+```
+
+### Tailwind Integration
+
+```typescript
+// tailwind.config.ts
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: 'var(--color-primary)',
+        'primary-hover': 'var(--color-primary-hover)',
+      },
+      spacing: {
+        sm: 'var(--spacing-sm)',
+        md: 'var(--spacing-md)',
+        lg: 'var(--spacing-lg)',
+      },
+    },
+  },
+};
+```
+
+This pipeline lets you change a token value in one place and have it propagate to CSS, Tailwind utilities, and any platform (iOS, Android) that consumes the same tokens.json source.

package/data/shared/framework/skills/ui-generation/references/generation-patterns.md

@@ -0,0 +1,110 @@
+# Generation Patterns
+
+## Description Parsing
+
+### Keyword-to-Component Mapping
+
+| Keywords | Component Type | Base Structure |
+|----------|---------------|----------------|
+| form, input, submit, field | Form | `<form>` with labeled inputs |
+| table, list, grid, data | Data Display | `<table>` or grid layout |
+| card, tile, item | Card | Flex/grid container with card items |
+| nav, menu, sidebar, header | Navigation | `<nav>` with links/buttons |
+| modal, dialog, popup | Overlay | Dialog with backdrop |
+| dashboard, overview, stats | Dashboard | Grid of metric cards + charts |
+| tabs, accordion, panel | Content Switcher | Tab/accordion pattern |
+
+### Modifier Detection
+
+| Modifier | Effect |
+|----------|--------|
+| "sortable" | Add sort handlers and indicators |
+| "searchable" / "filterable" | Add search/filter input above content |
+| "paginated" | Add pagination controls |
+| "editable" / "inline edit" | Add edit mode toggle |
+| "draggable" | Add drag handles and reorder logic |
+| "collapsible" | Add expand/collapse toggle |
+
+## Framework Templates
+
+### React (JSX + Tailwind)
+
+```tsx
+interface ComponentProps {
+  // Define based on parsed requirements
+}
+
+export function Component({ ...props }: ComponentProps) {
+  return (
+    <div className="...">
+      {/* Semantic structure */}
+    </div>
+  );
+}
+```
+
+### Vue (SFC)
+
+```vue
+<script setup lang="ts">
+interface Props {
+  // Define based on parsed requirements
+}
+const props = defineProps<Props>();
+</script>
+
+<template>
+  <div class="...">
+    <!-- Semantic structure -->
+  </div>
+</template>
+```
+
+### HTML/CSS
+
+```html
+<div class="component">
+  <!-- Semantic structure -->
+</div>
+
+<style>
+.component {
+  /* Layout and styling */
+}
+</style>
+```
+
+## Design Token Integration
+
+### Spacing Scale
+Use project tokens if available, otherwise default to 4px base:
+- `xs`: 4px | `sm`: 8px | `md`: 16px | `lg`: 24px | `xl`: 32px | `2xl`: 48px
+
+### Typography Scale
+- `text-xs`: 12px | `text-sm`: 14px | `text-base`: 16px
+- `text-lg`: 18px | `text-xl`: 20px | `text-2xl`: 24px
+
+### Color Strategy
+- Use semantic color names: `primary`, `secondary`, `success`, `warning`, `error`
+- Always define both light and dark mode variants
+- Ensure contrast ratios meet WCAG AA
+
+## State & Props Design
+
+### Props Principles
+- Required props: data the component cannot function without
+- Optional props with defaults: customization points
+- Render props / slots: composition for complex content areas
+- Event handlers: callbacks for user interactions
+
+### State Patterns
+- **Controlled**: Parent owns state, component receives via props — use for forms, filters
+- **Uncontrolled**: Component owns internal state — use for UI-only state (open/closed, hover)
+- **Server state**: Fetched data managed by query library — use for data display components
+
+### Multi-State Rendering
+Every data-driven component must handle:
+1. **Loading** — skeleton or spinner
+2. **Empty** — helpful message with action suggestion
+3. **Error** — error message with retry action
+4. **Populated** — the actual content

package/data/shared/framework/skills/ui-generation/references/storybook-design-system.md

@@ -0,0 +1,278 @@
+# Storybook & Design System Documentation
+
+## Storybook 8 Setup
+
+### CSF3 Format (Component Story Format 3)
+
+CSF3 uses objects instead of functions for cleaner, more declarative stories.
+
+```typescript
+// Button.stories.ts
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta = {
+  title: 'Components/Button',
+  component: Button,
+  tags: ['autodocs'],  // enables automatic docs page
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost'],
+    },
+    size: { control: 'radio', options: ['sm', 'md', 'lg'] },
+    disabled: { control: 'boolean' },
+  },
+  args: {
+    children: 'Click me',
+    variant: 'primary',
+    size: 'md',
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Each export is a story — just an object with args
+export const Primary: Story = {
+  args: { variant: 'primary' },
+};
+
+export const Secondary: Story = {
+  args: { variant: 'secondary' },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+```
+
+### Automatic Docs (autodocs)
+
+Adding `tags: ['autodocs']` in the meta generates a docs page with:
+- Component description (from JSDoc on the component)
+- Props table (auto-extracted from TypeScript types)
+- Live examples from all exported stories
+- Controls panel for interactive prop editing
+
+Configure globally in `.storybook/preview.ts`:
+
+```typescript
+const preview: Preview = {
+  tags: ['autodocs'],  // enable for all stories
+};
+export default preview;
+```
+
+---
+
+## Visual Testing with Chromatic
+
+### Integration Setup
+
+```bash
+npm install --save-dev chromatic
+npx chromatic --project-token=<token>
+```
+
+### CI Pipeline (GitHub Actions)
+
+```yaml
+# .github/workflows/chromatic.yml
+name: Chromatic
+on: push
+jobs:
+  chromatic:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # required for baseline comparison
+      - run: npm ci
+      - uses: chromaui/action@latest
+        with:
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          autoAcceptChanges: main  # auto-accept on main branch
+```
+
+### How It Works
+1. Chromatic captures a screenshot of every story on every push
+2. Compares against the accepted baseline screenshot
+3. Highlights pixel differences in a review UI
+4. Reviewers accept or reject visual changes before merge
+
+---
+
+## Design System Documentation Pages
+
+Use Storybook MDX to create non-component documentation pages.
+
+### Color Palette Page
+
+```mdx
+{/* docs/Colors.mdx */}
+import { Meta, ColorPalette, ColorItem } from '@storybook/blocks';
+
+<Meta title="Foundations/Colors" />
+
+# Color Palette
+
+<ColorPalette>
+  <ColorItem title="Primary" colors={{ Default: '#2563eb', Hover: '#1d4ed8', Light: '#dbeafe' }} />
+  <ColorItem title="Neutral" colors={{ 900: '#111827', 500: '#6b7280', 100: '#f3f4f6' }} />
+  <ColorItem title="Semantic" colors={{ Success: '#16a34a', Warning: '#f59e0b', Error: '#dc2626' }} />
+</ColorPalette>
+```
+
+### Typography and Spacing
+
+```mdx
+{/* docs/Typography.mdx */}
+import { Meta, Typeset } from '@storybook/blocks';
+
+<Meta title="Foundations/Typography" />
+
+# Typography
+
+<Typeset
+  fontSizes={['14px', '16px', '20px', '24px', '32px']}
+  fontFamily="Inter, system-ui, sans-serif"
+  fontWeight={400}
+  sampleText="The quick brown fox jumps over the lazy dog"
+/>
+```
+
+---
+
+## Component Variants Matrix
+
+Display all combinations of a component's visual states in one story.
+
+```typescript
+// Button.stories.ts
+export const VariantsMatrix: Story = {
+  render: () => (
+    <table style={{ borderCollapse: 'collapse' }}>
+      <thead>
+        <tr>
+          <th />
+          {['sm', 'md', 'lg'].map(size => <th key={size}>{size}</th>)}
+        </tr>
+      </thead>
+      <tbody>
+        {['primary', 'secondary', 'ghost'].map(variant => (
+          <tr key={variant}>
+            <td style={{ padding: '8px', fontWeight: 600 }}>{variant}</td>
+            {['sm', 'md', 'lg'].map(size => (
+              <td key={size} style={{ padding: '8px' }}>
+                <Button variant={variant} size={size}>Label</Button>
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  ),
+};
+```
+
+This pattern makes it easy to visually audit every combination of size, color, and state in a single view. Add rows for disabled and loading states as needed.
+
+---
+
+## Interaction Testing with Play Functions
+
+Play functions simulate user behavior directly in Storybook stories.
+
+```typescript
+import { expect, fn, userEvent, within } from '@storybook/test';
+
+export const FormSubmission: Story = {
+  args: {
+    onSubmit: fn(),  // mock function
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+
+    // Simulate user filling out a form
+    await userEvent.type(canvas.getByLabelText('Email'), 'user@example.com');
+    await userEvent.type(canvas.getByLabelText('Password'), 'secret123');
+    await userEvent.click(canvas.getByRole('button', { name: 'Sign in' }));
+
+    // Assert the callback was called with correct data
+    await expect(args.onSubmit).toHaveBeenCalledWith({
+      email: 'user@example.com',
+      password: 'secret123',
+    });
+  },
+};
+
+export const ValidationError: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Submit without filling required fields
+    await userEvent.click(canvas.getByRole('button', { name: 'Sign in' }));
+
+    // Assert error messages appear
+    await expect(canvas.getByText('Email is required')).toBeInTheDocument();
+  },
+};
+```
+
+### Running Interaction Tests
+- In Storybook UI: open the "Interactions" panel to see step-by-step playback
+- In CI: `npx test-storybook` runs all play functions headlessly via Playwright
+
+---
+
+## Accessibility Addon
+
+### Setup
+
+```bash
+npm install --save-dev @storybook/addon-a11y
+```
+
+```typescript
+// .storybook/main.ts
+const config: StorybookConfig = {
+  addons: [
+    '@storybook/addon-a11y',
+    // ... other addons
+  ],
+};
+```
+
+### Per-Story Configuration
+
+```typescript
+export const HighContrast: Story = {
+  args: { variant: 'primary' },
+  parameters: {
+    a11y: {
+      config: {
+        rules: [
+          { id: 'color-contrast', enabled: true },
+          { id: 'heading-order', enabled: true },
+        ],
+      },
+    },
+  },
+};
+
+// Disable a11y checks for a decorative-only story
+export const IconShowcase: Story = {
+  parameters: {
+    a11y: { disable: true },
+  },
+};
+```
+
+### What It Checks
+- Color contrast ratios (WCAG AA and AAA)
+- Missing alt text, label associations, ARIA roles
+- Keyboard navigation issues, focus management
+- Landmark regions, heading hierarchy
+
+Results appear in the "Accessibility" panel as violations, passes, and incomplete checks powered by axe-core.