aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/config/tech-stack.md

@@ -0,0 +1,48 @@
+# Design System Squad - Tech Stack
+
+## Core Stack
+
+| Tool | Purpose | Used By |
+|---|---|---|
+| Tailwind CSS v4 | token-first styling via `@theme` | @brad-frost |
+| shadcn/ui Registry | component distribution and bootstrap | @brad-frost |
+| TypeScript | component and metadata contracts | @brad-frost |
+| Storybook | component docs and review | @brad-frost |
+| Chromatic | visual regression checks | @brad-frost |
+| Style Dictionary / DTCG | token export pipelines | @brad-frost |
+
+## Governance & Ops
+
+| Tool | Purpose | Used By |
+|---|---|---|
+| Vale | copy governance lint | @dave-malouf |
+| GitHub Actions | deterministic CI checks | @design-chief |
+| WCAG reference data | accessibility gates and audits | @brad-frost |
+
+## AI Readiness
+
+| Tool | Purpose | Used By |
+|---|---|---|
+| `metadata/components.json` | AI-readable component catalog | @brad-frost |
+| MCP server skeleton | tool-ready DS artifacts exposure | @brad-frost |
+| `workspace/ui/registry.json` | registry sync source | @design-chief |
+
+## Output Paths
+
+```yaml
+output_paths:
+  domains_design_system: workspace/domains/design-system/
+  system_foundations: workspace/system/foundations/
+  ui_registry: workspace/ui/registry.json
+  squad_artifacts: squads/design/
+```
+
+## Scope Boundary
+
+Out of scope for this squad:
+
+- logo creation
+- brand strategy/pricing
+- thumbnails, photography, video editing
+
+These domains are handled in `squads/brand` and `squads/content-visual`.

package/pro/squads/design/config.yaml

