aiox-core 5.0.2 → 5.0.4

package/pro/squads/design/tasks/bundle-audit.md

@@ -0,0 +1,245 @@
+# Task: Bundle Size Audit
+
+> Command: `*bundle-audit [path]`
+> Purpose: Analyze CSS/JS bundle size contribution per component
+> **Execution Type:** `Worker`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `metrics`
+
+## Overview
+
+This task performs detailed bundle analysis:
+- CSS class usage and estimated size
+- Component JS size estimation
+- Tree-shaking opportunities
+- Duplicate code detection
+
+## Prerequisites
+
+- Target path (default: `app/components/`)
+- Build output available (optional, for accurate sizes)
+
+## Execution Steps
+
+### Step 1: CSS Class Analysis
+
+```bash
+# Extract all Tailwind classes used
+grep -rohn --include="*.tsx" 'className="[^"]*"' {path}/ \
+  | tr '"' '\n' | tr ' ' '\n' \
+  | grep -v "^$\|className=" \
+  | sort | uniq -c | sort -rn > /tmp/class-usage.txt
+
+# Count unique classes
+unique=$(cat /tmp/class-usage.txt | wc -l)
+
+# Most used classes (optimization candidates)
+head -20 /tmp/class-usage.txt
+
+# Rarely used classes (bundle bloat candidates)
+tail -50 /tmp/class-usage.txt | head -20
+```
+
+**Output:**
+```
+CSS Class Analysis
+==================
+Total unique classes: 234
+Estimated CSS footprint: ~12KB (234 * 50 bytes avg)
+
+Most Used (top 10):
+  142  flex
+  128  items-center
+   98  p-4
+   87  text-sm
+   ...
+
+Rarely Used (potential bloat):
+    1  animate-accordion-down
+    1  scroll-smooth
+    ...
+```
+
+### Step 2: Component Size Estimation
+
+```bash
+# Lines per component (proxy for JS size)
+find {path}/ -name "*.tsx" -exec wc -l {} \; \
+  | sort -rn > /tmp/component-sizes.txt
+
+# Top 10 largest
+head -10 /tmp/component-sizes.txt
+
+# Estimate JS size (rough: 1 line ≈ 50 bytes minified)
+while read lines file; do
+  kb=$(echo "scale=1; $lines * 50 / 1024" | bc)
+  echo "$kb KB - $file"
+done < /tmp/component-sizes.txt | head -10
+```
+
+**Output:**
+```
+Component Size Estimation
+=========================
+Largest Components:
+  18.2 KB - FeedbackSection.tsx (373 lines)
+  14.1 KB - ListGroupsView.tsx (289 lines)
+  ...
+
+Total estimated: ~150KB (before minification)
+After minification: ~45KB (estimated 70% reduction)
+After gzip: ~12KB (estimated 75% compression)
+```
+
+### Step 3: Import Analysis (Tree-shaking)
+
+```bash
+# Find unused imports (tree-shake candidates)
+# Check imports vs actual usage in file
+for file in $(find {path}/ -name "*.tsx"); do
+  imports=$(grep "^import" "$file" | grep -oP "{ [^}]+ }" | tr -d '{},' | tr ' ' '\n' | grep -v "^$")
+  for imp in $imports; do
+    count=$(grep -c "\b$imp\b" "$file")
+    if [ "$count" -eq 1 ]; then
+      echo "UNUSED: $imp in $file"
+    fi
+  done
+done
+```
+
+### Step 4: Duplicate Code Detection
+
+```bash
+# Find similar code blocks (potential extraction candidates)
+# Look for repeated JSX patterns
+grep -rhn --include="*.tsx" "<div className=" {path}/ \
+  | cut -d: -f3- \
+  | sort | uniq -c | sort -rn \
+  | awk '$1 > 3 {print}' | head -20
+```
+
+**Output:**
+```
+Duplicate Patterns Detected
+===========================
+   12  <div className="flex items-center gap-2">
+    8  <div className="p-4 rounded-lg border">
+    6  <div className="text-sm text-muted-foreground">
+    ...
+
+Recommendation: Extract to shared molecules
+```
+
+### Step 5: Bundle Report Generation
+
+```markdown
+# Bundle Audit Report
+Generated: {timestamp}
+Path: {path}
+
+## Summary
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Unique CSS Classes | 234 | <500 | ✅ |
+| Est. CSS Size | 12KB | <50KB | ✅ |
+| Est. JS Size (min) | 45KB | <100KB | ✅ |
+| Est. Total (gzip) | 15KB | <30KB | ✅ |
+
+## CSS Analysis
+
+### Class Usage Distribution
+| Range | Count | % of Total |
+|-------|-------|------------|
+| Used >50x | 12 | 5% |
+| Used 10-50x | 45 | 19% |
+| Used 2-10x | 89 | 38% |
+| Used 1x | 88 | 38% |
+
+### Top 10 Classes
+| Class | Usage | Estimated Size |
+|-------|-------|----------------|
+| flex | 142 | included |
+| items-center | 128 | included |
+| p-4 | 98 | included |
+| ... | ... | ... |
+
+### Rarely Used Classes (bloat candidates)
+| Class | Usage | Recommendation |
+|-------|-------|----------------|
+| animate-accordion-down | 1 | Consider removal |
+| scroll-smooth | 1 | Consider removal |
+| ... | ... | ... |
+
+## JS Analysis
+
+### Largest Components
+| Component | Lines | Est. Size | Status |
+|-----------|-------|-----------|--------|
+| FeedbackSection.tsx | 373 | 18KB | ⚠️ Refactor |
+| ListGroupsView.tsx | 289 | 14KB | ⚠️ Refactor |
+| ... | ... | ... | ... |
+
+### Tree-shaking Opportunities
+| File | Unused Imports | Savings |
+|------|----------------|---------|
+| Header.tsx | lodash, date-fns | ~5KB |
+| ... | ... | ... |
+
+## Duplicate Code
+
+### Repeated Patterns (extract to molecules)
+| Pattern | Occurrences | Files |
+|---------|-------------|-------|
+| `<div className="flex items-center gap-2">` | 12 | Card, List, ... |
+| ... | ... | ... |
+
+## Recommendations
+
+1. **HIGH:** Refactor FeedbackSection (18KB → target 5KB)
+2. **MEDIUM:** Extract 12 duplicate flex patterns to molecule
+3. **LOW:** Remove 15 rarely-used CSS classes
+4. **INFO:** Enable dynamic imports for Dialog, Modal
+
+## Projected Savings
+| Action | Current | After | Savings |
+|--------|---------|-------|---------|
+| Refactor large components | 150KB | 80KB | 47% |
+| Extract duplicates | - | - | ~5KB |
+| Remove unused classes | 12KB | 10KB | 17% |
+| **Total** | **162KB** | **90KB** | **44%** |
+```
+
+## Failure Handling
+
+- **No .tsx files found in path:** Exit with error "No component files in {path}. Verify target path."
+- **Tailwind config not found:** Skip custom class analysis, note "Custom CSS analysis skipped — no tailwind.config found"
+- **Build output not available:** Use line-count estimation instead of actual bundle sizes. Note "Estimates based on source lines, not build output"
+- **Import analysis produces false positives:** Filter out type-only imports and re-exported barrel imports before reporting unused
+
+## Output
+
+- `outputs/design-system/{project}/metrics/bundle-audit-report.md`
+- `outputs/design-system/{project}/metrics/class-usage.txt`
+- `outputs/design-system/{project}/metrics/component-sizes.txt`
+
+## Related Checklists
+
+- `squads/design/checklists/ds-pattern-audit-checklist.md`
+- `squads/design/checklists/ds-component-quality-checklist.md`
+
+## Success Criteria
+
+- [ ] All CSS classes catalogued
+- [ ] Component sizes estimated
+- [ ] Tree-shaking opportunities identified
+- [ ] Duplicate patterns found
+- [ ] Report with actionable recommendations
+
+## Related Commands
+
+- `*ds-health` - Overall health dashboard
+- `*dead-code` - Unused code detection
+- `*refactor-plan` - Plan component refactoring
+
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/contrast-matrix.md

