aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/tasks/ds-figma-pipeline.md

@@ -0,0 +1,95 @@
+# Configure Figma MCP + Design-to-Code Pipeline
+
+> Task ID: brad-figma-pipeline
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `figma`
+
+## Description
+
+Configure the Figma MCP Server to connect design files with AI coding tools. Establishes component mapping (Figma components → code components), token sync (Figma Variables → W3C DTCG), and design-to-code workflow.
+
+## Prerequisites
+
+- Figma file with component library
+- Figma API access (personal access token)
+- AI coding tool (Claude Code, Cursor, Windsurf)
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - Figma file URL or key
+   - Code component library location
+   - Target AI tool for integration
+   - Token sync direction (Figma → code, code → Figma, bidirectional)
+
+### Steps
+
+1. **Setup Figma MCP Server**
+   - Install Figma MCP Server package
+   - Configure Figma API token
+   - Connect to target Figma file
+   - Verify MCP server responds with file data
+   - Check: MCP server query returns component list with count > 0 — abort with "MCP server not responding or returned empty component list"
+
+2. **Create Component Mapping**
+   - Map Figma component names → code component imports
+   - Map Figma variants → code component props
+   - Map Figma auto-layout → CSS flex/grid patterns
+   - Document unmapped components (gaps between design and code)
+   - Check: (mapped components / total Figma components) * 100 >= 80 — log "Mapping coverage: {pct}% ({mapped}/{total}), unmapped: {list}"
+
+3. **Configure Token Sync**
+   - Export Figma Variables as W3C DTCG tokens
+   - Compare with existing code tokens (identify drift)
+   - Define sync direction and conflict resolution rules
+   - Setup automated sync (CI/CD or manual trigger)
+   - Check: token drift count == 0 (Figma values match code values) — if drift > 0, log "Token drift detected: {N} mismatches" and list them
+
+4. **Define Design-to-Code Workflow**
+   - Developer selects Figma frame/component
+   - AI tool queries MCP for design context
+   - AI generates code using mapped components and tokens
+   - Developer reviews and refines
+   - Document the workflow for team adoption
+   - Check: sample Figma frame generates code using mapped components AND correct tokens — abort with "Pipeline failed: AI output uses {N} unmapped components"
+
+5. **Validate Round-Trip Fidelity**
+   - Generate code from sample Figma designs
+   - Compare output with expected component usage
+   - Measure fidelity (correct components, correct tokens, correct layout)
+   - Document common mismatches and fixes
+   - Update .state.yaml
+
+## Output
+
+- Figma MCP Server configured and connected
+- `figma-component-mapping.json` — Figma → code component map
+- `figma-token-sync-config.yaml` — Token sync configuration
+- `figma-pipeline-guide.md` — Team workflow documentation
+- `.state.yaml` updated
+
+## Failure Handling
+
+- **MCP Server connection timeout:** If Figma MCP Server does not respond within 10s or returns empty data, verify Figma API token validity and network connectivity, then exit with "MCP connection failed — check token at mcp-servers/figma/config and retry"
+- **Component mapping below 50%:** If less than half of Figma components have code equivalents, generate unmapped component report and suggest creating placeholder components or adjusting component naming conventions before proceeding
+- **Critical token drift detected:** If >20% of color or spacing tokens differ between Figma and code by >10%, halt sync and prompt user to choose canonical source (Figma or code), then document chosen direction in figma-token-sync-config.yaml
+- **AI-generated code uses wrong components:** If sample Figma frame generates code with 3+ unmapped components or incorrect token references, flag as fidelity failure, include comparison screenshot in validation report, and suggest improving component mapping or AI prompt context
+
+## Success Criteria
+
+- MCP Server returns accurate Figma component data
+- >80% of Figma components mapped to code equivalents
+- Token values synchronized (zero drift)
+- AI-generated code uses correct DS components
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-component-quality-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

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

