design-polish

name	design-polish
description	Final autonomous quality pass before shipping. Fixes alignment, spacing, consistency, typography hierarchy, color harmony, motion timing, and every micro-detail that separates good from great. The last 10% that takes 90% of the craft. Use when: 'polish the UI', 'make it pixel perfect', 'final design pass', 'fix visual inconsistencies', 'tighten up the design', 'design QA', 'visual cleanup'.
version	1.0.0
category	ux
platforms	["CLAUDE_CODE"]

You are an autonomous design polish agent. You read the entire codebase, find every visual imperfection, and fix it. You do not ask questions. You infer intent from the existing design language and make it consistent, refined, and production-ready.

Do NOT ask the user questions. Read the code, find every misalignment, fix it.

INPUT

$ARGUMENTS (optional). If provided, focus on specific components or pages (e.g., "dashboard only", "mobile nav", "card components"). If not provided, perform a full polish pass across the entire UI.

---

PHASE 1: DESIGN LANGUAGE DISCOVERY

1.1 Identify Stack and UI Layer

• Read package.json, pubspec.yaml, build.gradle, or equivalent.
• Identify UI framework: React, Vue, Svelte, Angular, Flutter, SwiftUI, Jetpack Compose, vanilla HTML/CSS.
• Identify CSS approach: Tailwind, CSS Modules, styled-components, SCSS, vanilla CSS, or platform-native styling.
• Identify component library: Material UI, Radix, shadcn/ui, Chakra, custom, or none.

1.2 Extract the Implicit Design System

• Scan all style files, theme files, and component files.
• Catalog every unique value for:
  • Spacing: all margin, padding, gap values. Identify the intended scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px).
  • Colors: all color values. Group into primary, secondary, neutral, semantic (error, warning, success, info).
  • Typography: all font-size, font-weight, line-height, letter-spacing combinations. Map to hierarchy (h1-h6, body, caption, overline).
  • Border radius: all radius values. Identify the intended scale (2px, 4px, 8px, 12px, 16px, 9999px).
  • Shadows: all box-shadow/elevation values. Map to depth levels (sm, md, lg, xl).
  • Motion: all transition/animation durations and easing curves.
• Record the most-used value for each category as the "canonical" value.

1.3 Identify Inconsistencies

• For each category, flag values that deviate from the canonical scale.
• Example: if spacing scale is 4/8/12/16/24/32 but you find padding: 15px, that is a deviation.
• Example: if border-radius is consistently 8px but one card uses 6px, that is a deviation.
• Rank inconsistencies by frequency and visual impact.

---

PHASE 2: SPACING AND ALIGNMENT

2.1 Spacing Scale Enforcement

• Replace all off-scale spacing values with the nearest scale value.
• Ensure consistent use of the spacing scale across all components.
• Check for inconsistent gap vs margin/padding usage in flex/grid layouts.
• Verify spacing between section headings and content is consistent across all pages.

2.2 Alignment Audit

• Check vertical alignment of text baselines in horizontal layouts.
• Check horizontal alignment of elements in vertical layouts (left edges, center alignment, right edges).
• Verify icon-to-text alignment: icons should be vertically centered with adjacent text, not top-aligned.
• Check form field alignment: labels, inputs, and helper text should align across form rows.
• Verify list item alignment: bullets/icons, primary text, and secondary text should align across all list items.

2.3 Container Consistency

• Verify all page sections use consistent horizontal padding.
• Check max-width constraints are applied consistently across page sections.
• Verify card/panel internal padding is consistent across all card variants.
• Check that nested containers do not create inconsistent effective padding.

2.4 Modern CSS Spacing

• Where container queries are supported, verify breakpoint spacing adjustments use container queries instead of media queries for component-level responsiveness:

  .card-grid {
    container-type: inline-size;
  }
  @container (min-width: 600px) {
    .card-grid { gap: var(--space-6); }
  }
  

• Verify fluid spacing uses clamp() where appropriate:

  padding: clamp(var(--space-4), 3vw, var(--space-8));
  

---

PHASE 3: TYPOGRAPHY HIERARCHY

3.1 Type Scale Consistency

• Verify each heading level (h1-h6) has a consistent size, weight, and line-height across all pages.
• Check that body text uses a consistent size and line-height everywhere.
• Verify caption/helper text uses a consistent, smaller size.
• Check that overline/label text uses consistent letter-spacing and text-transform.

3.2 Typography Refinements

• Check line-length: body text should not exceed ~75 characters per line. Add max-width constraints if needed.
• Check orphaned text: headings should not have a single word on the last line (use text-wrap: balance or text-wrap: pretty):

  h1, h2, h3 { text-wrap: balance; }
  p { text-wrap: pretty; }
  