@@ -0,0 +1,204 @@
+name: design
+version: 2.1.0
+slashPrefix: DS
+title: Design System Squad
+description: Squad focado exclusivamente em Design System. Especializado em tokens, componentes, acessibilidade, registry,
+author: AIOS Team
+icon: 🎨
+type: specialist
+entry_agent: design-chief
+independence: true
+independence_details: |
+  This squad is completely self-contained:
+  - No database required
+  - No external APIs
+  - Works with any codebase (React, Vue, HTML/CSS)
+  - All operations are filesystem-based
+dependencies:
+  optional:
+    - name: Node.js
+      version: '>=18.0'
+      description: For component generation and npm packages
+    - name: Tailwind CSS
+      version: '>=4.0.0'
+      description: CSS-first token system with @theme
+    - name: shadcn/ui CLI
+      version: latest
+      description: Registry-first component distribution
+metadata:
+  version: 2.1.0
+  score: 10
+tier_system:
+  tier_0_foundation:
+    description: Entry point agents for operations and adoption strategy
+    agents: []
+  tier_1_masters:
+    description: Execution masters with specialist practices
+    agents: []
+  tier_2_specialists:
+    description: Deep specialists for DS implementation
+    agents: []
+  orchestrator:
+    description: Routes requests
+    agent: design-chief
+agents:
+  - design-chief
+  - brad-frost
+  - dave-malouf
+  - dan-mall
+  - nano-banana-generator
+  - ds-token-architect
+  - ds-foundations-lead
+  - storybook-expert
+tasks:
+  - ds-audit-codebase
+  - ds-build-component
+  - ds-build-mcp-server
+  - ds-calculate-roi
+  - ds-compose-molecule
+  - ds-consolidate-patterns
+  - ds-context-contract
+  - ds-extend-pattern
+  - ds-extract-tokens
+  - ds-generate-ai-metadata
+  - ds-generate-documentation
+  - ds-generate-migration-strategy
+  - ds-generate-shock-report
+  - ds-govern-a11y-compliance
+  - ds-health-metrics
+  - ds-integrate-squad
+  - ds-integrate-workspace
+  - ds-legacy-modernization
+  - ds-parallelization-gate
+  - ds-rebuild-artifact
+  - ds-reverse-engineer
+  - ds-scan-artifact
+  - ds-setup-design-system
+  - ds-sync-registry
+  - ds-generate-cursor-rules
+  - ds-mcp-status
+  - ds-query
+  - ds-validate-ai-readiness
+  - ds-agentic-audit
+  - ds-agentic-setup
+  - ds-token-w3c-extract
+  - ds-token-modes
+  - ds-motion-audit
+  - ds-visual-regression
+  - ds-fluent-audit
+  - ds-fluent-build
+  - ds-theme-multi-brand
+  - ds-multi-framework
+  - ds-governance
+  - ds-designops
+  - ds-critical-eye-inventory
+  - ds-critical-eye-score
+  - ds-critical-eye-compare
+  - ds-critical-eye-decide
+  - ds-critical-eye-report
+  - ds-figma-pipeline
+  - f1-ingest-figma-tokens
+  - f1-map-tokens-to-shadcn
+  - f1-apply-foundations
+  - f1-qa-foundations
+  - f2-ingest-base-components
+  - f2-adapt-shadcn-components
+  - f2-qa-base-components
+  - f3-derive-components
+  - f3-qa-derived-components
+  - sb-install
+  - sb-configure
+  - sb-expand-shadcn
+  - sb-generate-all-stories
+  - sb-verify
+  - sb-brownfield-scan
+  - sb-brownfield-migrate
+  - sb-sync-workspace
+  - a11y-audit
+  - aria-audit
+  - contrast-matrix
+  - focus-order-audit
+  - atomic-refactor-plan
+  - atomic-refactor-execute
+  - audit-reading-experience
+  - audit-tailwind-config
+  - bootstrap-shadcn-library
+  - bundle-audit
+  - dead-code-detection
+  - design-compare
+  - export-design-tokens-dtcg
+  - tailwind-upgrade
+  - token-usage-analytics
+  - ux-rewrite-sixth-grade
+  - validate-design-fidelity
+  - designops-maturity-assessment
+  - designops-metrics-setup
+  - design-team-scaling
+  - design-tooling-audit
+  - design-process-optimization
+  - design-triage
+  - design-review-orchestration
+  - create-doc
+  - execute-checklist
+templates:
+  - component-prompt-injection-tmpl
+  - component-visual-spec-tmpl
+  - design-fidelity-report-tmpl
+  - ds-artifact-analysis
+  - ds-health-report-tmpl
+  - ds-migration-strategy-tmpl
+  - ds-state-persistence-tmpl
+  - ds-tokens-schema-tmpl
+  - ds-ai-component-metadata-schema-tmpl
+  - migration-strategy-tmpl
+  - state-persistence-tmpl
+  - tokens-schema-tmpl
+  - reading-design-tokens
+  - agent-template
+  - clone-mind-template
+  - critical-eye-cycle-report-tmpl
+checklists:
+  - atomic-refactor-checklist
+  - ds-accessibility-wcag-checklist
+  - ds-a11y-release-gate-checklist
+  - ds-component-quality-checklist
+  - ds-migration-readiness-checklist
+  - ds-pattern-audit-checklist
+  - token-mapping-checklist
+  - component-adaptation-checklist
+  - design-fidelity-checklist
+  - reading-accessibility-checklist
+  - design-handoff-checklist
+  - design-team-health-checklist
+  - designops-maturity-checklist
+  - ds-critical-eye-review-checklist
+workflows:
+  - audit-only
+  - brownfield-complete
+  - greenfield-new
+  - self-healing-workflow
+  - agentic-readiness
+  - dtcg-tokens-governance
+  - motion-quality
+  - foundations-pipeline
+  - storybook-full-setup
+  - storybook-brownfield-migration
+  - critical-eye
+tags:
+  - design-system
+  - tokens
+  - components
+  - accessibility
+  - wcag
+  - atomic-design
+  - tailwind-v4
+  - shadcn-registry
+  - machine-readable
+  - mcp
+  - designops
+  - storybook
+  - csf3
+  - interaction-testing
+  - visual-regression
+  - brownfield-migration
+  - component-stories