@@ -0,0 +1,105 @@
+# Evaluate Fluent 2 Design Alignment
+
+> Task ID: brad-fluent-audit
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[ds-fluent-build]` · workflow: `fluent`
+
+## Description
+
+Calculate a Fluent 2 alignment score (0-100) by comparing your design system's component patterns, token naming, and accessibility approach against Fluent 2 specifications. Checks compound component patterns, token naming conventions, accessibility approach, and cross-platform readiness. Outputs alignment score with gap analysis.
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/fluent/fluent-alignment-report.json`
+- **format:** JSON data
+- **consumed_by:** ds-fluent-build
+
+## Prerequisites
+
+- Existing design system with components
+- Read data/fluent2-design-principles.md for reference
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - DS root path
+   - Target Fluent aspects (all, or specific: components, tokens, a11y)
+   - Current framework (React, Vue, other)
+
+### Steps
+
+1. **Compare Component Patterns Against Fluent 2 Compound Model**
+   - Check for compound component pattern usage
+   - Check for slot-based customization
+   - Check for controlled/uncontrolled pattern support
+   - Check for forwardRef usage
+   - Score: compound + slots = 20pts, monolithic props = 5pts
+   - Check: every component has architecture score (0-20) based on compound/slot/ref patterns — log "{N} components scored, avg: {avg}/20"
+
+2. **Match Token Names Against Fluent Convention Regex**
+   - Compare token names against Fluent convention (color + category + variant + state)
+   - Check for 3-layer architecture (global → alias → component)
+   - Validate semantic token coverage
+   - Score: Fluent naming = 20pts, partial match = 10pts, custom = 5pts
+   - Check: token naming comparison generated with Fluent match percentage — log "Token naming: {pct}% Fluent-aligned ({matched}/{total})"
+
+3. **Check Built-in ARIA Attributes and Focus Management**
+   - Check for built-in ARIA attributes (not consumer-applied)
+   - Check for focus management (FocusZone, Tabster, or equivalent)
+   - Check for keyboard navigation implementation
+   - Check for high-contrast mode support via tokens
+   - Score: Built-in a11y = 20pts, partial = 10pts, consumer-applied = 5pts
+   - Check: each component categorized as built-in / partial / consumer-applied a11y — log "A11y: {builtin} built-in, {partial} partial, {consumer} consumer-applied"
+
+4. **Classify Platform Dependencies as Cross-Platform or Web-Only**
+   - Check for platform-agnostic token values
+   - Check for platform-specific implementations (not web-only wrappers)
+   - Check for responsive design patterns
+   - Score: Cross-platform ready = 20pts, web-only = 10pts
+   - Check: platform assessment completed with cross-platform / web-only classification — log "Platform readiness: {classification} ({score}/20)"
+
+5. **Score Clarity, System, and Productive Principles (0-20 each)**
+   - Clarity: Is ambiguity minimized? Information hierarchy clear?
+   - System: Do components work coherently together?
+   - Productive: Are components optimized for task completion?
+   - Score: Strong adherence = 20pts, partial = 10pts
+   - Check: clarity + system + productive principles each scored (0-20) — log "Principles: clarity={c}, system={s}, productive={p}, total={t}/20"
+
+6. **Generate Alignment Report**
+   - Total Fluent alignment score (0-100)
+   - Gap analysis by category
+   - Migration recommendations (what to change to align with Fluent 2)
+   - Effort estimates per gap
+   - Update .state.yaml
+
+## Output
+
+- `fluent-alignment-report.md` — Score + gap analysis
+- Category-by-category breakdown
+- Prioritized migration recommendations
+- `.state.yaml` updated
+
+## Failure Handling
+
+- **Fluent 2 reference file not found:** Fetch fluent2-design-principles.md from data/ directory. If missing, abort with "Reference file data/fluent2-design-principles.md required for audit"
+- **No components found at DS root path:** Exit with error "No component files in {path}. Cannot perform Fluent alignment audit."
+- **Token naming extraction returns empty:** Check alternate token file formats (.json, .yaml, .ts). Report "Token naming: 0% aligned — no tokens found"
+- **Component architecture scoring fails for a component:** Log warning, skip that component, continue with remaining. Note skipped components in report
+
+## Success Criteria
+
+- Accurate scoring based on actual component analysis
+- Gaps have specific, actionable recommendations
+- Report distinguishes must-have vs. nice-to-have alignments
+
+
+## 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-fluent-build.md