@@ -0,0 +1,373 @@
+# Task: contrast-matrix
+
+> **Command:** `*contrast-matrix {path}`
+> **Agent:** Brad Frost (Design System Architect)
+> **Purpose:** Generate complete color contrast matrix with WCAG 2.2 + APCA validation
+> **Execution Type:** `Worker`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `accessibility`
+
+---
+
+## Overview
+
+Generates a comprehensive contrast matrix showing all foreground/background color combinations in the codebase with:
+- WCAG 2.2 contrast ratios (AA and AAA)
+- APCA (Advanced Perceptual Contrast Algorithm) Lc values
+- Usage locations
+- Pass/fail indicators
+- Remediation suggestions
+
+---
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | Directory to scan (e.g., `./app/components`) |
+| `--format` | No | Output: `table`, `html`, `json` (default: `table`) |
+| `--include-tokens` | No | Include design token colors |
+| `--theme` | No | Filter by theme: `light`, `dark`, `sepia`, `all` (default: `all`) |
+
+---
+
+## Execution Steps
+
+### Phase 1: Color Extraction
+
+Extract all colors from:
+
+```typescript
+// Sources to scan
+const colorSources = [
+  // CSS/SCSS
+  'color:', 'background-color:', 'border-color:', 'fill:', 'stroke:',
+  // Tailwind classes
+  'text-', 'bg-', 'border-', 'fill-', 'stroke-',
+  // CSS variables
+  'var(--color-', '--color-',
+  // Inline styles
+  'style={{ color:', 'style={{ backgroundColor:',
+  // Hex values
+  '#[0-9A-Fa-f]{3,8}',
+  // RGB/RGBA
+  'rgb(', 'rgba(',
+  // HSL/HSLA
+  'hsl(', 'hsla(',
+  // OKLCH
+  'oklch('
+];
+
+interface ExtractedColor {
+  value: string;           // Normalized hex
+  original: string;        // Original format found
+  source: 'css' | 'tailwind' | 'token' | 'inline';
+  usage: 'foreground' | 'background' | 'border' | 'unknown';
+  files: Array<{ path: string; line: number }>;
+  theme?: 'light' | 'dark' | 'sepia';
+}
+```
+
+### Phase 2: Contrast Calculation
+
+For each foreground/background pair:
+
+```typescript
+interface ContrastResult {
+  foreground: string;
+  background: string;
+
+  // WCAG 2.x Contrast Ratio
+  wcagRatio: number;        // e.g., 4.52:1
+
+  // WCAG 2.2 Compliance
+  wcag: {
+    AA_normal: boolean;     // ≥4.5:1 for <18px
+    AA_large: boolean;      // ≥3:1 for ≥18px/bold
+    AAA_normal: boolean;    // ≥7:1
+    AAA_large: boolean;     // ≥4.5:1
+    ui_components: boolean; // ≥3:1 (borders, icons)
+  };
+
+  // APCA (Lc values)
+  apca: {
+    Lc: number;             // Lightness contrast (-108 to +106)
+    recommended_size: string; // e.g., "14px+" or "18px bold+"
+    pass: boolean;
+  };
+
+  // Usage context
+  usage: Array<{
+    file: string;
+    line: number;
+    element: string;        // e.g., "Button", "p", "span"
+    fontSize: string;       // If detectable
+    fontWeight: string;     // If detectable
+  }>;
+}
+```
+
+### Phase 3: WCAG 2.2 + APCA Calculations
+
+**WCAG 2.x Contrast Ratio Formula:**
+```typescript
+function getWCAGContrastRatio(fg: string, bg: string): number {
+  const L1 = getRelativeLuminance(fg);
+  const L2 = getRelativeLuminance(bg);
+  const lighter = Math.max(L1, L2);
+  const darker = Math.min(L1, L2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+function getRelativeLuminance(hex: string): number {
+  const rgb = hexToRgb(hex);
+  const [r, g, b] = rgb.map(c => {
+    c = c / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+```
+
+**APCA Lc Calculation:**
+```typescript
+// APCA W3 reference algorithm
+function getAPCAContrast(textColor: string, bgColor: string): number {
+  // Uses SAPC (Spatial Perception of Color) model
+  // Returns Lc (Lightness contrast) value
+  // Positive = light text on dark bg
+  // Negative = dark text on light bg
+  // |Lc| ≥ 60 is generally readable
+  // |Lc| ≥ 75 is comfortable for body text
+  // |Lc| ≥ 90 is excellent
+}
+```
+
+**APCA Minimum Lc Values by Font Size/Weight:**
+
+| Font Size | Weight | Min |Lc| for Body | Min |Lc| for UI |
+|-----------|--------|---------------------|-------------------|
+| 12px | 400 | 90 | 75 |
+| 14px | 400 | 75 | 60 |
+| 16px | 400 | 60 | 50 |
+| 18px | 400 | 55 | 45 |
+| 24px | 400 | 45 | 40 |
+| 14px | 700 | 60 | 50 |
+| 18px | 700 | 50 | 40 |
+
+### Phase 4: Matrix Generation
+
+Group by theme and generate matrix:
+
+```typescript
+interface ContrastMatrix {
+  theme: 'light' | 'dark' | 'sepia';
+  colors: {
+    foregrounds: ExtractedColor[];
+    backgrounds: ExtractedColor[];
+  };
+  pairs: ContrastResult[];
+  summary: {
+    total_pairs: number;
+    wcag_aa_pass: number;
+    wcag_aaa_pass: number;
+    apca_pass: number;
+    failures: number;
+  };
+}
+```
+
+---
+
+## Output
+
+### 1. Matrix Table (Default)
+
+```markdown
+# Color Contrast Matrix
+
+**Theme:** Light
+**Scanned:** ./app/components (487 files)
+**Date:** 2026-01-05
+
+## Summary
+
+| Metric | Count | Percentage |
+|--------|-------|------------|
+| Total pairs | 156 | 100% |
+| WCAG AA Pass | 142 | 91.0% |
+| WCAG AAA Pass | 98 | 62.8% |
+| APCA Pass | 138 | 88.5% |
+| **Failures** | **14** | **9.0%** |
+
+## Complete Matrix
+
+| Foreground | Background | Ratio | AA | AAA | APCA Lc | Status |
+|------------|------------|-------|----|----|---------|--------|
+| #212121 | #FAFAFA | 16.1:1 | ✓ | ✓ | -92.4 | ✅ Pass |
+| #424242 | #FFFFFF | 10.5:1 | ✓ | ✓ | -85.2 | ✅ Pass |
+| #757575 | #FFFFFF | 4.6:1 | ✓ | ✗ | -63.1 | ⚠️ AA only |
+| #999999 | #FFFFFF | 2.8:1 | ✗ | ✗ | -48.7 | ❌ Fail |
+| #D4AF37 | #1A1A1A | 8.2:1 | ✓ | ✓ | +78.3 | ✅ Pass |
+
+## Failures Detail
+
+### ❌ #999999 on #FFFFFF (2.8:1)
+
+**Problem:** Fails WCAG AA (need 4.5:1)
+**APCA Lc:** -48.7 (need ≥60 for body text)
+**Used in:**
+- `app/components/ui/Input.tsx:45` - placeholder text
+- `app/components/ui/Label.tsx:12` - disabled state
+
+**Recommendations:**
+1. Darken to #767676 for 4.5:1 (minimum AA)
+2. Darken to #595959 for 7:1 (AAA compliant)
+3. Or change background to #F0F0F0 with #999999 = 3.3:1 (large text only)
+
+### ⚠️ #757575 on #FFFFFF (4.6:1)
+
+**Problem:** Passes AA but fails AAA
+**Used in:**
+- `app/components/shared/Caption.tsx:8` - 12px caption text
+
+**Note:** For 12px text, APCA recommends Lc ≥ 75. Current Lc is -63.1.
+**Recommendation:** Darken to #616161 for Lc -72 or increase font size to 14px+.
+```
+
+### 2. HTML Report (with --format html)
+
+Interactive HTML with:
+- Color swatches
+- Visual comparison
+- Filter by pass/fail
+- Sort by ratio
+- Export to CSV
+
+### 3. JSON Output (with --format json)
+
+```json
+{
+  "meta": {
+    "path": "./app/components",
+    "date": "2026-01-05T14:30:00Z",
+    "theme": "all"
+  },
+  "themes": [
+    {
+      "name": "light",
+      "pairs": [
+        {
+          "fg": "#212121",
+          "bg": "#FAFAFA",
+          "wcag_ratio": 16.1,
+          "wcag_aa": true,
+          "wcag_aaa": true,
+          "apca_lc": -92.4,
+          "apca_pass": true,
+          "usage": [...]
+        }
+      ],
+      "summary": {
+        "total": 156,
+        "aa_pass": 142,
+        "aaa_pass": 98,
+        "failures": 14
+      }
+    }
+  ]
+}
+```
+
+---
+
+## WCAG 2.2 + Reading Guide Alignment
+
+This task validates against the reading guide principles:
+
+| Rule | Contrast Requirement | This Task |
+|------|---------------------|-----------|
+| Rule 8 | Minimum 4.5:1 (WCAG AA) | ✓ Validates |
+| Rule 10 | Dark mode: avoid pure black/white | ✓ Detects 21:1 |
+| Rule 13 | Links distinguishable ≥3:1 from text | ✓ Validates link colors |
+| Accessibility | APCA for modern accuracy | ✓ Includes APCA Lc |
+
+**Special Checks:**
+- Dark mode halation detection (contrast > 18:1 flagged)
+- Link vs text color contrast (≥3:1 required)
+- Focus indicator contrast (≥3:1 vs background)
+- Placeholder text contrast (often fails)
+
+---
+
+## Integration
+
+```bash
+# Full matrix
+*contrast-matrix ./app/components
+
+# Light theme only, HTML output
+*contrast-matrix ./app/components --theme light --format html
+
+# Include design tokens
+*contrast-matrix ./app/components --include-tokens
+
+# As part of full audit
+*a11y-audit ./app/components --scope color
+# → Calls *contrast-matrix internally
+```
+
+---
+
+## State Update
+
+```yaml
+contrast_matrix:
+  last_run: "2026-01-05T14:30:00Z"
+  path: "./app/components"
+  themes_scanned: ["light", "dark"]
+  results:
+    total_pairs: 156
+    wcag_aa_pass: 142
+    wcag_aaa_pass: 98
+    apca_pass: 138
+    failures: 14
+    failure_rate: "9.0%"
+  critical_failures:
+    - fg: "#999999"
+      bg: "#FFFFFF"
+      ratio: 2.8
+      files: ["Input.tsx:45", "Label.tsx:12"]
+  next_action: "Fix 14 contrast failures"
+```
+
+---
+
+## Failure Handling
+
+- **Color extraction returns >1000 unique pairs:** Filter to high-frequency combinations (used >=5 times), group similar colors within ΔE <3, generate subset matrix with coverage threshold, provide full matrix as JSON export
+- **APCA calculation library unavailable or outdated:** Fallback to WCAG 2.2 ratios only, document APCA as recommended future enhancement, suggest apca-w3 npm package installation for next run
+- **Dynamic theme switching prevents color extraction:** Run matrix per theme separately, capture CSS variables per theme context, manually test theme switcher to extract computed values from DevTools, aggregate results by theme
+- **Contrast failures exceed remediation capacity (>100 failures):** Triage by component usage frequency and user-facing visibility, auto-generate fix suggestions for top 20 failures, provide batch color adjustment script for systematic fixes, schedule phased remediation
+
+## Success Criteria
+
+- [ ] All foreground/background color combinations extracted from codebase
+- [ ] WCAG 2.2 contrast ratios calculated for every combination
+- [ ] APCA Lc values calculated for every combination
+- [ ] Pass/fail indicators for AA, AAA, and APCA thresholds
+- [ ] Matrix output generated in requested format (table/html/json)
+- [ ] Failing combinations include remediation suggestions with closest passing color
+- [ ] Design token colors included when --include-tokens flag used
+
+---
+
+**Brad says:** "Contrast isn't subjective. Numbers don't lie. 4.5:1 or it fails."
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-accessibility-wcag-checklist.md`
+- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.