aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/tasks/ds-audit-codebase.md

@@ -0,0 +1,273 @@
+# Audit Codebase for UI Pattern Redundancy
+
+> Task ID: brad-audit-codebase
+> Agent: Brad (Design System Architect)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[ds-consolidate-patterns]` · workflow: `brownfield-audit`
+> **On Fail:** If scan finds 0 patterns → verify path and file extensions. If scan errors → check file permissions and memory limits (`--max-old-space-size=4096`). Do NOT proceed to consolidate with empty/corrupt inventory. Re-run audit after fixing root cause.
+
+## Description
+
+Scan codebase to detect UI pattern redundancies (buttons, colors, spacing, typography, forms) and quantify technical debt with hard metrics. Brad's specialty: showing you the horror show you've created. **v4.0: Also evaluates machine-readability for agentic DS workflows and motion token coverage.**
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/audit/pattern-inventory.json`
+- **format:** JSON data
+- **consumed_by:** ds-consolidate-patterns
+
+## Prerequisites
+
+- Codebase with UI code (React, Vue, HTML, or vanilla CSS)
+- Bash shell access
+- grep, find, awk utilities available
+- Reference: Read data/agentic-ds-principles.md for machine-readability checks
+- Reference: Read data/motion-tokens-guide.md for animation audit criteria
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to gather scan parameters.
+
+1. **Gather Scan Parameters**
+   - Ask for scan path (e.g., ./src, ./app, ./components)
+   - Detect frameworks automatically or ask for confirmation
+   - Confirm output directory (default: outputs/design-system/{project}/audit/)
+
+2. **Validate Scan Path**
+   - Run `test -d $path && test -r $path` and confirm both return exit code 0
+   - Count total files with `find $path -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.css" \) | wc -l`
+   - Estimate scan time (100k LOC ~2 min)
+
+3. **Confirm and Execute**
+   - Show scan plan summary
+   - Ask for confirmation before starting
+   - Begin pattern detection
+
+### Steps
+
+1. **Validate Environment**
+   - Run `test -d $path` to confirm scan path exists; abort if exit code != 0
+   - Run `test -r $path` to confirm read permissions; abort if exit code != 0
+   - Create output directory structure with `mkdir -p`
+   - Check: `test -d $path && test -r $path` — abort with "Path not found or not readable: $path"
+
+2. **Detect Frameworks**
+   - Count React/JSX files (*.jsx, *.tsx)
+   - Count Vue files (*.vue)
+   - Count HTML files (*.html)
+   - Count CSS files (*.css, *.scss, *.sass)
+   - Check: file count > 0 for at least one of (.jsx, .tsx, .vue, .html, .css) — abort with "No UI files found in $path"
+
+3. **Scan Button Patterns**
+   - Detect button elements (<button, <Button, className="btn")
+   - Count total button instances across all files
+   - Extract unique button class names and patterns
+   - Calculate redundancy factor (instances / unique patterns)
+   - Check: button_count is integer >= 0 — log "Found {N} button patterns across {M} files"
+
+4. **Scan Color Usage**
+   - Extract hex colors (#RGB, #RRGGBB)
+   - Extract rgb/rgba colors
+   - Count unique color values
+   - Count total color usage instances
+   - Identify top 10 most-used colors
+   - Calculate redundancy factor
+   - Check: unique_colors array length > 0 OR log "No colors found — verify CSS/SCSS files exist in scan path"
+
+5. **Scan Spacing Patterns**
+   - Extract padding values (padding: Npx)
+   - Extract margin values (margin: Npx)
+   - Count unique spacing values
+   - Identify most common patterns
+   - Check: spacing_values array populated — log "{N} unique spacing values found"
+
+6. **Scan Typography**
+   - Extract font-family declarations
+   - Extract font-size values
+   - Extract font-weight values
+   - Count unique typography patterns
+   - Check: font_families count >= 1 AND font_sizes count >= 1 — log "{N} font families, {M} font sizes cataloged"
+
+7. **Scan Form Patterns**
+   - Count input elements
+   - Extract unique input class patterns
+   - Count form elements
+   - Extract unique form patterns
+   - Check: input_instances and form_instances are integers >= 0 — log "{N} input elements, {M} form elements found"
+
+8. **Generate Inventory Report**
+   - Create pattern-inventory.json with all metrics
+   - Include scan metadata (timestamp, path, file counts)
+   - Calculate redundancy factors for each pattern type
+   - Check: `python -m json.tool pattern-inventory.json` returns exit code 0 — abort with "Invalid JSON in pattern-inventory.json"
+
+9. **Create State File**
+   - Generate .state.yaml for Merovingian handoff
+   - Record all pattern counts and metrics
+   - Log agent history
+   - Set phase to "audit_complete"
+   - Write inventory summary to .state.yaml:
+     ```yaml
+     last_command: audit
+     audit_complete: true
+     inventory_file: pattern-inventory.json
+     scan_path: {path}
+     timestamp: {ISO-8601}
+     summary:
+       total_files: {count}
+       patterns_found: {count}
+       redundancy_score: {score}
+     ```
+   - Check: `test -f .state.yaml` AND YAML parses without error — abort with "State file missing or invalid YAML"
+
+## Output
+
+- **pattern-inventory.json**: Structured data with all pattern counts, redundancy factors, and usage statistics
+- **.state.yaml**: Brad's state file for handoff to Merovingian or next command
+- **Console summary**: Key metrics displayed for immediate review
+
+### Output Format
+
+```json
+{
+  "scan_metadata": {
+    "timestamp": "2025-10-27T12:00:00Z",
+    "scan_path": "./src",
+    "total_files": 487,
+    "frameworks_detected": {
+      "react": true,
+      "vue": false,
+      "html": false
+    }
+  },
+  "patterns": {
+    "buttons": {
+      "unique_patterns": 47,
+      "total_instances": 327,
+      "redundancy_factor": 6.96
+    },
+    "colors": {
+      "unique_hex": 82,
+      "unique_rgb": 7,
+      "total_unique": 89,
+      "total_instances": 1247,
+      "redundancy_factor": 14.01
+    },
+    "spacing": {
+      "unique_padding": 19,
+      "unique_margin": 15
+    },
+    "typography": {
+      "unique_font_families": 4,
+      "unique_font_sizes": 15,
+      "unique_font_weights": 6
+    },
+    "forms": {
+      "input_instances": 189,
+      "unique_input_patterns": 23,
+      "form_instances": 45,
+      "unique_form_patterns": 12
+    }
+  }
+}
+```
+
+## Anti-Patterns
+
+- **"Grep and pray"** — Running generic grep without framework-specific patterns. A React codebase needs JSX-aware scanning (`className=`, `styled.`), not just CSS selectors. Always detect framework FIRST
+- **"Color counting without context"** — Counting `#fff` and `#FFF` as different colors. Normalize all colors to lowercase hex before counting. Also convert `rgb(255,255,255)` to hex for deduplication
+- **"Ignoring dynamic patterns"** — Only scanning static CSS while missing Tailwind classes (`bg-blue-500`), CSS-in-JS (`styled.div`), or theme variables. Scan ALL style sources, not just .css files
+- **"Partial scan, full conclusions"** — Scanning only `/components` but making claims about the entire codebase. Always state scan scope clearly and don't extrapolate beyond scanned files
+- **"Redundancy without severity"** — Reporting "47 unique colors" without indicating which are close duplicates (e.g., #333 vs #343434). Use HSL clustering to group near-duplicates and show actual waste
+
+## Failure Handling
+
+- **Scan timeout (>5 min for <100k LOC):** Reduce scan scope — split into subdirectories and audit individually
+- **Zero patterns detected:** Verify scan path contains UI code. Try alternate file extensions. If truly zero, document as "clean codebase"
+- **Permission errors >10%:** Run with elevated permissions or exclude restricted directories. Document excluded paths
+- **Invalid JSON output:** Re-run scan step that failed. If persistent, generate partial report with available data
+
+## Success Criteria
+
+- [ ] Scan completes in <2 minutes for 100k LOC
+- [ ] All pattern types detected (buttons, colors, spacing, typography, forms)
+- [ ] Redundancy factors calculated for measurable patterns
+- [ ] Valid JSON output generated with complete data
+- [ ] State file created for next command (consolidate/tokenize)
+- [ ] No scan errors or missing permissions
+
+## Error Handling
+
+- **Scan path does not exist**: Exit with clear error message, suggest valid paths
+- **No UI files found**: Warn user, check if path is correct or files exist
+- **Permission denied**: Explain which directory needs read access
+- **Partial scan failure**: Log which files failed, continue with remaining files, report incomplete data
+
+## Security Considerations
+
+- Read-only access to codebase (no writes during scan)
+- No code execution during pattern detection
+- Validate file paths to prevent directory traversal
+- Handle malformed files gracefully (invalid CSS/JSX)
+- Skip binary files and large non-text files
+
+## Examples
+
+### Example 1: React Codebase Scan
+
+```bash
+*audit ./src
+```
+
+Output:
+```
+🔍 Brad: Scanning ./src for UI chaos...
+
+📊 Files found:
+  - React/JSX: 234
+  - CSS/SCSS: 89
+  - TOTAL: 323
+
+🔍 Scanning BUTTONS...
+📊 BUTTONS:
+  - Total instances: 327
+  - Unique patterns: 47
+  - Redundancy factor: 7.0x
+
+🎨 Scanning COLORS...
+📊 COLORS:
+  - Unique hex values: 82
+  - Total usage instances: 1247
+  - Redundancy factor: 15.2x
+
+✅ Inventory saved: outputs/design-system/my-app/audit/pattern-inventory.json
+✅ State saved: outputs/design-system/my-app/.state.yaml
+```
+
+### Example 2: Vue Codebase Scan
+
+```bash
+*audit ./components
+```
+
+Output shows Vue-specific patterns (v-btn, el-button, etc.)
+
+## Notes
+
+- Redundancy factor >3x indicates significant technical debt
+- Colors >50 unique values = major consolidation opportunity
+- Buttons >20 variations = serious pattern explosion
+- Run this audit periodically to prevent pattern regression
+- Brad recommends: If redundancy factors are high, run *consolidate next
+- For cost analysis of this waste, run *calculate-roi after audit
+- v4.0: Also scan for animation/transition values as motion token candidates
+- v4.0: Check machine-readability score (Storybook, structured tokens, docs) per agentic-ds-principles.md
+- v4.0: Use *motion-audit for deep animation analysis, *agentic-audit for full agentic readiness
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+

package/pro/squads/design/tasks/ds-build-component.md

@@ -0,0 +1,349 @@
+# Build Production-Ready Component
+
+> Task ID: atlas-build-component
+> Agent: Brad (Design System Architect)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[ds-compose-molecule, ds-extend-pattern]` · workflow: `greenfield`
+
+## Description
+
+Generate production-ready React TypeScript component from design tokens. Includes component file, styles (CSS Modules), tests, optional Storybook stories, and documentation. All styling uses tokens (zero hardcoded values). **v4.0: Supports Fluent 2 patterns as component blueprint option. Generates Storybook stories with Chromatic-ready visual test states.**
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/components/{Component}/`
+- **format:** TypeScript source (TSX, CSS Module, tests, stories, docs)
+- **consumed_by:** ds-compose-molecule, ds-extend-pattern
+
+## Prerequisites
+
+- Setup completed (*setup command run successfully)
+- Tokens loaded and accessible
+- React and TypeScript configured
+- Reference: Read data/fluent2-design-principles.md for Fluent 2 component patterns
+- Reference: Read data/ds-reference-architectures.md for cross-system component patterns
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to configure component.
+
+1. **Select Component Type**
+   - Atomic level (atom, molecule, organism)
+   - Component name (Button, Input, Card, etc)
+   - Confirm token availability for this component
+
+2. **Configure Component Features**
+   - Variants needed (primary, secondary, destructive)
+   - Sizes needed (sm, md, lg)
+   - States needed (hover, disabled, loading, error)
+   - Additional props
+
+3. **Review Generation Plan**
+   - Show files to be generated
+   - Confirm test coverage requirements
+   - Ask for Storybook stories (if enabled)
+
+### Steps
+
+1. **Validate Prerequisites**
+   - Run `test -f tokens.yaml` (or tokens.json) to confirm tokens file exists; abort with "Tokens not found — run *setup first" if missing
+   - Search for existing `{Component}.tsx` in the design-system directory; if found, prompt user to confirm overwrite
+   - Validate component name matches PascalCase regex `/^[A-Z][a-zA-Z]+$/`
+   - Check: tokens file exists AND component name is PascalCase (`/^[A-Z][a-zA-Z]+$/`) — abort if either fails
+
+2. **Load Token References**
+   - Identify which tokens this component needs
+   - Validate token availability
+   - Generate token import statements
+   - Check: grep each required token name in tokens file — list missing tokens if any
+
+3. **Generate Component File**
+   - Create TypeScript React component
+   - Add prop type definitions (strict typing)
+   - Implement variants, sizes, states
+   - Add accessibility attributes (ARIA)
+   - Use semantic HTML elements
+   - Check: `tsc --noEmit {component}.tsx` returns exit code 0 — fix type errors before proceeding
+
+4. **Generate Component Styles**
+   - Create CSS Module file ({Component}.module.css)
+   - Use CSS custom properties from tokens
+   - Implement all variants and states
+   - Add responsive styles if needed
+   - Zero hardcoded values (all from tokens)
+   - Check: zero hardcoded color/spacing values in CSS module — grep for `#[0-9a-f]` and `[0-9]+px` (excluding 0px)
+
+5. **Generate Unit Tests**
+   - Create test file ({Component}.test.tsx)
+   - Test all variants render correctly
+   - Test all sizes work
+   - Test disabled state
+   - Test onClick/events
+   - Aim for >80% coverage
+   - Check: `npm test -- --coverage {Component}.test.tsx` exits 0 AND coverage >= 80% — fix failing tests before proceeding
+
+6. **Generate Storybook Stories (Optional)**
+   - If Storybook enabled, create {Component}.stories.tsx
+   - Story for each variant
+   - Story for each size
+   - Interactive controls for props
+   - Check: stories file exports at least one named story AND `tsc --noEmit {Component}.stories.tsx` exits 0
+
+7. **Run Accessibility Checks**
+   - Confirm all interactive elements have `aria-label` or visible text by searching component source for button/a/input tags without labels
+   - Measure color contrast ratio for all foreground/background token pairs and confirm each >= 4.5:1 (use WCAG contrast formula)
+   - Tab through all interactive elements in render order and confirm focus moves logically without traps
+   - Add `:focus-visible` outline styles using `var(--color-focus)` token
+   - Check: all interactive elements have ARIA labels AND color contrast ratio >= 4.5:1 AND focus-visible styles present
+
+8. **Generate Component Documentation**
+   - Create {Component}.md in docs/
+   - Document props and types
+   - Show usage examples
+   - List variants and sizes
+   - Include accessibility notes
+   - Check: {Component}.md exists AND contains sections: Props, Usage Examples, Variants, Accessibility
+
+9. **Update Component Index**
+   - Add to design-system/index.ts
+   - Export component for easy import
+   - Update barrel exports
+   - Check: `grep -q "{Component}" index.ts` — abort with "{Component} not found in index.ts exports"
+
+10. **Update State File**
+    - Add component to patterns_built in .state.yaml
+    - Record atomic level, variants, test coverage
+    - Increment component count
+    - Check: .state.yaml contains component name in patterns_built array AND component_count incremented
+
+## Output
+
+- **{Component}.tsx**: React TypeScript component
+- **{Component}.module.css**: Styles using tokens
+- **{Component}.test.tsx**: Unit tests
+- **{Component}.stories.tsx**: Storybook stories (optional)
+- **{Component}.md**: Component documentation
+- **Updated index.ts**: Component exported
+- **.state.yaml**: Updated with component metadata
+
+### Output Format
+
+```typescript
+// Button.tsx
+import React from 'react';
+import styles from './Button.module.css';
+
+export interface ButtonProps {
+  /** Visual style variant */
+  variant?: 'primary' | 'secondary' | 'destructive';
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg';
+  /** Button content */
+  children: React.ReactNode;
+  /** Click handler */
+  onClick?: () => void;
+  /** Disabled state */
+  disabled?: boolean;
+  /** HTML type attribute */
+  type?: 'button' | 'submit' | 'reset';
+}
+
+export const Button: React.FC<ButtonProps> = ({
+  variant = 'primary',
+  size = 'md',
+  children,
+  onClick,
+  disabled = false,
+  type = 'button',
+}) => {
+  const className = `${styles.btn} ${styles[`btn-${variant}`]} ${styles[`btn-${size}`]}`;
+
+  return (
+    <button
+      type={type}
+      className={className}
+      onClick={onClick}
+      disabled={disabled}
+      aria-disabled={disabled}
+    >
+      {children}
+    </button>
+  );
+};
+```
+
+```css
+/* Button.module.css */
+.btn {
+  font-family: var(--font-base);
+  font-size: var(--font-size-base);
+  font-weight: var(--font-weight-semibold);
+  border-radius: var(--radius-base);
+  padding: var(--space-md) var(--space-lg);
+  border: none;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.btn-primary {
+  background: var(--color-primary);
+  color: white;
+}
+
+.btn-primary:hover:not(:disabled) {
+  background: var(--color-primary-dark);
+}
+
+.btn-secondary {
+  background: var(--color-secondary);
+  color: white;
+}
+
+.btn-destructive {
+  background: var(--color-error);
+  color: white;
+}
+
+.btn-sm {
+  font-size: var(--font-size-sm);
+  padding: var(--space-sm) var(--space-md);
+}
+
+.btn-lg {
+  font-size: var(--font-size-lg);
+  padding: var(--space-lg) var(--space-xl);
+}
+```
+
+## Failure Handling
+
+- **Missing required tokens:** If grep fails to find token name in tokens file, abort with "Required token {name} not found. Available tokens: {list}. Run *setup or add missing tokens before building component."
+- **TypeScript compilation errors:** If `tsc --noEmit {component}.tsx` returns non-zero exit code, abort with "TypeScript errors in {Component}.tsx: {errors}. Fix type errors before proceeding."
+- **Hardcoded design values detected:** If CSS module contains hardcoded colors (#hex) or spacing values (e.g., 16px except 0px), abort with "{N} hardcoded values detected. Replace with tokens: {list}."
+- **Test coverage below threshold:** If `npm test --coverage` shows coverage <80%, abort with "Test coverage {actual}% below required 80%. Add tests for: {uncovered paths}."
+
+## Success Criteria
+
+- [ ] Component compiles without TypeScript errors
+- [ ] All styling uses tokens (zero hardcoded values)
+- [ ] Props fully typed with TSDoc comments
+- [ ] All variants and sizes implemented
+- [ ] Disabled state handled correctly
+- [ ] WCAG AA accessibility standards met
+- [ ] Unit tests pass with >80% coverage
+- [ ] Component documented with examples
+- [ ] Storybook stories work (if enabled)
+
+## Anti-Patterns
+
+- **"Div soup"** — Using `<div>` for everything instead of semantic HTML. A clickable element MUST be `<button>`, a navigation link MUST be `<a>`. Never add `role="button"` to a `<div>` when `<button>` exists
+- **"Hardcoded magic numbers"** — Writing `padding: 16px` instead of `padding: var(--spacing-4)`. Zero hardcoded values means ZERO — including border-radius, font-size, line-height, and box-shadow values
+- **"any-driven development"** — Using TypeScript `any` to make the compiler happy. Every prop must have a specific type. Use discriminated unions for variants: `type ButtonVariant = 'primary' | 'secondary' | 'destructive'`
+- **"Testing the framework, not the component"** — Writing tests like "renders without crashing" that test React, not your component. Test: variants render correct classes, disabled prevents onClick, keyboard events fire handlers
+- **"Accessibility as afterthought"** — Adding ARIA after the component is "done". Build accessible from step 1: semantic HTML first, then ARIA only where HTML semantics are insufficient
+
+## Error Handling
+
+- **Token not found**: Report which token is missing, suggest alternatives
+- **Component exists**: Ask to overwrite or use different name
+- **TypeScript errors**: Display errors, suggest fixes
+- **Test failures**: Show failing tests, don't complete until fixed
+- **Accessibility violations**: Warn and suggest improvements
+
+## Security Considerations
+
+- Sanitize component name (prevent injection)
+- Validate token references
+- Escape user content in examples
+- No eval() or dynamic code execution
+
+## Examples
+
+### Example 1: Build Button Component
+
+```bash
+*build button
+```
+
+Output:
+```
+🏗️ Merovingian: Building Button component...
+
+📋 Configuration:
+  - Type: Atom
+  - Variants: primary, secondary, destructive
+  - Sizes: sm, md, lg
+  - Tests: Yes (>80% coverage)
+  - Storybook: Yes
+
+✓ Generated Button.tsx (142 lines)
+✓ Generated Button.module.css (89 lines, 0 hardcoded values)
+✓ Generated Button.test.tsx (18 tests)
+✓ Generated Button.stories.tsx (6 stories)
+✓ Generated Button.md (documentation)
+
+🧪 Running tests...
+  ✓ renders with default props
+  ✓ renders all variants correctly
+  ✓ renders all sizes correctly
+  ✓ handles disabled state
+  ✓ calls onClick handler
+  ... 13 more tests
+  Coverage: 94.2%
+
+♿ Accessibility check:
+  ✓ ARIA attributes present
+  ✓ Color contrast: 4.8:1 (WCAG AA ✓)
+  ✓ Keyboard navigable
+  ✓ Focus indicators visible
+
+✅ Button component ready!
+
+Import: import { Button } from '@/design-system';
+Usage: <Button variant="primary">Click me</Button>
+
+Merovingian says: "Built right. Built once."
+```
+
+### Example 2: Build Input Component
+
+```bash
+*build input
+```
+
+Output includes additional features:
+- Validation states (error, success)
+- Helper text prop
+- Label integration
+- Icon slots
+
+## Notes
+
+- All components strictly typed with TypeScript
+- Zero hardcoded values enforced (tokens only)
+- Accessibility is non-negotiable (WCAG AA minimum)
+- Test coverage >80% required
+- CSS Modules scope styles automatically
+- Variants and sizes are extensible
+- Components are tree-shakeable
+- Storybook stories enable visual testing
+- Documentation auto-generated from types
+- Components follow Atomic Design principles
+- Merovingian ensures quality at every step
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/ds-build-mcp-server.md

@@ -0,0 +1,84 @@
+# Build MCP Server for Design System
+
+> Task ID: brad-ds-build-mcp-server
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+
+## Description
+
+Design and implement a Model Context Protocol (MCP) server that exposes design system assets to AI agents.
+
+Core data exposed:
+- component metadata
+- registry entries
+- token catalogs
+- usage guidelines
+
+## Prerequisites
+
+- AI metadata generated (`ds-generate-ai-metadata`)
+- Registry and workspace structure validated
+- Stable token files and schemas
+
+## Workflow
+
+1. **Define MCP Capabilities**
+- Tools to query:
+  - list components
+  - inspect component contract
+  - search by intent/context
+  - resolve required tokens
+
+2. **Implement Server Skeleton**
+- Create:
+  - `workspace/domains/design-system/mcp/server.ts`
+  - `workspace/domains/design-system/mcp/handlers/*`
+- Keep handlers deterministic and stateless.
+
+3. **Connect Data Sources**
+- `metadata/components.json`
+- `workspace/ui/registry.json`
+- token files under `domains/design-system/tokens`
+
+4. **Add Query Guards**
+- Schema validation on load.
+- Safe fallback for missing component entries.
+- No execution of arbitrary user code.
+
+5. **Validate with Real Queries**
+- Query by component name, intent, and accessibility requirement.
+- Verify returned contracts are complete and traceable.
+
+6. **Document Contract**
+- Input/output schema for each MCP tool.
+- Versioning and compatibility policy.
+
+## Deliverables
+
+- MCP server scaffold with handlers
+- Queryable design system knowledge surface
+- Contract documentation for AI consumers
+
+## Success Criteria
+
+- [ ] MCP server lists and resolves all registered components
+- [ ] Responses include props, variants, a11y, and token links
+- [ ] Schema validation blocks invalid metadata
+- [ ] Agent can generate UI using only exposed system contracts
+
+## Notes
+
+- Treat MCP as infrastructure, not integration glue.
+- Keep response payloads concise and fully structured.
+- Favor machine contracts over natural language in API surfaces.
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+
+## Process Guards
+- **Execution Type:** `Hybrid`
+- **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `design-system`
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.