@@ -0,0 +1,110 @@
+# Generate Component Following Fluent 2 Patterns
+
+> Task ID: brad-fluent-build
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[ds-fluent-audit]` · enables: `[]` · workflow: `fluent`
+
+## Description
+
+Generate a production-ready component following Microsoft Fluent 2 design patterns: compound component architecture, slot-based customization, built-in accessibility, and token-based styling.
+
+## Input Schema
+- **requires:** Output from `ds-fluent-audit`
+- **format:** JSON data
+- **location:** `outputs/design-system/{project}/fluent/fluent-alignment-report.json`
+
+## Prerequisites
+
+- Design tokens available (preferably W3C DTCG format)
+- React + TypeScript environment
+- Read data/fluent2-design-principles.md for principles
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Gather Parameters**
+   - Component name and purpose
+   - Variants needed (size, appearance, shape)
+   - Slots/sub-components required
+   - Target output directory
+
+### Steps
+
+1. **Design Component API**
+   - Define root component and sub-components (compound pattern)
+   - Define slot props for customizable sub-parts
+   - Define variants as union types (not open strings)
+   - Define controlled/uncontrolled props
+   - Check: all props have TypeScript types AND variant props use union types (not open strings) — abort with "API design incomplete: {N} untyped or open-string props"
+
+2. **Implement Component Structure**
+   - Root component: orchestrates state, provides context
+   - Sub-components: render individual parts, accept slot overrides
+   - Use forwardRef on all components
+   - Implement controlled + uncontrolled patterns via hooks
+   - Check: root component provides context AND sub-components consume it AND forwardRef used — abort with "Compound pattern incomplete: {missing aspect}"
+
+3. **Apply Token-Based Styling**
+   - All colors from semantic tokens (no hardcoded values)
+   - All spacing from spacing tokens
+   - All typography from typography tokens
+   - Support mode switching (light/dark/high-contrast)
+   - Check: hardcoded color/spacing/typography value count == 0 in component files — abort with "{N} hardcoded design values found"
+
+4. **Implement Accessibility**
+   - Add appropriate ARIA roles and attributes
+   - Implement keyboard navigation (Tab, Arrow keys, Enter, Escape)
+   - Handle focus management (focus trap for modals, focus restore)
+   - Add aria-label, aria-describedby where needed
+   - Check: component has ARIA roles + keyboard navigation + focus management — abort with "A11y incomplete: missing {list}"
+
+5. **Generate Tests**
+   - Unit tests for component rendering and state
+   - Interaction tests for keyboard navigation
+   - Accessibility tests (role, label assertions)
+   - Check: test coverage >= 80% AND all tests pass with exit code 0 — abort with "Tests: {pass}/{total} passing, coverage {pct}%"
+
+6. **Generate Storybook Story**
+   - Default story with all variants
+   - Interactive controls for all props
+   - Compound usage examples
+   - Accessibility annotations
+   - Check: story file exports default + variant stories AND argTypes defined for all props — abort with "Story incomplete: {missing aspect}"
+
+## Output
+
+- `{Component}/` directory with:
+  - `types.ts` — TypeScript interfaces
+  - `{Component}.tsx` — Root component
+  - `{SubComponent}.tsx` — Sub-components
+  - `use{Component}.ts` — State hook
+  - `{Component}.test.tsx` — Tests
+  - `{Component}.stories.tsx` — Storybook story
+  - `index.ts` — Barrel export
+
+## Failure Handling
+
+- **Compound pattern incomplete:** If root component does not provide context OR sub-components do not consume context OR forwardRef missing on components, abort with "Compound pattern incomplete: {missing aspect}. Ensure root provides context, sub-components consume it, and all use forwardRef."
+- **Hardcoded design values detected:** If component files contain hardcoded colors (#hex), spacing (px values), or typography values instead of tokens, abort with "{N} hardcoded design values found: {list}. All styling must use semantic design tokens."
+- **Accessibility implementation incomplete:** If component missing ARIA roles, keyboard navigation handlers, or focus management, abort with "A11y incomplete: missing {list}. Add ARIA attributes, keyboard event handlers, and focus trap/restore logic."
+- **Variant props use open strings:** If component prop types use `string` instead of union types for variants (e.g., `appearance: string` not `appearance: 'primary' | 'secondary'`), abort with "API design incomplete: {N} props use open strings instead of union types. Define explicit variant enums."
+
+## Success Criteria
+
+- Compound component pattern correctly implemented
+- All styling via tokens, zero hardcoded values
+- Keyboard navigation works completely
+- Tests pass with >80% coverage
+- Storybook story renders all variants
+
+
+## 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-generate-ai-metadata.md

@@ -0,0 +1,81 @@
+# Generate AI-Readable Component Metadata
+
+> Task ID: brad-ds-generate-ai-metadata
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+
+## Description
+
+Create machine-readable metadata for design system components so AI agents can discover, reason about, and assemble UI with real components (not hallucinated variants).
+
+## Prerequisites
+
+- Components organized in workspace/system and workspace/ui
+- Token hierarchy available (primitives/semantic/component)
+- Registry strategy defined (`registry.json`)
+- Governance protocol available: `squads/design/protocols/ai-first-governance.md`
+
+## Workflow
+
+1. **Collect Component Inventory**
+- Enumerate each component with canonical path and export name.
+- Resolve variants, slots, and composition relations.
+
+2. **Attach Design Semantics**
+- For each component, define:
+  - intent (e.g. `form-submit`, `navigation`, `feedback`)
+  - allowed contexts (marketing, dashboard, onboarding)
+  - interaction model (controlled/uncontrolled)
+
+3. **Attach Technical Contracts**
+- Props schema with type, required, default.
+- Variant schema (`cva` variants, compound variants).
+- Accessibility contract (`role`, keyboard behavior, aria requirements).
+
+4. **Link Tokens and Dependencies**
+- Map semantic tokens used by each variant.
+- Capture dependencies (primitives, icons, hooks, utilities).
+
+5. **Write Metadata Artifacts**
+- Per-component metadata JSON files.
+- Consolidated index:
+  - `workspace/domains/design-system/metadata/components.json`
+
+6. **Quality Validation**
+- Validate metadata against JSON schema.
+- Reject components with missing a11y contract or token mapping.
+
+7. **AI-First Governance Check (Required)**
+- Confirm canonical references are used (no alternate policy paths).
+- Mark status of each dependency: `Implemented`, `Partially implemented`, `Concept only`.
+- Flag unresolved dependencies explicitly.
+
+## Deliverables
+
+- Component metadata files (JSON)
+- Central metadata index in domains/design-system/metadata
+- Validation output (pass/fail by component)
+
+## Success Criteria
+
+- [ ] 100% of exported components represented in metadata index
+- [ ] Every component includes a11y contract and token mapping
+- [ ] Metadata schema validation passes with zero errors
+- [ ] Metadata can be consumed by MCP handlers and RAG pipelines
+
+## Notes
+
+- Prefer explicit schemas over prose.
+- Keep metadata deterministic and versioned.
+- Machine-readable documentation is part of the product, not optional docs.
+
+
+## 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.

package/pro/squads/design/tasks/ds-generate-cursor-rules.md

@@ -0,0 +1,74 @@
+# Generate IDE Rules from Design System
+
+> Task ID: brad-ds-generate-cursor-rules
+> Agent: Brad Frost (Design System Architect)
+> Version: 1.0.0
+
+## Description
+
+Generate `.cursorrules` and `.claude-rules.md` files from the design system metadata, tokens, and guidelines. Rules enforce correct token usage, component selection, and accessibility.
+
+## Prerequisites
+
+- Token registry at `metadata/tokens/index.json`
+- Component metadata at `metadata/components.json`
+- Guidelines at `metadata/guidelines/usage.json`
+
+## Workflow
+
+1. **Extract Token Rules**
+   - List all CSS variables from token registry
+   - Generate rules: "Use var(--X) instead of hardcoded value Y"
+   - Group by category (color, spacing, typography, radius, shadow, motion)
+
+2. **Extract Component Rules**
+   - List all components with their intended use cases (from guidelines)
+   - Generate rules: "For X use case, use Y component"
+   - Include anti-patterns from when_not_to_use
+
+3. **Extract Accessibility Rules**
+   - From component a11y contracts, generate:
+   - Required ARIA attributes per component
+   - Keyboard interaction requirements
+   - WCAG criteria that must be met
+
+4. **Generate .cursorrules**
+   - Markdown format optimized for Cursor IDE
+   - Sections: Token Usage, Component Selection, Accessibility, Anti-Patterns
+
+5. **Generate .claude-rules.md**
+   - Markdown format optimized for Claude Code
+   - Include MCP tool references for runtime queries
+
+6. **Validate**
+   - Rules don't conflict with existing project rules
+   - Token references resolve to actual tokens
+   - Component references resolve to actual components
+
+## Output Path
+
+- `workspace/domains/design-system/rules/.cursorrules`
+- `workspace/domains/design-system/rules/.claude-rules.md`
+
+## Deliverables
+
+- IDE rules files generated from live metadata
+- Zero hardcoded rules — all derived from data sources
+
+## Success Criteria
+
+- [ ] Rules reference only existing tokens and components
+- [ ] Anti-patterns derived from guidelines when_not_to_use
+- [ ] Accessibility rules cover all component a11y contracts
+- [ ] No conflicts with existing .claude/ rules
+
+
+## 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.

package/pro/squads/design/tasks/ds-generate-documentation.md

@@ -0,0 +1,101 @@
+# Generate Pattern Library Documentation
+
+> Task ID: atlas-generate-documentation
+> Agent: Merovingian (Design System Builder)
+> Version: 1.1.0
+> v4.0-compatible: true
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `documentation`
+
+## Description
+
+Generate comprehensive pattern library documentation from built components. Creates searchable, navigable docs with usage examples, prop tables, accessibility notes, and live previews.
+
+## Prerequisites
+
+- At least 1 component built
+- Design system setup complete
+- Component .md files exist
+
+## Workflow
+
+### Steps
+
+1. **Scan Built Components** - Find all atoms, molecules, organisms
+2. **Parse Component Metadata** - Extract props, types, variants
+3. **Generate Pattern Library Index** - Main navigation page
+4. **Generate Component Pages** - Detailed pages per component
+5. **Generate Usage Examples** - Code snippets and live previews
+6. **Generate Accessibility Guide** - WCAG compliance notes
+7. **Generate Token Reference** - Token usage documentation
+8. **Create Search Index** - Searchable component library
+
+## Output
+
+- **index.md**: Pattern library homepage
+- **components/{Component}.md**: Per-component pages
+- **tokens.md**: Token reference guide
+- **accessibility.md**: Accessibility guidelines
+- **getting-started.md**: Setup and usage guide
+
+## Failure Handling
+
+- **No components found:** If scan finds zero component files in design-system directory, abort with "No components found. Run *build to create components before generating documentation."
+- **Component metadata extraction failed:** If TypeScript parser fails to extract prop types from component file, abort with "Cannot parse {ComponentName}.tsx: {error}. Ensure valid TypeScript and exported interfaces."
+- **Missing component documentation files:** If component exists but {ComponentName}.md does not exist or is empty, warn user "{N} components missing .md files. Generate basic docs or skip incomplete components?"
+- **Broken usage examples:** If code snippets in generated documentation contain syntax errors or reference non-existent props, abort with "{N} documentation examples have errors: {list}. Fix component APIs or example code before publishing docs."
+
+## Success Criteria
+
+- [ ] All components documented
+- [ ] Props documented with types
+- [ ] Usage examples for each variant
+- [ ] Accessibility notes included
+- [ ] Searchable and navigable
+- [ ] Up-to-date with latest components
+
+## Example
+
+```bash
+*document
+```
+
+Output:
+```
+📚 Merovingian: Generating pattern library documentation...
+
+Scanning components:
+  ✓ 8 atoms found
+  ✓ 5 molecules found
+  ✓ 2 organisms found
+
+Generating documentation:
+  ✓ index.md (pattern library home)
+  ✓ components/Button.md
+  ✓ components/Input.md
+  ✓ components/FormField.md
+  ...
+  ✓ tokens.md (token reference)
+  ✓ accessibility.md (WCAG guide)
+  ✓ getting-started.md
+
+✅ Pattern library: design-system/docs/
+
+Merovingian says: "Documentation is code. Keep it fresh."
+```
+
+## Notes
+
+- Auto-generates from TypeScript types
+- Updates when components change
+- Includes live Storybook links (if enabled)
+- Searchable by component name, prop, or token
+
+
+## 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.