package/pro/squads/design/data/agentic-design-systems-guide.md

@@ -0,0 +1,46 @@
+# Agentic Design Systems Guide
+
+## Purpose
+
+Define how the Design Squad evolves from human-readable documentation into machine-readable infrastructure for AI agents.
+
+## Principles
+
+1. **Registry-first distribution**
+- Components are distributed as source and registry entries, not opaque packages.
+
+2. **Token hierarchy is mandatory**
+- `primitives` -> `semantic` -> `component`.
+- No direct component hardcoding against primitive values.
+
+3. **Metadata is product surface**
+- Every component must publish a machine-readable contract.
+- Include props, variants, accessibility, and token dependencies.
+
+4. **Workspace boundaries are explicit**
+- `workspace/domains/design-system`: token source and metadata.
+- `workspace/system`: primitives and reusable patterns.
+- `workspace/ui`: final components and blocks.
+
+5. **MCP exposure for AI execution**
+- Agents query DS artifacts via MCP handlers.
+- Responses must be structured, deterministic, and schema-validated.
+
+## Minimal Artifact Set
+
+- `workspace/domains/design-system/tokens/**`
+- `workspace/domains/design-system/metadata/components.json`
+- `workspace/ui/registry.json`
+- `workspace/domains/design-system/mcp/server.ts`
+
+## Governance
+
+- Schema validation in CI for metadata and token exports.
+- Version every metadata contract change.
+- Block component publication if a11y contract is missing.
+
+## Success Metrics
+
+- 100% component metadata coverage.
+- 0 unknown variants generated by AI consumers.
+- Reduced UI drift across squads through shared registry contracts.

package/pro/squads/design/data/agentic-ds-principles.md

@@ -0,0 +1,100 @@
+# Agentic Design Systems — Principles for DS+AI
+
+**Source:** Brad Frost's 2026 work on AI-constrained design systems
+**Purpose:** Guide for making design systems AI-ready and using DS as a constraint layer for generative AI
+
+---
+
+## What Is an Agentic Design System?
+
+An Agentic DS is a design system where AI agents are **deliberately constrained** to work only with the system's approved materials — tokens, components, patterns, and composition rules. The AI doesn't freestyle; it assembles from sanctioned building blocks.
+
+**Key distinction:** The DS becomes the AI's vocabulary. If a token doesn't exist, the AI can't use that value. If a component isn't in the library, the AI can't invent one.
+
+---
+
+## The "Vibe Coding" Problem
+
+Unconstrained AI generates plausible-looking but undisciplined output:
+- Hardcoded color values instead of tokens
+- Custom spacing that doesn't follow your scale
+- Components that look right but don't match your API
+- Accessibility gaps because the AI optimized for appearance
+
+When AI is constrained to DS materials:
+- Every color comes from your token set
+- Every spacing value follows your scale
+- Every component matches your documented API
+- Accessibility is inherited from tested components
+
+---
+
+## Machine-Readable Infrastructure Requirements
+
+### Structured Design Tokens
+
+```json
+{
+  "color": {
+    "primary": {
+      "$value": "#0066CC",
+      "$type": "color",
+      "$description": "Primary brand color. Use for CTAs and key actions."
+    }
+  }
+}
+```
+
+### Component API Documentation
+
+Every component needs:
+- **Props/API surface** — what inputs it accepts, with types
+- **Variants** — enumerated options (size: sm | md | lg)
+- **Composition rules** — what goes inside, what doesn't
+- **Usage guidelines** — when to use vs. alternatives
+- **Accessibility** — ARIA roles, keyboard behavior
+
+### Storybook MCP Addon
+
+The Storybook MCP addon exposes component stories as structured context for LLMs:
+1. Storybook indexes your component library
+2. MCP addon wraps that index as a tool for AI agents
+3. AI queries the tool before generating UI code
+4. Generated code uses real components with correct props
+
+Without MCP: AI generates `<div className="nav-item">` with custom CSS
+With MCP: AI generates `<NavItem variant="primary" icon={HomeIcon}>` using your actual component
+
+---
+
+## Checklist: Is Your DS AI-Ready?
+
+### Tokens
+- [ ] Tokens in W3C DTCG JSON format (not just Figma variables)
+- [ ] Every token has `$description` explaining usage intent
+- [ ] Modes (light/dark/hc) defined with explicit mappings
+- [ ] Token files published as versioned artifacts
+
+### Components
+- [ ] Every component has typed prop definitions
+- [ ] Variants are enumerated, not open-ended
+- [ ] Composition rules documented (what nests inside what)
+- [ ] Storybook stories exist for every component and variant
+- [ ] Accessibility requirements documented per component
+
+### Infrastructure
+- [ ] Storybook MCP addon installed and configured
+- [ ] Component metadata exportable as JSON
+- [ ] API docs auto-generated from source
+- [ ] Version-pinned so AI references a stable snapshot
+
+### Governance
+- [ ] Process for AI-generated contributions (review, lint, test)
+- [ ] Token validation in CI (no hardcoded values)
+- [ ] Component usage auditing (detect drift from DS)
+
+---
+
+## Key Takeaway
+
+The design system that wins in an AI-assisted world isn't the prettiest — it's the most **machine-readable**. Structured tokens, typed component APIs, and explicit composition rules turn your DS from a reference guide into an enforcement mechanism.