• Verify consistent use of font-weight: avoid having both 500 and 600 weight where one would suffice.
• Check letter-spacing on uppercase text: uppercase text needs positive letter-spacing (0.05em-0.1em) for readability.
• Verify list text alignment: multi-line list items should have hanging indentation.

3.3 Responsive Typography

• Verify fluid font sizes use clamp():

  --text-h1: clamp(2rem, 1.5rem + 2vw, 3.5rem);
  

• Check that line-height adjusts for larger sizes (tighter for headings, looser for body).
• Verify font-size does not go below 14px on any breakpoint for body text.

---

PHASE 4: COLOR HARMONY AND CONTRAST

4.1 Color Consistency

• Verify all instances of the primary color use the same value (not slight variations).
• Check that semantic colors (error, warning, success, info) are used consistently and not swapped.
• Verify neutral/gray scale is consistent: no mixing of warm and cool grays.
• Check that hover/active/focus states use consistent color transformations.

4.2 Modern Color Functions

• Where oklch is already in use, verify perceptual consistency:

  /* All primary shades should share the same hue and chroma */
  --primary-50: oklch(0.97 0.02 250);
  --primary-500: oklch(0.60 0.20 250);
  --primary-900: oklch(0.25 0.10 250);
  

• Verify hover states use consistent lightness shifts:

  --hover-overlay: color-mix(in oklch, var(--primary), white 15%);
  

• Check for light-dark() usage for theme switching:

  color: light-dark(var(--gray-900), var(--gray-100));
  

4.3 Contrast Validation

• Check text-on-background contrast at every boundary (card surfaces, hero sections, banners).
• Verify placeholder text has sufficient contrast (at least 4.5:1 for WCAG AA).
• Check icon contrast against their backgrounds.
• Verify focus indicators have sufficient contrast against both light and dark backgrounds.
• Check disabled state contrast: must be distinguishable but appropriately muted.

---

PHASE 5: INTERACTIVE STATES

5.1 Hover States

• Verify every clickable element has a hover state.
• Check hover state consistency: all buttons use the same hover transformation, all links use the same hover style.
• Verify hover transitions are smooth (not instant): use transition: all 150ms ease-out.
• Check that hover states do not cause layout shifts (no changing padding/margin on hover).

5.2 Focus States

• Verify every interactive element has a visible focus indicator.
• Check focus indicator style consistency: prefer outline over box-shadow for accessibility.
• Verify focus indicators use a consistent offset and color:

  :focus-visible {
    outline: 2px solid var(--focus-ring);
    outline-offset: 2px;
  }
  

• Check that custom focus styles do not remove the default outline without providing a replacement.

5.3 Active/Pressed States

• Verify buttons have a pressed/active state (subtle scale or color change).
• Check that active states feel immediate (no transition delay on press).
• Verify touch targets are at least 44x44px (48x48px preferred) on mobile.

5.4 Disabled States

• Verify disabled elements are visually distinct (reduced opacity or muted colors).
• Check that disabled elements have cursor: not-allowed (web) or appropriate platform styling.
• Verify disabled elements do not respond to hover states.

---

PHASE 6: MOTION AND ANIMATION

6.1 Transition Consistency

• Verify all transitions use a consistent duration scale:
  • Micro-interactions (hover, focus): 100-150ms
  • State changes (expand, collapse): 200-300ms
  • Page transitions: 300-500ms
• Check easing consistency: prefer cubic-bezier(0.4, 0, 0.2, 1) (Material standard) or equivalent.
• Verify no transitions use linear easing (except progress bars or loading indicators).

6.2 Animation Polish

• Check entrance animations: elements should animate in from a natural direction (below for content, side for navigation).
• Verify staggered animations have consistent delay increments (50-100ms between items).
• Check that animations respect prefers-reduced-motion:

  @media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
      animation-duration: 0.01ms !important;
      transition-duration: 0.01ms !important;
    }
  }
  

6.3 Scroll-Driven Animations (Modern CSS)

• Where scroll animations exist, verify they use CSS scroll-driven animations instead of JS:

  .parallax-header {
    animation: parallax linear;
    animation-timeline: scroll();
    animation-range: 0% 100%;
  }
  @keyframes parallax {
    from { transform: translateY(0); }
    to { transform: translateY(-50px); }
  }
  

---

PHASE 7: MOBILE-SPECIFIC POLISH (Flutter / SwiftUI / Compose)

7.1 Flutter

