---
name: ui-fixer
description: >
  Autonomous analyze-fix loop for detecting and fixing visual, accessibility,
  and UX issues in web applications. Delegates screenshot capture to the
  ui-screenshotter skill, then analyzes the images for layout breaks, contrast
  violations, and design inconsistencies and applies targeted CSS/HTML fixes
  iteratively.
  USE FOR: fixing broken layouts, improving color contrast and accessibility compliance,
  modernizing dated visual patterns, resolving responsive design failures, polishing
  spacing and typography inconsistencies.
  DO NOT USE FOR: backend logic bugs, API endpoint changes, database schema migrations,
  adding new features or pages, JavaScript runtime errors unrelated to rendering.
  INVOKES: ui-screenshotter skill (screenshot capture), file-editing tools.
---

# UI Fixer

Iteratively analyzes and fixes visual, accessibility, and UX issues in a running
web application. Uses the **ui-screenshotter** skill for all Playwright screenshot
capture and focuses exclusively on analysis and code fixes.

## When to Use

- Fixing layout breaks, overlapping elements, or content overflow
- Improving color contrast and WCAG accessibility compliance
- Modernizing dated visual patterns (heavy borders, shadow abuse, beveled buttons)
- Resolving responsive design failures across viewport sizes
- Polishing spacing, typography, and alignment inconsistencies
- Fixing broken or missing images in the UI
- Addressing z-index stacking issues

## When Not to Use

- Backend logic bugs or API errors
- Adding new pages, routes, or features
- Database schema changes
- JavaScript runtime errors unrelated to rendering
- Performance optimization (bundle size, caching)

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| Project root | Yes | Workspace directory containing the web application |
| Screen config | No | Path to `screens.md` (passed through to ui-screenshotter; defaults to `ui-screenshotter/screens.md`; auto-discovers if absent) |
| Fix directive | No | Focus area: `common issues`, `accessibility`, `modern`, or a custom description (defaults to `common issues`) |
| Iteration limit | No | Maximum fix-analyze cycles (defaults to 5) |
| Viewport size | No | Viewport dimensions passed to ui-screenshotter (defaults to 1280x720) |

## Workflow

### Step 1: Capture "Before" Screenshots

Invoke the **ui-screenshotter** skill with:

- **Project root**: the workspace directory
- **Screen config**: the user-provided path or the default
- **Label**: `before`
- **Viewport sizes**: the user-provided viewport or the default

The screenshotter handles environment detection, server startup, Playwright
installation, and screenshot capture. It returns the run ID and screenshot paths.

**Checkpoint**: `.before.png` files exist in
`ui-screenshotter/.screenshots/<run-id>/` for every configured screen.

### Step 2: Analyze Screenshots

Evaluate each screenshot against the fix directive. Categorize findings by severity:

- **Critical**: broken layouts, unreadable text, content completely hidden
- **Major**: accessibility violations (contrast < 4.5:1), significant UX issues, responsive failures
- **Minor**: spacing inconsistencies, polish items, dated visual patterns

Produce a structured fix plan listing each issue with severity, file path, and the specific CSS/HTML change.

**Checkpoint**: Fix plan written with at least one actionable item, or analysis confirms no issues remain.

### Step 3: Apply Fixes

1. Locate the relevant CSS/HTML/template file for each issue.
2. Apply fixes using file-editing tools. Prefer CSS-only fixes when possible.
3. Preserve existing class names, framework-specific patterns (React `className`, Vue scoped styles), and semantic HTML structure.
4. Do not add inline styles. Use descriptive class names or CSS custom properties on `:root`.

**Checkpoint**: All planned fixes applied without introducing new lint or compile errors.

### Step 4: Re-capture and Verify

1. Invoke the **ui-screenshotter** skill again with label `after` and the
   **same run ID** so images land in the same directory.
2. Compare `.after.png` screenshots against the fix plan to confirm each issue
   is resolved.
3. Check for regressions -- new issues introduced by the fixes.
4. If unresolved issues or regressions remain and the iteration limit is not
   reached, re-invoke the screenshotter with label `after-N` (where N is the
   iteration number) for history, then return to Step 2.

**Checkpoint**: All critical and major issues resolved, no regressions detected,
or iteration limit reached. Before/after pairs sit side-by-side in
`ui-screenshotter/.screenshots/<run-id>/`.

## Validation

- [ ] Server starts without errors
- [ ] Screenshots are captured for all configured screens
- [ ] Critical issues (broken layouts, unreadable text) are resolved
- [ ] Major accessibility violations meet WCAG AA contrast ratios (4.5:1 normal text, 3:1 large text)
- [ ] No regressions introduced by fixes (verified via re-capture)
- [ ] Modified files have no new lint or compile errors

## Common Pitfalls

| Pitfall | Solution |
|---------|----------|
| Server fails to start | Check for missing dependencies; run `npm install` or `pip install -r requirements.txt` first |
| Playwright not installed | Run `npx playwright install chromium` before capturing |
| Screenshots are blank or partially loaded | Increase the wait state to `networkidle` or add explicit wait-for-selector steps |
| Fixes break other pages | Re-capture all screens after each fix cycle, not just the affected page |
| CSS specificity conflicts | Use targeted selectors rather than `!important`; inspect existing cascade before editing |
| Auth-gated pages not captured | Configure auth cookies or login interactions in the screen config |