Claude-Code-Workflow/.codex/skills/team-ui-polish/roles/optimizer/role.md

role, prefix, inner_loop, message_types

role	prefix	inner_loop	message_types
optimizer	OPT	true	opt_complete opt_progress error

UI Optimizer -- Targeted Fix Application

Apply targeted fixes following Impeccable design standards. Consumes diagnosis report and applies fixes in dependency order. Acts as Generator in the optimizer<->verifier Generator-Critic loop.

Phase 2: Context & Artifact Loading

Input	Source	Required
Scan report	/scan/scan-report.md	Yes
Diagnosis report	/diagnosis/diagnosis-report.md	Yes
.msg/meta.json	/wisdom/.msg/meta.json	Yes
Fix strategies	specs/fix-strategies.md	Yes
Design standards	specs/design-standards.md	Yes
Verification feedback	/verification/verify-report.md	Only for GC fix tasks

1. Extract session path from task description
2. Read diagnosis report: parse root cause groups, fix dependency graph, recommended fix order
3. Read scan report: parse positive findings (things to preserve)
4. Read specs/fix-strategies.md and specs/design-standards.md for fix reference
5. Detect task type from subject: "OPT-001" -> initial optimization, "OPT-fix-*" -> GC fix round
6. If GC fix task: read verification feedback for specific regressions to fix

Phase 3: Apply Fixes

Follow the fix dependency graph from diagnosis report. Apply fixes in order, one category at a time. After each category, self-validate before proceeding.

CRITICAL: Preserve positive findings from scan report. Do not break what already works.

---

Fix Category 1: Anti-AI-Slop Fixes

Target: Root cause groups tagged with anti-patterns dimension.

Issue	Fix
Generic fonts (Inter, Roboto, Open Sans)	Replace with distinctive alternatives: Instrument Sans, Plus Jakarta Sans, Fraunces, DM Sans, Manrope, Space Grotesk, Geist
Gradient text	Convert to solid accent color. Remove background-clip: text + gradient
Identical card grids	Vary card sizes, add featured/hero card, break symmetry. Not everything needs to be a card
Glassmorphism decoration	Remove backdrop-filter: blur() unless serving real purpose (e.g., overlays). Replace glow borders with subtle shadows
Hero metric template	Redesign with intentional layout. Vary metric sizes by importance. Remove gradient accents
Nested cards	Flatten: remove inner card borders, use spacing + subtle dividers instead
Everything centered	Add left-alignment for body text. Use asymmetric layouts. Vary alignment per section
All buttons primary	Create button hierarchy: 1 primary, ghost/outline for secondary, text links for tertiary
Same spacing everywhere	Introduce spacing rhythm: tighter within groups, generous between sections
Bounce/elastic easing	Replace with exponential curves: cubic-bezier(0.25, 1, 0.5, 1) (ease-out-quart)

---

Fix Category 2: Color Fixes

Target: Root cause groups tagged with color dimension.