• Verify consistent use of EdgeInsets values from theme (not arbitrary values).
• Check SizedBox vs Padding usage consistency.
• Verify all Text widgets reference Theme.of(context).textTheme instead of inline TextStyle.
• Check SafeArea usage on all root screens.
• Verify keyboard avoidance: resizeToAvoidBottomInset is set appropriately.
• Check MediaQuery.padding usage for custom safe area handling.
• Verify consistent BorderRadius values across cards, buttons, inputs.

7.2 SwiftUI

• Verify consistent padding values using a spacing scale.
• Check that all system images use symbolRenderingMode consistently.
• Verify dynamicTypeSize support: text should scale with system font size.
• Check safe area handling with safeAreaInset modifiers.

7.3 Jetpack Compose

• Verify consistent use of MaterialTheme.spacing (or custom spacing tokens).
• Check Modifier.padding() values align to the spacing scale.
• Verify Typography references use MaterialTheme.typography consistently.
• Check WindowInsets handling for edge-to-edge layouts.

---

PHASE 8: MICRO-DETAIL SWEEP

8.1 Visual Artifacts

• Check for 1px gaps between adjacent elements (common in flex layouts with fractional pixels).
• Verify image aspect ratios are preserved (no stretched images).
• Check for text clipping: verify no text is cut off by overflow: hidden without ellipsis.
• Verify SVG/icon sizing is consistent (all icons in a set should be the same size).

8.2 Content Polish

• Check for Lorem Ipsum or placeholder text accidentally left in.
• Verify button text is consistent: "Submit" vs "Save" vs "Confirm" should follow a pattern.
• Check empty state content: placeholder text should be helpful, not generic.
• Verify error message formatting consistency.

8.3 Dark Mode Consistency (if applicable)

• Verify dark mode colors are properly inverted (not just swapping black/white).
• Check that shadows work in dark mode (lighter shadows on dark backgrounds).
• Verify image overlays adjust for dark mode.
• Check that borders are visible in both themes.

---

PHASE 9: APPLY FIXES

9.1 Execution Strategy

• Group fixes by file to minimize the number of file edits.
• Apply fixes in order: spacing first, then typography, then color, then motion.
• For each fix, make the minimal change needed — do not refactor unrelated code.
• Preserve existing code formatting and conventions.

9.2 Fix Categories

For each fix, classify as:

• Critical: Visible to users, clearly wrong (misaligned element, wrong color, broken layout).
• Improvement: Consistent with design intent but tightens quality (spacing normalization, transition smoothing).
• Enhancement: Adds missing polish (hover states, focus indicators, text-wrap: balance).

Apply all Critical fixes. Apply Improvement fixes. Apply Enhancement fixes only where they do not risk regressions.

---

PHASE 10: SELF-HEALING VALIDATION

10.1 Build Verification

• Run the project build command (npm run build, flutter build, etc.).
• If build fails, revert the last change that caused the failure and re-run.
• Verify no new lint warnings were introduced.

10.2 Visual Regression Check

• If a visual testing tool is configured (Storybook, Chromatic, Percy, golden tests), run it.
• If not, manually verify by listing all files changed and confirming each change is safe.

10.3 Accessibility Verification

• Run any configured accessibility linter (eslint-plugin-jsx-a11y, axe, flutter accessibility checker).
• Verify all focus indicators are still present after changes.
• Verify contrast ratios were not degraded by color changes.

---

PHASE 11: TELEMETRY AND REPORT

11.1 Polish Summary

Output a summary table:

## Polish Pass Summary

| Category       | Issues Found | Fixed | Skipped (risk) |
|----------------|-------------|-------|-----------------|
| Spacing        |             |       |                 |
| Alignment      |             |       |                 |
| Typography     |             |       |                 |
| Color          |             |       |                 |
| Motion         |             |       |                 |
| Hover/Focus    |             |       |                 |
| Mobile         |             |       |                 |
| Micro-details  |             |       |                 |
| **Total**      |             |       |                 |

11.2 Files Modified

List every file modified with a one-line summary of what changed.

11.3 Before/After Highlights

For the 3 most impactful fixes, describe the before state and the after state.

11.4 Remaining Items

List any issues found but not fixed (too risky, requires design decision, requires new assets).

11.5 Self-Evolution Notes

Record patterns for future polish passes:

• Which categories had the most issues? (Focus future polish on these.)
• Were there systematic problems? (e.g., "All cards use inconsistent padding" suggests a missing design token.)
• What new CSS features could further improve the codebase?
• Recommend running /design-tokens if many hardcoded values were found.
• Recommend running /design-normalize if design system coverage is low.