claude-code-workflow 7.2.27 → 7.2.28

package/.codex/skills/team-ui-polish/specs/fix-strategies.md

@@ -0,0 +1,235 @@
+# Fix Strategies
+
+Maps issue categories to Impeccable fix strategies. Used by diagnostician for fix planning and optimizer for implementation guidance.
+
+## Strategy Index
+
+| Issue Category | Fix Strategy | Impeccable Concept | Scope |
+|----------------|-------------|-------------------|-------|
+| AI slop aesthetic | De-template | normalize + critique | Systemic |
+| Color problems | Colorize | colorize | Systemic / Per-file |
+| Typography issues | Typeset | typeset | Systemic |
+| Spacing/layout | Arrange | arrange | Systemic / Per-file |
+| Animation issues | Animate | animate | Per-file |
+| Missing states | Harden | harden + polish | Per-component |
+| Visual noise | Simplify | quieter + distill | Per-component |
+| Too bland/weak | Strengthen | bolder + delight | Per-component |
+| Inconsistency | Normalize | normalize | Systemic |
+| Final pass | Polish | polish | Per-component |
+| Hierarchy issues | Clarify | distill + bolder | Per-page |
+| Responsive issues | Adapt | adapt | Per-component |
+
+---
+
+## De-template (Anti-AI-Slop)
+
+**When**: Anti-patterns dimension score 0-2 (AI slop or heavy AI influence)
+
+**Strategy**:
+1. Replace generic fonts with distinctive alternatives (see design-standards.md Typography)
+2. Convert gradient text to solid accent colors with weight/size emphasis instead
+3. Break identical card grids: vary sizes, add featured card, introduce asymmetry
+4. Remove decorative glassmorphism (keep functional like overlays)
+5. Redesign hero metrics with intentional hierarchy, not template layout
+6. Flatten nested cards into single-level with spacing
+7. Add left-alignment for body text, centering only for specific hero elements
+8. Create button hierarchy: 1 primary, ghost secondary, text tertiary
+9. Introduce spacing rhythm (tight within groups, generous between sections)
+10. Replace bounce easing with exponential curves
+
+**Dependency**: Requires Colorize and Typeset to be planned (often executed together).
+
+---
+
+## Colorize
+
+**When**: Color dimension score 0-2 or any P0/P1 color issues
+
+**Strategy**:
+1. **Token foundation** (if no tokens exist):
+   - Create CSS custom property file with full neutral scale (50-950)
+   - Define primary, semantic (success/warning/error/info), and surface tokens
+   - All neutrals tinted toward brand hue (OKLCH chroma 0.005-0.01)
+
+2. **Pure black/white removal**:
+   - `#000` -> `oklch(0.08-0.15 0.01 <hue>)` (near-black, brand tinted)
+   - `#fff` -> `oklch(0.97-0.99 0.005 <hue>)` (near-white, brand tinted)
+
+3. **Gray tinting**:
+   - Convert all pure grays to brand-tinted variants
+   - Add chroma 0.005-0.01 at brand hue
+
+4. **Contrast fixes**:
+   - Measure each text/background pair
+   - Adjust lightness until WCAG AA met (4.5:1 normal, 3:1 large)
+
+5. **OKLCH conversion**:
+   - Convert key palette colors from hex/hsl to oklch
+   - Generate tint/shade scales in OKLCH for perceptual uniformity
+
+6. **60-30-10 enforcement**:
+   - Audit accent color usage, reduce to ~10%
+   - Ensure neutral dominates at ~60%
+
+**Dependency**: Should run before De-template (anti-slop fixes may need new colors).
+
+---
+
+## Typeset
+
+**When**: Typography dimension score 0-2 or muddy hierarchy
+
+**Strategy**:
+1. **Font replacement**: Swap generic fonts for distinctive alternatives
+   - Body: Plus Jakarta Sans, Instrument Sans, DM Sans, Geist
+   - Display: Space Grotesk, Manrope, Fraunces
+2. **Scale establishment**: Choose modular ratio (1.25 or 1.333 recommended), generate size scale
+3. **Fluid sizing**: Add `clamp()` for h1-h3 display sizes
+4. **Line length**: Add `max-width: 65ch` to prose containers
+5. **Vertical rhythm**: Set line-height system (1.5 body, 1.2 headings)
+6. **Font loading**: Add `font-display: swap` to all @font-face
+
+**Dependency**: Run before Clarify (hierarchy depends on type scale).
+
+---
+
+## Arrange
+
+**When**: Spacing dimension score 0-2 or arbitrary spacing values
+
+**Strategy**:
+1. **Scale creation**: Define 4pt base scale as CSS custom properties
+2. **Value replacement**: Map arbitrary values to nearest scale value
+3. **Rhythm introduction**: Tight (4-8px) within groups, comfortable (16-24px) between items, generous (48-96px) between sections
+4. **Card flattening**: Remove nested cards, replace with spacing + subtle dividers
+5. **Gap conversion**: Replace margin between siblings with gap on flex/grid parent
+6. **Touch targets**: Ensure all interactive elements are 44x44px minimum
+
+**Dependency**: Independent, but benefits from Colorize tokens being in place.
+
+---
+
+## Animate
+
+**When**: Motion dimension score 0-2 or layout property animations
+
+**Strategy**:
+1. **Property fix**: Replace layout animations (width/height/margin/padding) with transform+opacity
+2. **Easing fix**: Replace ease/linear/bounce with exponential curves
+3. **Reduced-motion**: Add `@media (prefers-reduced-motion: reduce)` global rule
+4. **Token system**: Create duration + easing custom properties
+5. **Stagger cap**: Cap stagger at 10 items, 500ms total
+6. **will-change**: Remove from CSS, document JS activation pattern
+
+**Dependency**: Independent.
+
+---
+
+## Harden
+
+**When**: Interaction states dimension score 0-2 or missing critical states
+
+**Strategy**:
+1. **Hover**: Add `:hover` with subtle visual change, wrap in `@media(hover:hover)`
+2. **Focus**: Add `:focus-visible` with 2px solid accent ring, offset 2px
+3. **Active**: Add `:active` with scale(0.97) or darker background
+4. **Disabled**: Add `[disabled]` with opacity 0.5, cursor not-allowed
+5. **Loading**: Add aria-busy pattern with spinner/skeleton
+6. **Error/Success**: Add form validation visual states
+7. **Focus ring**: Ensure 3:1 contrast against all adjacent colors
+8. **Labels**: Replace placeholder-as-label with visible `<label>` elements
+9. **Touch targets**: Pad interactive elements to 44px minimum
+
+**Dependency**: Requires Colorize tokens for consistent state colors.
+
+---
+
+## Simplify (quieter + distill)
+
+**When**: Visual noise, too many decorations, competing elements
+
+**Strategy**:
+1. Remove decorative elements that do not aid comprehension
+2. Mute icon colors (reduce saturation/opacity)
+3. Remove background decorations and unnecessary borders
+4. Reduce shadow intensity
+5. Simplify card borders (remove or lighten)
+6. Remove sparkline decorations without data value
+
+**Dependency**: Independent.
+
+---
+
+## Strengthen (bolder + delight)
+
+**When**: Too bland, everything same weight, no emphasis
+
+**Strategy**:
+1. Increase primary element size by 1.5-2x
+2. Add color saturation to primary CTA
+3. Increase weight contrast (bold primary, regular secondary)
+4. Add subtle micro-interactions (hover lift, active press)
+5. Introduce one distinctive element (asymmetric layout, unexpected color, custom illustration)
+
+**Dependency**: Requires Typeset and Colorize to be in place.
+
+---
+
+## Clarify (hierarchy)
+
+**When**: Visual hierarchy dimension score 0-2 or fails squint test
+
+**Strategy**:
+1. Identify primary element, increase to 3:1 ratio over body
+2. Use 2-3 hierarchy tools together (size + weight + color)
+3. Group related content with proximity (smaller gaps within, larger between)
+4. Reduce visual weight of competing secondary elements
+5. Ensure only 1 primary CTA per viewport
+6. Add progressive disclosure where appropriate
+
+**Dependency**: Requires Typeset (size hierarchy) and Colorize (color hierarchy).
+
+---
+
+## Adapt (responsive)
+
+**When**: Responsive dimension score 0-2 or broken mobile experience
+
+**Strategy**:
+1. Replace fixed widths with fluid (%, vw, fr, min/max/clamp)
+2. Add missing breakpoints (640, 768, 1024, 1280px)
+3. Fix overflow (horizontal scroll causes)
+4. Fix mobile text sizes (minimum 14px)
+5. Fix touch targets (minimum 44px)
+6. Add container queries for component-level responsive
+7. Restructure hidden content (adapt, don't hide)
+8. Add viewport meta tag if missing
+
+**Dependency**: Run last -- tests all other fixes at different viewports.
+
+---
+
+## Fix Order (Default)
+
+When applying all strategies in a full polish cycle:
+
+```
+Phase 1: Foundation
+  1. Colorize (token system + color fixes)
+  2. Typeset (font + scale + fluid sizing)
+  3. Arrange (spacing scale + layout)
+
+Phase 2: Aesthetic
+  4. De-template (anti-AI-slop cleanup)
+  5. Simplify or Strengthen (as needed)
+
+Phase 3: Interaction
+  6. Animate (motion system)
+  7. Harden (interaction states)
+
+Phase 4: Structure
+  8. Clarify (visual hierarchy)
+
+Phase 5: Validation
+  9. Adapt (responsive -- tests everything)
+```

package/.codex/skills/team-ui-polish/specs/pipelines.md

@@ -0,0 +1,81 @@
+# Pipeline Definitions
+
+UI polish pipeline modes and task registry.
+
+## Pipeline Modes
+
+| Mode | Description | Task Count |
+|------|-------------|------------|
+| scan-only | Discover + diagnose, report only | 2 tasks |
+| targeted | Fix specific dimensions: scan -> diagnose -> optimize -> verify | 4 tasks |
+| full | Complete polish cycle with GC loop on verify failure | 4 tasks + GC |
+
+## Scan-Only Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| SCAN-001 | scanner | [] | 8-dimension UI audit against Impeccable design standards |
+| DIAG-001 | diagnostician | [SCAN-001] | Root cause analysis, severity classification, fix dependency graph |
+
+## Targeted Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| SCAN-001 | scanner | [] | 8-dimension UI audit (filtered to target dimensions) |
+| DIAG-001 | diagnostician | [SCAN-001] | Root cause analysis for targeted dimensions |
+| OPT-001 | optimizer | [DIAG-001] | Apply targeted fixes per Impeccable standards |
+| VERIFY-001 | verifier | [OPT-001] | Before/after comparison, regression check |
+
+## Full Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| SCAN-001 | scanner | [] | Full 8-dimension UI audit |
+| DIAG-001 | diagnostician | [SCAN-001] | Complete root cause analysis with fix dependency graph |
+| OPT-001 | optimizer | [DIAG-001] | Apply all fixes in dependency order |
+| VERIFY-001 | verifier | [OPT-001] | Verification with GC loop trigger |
+
+## GC Loop (Full Mode Only)
+
+| Checkpoint | Task | Condition | Action |
+|------------|------|-----------|--------|
+| VERIFY completes | VERIFY-* | verify_passed (no regressions, score >= before) | Pipeline complete |
+| VERIFY completes | VERIFY-* | verify_failed (non-critical regressions) | gc_rounds < 2 -> create OPT-fix task |
+| VERIFY completes | VERIFY-* | fix_required (critical regressions or score drop) | gc_rounds < 2 -> create OPT-fix task (CRITICAL) |
+| VERIFY completes | VERIFY-* | gc_rounds >= 2 | Escalate to user |
+
+### GC Fix Tasks (dynamically created)
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| OPT-fix-1 | optimizer | [VERIFY-001] | Fix regressions from round 1 verification |
+| VERIFY-002 | verifier | [OPT-fix-1] | Re-verify after round 1 fixes |
+| OPT-fix-2 | optimizer | [VERIFY-002] | Fix regressions from round 2 verification (if needed) |
+| VERIFY-003 | verifier | [OPT-fix-2] | Final re-verify (max round) |
+
+## Collaboration Patterns
+
+| Pattern | Roles | Description |
+|---------|-------|-------------|
+| CP-1 Linear Pipeline | All | Base sequential flow: scan -> diagnose -> optimize -> verify |
+| CP-2 Review-Fix (GC) | optimizer <-> verifier | Generator-Critic loop, max 2 rounds |
+
+## Spawn Rules
+
+| Mode | Behavior |
+|------|----------|
+| scan-only | Sequential: SCAN-001 then DIAG-001 |
+| targeted | Sequential: SCAN -> DIAG -> OPT -> VERIFY |
+| full | Sequential: SCAN -> DIAG -> OPT -> VERIFY, then GC loop if verify triggers |
+
+All modes use sequential spawning (one task at a time) since each task depends on the previous.
+
+## Output Artifacts
+
+| Task | Output Path |
+|------|-------------|
+| SCAN-001 | <session>/scan/scan-report.md |
+| DIAG-001 | <session>/diagnosis/diagnosis-report.md |
+| OPT-001 / OPT-fix-* | <session>/optimization/fix-log.md + modified source files |
+| VERIFY-001 / VERIFY-* | <session>/verification/verify-report.md |
+| Screenshots (if DevTools) | <session>/evidence/*.png |

package/.codex/skills/team-ui-polish/specs/scoring-guide.md

@@ -0,0 +1,162 @@
+# Scoring Guide
+
+How to score each dimension consistently. Used by scanner for initial audit and verifier for re-assessment.
+
+## Rating Bands (Total Score out of 36)
+
+| Range | Rating | Description |
+|-------|--------|-------------|
+| 32-36 | Excellent | Distinctive, intentional design. Minimal or zero issues |
+| 25-31 | Good | Solid design with minor polish opportunities |
+| 18-24 | Acceptable | Functional but significant design work needed |
+| 11-17 | Poor | Major overhaul required across multiple dimensions |
+| 0-10 | Critical | AI slop gallery or fundamentally broken design |
+
+## Per-Dimension Scoring (0-4)
+
+### General Rubric
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Completely failing. Multiple major violations. Fundamental problems |
+| 1 | Major gaps. 3-4 violations. Some effort but insufficient |
+| 2 | Partial effort. 1-2 noticeable issues. Functional but not good |
+| 3 | Mostly clean. Subtle issues only. Good with minor polish needed |
+| 4 | Excellent. Genuinely distinctive/intentional. Meets all standards |
+
+### Dimension 1: Anti-AI-Slop Detection
+
+| Score | Criteria |
+|-------|----------|
+| 0 | 5+ AI slop tells present. Looks immediately AI-generated |
+| 1 | 3-4 AI slop tells. Heavy AI influence obvious |
+| 2 | 1-2 noticeable AI tells. Some templated elements |
+| 3 | Subtle traces only. Mostly intentional design choices |
+| 4 | Zero AI tells. Genuinely distinctive aesthetic. Would never guess AI-made |
+
+### Dimension 2: Color Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Multiple WCAG AA failures, pure black/white everywhere, hard-coded colors, no system |
+| 1 | Some contrast issues, hard-coded colors, no token system, pure grays |
+| 2 | Basic contrast OK, some OKLCH or tokens, but gaps (untinted grays, missing semantic colors) |
+| 3 | Good color system with minor gaps (a few hard-coded values, imperfect 60-30-10) |
+| 4 | OKLCH-based, fully tokenized, WCAG AA+ compliant, proper 60-30-10, semantic roles defined |
+
+### Dimension 3: Typography Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Generic font, no scale, body text <16px, no hierarchy |
+| 1 | Overused font, muddy sizes (many close values), missing fluid sizing |
+| 2 | Decent font choice but inconsistent scale or line-height issues |
+| 3 | Good typography with minor gaps (missing clamp, slight rhythm inconsistencies) |
+| 4 | Distinctive font, clear modular scale, fluid sizing, proper vertical rhythm, max-width on prose |
+
+### Dimension 4: Spacing & Layout Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Random spacing, nested cards, fixed widths, tiny touch targets |
+| 1 | Some spacing pattern but many arbitrary values, cards overused |
+| 2 | Decent spacing but monotonous rhythm or occasional arbitrary values |
+| 3 | Good spacing system with minor gaps (occasional non-scale value, mostly gap usage) |
+| 4 | Consistent scale, varied rhythm, gap for siblings, proper touch targets, no card nesting |
+
+### Dimension 5: Motion & Animation Quality
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Layout animations, no reduced-motion, bounce easing, no system |
+| 1 | Some transform-based but bad easing, missing reduced-motion |
+| 2 | Decent animations but no token system or still missing reduced-motion |
+| 3 | Good system with minor gaps (occasional ease default, missing exit animation) |
+| 4 | Transform+opacity only, exponential easing, reduced-motion query, duration tokens, proper stagger |
+
+### Dimension 6: Interaction States
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No hover, no focus, outline:none without replacement, no loading states |
+| 1 | Basic hover but missing focus/active on many elements, no loading states |
+| 2 | Hover + focus exist but no focus-visible, missing some states (disabled, error, empty) |
+| 3 | Most states present with minor gaps (imperfect focus ring, missing empty state) |
+| 4 | All 8 states implemented, focus-visible, proper focus ring, loading/error/success/empty states |
+
+### Dimension 7: Visual Hierarchy
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Everything same visual weight, no clear primary action, fails squint test completely |
+| 1 | Some size differences but no clear hierarchy system, multiple competing primary actions |
+| 2 | Basic hierarchy via size but missing weight/color/space dimensions |
+| 3 | Good hierarchy with minor issues (occasional visual competition, could be stronger) |
+| 4 | Clear squint test pass, obvious primary action, multi-dimension hierarchy, progressive disclosure |
+
+### Dimension 8: Responsive Design
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No responsive design, horizontal scroll, completely broken on mobile |
+| 1 | Basic media queries but many breakage points, some fixed widths |
+| 2 | Decent mobile but some fixed widths, small targets, or missing breakpoints |
+| 3 | Good responsive with minor issues (missing container queries, occasional small target) |
+| 4 | Fluid design, proper breakpoints, container queries, 44px targets, no overflow, adapted content |
+
+### Dimension 9: Cognitive Load & UX Writing
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Information overload everywhere, no grouping, generic labels, useless error messages |
+| 1 | Some grouping but >7 data groups visible, many generic labels, errors without fix guidance |
+| 2 | Decent grouping but missing progressive disclosure, some generic buttons, partial error messages |
+| 3 | Good information architecture with minor issues (occasional generic label, one missing empty state) |
+| 4 | Clear progressive disclosure, verb+object labels, what+why+fix errors, guided empty states, proper grouping |
+
+### Dimension 10: Dark Mode Quality (Conditional)
+
+Only scored if dark mode exists. If no dark mode, this dimension is excluded from total.
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Pure black bg, no surface hierarchy, saturated colors vibrating, dangerous combos |
+| 1 | Some dark surfaces but flat (same lightness), still using light-mode font weights |
+| 2 | Basic surface hierarchy but still saturated accents or missing font weight reduction |
+| 3 | Good dark mode with minor issues (occasional pure black, one dangerous combo) |
+| 4 | Proper surface hierarchy (lighter=higher), desaturated accents, reduced font weights, tinted dark bg |
+
+When dark mode exists: total out of 40, bands shift +4. When no dark mode: total out of 36.
+
+---
+
+## Severity Mapping
+
+| Severity | Definition | Score Correlation | Action |
+|----------|-----------|-------------------|--------|
+| P0 Blocking | Prevents use or violates law/standard. WCAG AA failure, missing focus, horizontal scroll on mobile, no viewport meta | Any dimension at 0 | Fix immediately, blocks release |
+| P1 Major | Significant UX harm or near-violation. Pure black/white, missing hover, all buttons primary, muddy hierarchy | Any dimension at 1 | Fix before release |
+| P2 Minor | Annoyance with workaround. No OKLCH, overused fonts, monotonous spacing, no container queries | Any dimension at 2 | Fix in next polish pass |
+| P3 Polish | Nice-to-fix, minimal user impact. Missing exit animation, optical adjustments, font fallback metrics | Dimension at 3 with minor issues | Fix when convenient |
+
+---
+
+## Scoring Process
+
+1. For each dimension, go through every checklist item in the scanner audit
+2. Count the number and severity of violations found
+3. Apply the dimension-specific rubric to assign 0-4
+4. Sum all 8 dimensions for total (0-32)
+5. Apply rating band
+
+### Tie-Breaking Rules
+- If between two scores, the presence of any P0 issue in that dimension rounds down
+- If between two scores with no P0, consider the count of P1 issues
+- When in doubt, score lower (conservative) -- it is better to fix something unnecessary than miss something important
+
+### Verification Scoring
+When verifier re-scores after optimization:
+- Use identical checklist and rubric as original scan
+- Score independently (do not adjust based on "how much improved")
+- Report both absolute score and delta from original
+- Flag any dimension where score decreased (regression)

package/.codex/skills/team-ui-polish/specs/team-config.json

@@ -0,0 +1,73 @@
+{
+  "team_name": "ui-polish",
+  "team_display_name": "UI Polish",
+  "description": "Auto-discover and fix UI design issues using Impeccable design standards",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Pipeline orchestration, scope assessment, GC loop management",
+      "message_types": ["task_unblocked", "gc_checkpoint", "fix_required", "error", "shutdown"]
+    },
+    "scanner": {
+      "task_prefix": "SCAN",
+      "responsibility": "8-dimension UI audit using Impeccable design standards",
+      "message_types": ["scan_complete", "scan_progress", "error"]
+    },
+    "diagnostician": {
+      "task_prefix": "DIAG",
+      "responsibility": "Root cause analysis, severity classification, fix prioritization",
+      "message_types": ["diag_complete", "diag_progress", "error"]
+    },
+    "optimizer": {
+      "task_prefix": "OPT",
+      "responsibility": "Apply targeted fixes following Impeccable design standards",
+      "message_types": ["opt_complete", "opt_progress", "error"]
+    },
+    "verifier": {
+      "task_prefix": "VERIFY",
+      "responsibility": "Before/after comparison, regression detection",
+      "message_types": ["verify_passed", "verify_failed", "fix_required", "error"]
+    }
+  },
+
+  "pipelines": {
+    "scan-only": {
+      "description": "Discover + diagnose, no fixes (report only)",
+      "task_chain": ["SCAN-001", "DIAG-001"],
+      "complexity": "low"
+    },
+    "targeted": {
+      "description": "Fix specific dimensions only",
+      "task_chain": ["SCAN-001", "DIAG-001", "OPT-001", "VERIFY-001"],
+      "complexity": "medium"
+    },
+    "full": {
+      "description": "Complete polish cycle with GC loop",
+      "task_chain": ["SCAN-001", "DIAG-001", "OPT-001", "VERIFY-001"],
+      "gc_loop": true,
+      "complexity": "high"
+    }
+  },
+
+  "innovation_patterns": {
+    "generator_critic": {
+      "generator": "optimizer",
+      "critic": "verifier",
+      "max_rounds": 2,
+      "convergence": "verify.regressions === 0 && verify.score_delta >= 0",
+      "escalation": "Coordinator intervenes after max rounds"
+    }
+  },
+
+  "session_dirs": {
+    "base": ".workflow/.team/UIP-{slug}-{YYYY-MM-DD}/",
+    "scan": "scan/",
+    "diagnosis": "diagnosis/",
+    "optimization": "optimization/",
+    "verification": "verification/",
+    "evidence": "evidence/",
+    "messages": ".workflow/.team-msg/{team-name}/"
+  }
+}