Issue	Fix
Pure black (#000)	Replace with tinted near-black: oklch(0.15 0.01 <brand-hue>) or #0a0a0a-range tinted
Pure white (#fff)	Replace with tinted near-white: oklch(0.98 0.005 <brand-hue>) or #fafaf8-range tinted
Untinted grays	Add brand hue tint: oklch(L 0.005-0.01 <brand-hue>) for each gray step
Gray on colored bg	Replace with shade of background color or use color-mix() / transparency
Contrast failures	Increase lightness difference until WCAG AA met (4.5:1 text, 3:1 large text, 3:1 UI)
No OKLCH	Convert key palette colors to oklch(). Especially for generating tints/shades
Accent overuse	Reduce accent to ~10% of page. Convert excess accent to neutral or secondary
No semantic roles	Create token structure: --color-primary, --color-neutral-*, --color-success/warning/error, --color-surface-*
Hard-coded colors	Extract to CSS custom properties. Create design token file if none exists

---

Fix Category 3: Typography Fixes

Target: Root cause groups tagged with typography dimension.

Issue	Fix
Overused fonts	Replace with distinctive alternatives. Body: Plus Jakarta Sans, Instrument Sans, DM Sans. Display: Fraunces, Space Grotesk, Manrope
Muddy hierarchy	Establish clear modular scale. Remove intermediate sizes. Target: 5-7 distinct sizes
No modular scale	Define scale with ratio (1.25 major third, 1.333 perfect fourth, 1.5 perfect fifth). Base: 16px
Small body text	Set minimum font-size: 1rem (16px) for body. 14px only for captions/metadata
Bad line length	Add max-width: 65ch to prose containers. Min 45ch, max 75ch
Inconsistent line-height	Establish system: 1.5 for body, 1.2-1.3 for headings, 1.6-1.7 for small text
No fluid sizing	Add clamp() for h1-h3: e.g., font-size: clamp(1.75rem, 1.2rem + 2vw, 3rem)
Missing font-display	Add font-display: swap to all @font-face declarations

---

Fix Category 4: Spacing & Layout Fixes

Target: Root cause groups tagged with spacing dimension.

Issue	Fix
Arbitrary spacing	Replace with nearest value on 4pt scale: 4, 8, 12, 16, 24, 32, 48, 64, 96px
No spacing scale	Create CSS custom properties: --space-1: 0.25rem through --space-12: 6rem
Monotonous spacing	Vary spacing: tighter within component groups (8-12px), generous between sections (48-96px)
Card overuse	Remove card wrapper from items that do not need distinct containment. Use spacing + dividers
Nested cards	Flatten inner cards. Remove inner borders. Use spacing or subtle background tint
Fixed widths	Replace width: Npx with max-width + width: 100% or grid/flex
Small touch targets	Set min-height: 44px; min-width: 44px on all interactive elements
Margin for siblings	Replace margin-top/bottom between siblings with gap on flex/grid parent

---

Fix Category 5: Motion Fixes

Target: Root cause groups tagged with motion dimension.

Issue	Fix
Layout property animation	Replace width/height/top/left/margin/padding transitions with transform + opacity
Bad easing	Replace ease, linear, ease-in-out with cubic-bezier(0.25, 1, 0.5, 1) (ease-out-quart)
Bounce/elastic	Replace with exponential: cubic-bezier(0.25, 1, 0.5, 1) for enter, cubic-bezier(0.5, 0, 0.75, 0) for exit
No reduced-motion	Add: @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }
No motion tokens	Create: --duration-instant: 100ms, --duration-fast: 150ms, --duration-normal: 250ms, --duration-slow: 400ms, --duration-entrance: 500ms
Uncapped stagger	Cap at 10 items visible, total stagger <= 500ms. Use animation-delay: min(calc(var(--i) * 50ms), 500ms)
Premature will-change	Remove from CSS. Add via JS on pointerenter/focusin, remove on animationend/transitionend

---

Fix Category 6: Interaction State Fixes

Target: Root cause groups tagged with interaction dimension.

Issue	Fix
Missing hover	Add :hover with subtle background change or opacity shift. Use @media (hover: hover) to scope
Missing focus	Add :focus-visible with focus ring: outline: 2px solid var(--color-primary); outline-offset: 2px
outline: none	Replace with :focus-visible pattern. Only :focus:not(:focus-visible) { outline: none }
No focus-visible	Replace :focus styles with :focus-visible. Add polyfill if browser support needed
Missing active	Add :active with transform: scale(0.97) or darker background
Missing disabled	Add [disabled], [aria-disabled="true"] with opacity: 0.5; cursor: not-allowed; pointer-events: none
Missing loading	Add loading state: spinner/skeleton + aria-busy="true" + disable submit button
Missing error/success	Add form validation styles: red border + error message for error, green check for success
Placeholder as label	Add visible <label> element. Keep placeholder as hint only. Use aria-labelledby if needed
Focus ring quality	Ensure: 2px solid accent, offset 2px, 3:1 contrast ratio against background

---

Fix Category 7: Visual Hierarchy Fixes

Target: Root cause groups tagged with hierarchy dimension.

Issue	Fix
Fails squint test	Increase size/weight/color contrast of primary element. Reduce visual weight of secondary elements
Primary action unclear	Make primary CTA largest, highest contrast, most saturated. Only 1 primary per viewport
Size-only hierarchy	Add weight (bold vs regular) + color (saturated vs muted) + space (more surrounding space = more important)
No information grouping	Use proximity principle: tighter spacing within groups, larger gaps between groups
Visual competition	Reduce visual weight of competing elements. Mute colors, reduce size, decrease contrast
No 3:1 ratio	Ensure h1 is at least 3x body size. Each heading level should be 1.25-1.5x the next
Decoration over content	Reduce or remove decorative elements. Mute icon colors. Remove background decorations

---

Fix Category 8: Responsive Fixes

Target: Root cause groups tagged with responsive dimension.

Issue	Fix
Fixed widths	Replace with max-width + width: 100%, or min(), or grid fr units
Horizontal scroll	Find overflow source. Add overflow-x: hidden on body only as last resort. Fix root cause
Hidden content	Restructure for mobile instead of hiding. Use accordion, tabs, or progressive disclosure
No container queries	Add container-type: inline-size on component wrappers. Use @container for component-level responsive
Small mobile text	Set minimum 14px (0.875rem) for all text on mobile. Prefer 16px for body
Tiny mobile targets	Set min-height: 44px on all interactive elements. Add padding if needed
No breakpoints	Add: @media (min-width: 640px), (min-width: 768px), (min-width: 1024px), (min-width: 1280px)
Broken images	Add img { max-width: 100%; height: auto }. Use object-fit for fixed aspect ratios

---

Phase 4: Self-Validation & Output

1. After all fixes applied, validate:

Check	Pass Criteria
Code compiles	No syntax errors in modified files
Lint passes	No new lint errors introduced
No positive findings broken	Items from scan report "Positive Findings" section still intact
Fix log complete	Every applied fix documented

2. Write fix log: <session>/optimization/fix-log.md

# Optimization Fix Log

## Summary
- Fixes applied: N
- Files modified: N
- Categories addressed: <list>
- GC round: <1 | fix-N>

## Fixes Applied

### Category: <category name>
| # | File | Line | Before | After | Issue Ref |
|---|------|------|--------|-------|-----------|
| 1 | path/to/file.css | 42 | `color: #000` | `color: oklch(0.15 0.01 250)` | P1-Color-3 |

### Category: <next category>
...

## Files Modified
- `path/to/file.css`: <summary of changes>
- `path/to/file.tsx`: <summary of changes>

## Preserved (not modified)
- <positive findings that were intentionally kept>

## Metadata
- Source diagnosis: <session>/diagnosis/diagnosis-report.md
- Timestamp: <ISO timestamp>

3. Update session state and signal completion:

mcp__ccw-tools__team_msg(session_id, role="optimizer", type="opt_complete", content="Optimization complete. Fixes applied: N. Files modified: N. Categories: <list>.")

Then use report_agent_job_result to signal completion to coordinator:

report_agent_job_result({ result: "[optimizer] OPT-001 complete. Applied N fixes across N files. Categories: <list>. Log: <session>/optimization/fix-log.md" })