aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/data/wcag-compliance-guide.md

@@ -0,0 +1,267 @@
+# WCAG Compliance Guide
+
+**Standard:** WCAG 2.1 Level AA (minimum), AAA target
+**Purpose:** Ensure design system components meet accessibility standards
+**Reference:** https://www.w3.org/WAI/WCAG21/quickref/
+
+---
+
+## Quick Reference: WCAG AA Requirements
+
+### Color Contrast
+
+**Text:**
+- Normal text (< 18px): ≥ 4.5:1 contrast ratio
+- Large text (≥ 18px or bold ≥ 14px): ≥ 3:1 contrast ratio
+
+**Non-Text (UI components):**
+- Icons, buttons, form borders: ≥ 3:1 contrast ratio
+
+**Testing:**
+```bash
+# Use browser dev tools or:
+npm install -g pa11y
+pa11y --standard WCAG2AA http://localhost:3000
+```
+
+### Keyboard Navigation
+
+**Required:**
+- All interactive elements accessible via Tab key
+- Logical tab order (top → bottom, left → right)
+- Enter/Space activates buttons
+- Arrow keys for radio groups, menus
+- Escape closes modals, dropdowns
+
+**Focus Indicators:**
+- Visible focus outline (≥ 3:1 contrast)
+- Never `outline: none` without replacement
+
+```css
+/* Good */
+button:focus {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+}
+
+/* Bad */
+button:focus {
+    outline: none;  /* ❌ Removes keyboard navigation indicator */
+}
+```
+
+### ARIA Attributes
+
+**When to use:**
+- Custom widgets (not semantic HTML)
+- Dynamic content updates
+- Complex interactions
+
+**Common ARIA:**
+```html
+<!-- Button with icon only -->
+<button aria-label="Close dialog">
+    <CloseIcon />
+</button>
+
+<!-- Loading state -->
+<div aria-live="polite" aria-busy="true">
+    Loading...
+</div>
+
+<!-- Expanded state -->
+<button
+    aria-expanded="false"
+    aria-controls="menu"
+>
+    Menu
+</button>
+
+<!-- Disabled -->
+<button disabled aria-disabled="true">
+    Submit
+</button>
+```
+
+---
+
+## WCAG AAA (Target, not required)
+
+**Enhanced Requirements:**
+- Text contrast: ≥ 7:1 (normal), ≥ 4.5:1 (large)
+- No images of text
+- Enhanced visual presentation (line height ≥ 1.5)
+
+---
+
+## Component-Specific Guidelines
+
+### Buttons
+
+```tsx
+// ✅ Good
+<button
+    onClick={handleClick}
+    disabled={isDisabled}
+    aria-disabled={isDisabled}
+    aria-label="Save changes"
+>
+    Save
+</button>
+
+// ❌ Bad
+<div onClick={handleClick}>  // Not keyboard accessible
+    Save
+</div>
+```
+
+### Forms
+
+```tsx
+// ✅ Good
+<label htmlFor="email">Email</label>
+<input
+    id="email"
+    type="email"
+    required
+    aria-required="true"
+    aria-invalid={hasError}
+    aria-describedby="email-error"
+/>
+{hasError && (
+    <span id="email-error" role="alert">
+        Invalid email format
+    </span>
+)}
+
+// ❌ Bad
+<input placeholder="Email" />  // No label
+```
+
+### Modals
+
+```tsx
+// ✅ Good
+<div
+    role="dialog"
+    aria-modal="true"
+    aria-labelledby="dialog-title"
+>
+    <h2 id="dialog-title">Confirm Action</h2>
+    <p>Are you sure?</p>
+    <button onClick={onConfirm}>Yes</button>
+    <button onClick={onCancel}>No</button>
+</div>
+
+// Focus trap: Tab cycles within modal
+// Escape closes modal
+```
+
+---
+
+## Testing Checklist
+
+### Automated Testing
+
+```bash
+# Install tools
+npm install --save-dev @testing-library/jest-dom
+npm install --save-dev jest-axe
+
+# Test example
+import { axe } from 'jest-axe';
+
+test('Button is accessible', async () => {
+    const { container } = render(<Button>Click me</Button>);
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+});
+```
+
+### Manual Testing
+
+- [ ] Navigate entire app with keyboard only (no mouse)
+- [ ] Test with screen reader (NVDA, JAWS, VoiceOver)
+- [ ] Zoom to 200% - all content still accessible
+- [ ] Check color contrast with dev tools
+- [ ] Test with high contrast mode
+
+---
+
+## Common Violations & Fixes
+
+### Violation 1: Missing Alt Text
+
+```tsx
+// ❌ Bad
+<img src="logo.png" />
+
+// ✅ Good
+<img src="logo.png" alt="Company logo" />
+
+// ✅ Good (decorative)
+<img src="decoration.png" alt="" />
+```
+
+### Violation 2: Low Contrast
+
+```css
+/* ❌ Bad */
+.text {
+    color: #999;           /* 2.8:1 contrast */
+    background: #fff;
+}
+
+/* ✅ Good */
+.text {
+    color: #666;           /* 5.7:1 contrast ✓ */
+    background: #fff;
+}
+```
+
+### Violation 3: Click-Only Elements
+
+```tsx
+// ❌ Bad
+<div onClick={handleClick}>Click me</div>
+
+// ✅ Good
+<button onClick={handleClick}>Click me</button>
+
+// ✅ Good (if div required)
+<div
+    role="button"
+    tabIndex={0}
+    onClick={handleClick}
+    onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            handleClick();
+        }
+    }}
+>
+    Click me
+</div>
+```
+
+---
+
+## Resources
+
+- **WCAG Quick Reference:** https://www.w3.org/WAI/WCAG21/quickref/
+- **ARIA Authoring Practices:** https://www.w3.org/WAI/ARIA/apg/
+- **axe DevTools:** Browser extension for automated testing
+- **WAVE:** Web accessibility evaluation tool
+
+---
+
+## Design System Enforcement
+
+**All components MUST:**
+- Pass axe automated tests
+- Have ≥ 4.5:1 text contrast
+- Be keyboard navigable
+- Have visible focus indicators
+- Include proper ARIA attributes
+- Be tested with screen readers
+
+**Non-negotiable. Brad says: "Accessibility is quality."**

