claude-code-workflow 7.2.26 → 7.2.28

package/.codex/skills/team-visual-a11y/roles/typo-auditor/role.md

@@ -0,0 +1,185 @@
+---
+role: typo-auditor
+prefix: TYPO
+inner_loop: false
+message_types: [state_update]
+---
+
+# Typography Readability Auditor
+
+Typography accessibility audit across all viewports. Font sizes at breakpoints, line-height ratios, clamp() validation, reading width measurement, font loading strategy assessment. Produce detailed typography report with breakpoint-by-breakpoint analysis.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Target (URL or file paths) | From task description CONTEXT | Yes |
+| WCAG level (AA/AAA) | From task description CONTEXT | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+
+1. Extract session path, target, and WCAG level from task description
+2. Identify target:
+   - URL -> use Chrome DevTools for rendered typography (navigate_page, resize_page, screenshot)
+   - File paths -> read CSS/SCSS files directly for typography definitions
+   - Full site -> enumerate stylesheets from HTML entry points
+3. Read typography standards from specs/typography-scale.md for reference thresholds
+
+## Phase 3: Typography Audit Execution
+
+### Step 1: Typography Definition Extraction
+
+**Static analysis** (always):
+- Glob for CSS/SCSS/Tailwind files -> extract typography definitions
+- Extract: font-family, font-size, line-height, letter-spacing, font-weight, font-display
+- Parse clamp() functions: `clamp(min, preferred, max)` -> validate min/max bounds
+- Parse @media queries for responsive breakpoints
+- Record source location (file:line) for each rule
+
+**Runtime analysis** (if Chrome DevTools available):
+- Navigate to target URL
+- For each breakpoint (320px, 768px, 1024px, 1400px):
+  - `mcp__chrome-devtools__resize_page({ width: <breakpoint>, height: 900 })`
+  - `mcp__chrome-devtools__evaluate_script({ expression: "..." })` to measure:
+    - Computed font-size on body, headings (h1-h6), paragraphs, captions
+    - Computed line-height on same elements
+    - Container width and character count per line
+  - `mcp__chrome-devtools__take_screenshot({})` -> save to `<session>/evidence/typo-{breakpoint}px.png`
+
+### Step 2: Font Size Audit
+
+| Breakpoint | Element | Minimum Size | Standard |
+|-----------|---------|-------------|----------|
+| 320px (mobile) | Body text | 16px | WCAG 1.4.4 |
+| 320px (mobile) | Small/caption | 14px | Best practice |
+| 768px (tablet) | Body text | 16px | WCAG 1.4.4 |
+| 1024px (desktop) | Body text | 16px | WCAG 1.4.4 |
+| 1400px (wide) | Body text | 16px | WCAG 1.4.4 |
+
+**clamp() validation**:
+- Minimum value >= 14px (absolute floor)
+- Maximum value reasonable for element type (headings: max ~72px, body: max ~20px)
+- Preferred value uses viewport unit (vw) for fluid scaling
+- Check: `clamp(min, preferred, max)` where min >= 14px for any text
+
+**200% zoom check** (WCAG 1.4.4):
+- At 200% zoom, no content should be clipped or lost
+- Text should reflow without horizontal scrolling
+
+### Step 3: Line Height Audit
+
+| Element Type | Expected Range | Standard |
+|-------------|---------------|----------|
+| Body text | 1.5 - 1.75 | WCAG 1.4.12, readability |
+| Headings | 1.1 - 1.3 | Visual impact |
+| Code blocks | 1.5 - 1.7 | Scanning readability |
+| Buttons/labels | 1.2 - 1.5 | UI element |
+
+Check for unitless line-height (preferred over px/em for inheritance).
+
+### Step 4: Letter Spacing Audit
+
+| Element Type | Expected Range | Standard |
+|-------------|---------------|----------|
+| Display headings | -0.02em to 0 | Tight for visual |
+| Body text | 0 (default) | Normal |
+| Uppercase labels | 0.05em - 0.1em | Legibility |
+| Monospace code | 0.08em - 0.15em | Wide for scanning |
+
+**WCAG 1.4.12 override test**: Text must remain readable when user overrides:
+- Line height to at least 1.5x font size
+- Letter spacing to at least 0.12em
+- Word spacing to at least 0.16em
+
+### Step 5: Reading Width Audit
+
+Measure characters per line for body text containers:
+
+| Metric | Optimal | Acceptable | Flag |
+|--------|---------|-----------|------|
+| Characters per line | 66ch | 45-75ch | < 45 or > 75 |
+| Max container width | 65ch-75ch | Up to 900px | > 900px without column |
+
+Check: `max-width` or `width` on body text containers.
+
+### Step 6: Font Loading Strategy
+
+| Property | Good | Acceptable | Poor |
+|----------|------|-----------|------|
+| Body font | `font-display: swap` | `font-display: fallback` | `font-display: block` or missing |
+| Display font | `font-display: optional` | `font-display: swap` | `font-display: block` |
+| Preload | Critical fonts preloaded | Some preloaded | None preloaded |
+| Fallback stack | System font fallback defined | Generic fallback | No fallback |
+
+Check for FOUT (Flash of Unstyled Text) / FOIT (Flash of Invisible Text) risks.
+
+## Phase 4: Report Generation & Output
+
+1. Write audit report to `<session>/audits/typography/typo-audit-{NNN}.md`:
+
+```markdown
+# Typography Accessibility Audit - {NNN}
+[typo-auditor]
+
+## Summary
+- **Total typography rules audited**: {count}
+- **Pass**: {pass_count} | **Fail**: {fail_count}
+- **WCAG Level**: {AA|AAA}
+- **Critical issues**: {count}
+- **High issues**: {count}
+
+## Font Size by Breakpoint
+| Breakpoint | Element | Computed Size | Min Required | Status |
+|-----------|---------|--------------|-------------|--------|
+| 320px | body | Xpx | 16px | PASS/FAIL |
+| 320px | h1 | Xpx | -- | OK |
+| ... | ... | ... | ... | ... |
+
+## clamp() Validation
+| Rule | clamp() Value | Min | Max | Status |
+|------|--------------|-----|-----|--------|
+| .body | clamp(1rem, 2vw, 1.25rem) | 16px | 20px | PASS/FAIL |
+| ... | ... | ... | ... | ... |
+
+## Line Height Audit
+| Element | Current | Expected Range | Status |
+|---------|---------|---------------|--------|
+| body | 1.6 | 1.5-1.75 | PASS |
+| h1 | 1.2 | 1.1-1.3 | PASS |
+| ... | ... | ... | ... |
+
+## Letter Spacing Audit
+| Element | Current | Expected Range | Status |
+|---------|---------|---------------|--------|
+| ... | ... | ... | ... |
+
+## Reading Width
+| Container | Width | Chars/Line | Optimal (45-75) | Status |
+|-----------|-------|-----------|-----------------|--------|
+| .content | 700px | ~68ch | Yes | PASS |
+| ... | ... | ... | ... | ... |
+
+## Font Loading
+| Font | font-display | Preload | Fallback | Status |
+|------|-------------|---------|----------|--------|
+| ... | swap | yes/no | system | PASS/FAIL |
+
+## Text Spacing Override Test (WCAG 1.4.12)
+| Override | Applied | Content Readable | Status |
+|---------|---------|-----------------|--------|
+| line-height: 1.5x | Yes | Yes/No | PASS/FAIL |
+| letter-spacing: 0.12em | Yes | Yes/No | PASS/FAIL |
+| word-spacing: 0.16em | Yes | Yes/No | PASS/FAIL |
+
+## Issues (by severity)
+### Critical
+- ...
+### High
+- ...
+### Medium
+- ...
+```
+
+2. Update `<session>/.msg/meta.json` under `typo-auditor` namespace:
+   - Read existing -> merge `{ "typo-auditor": { audit_id, total_rules, pass_count, fail_count, critical_count, high_count, breakpoints_tested, timestamp } }` -> write back