package/pro/squads/design/data/atomic-design-principles.md

@@ -0,0 +1,108 @@
+# Atomic Design Principles
+
+**Source:** Brad Frost's Atomic Design methodology
+**Application:** Merovingian component organization
+
+---
+
+## The Five Levels
+
+### Atoms
+**Definition:** Basic building blocks that can't be broken down further.
+
+**Examples:**
+- Button
+- Input
+- Label
+- Icon
+- Heading
+- Text
+
+**Rules:**
+- Standalone, reusable
+- No dependencies on other atoms
+- Uses tokens only (no hardcoded values)
+- Single responsibility
+
+### Molecules
+**Definition:** Groups of atoms functioning together as a unit.
+
+**Examples:**
+- FormField (Label + Input + HelperText)
+- SearchBar (Input + Button)
+- Card Header (Icon + Heading + Text)
+
+**Rules:**
+- Composes atoms (doesn't reimplement)
+- Adds composition logic
+- Atoms remain independent
+
+### Organisms
+**Definition:** Complex UI components composed of molecules and/or atoms.
+
+**Examples:**
+- Navigation (Logo + NavLinks + SearchBar + UserMenu)
+- LoginForm (FormFields + Button + Link)
+- ProductCard (Image + CardHeader + CardBody + Button)
+
+**Rules:**
+- Distinct section of interface
+- Can be reused across templates
+- Manages internal state if needed
+
+### Templates
+**Definition:** Page-level layout without real content.
+
+**Examples:**
+- DashboardLayout
+- ArticleLayout
+- CheckoutFlowLayout
+
+**Rules:**
+- Defines page structure
+- Placeholder content
+- Reusable across pages
+
+### Pages
+**Definition:** Templates with real content.
+
+**Examples:**
+- Homepage
+- Product Detail Page
+- User Dashboard
+
+**Note:** Merovingian focuses on atoms → organisms. Pages are application-specific.
+
+---
+
+## Benefits
+
+1. **Consistency:** Reusing atoms ensures UI consistency
+2. **Scalability:** New features built from existing components
+3. **Maintenance:** Fix once, applies everywhere
+4. **Testing:** Test atoms thoroughly, compose with confidence
+5. **Collaboration:** Clear component taxonomy
+
+---
+
+## Merovingian Implementation
+
+```
+design-system/
+├── atoms/
+│   ├── Button/
+│   ├── Input/
+│   └── Label/
+├── molecules/
+│   ├── FormField/
+│   └── SearchBar/
+├── organisms/
+│   ├── Navigation/
+│   └── LoginForm/
+└── templates/
+    └── DashboardLayout/
+```
+
+**Merovingian builds:** atoms first → molecules → organisms → templates
+
+**Reference:** https://atomicdesign.bradfrost.com/