package/pro/squads/design/docs/AUDIT_REPORT.md

@@ -0,0 +1,97 @@
+# Design Squad Audit Report
+
+## Audit Metadata
+- Squad: `squads/design`
+- Auditor mode: `squad-pedro` (`@pedro-valerio` process hardening)
+- Date: 2026-02-17
+- Scope: structural integrity, workflow validity, manifest drift, command mapping, task anatomy, quality gates
+
+## Objective
+Validate 100% of the Design squad with veto-grade process checks and eliminate all blocking inconsistencies.
+
+## Method
+1. Structural validation using `validate-design-squad.py`
+2. Manifest parity checks (`squad.yaml` vs filesystem)
+3. Workflow agent identity and command mapping checks
+4. Task anatomy compliance checks
+5. End-to-end quality gates
+
+## Initial High-Risk Findings (Before Fix)
+1. Workflows referenced invalid agent id `design-system` (not declared in `squad.yaml`).
+2. Workflows used `*sync-registry` but Brad command mapping had no explicit route.
+3. Manifest drift: 4 task files and 2 template files existed on disk but were not declared in `squad.yaml`.
+4. Task anatomy gaps across many task files (missing one or more: Execution Type, Dependencies, On Fail, Success/Completion).
+5. `nano-banana-generator` skipped strict structural validation due to missing/insufficient embedded YAML block fields.
+
+## Corrections Applied
+
+### 1) Workflow Agent Normalization
+- Replaced all workflow step agents from `design-system` to `brad-frost`.
+- Files updated:
+  - `squads/design/workflows/audit-only.yaml`
+  - `squads/design/workflows/brownfield-complete.yaml`
+  - `squads/design/workflows/greenfield-new.yaml`
+  - `squads/design/workflows/agentic-readiness.yaml`
+  - `squads/design/workflows/dtcg-tokens-governance.yaml`
+  - `squads/design/workflows/motion-quality.yaml`
+
+### 2) Workflow Command Mapping Hardening
+- Added explicit mapping in Brad agent:
+  - `*sync-registry -> squads/design/tasks/ds-sync-registry.md`
+- File updated:
+  - `squads/design/agents/brad-frost.md`
+
+### 3) Manifest Drift Elimination
+- Added missing tasks to `squad.yaml`:
+  - `ds-generate-cursor-rules`
+  - `ds-mcp-status`
+  - `ds-query`
+  - `ds-validate-ai-readiness`
+- Added missing templates to `squad.yaml`:
+  - `agent-template`
+  - `clone-mind-template`
+- Synced generated config from `squad.yaml`:
+  - `squads/design/config.yaml`
+
+### 4) Task Anatomy Standardization
+- Normalized task files to include process guard sections where absent:
+  - `Execution Type`
+  - `Dependencies`
+  - `On Fail`
+  - `Success Criteria` or `Completion Criteria`
+- Result: no remaining anatomy gaps.
+
+### 5) Agent Validation Completion
+- Added robust embedded YAML contract for `nano-banana-generator` with required fields including `whenToUse`.
+- File updated:
+  - `squads/design/agents/nano-banana-generator.md`
+
+## Final Validation Evidence
+
+### Structural
+- Command: `python3 squads/design/scripts/validate-design-squad.py --output json`
+- Result: `all_passed: true`
+
+### Manifest Parity
+- `tasks`: listed=67, actual=67, drift=0
+- `templates`: listed=15, actual=15, drift=0
+- `checklists`: listed=11, actual=11, drift=0
+- `data`: listed=19, actual=19, drift=0
+- `workflows`: listed=7, actual=7, drift=0
+
+### Workflow Integrity
+- Invalid workflow agents: `0`
+- Unmapped workflow commands: `[]`
+
+### Task Process Compliance
+- Task anatomy gaps: `0`
+
+### Quality Gates
+- `npm run lint` -> PASS
+- `npm run typecheck` -> PASS
+- `npm test` -> PASS
+
+## Final Status
+- Design squad is **process-hardened** and **operationally consistent**.
+- No blocking structural, workflow, or manifest issues remain in this audit scope.
+