package/.codex/skills/team-visual-a11y/specs/focus-patterns.md

@@ -0,0 +1,325 @@
+# Focus Management Patterns
+
+Reference guide for focus indicator styles, skip links, focus traps, and ARIA patterns. Used by focus-auditor and fix-implementer roles.
+
+## Focus Indicator Style
+
+### Recommended Pattern
+
+```css
+/* Keyboard focus: visible outline */
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}
+
+/* Mouse click: no outline */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+### Requirements
+
+| Property | Minimum | Rationale |
+|----------|---------|-----------|
+| outline-width | 2px | Visibility at distance |
+| outline-style | solid | Consistent rendering |
+| outline-offset | 2px | Separation from element edge |
+| Contrast vs adjacent | >= 3:1 | WCAG 2.4.11 |
+
+### Anti-Patterns (Do NOT)
+
+```css
+/* BAD: Removes all focus indicators */
+*:focus { outline: none; }
+
+/* BAD: Removes focus without alternative */
+button:focus { outline: 0; }
+
+/* BAD: Only uses box-shadow (invisible in high contrast mode) */
+:focus-visible { outline: none; box-shadow: 0 0 0 2px blue; }
+```
+
+### Correct Alternative Indicator
+
+```css
+/* If not using outline, MUST provide visible alternative */
+:focus-visible {
+  outline: 2px solid transparent; /* For Windows high contrast mode */
+  box-shadow: 0 0 0 2px var(--color-accent);
+}
+```
+
+## Skip Link
+
+### HTML
+
+```html
+<body>
+  <a href="#main" class="skip-link">Skip to main content</a>
+  <!-- navigation, header, etc. -->
+  <main id="main" tabindex="-1">
+    <!-- main content -->
+  </main>
+</body>
+```
+
+### CSS
+
+```css
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  top: auto;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  z-index: -1;
+}
+
+.skip-link:focus {
+  position: fixed;
+  left: 16px;
+  top: 16px;
+  width: auto;
+  height: auto;
+  overflow: visible;
+  z-index: 9999;
+  background: var(--color-paper, #fff);
+  color: var(--color-ink, #000);
+  padding: 8px 16px;
+  border: 2px solid var(--color-ink, #000);
+  border-radius: 4px;
+  font-size: 1rem;
+  text-decoration: underline;
+}
+```
+
+### Requirements
+
+| Check | Requirement |
+|-------|-------------|
+| Position | First focusable element in DOM |
+| Default state | Visually hidden (not display:none or visibility:hidden) |
+| Focus state | Visible, fixed position, high z-index |
+| Target | Points to main content area with valid ID |
+| Contrast | Link text meets 4.5:1 contrast against background |
+
+## Focus Trap (Modals/Dialogs)
+
+### Implementation Pattern
+
+```javascript
+function trapFocus(dialog) {
+  const focusableSelector = [
+    'a[href]', 'button:not([disabled])', 'input:not([disabled])',
+    'select:not([disabled])', 'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])'
+  ].join(', ');
+
+  const focusableElements = dialog.querySelectorAll(focusableSelector);
+  const firstFocusable = focusableElements[0];
+  const lastFocusable = focusableElements[focusableElements.length - 1];
+
+  // Store trigger for focus restore
+  const trigger = document.activeElement;
+
+  // Move focus to first element
+  firstFocusable.focus();
+
+  dialog.addEventListener('keydown', function(e) {
+    if (e.key === 'Escape') {
+      closeDialog(dialog);
+      trigger.focus(); // Restore focus
+      return;
+    }
+
+    if (e.key !== 'Tab') return;
+
+    if (e.shiftKey) {
+      // Shift+Tab at first element -> wrap to last
+      if (document.activeElement === firstFocusable) {
+        e.preventDefault();
+        lastFocusable.focus();
+      }
+    } else {
+      // Tab at last element -> wrap to first
+      if (document.activeElement === lastFocusable) {
+        e.preventDefault();
+        firstFocusable.focus();
+      }
+    }
+  });
+}
+```
+
+### Dialog HTML Pattern
+
+```html
+<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Dialog Title</h2>
+  <div class="dialog-content">
+    <!-- content -->
+  </div>
+  <div class="dialog-actions">
+    <button type="button">Cancel</button>
+    <button type="button">Confirm</button>
+  </div>
+</div>
+```
+
+### Requirements
+
+| Step | Action | Detail |
+|------|--------|--------|
+| Open | Store trigger | `const trigger = document.activeElement` |
+| Open | Move focus | Focus first focusable element in dialog |
+| Open | Lock background | `document.body.style.overflow = 'hidden'` or `inert` attribute |
+| Open | Set ARIA | `aria-modal="true"` on dialog |
+| Tab | Cycle within | Tab/Shift+Tab wrap within dialog focusable elements |
+| Escape | Close + restore | Close dialog, restore focus to trigger |
+| Close | Unlock background | Remove scroll lock / inert |
+
+## ARIA Patterns
+
+### Button Patterns
+
+```html
+<!-- Standard button -->
+<button type="button">Save</button>
+
+<!-- Icon-only button (needs aria-label) -->
+<button type="button" aria-label="Close dialog">
+  <svg><!-- X icon --></svg>
+</button>
+
+<!-- Toggle button -->
+<button type="button" aria-pressed="false">Bold</button>
+
+<!-- Disclosure button -->
+<button type="button" aria-expanded="false" aria-controls="panel-1">
+  Show details
+</button>
+<div id="panel-1" hidden>Details content</div>
+```
+
+### Dialog Pattern
+
+```html
+<div role="dialog" aria-modal="true" aria-labelledby="dlg-title" aria-describedby="dlg-desc">
+  <h2 id="dlg-title">Confirm Action</h2>
+  <p id="dlg-desc">Are you sure you want to proceed?</p>
+  <button type="button">Cancel</button>
+  <button type="button">Confirm</button>
+</div>
+```
+
+### Live Region Patterns
+
+```html
+<!-- Status updates (polite) -->
+<div role="status" aria-live="polite">
+  3 items in cart
+</div>
+
+<!-- Error messages (assertive) -->
+<div role="alert" aria-live="assertive">
+  Email address is invalid
+</div>
+
+<!-- Log/chat (polite, additions only) -->
+<div role="log" aria-live="polite" aria-relevant="additions">
+  <!-- new messages appended here -->
+</div>
+```
+
+### Navigation Pattern
+
+```html
+<!-- Primary navigation -->
+<nav aria-label="Primary">
+  <ul role="menubar">
+    <li role="none"><a role="menuitem" href="/">Home</a></li>
+    <li role="none"><a role="menuitem" href="/about">About</a></li>
+  </ul>
+</nav>
+
+<!-- Breadcrumb -->
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/products">Products</a></li>
+    <li aria-current="page">Widget</li>
+  </ol>
+</nav>
+```
+
+### Tab Pattern
+
+```html
+<div role="tablist" aria-label="Settings">
+  <button role="tab" aria-selected="true" aria-controls="panel-general" id="tab-general">
+    General
+  </button>
+  <button role="tab" aria-selected="false" aria-controls="panel-security" id="tab-security" tabindex="-1">
+    Security
+  </button>
+</div>
+<div role="tabpanel" id="panel-general" aria-labelledby="tab-general">
+  General settings content
+</div>
+<div role="tabpanel" id="panel-security" aria-labelledby="tab-security" hidden>
+  Security settings content
+</div>
+```
+
+**Keyboard**: Arrow Left/Right to switch tabs, Tab to move into panel content.
+
+### Form Error Pattern
+
+```html
+<label for="email">Email</label>
+<input
+  type="email"
+  id="email"
+  aria-required="true"
+  aria-invalid="true"
+  aria-describedby="email-error"
+>
+<div id="email-error" role="alert">
+  Please enter a valid email address
+</div>
+```
+
+## Keyboard Navigation Reference
+
+| Component | Key | Action |
+|-----------|-----|--------|
+| Link | Enter | Activate |
+| Button | Enter, Space | Activate |
+| Checkbox | Space | Toggle |
+| Radio group | Arrow Up/Down | Select previous/next |
+| Tab list | Arrow Left/Right | Switch tab |
+| Menu | Arrow Up/Down | Navigate items |
+| Menu | Enter | Select item |
+| Menu | Escape | Close menu |
+| Dialog | Escape | Close dialog |
+| Slider | Arrow Left/Right | Decrease/increase |
+| Combobox | Arrow Down | Open dropdown |
+| Combobox | Enter | Select highlighted |
+| Combobox | Escape | Close dropdown |
+| Tree | Arrow Up/Down | Navigate siblings |
+| Tree | Arrow Right | Expand / enter child |
+| Tree | Arrow Left | Collapse / go to parent |
+
+## Target Size Reference
+
+| Standard | Minimum Size | Notes |
+|----------|-------------|-------|
+| WCAG 2.5.8 (AA) | 24x24px CSS pixels | Or adequate spacing between targets |
+| WCAG 2.5.5 (AAA) | 44x44px CSS pixels | Recommended for touch interfaces |
+| Apple HIG | 44x44pt | iOS touch targets |
+| Material Design | 48x48dp | Android touch targets |
+
+**Exceptions**: Inline links within text, browser default controls, essential fixed-size elements.

package/.codex/skills/team-visual-a11y/specs/oklch-standards.md

@@ -0,0 +1,130 @@
+# OKLCH Color Accessibility Standards
+
+Reference guide for OKLCH-based perceptual color analysis. Used by color-auditor and fix-implementer roles.
+
+## OKLCH Basics
+
+```
+oklch(Lightness% Chroma Hue)
+```
+
+- **Lightness (L)**: 0% (black) to 100% (white) -- perceptually uniform
+- **Chroma (C)**: 0 (achromatic/gray) to ~0.37 (maximum saturation) -- perceptual colorfulness
+- **Hue (H)**: 0-360 degrees -- color wheel angle
+
+OKLCH is perceptually uniform: equal numeric changes produce equal perceived changes, unlike HSL/RGB.
+
+## Lightness Guidelines
+
+| Element | L Range | Rationale |
+|---------|---------|-----------|
+| Dark text on light background | L <= 40% | Ensures sufficient contrast against light surfaces |
+| Light background for text | L >= 90% | Provides clean reading surface |
+| Accent colors (interactive) | L 50-65% | Vibrant but readable |
+| Disabled/muted elements | L 55-70% | Intentionally reduced contrast (with care) |
+| Dark mode text | L >= 85% | Light text on dark background |
+| Dark mode background | L <= 20% | Dark surface for light text |
+
+## Chroma Guidelines
+
+| Use Case | C Range | Notes |
+|----------|---------|-------|
+| Neutral/text colors | C = 0 | Pure achromatic for maximum readability |
+| Subtle warm/cool tint | C = 0.005-0.02 | Adds warmth without color distraction |
+| Standard accent | C = 0.1-0.15 | Good balance of color and readability |
+| Vibrant accent | C = 0.2-0.25 | Use sparingly, max 1-2 per palette |
+| Maximum saturation | C > 0.25 | Avoid for text; OK for decorative only |
+
+## Impeccable Palette Reference
+
+```css
+/* Neutrals */
+--color-ink:       oklch(10% 0 0);      /* Primary text */
+--color-paper:     oklch(98% 0 0);      /* Primary background */
+--color-cream:     oklch(96% 0.005 350); /* Warm background variant */
+--color-charcoal:  oklch(25% 0 0);      /* Secondary text */
+--color-ash:       oklch(55% 0 0);      /* Muted/disabled text */
+--color-mist:      oklch(92% 0 0);      /* Border/divider */
+
+/* Accent */
+--color-accent:       oklch(60% 0.25 350); /* Primary action */
+--color-accent-hover: oklch(52% 0.25 350); /* Hover state (darker) */
+```
+
+### Palette Analysis
+
+| Name | L | C | H | Role | Contrast vs paper (98%) |
+|------|---|---|---|------|------------------------|
+| ink | 10% | 0 | 0 | Body text | ~15.4:1 (AAA) |
+| charcoal | 25% | 0 | 0 | Secondary text | ~9.5:1 (AAA) |
+| ash | 55% | 0 | 0 | Muted text | ~3.8:1 (AA large only) |
+| accent | 60% | 0.25 | 350 | Interactive | ~3.4:1 (large text / non-text only) |
+| accent-hover | 52% | 0.25 | 350 | Hover state | ~4.6:1 (AA) |
+
+## Contrast Verification Methods
+
+### WCAG 2.1 Contrast Ratio
+
+Formula: `(L1 + 0.05) / (L2 + 0.05)` where L1, L2 are relative luminances (L1 > L2).
+
+Convert OKLCH -> sRGB -> linear RGB -> relative luminance:
+`L_rel = 0.2126 * R_linear + 0.7152 * G_linear + 0.0722 * B_linear`
+
+| Text Type | AA | AAA |
+|-----------|-----|-----|
+| Normal text (< 18pt / < 14pt bold) | >= 4.5:1 | >= 7:1 |
+| Large text (>= 18pt / >= 14pt bold) | >= 3:1 | >= 4.5:1 |
+| Non-text (UI components, icons) | >= 3:1 | >= 3:1 |
+
+### APCA Contrast (Advanced)
+
+APCA (Accessible Perceptual Contrast Algorithm) uses OKLCH lightness for perceptual accuracy.
+
+Lc (Lightness contrast) values:
+
+| Use Case | Minimum Lc | Description |
+|----------|-----------|-------------|
+| Body text (14-16px) | >= 75 | Primary reading content |
+| Content text (18px) | >= 60 | Secondary content |
+| Large text (24px+) | >= 45 | Headings, display |
+| Non-text elements | >= 30 | Icons, borders, focus indicators |
+| Placeholder/disabled | >= 15 | Intentionally muted |
+
+### Focus Indicator Contrast
+
+Focus indicators must have >= 3:1 contrast against adjacent colors:
+- Outline color vs element background
+- Outline color vs surrounding page background
+- Both must pass
+
+## Color Blindness Reference
+
+### Confusion Lines
+
+| Type | Prevalence | Confuses | Safe Alternatives |
+|------|-----------|----------|-------------------|
+| Protanopia (red-blind) | ~1% male | Red/green, red/brown | Use blue/orange, add patterns |
+| Deuteranopia (green-blind) | ~5% male | Green/red, green/brown | Use blue/orange, add patterns |
+| Tritanopia (blue-blind) | ~0.01% | Blue/yellow | Use red/green pairs (opposite) |
+| Achromatopsia (no color) | ~0.003% | All chromatic | Rely on lightness difference only |
+
+### Safe Color Pairs
+
+Always ensure information is not conveyed by color alone. Safe strategies:
+- Use lightness difference (>= 40% L difference)
+- Add text labels, icons, or patterns alongside color
+- Use blue + orange (safe for most color blindness types)
+- Avoid red-only or green-only indicators
+
+## Dark Mode Color Mapping
+
+When converting light mode to dark mode:
+
+| Light Mode | Dark Mode | Rule |
+|-----------|----------|------|
+| Text L <= 40% | Text L >= 85% | Invert lightness range |
+| Background L >= 90% | Background L <= 20% | Invert lightness range |
+| Accent L 50-65% | Accent L 60-75% | Slight lightness increase |
+| Border L ~92% | Border L ~25% | Invert proportionally |
+
+Maintain same hue and similar chroma; adjust lightness to preserve contrast ratios.