Skip to content
Skills Library
Design & UX · Building & coding

visual-polish-loop

/visual-polish-loop

Run a recursive, evidence-driven visual polish loop on a web UI. Audit every page, theme and state against a quality bar (palette, contrast, surfaces, typography, spacing, component states, focus), prototype genuinely different directions on the real pages, implement the winner through design tokens, then capture, have independent reviewers scrutinize, fix and repeat until a round comes back clean, and deliver a PR with before/after evidence and metrics. Use this whenever someone asks to polish, refine, clean up, unify, uplift or "make seamless" a UI, theme, palette or colour system, close a q

Repository
tinderbox ↗
Licence
MPL-2.0
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
7
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MPL-2.0, otwarta.

What to check before installing
  • 7 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/capture.mjs, scripts/contrast-audit.mjs, scripts/focus-sheet.mjs, scripts/lib.mjs, scripts/login.mjs, scripts/palette-audit.mjs, scripts/sheet.mjs

What it does and when to use it

Run a recursive, evidence-driven visual polish loop on a web UI. Audit every page, theme and state against a quality bar (palette, contrast, surfaces, typography, spacing, component states, focus), prototype genuinely different directions on the real pages, implement the winner through design tokens, then capture, have independent reviewers scrutinize, fix and repeat until a round comes back clean, and deliver a PR with before/after evidence and metrics. Use this whenever someone asks to polish, refine, clean up, unify, uplift or "make seamless" a UI, theme, palette or colour system, close a q

Triggers from the description

make seamless
Original author description

Run a recursive, evidence-driven visual polish loop on a web UI. Audit every page, theme and state against a quality bar (palette, contrast, surfaces, typography, spacing, component states, focus), prototype genuinely different directions on the real pages, implement the winner through design tokens, then capture, have independent reviewers scrutinize, fix and repeat until a round comes back clean, and deliver a PR with before/after evidence and metrics. Use this whenever someone asks to polish, refine, clean up, unify, uplift or "make seamless" a UI, theme, palette or colour system, close a q

How it works

  1. What you deliver
  2. Principles, and why
  3. The scripts
  4. Phase 0: Frame the job → brief.md
  5. Phase 1: Harness and baseline
  6. Phase 2: Audit → audit.md
  7. Phase 3: Directions → directions/
  8. Phase 4: Implement
  9. Phase 5: The loop → loop-log.md
  10. Phase 6: Deliver
Original SKILL.md headings · 218 lines, 1,713 words
SKILL.md preview
---
name: visual-polish-loop
description: Run a recursive, evidence-driven visual polish loop on a web UI. Audit every page, theme and state against a quality bar (palette, contrast, surfaces, typography, spacing, component states, focus), prototype genuinely different directions on the real pages, implement the winner through design tokens, then capture, have independent reviewers scrutinize, fix and repeat until a round comes back clean, and deliver a PR with before/after evidence and metrics. Use this whenever someone asks to polish, refine, clean up, unify, uplift or "make seamless" a UI, theme, palette or colour system, close a quality gap between two themes or screens, do a design or finish pass with high scrutiny, or says "visual clean loop" / "visual polish loop", even if they only mention colours or say it "doesn't feel as polished as" something. Not for building new features or single-bug visual fixes.
---

# Visual polish loop

Raise a UI's finish to a clear bar by measuring, prototyping and reviewing on
the real rendered pages, in rounds, until fresh reviewers stop finding problems.

This is modelled on a run that worked very well (fl1nt.dev's Christmas palette,
`references/worked-example.md`). The agent named concrete root causes: warm
brown panels on a navy sky, khaki tints, sepia text, 8 golds and 11 reds. It
tried four real directions on the live pages and rebuilt the palette as tokens
from the art's own colour ramps. It measured contrast across 777 text elements
before and after, and a review pass caught three leftovers before the PR. That
depth is the standard here.

## What you deliver

- A PR (unless told otherwise; never merge without authorization) containing
  the audit findings, the system chosen and why, the directions tried,
  before/after evidence for every page and state in scope, metrics before and
  after, what was checked, and pre-existing issues you noticed.
- Working files under `.agent-artifacts/visual-polish/` (untracked):
  `brief.md`, `config.json`, `audit.md`, `directions/`, `loop-log.md`,
  `shots/`, `sheets/`, `metrics/`, and a handoff note for context resets.

## Principles, and why

1. **The bar decides.** "Polished" means nothing until you name what it's
   measured against: the product's best screens, its other theme, its brand
   art, a design system. For the Christmas theme the bar was the everyday
   theme's restraint ("few hues, high contrast, crisp"). Describe the bar in
   its own terms before touching anything.
2. **Measure on the real pages.** Users see rendered pixels, not source. Work
   from screenshots of the running app, computed colours and contrast numbers.
   Reading CSS or mocking up screens misses tint stacking, overrides and
   states.
3. **Everything, not a sample.** Cover every route, theme, state and viewport
   in scope. Sample-based checks have missed most failures before. The bugs
   live in the dialog nobody opened and the empty state nobody seeded.
4. **Uplift, not redesign.** Keep the product's identity, layout and features.
   Fix cohesion and finish. Change layout only when a finish problem demands
   it, and say so. The user's global instructions may describe a product's
   identity; follow them.
5. **Systems over patches.** One source of truth (tokens/CSS variables), each
   colour with one job, states derived from tokens. A hex tweak that fixes one
   screen quietly breaks another.
6. **Fresh eyes.** The author is the worst reviewer of their own pass.
   Reviewers get the bar and the evidence, never your conclusions.
7. **Bounded.** Rounds have exit criteria. Converge, report what remains, stop.

## The scripts

All in `scripts/` (Node ESM, need only Playwright: the project's own, a global
install, or the playwright-cli bundle; set `PLAYWRIGHT_PATH` otherwise).
Run them from the project root. They read
`.agent-artifacts/visual-polish/config.json` (pass `--config` to override).
Start the config from `assets/config.example.json`; every field is documented
in `references/config.md`.

| Script | What it gives you |
| --- | --- |
| `capture.mjs --tag T [--css proto.css]` | Full-page shots of every route × state × viewport, 2x crops of named and common components, console errors and failed requests per page. `--css` injects a prototype stylesheet. |
| `sheet.mjs grid\|pairs\|compare\|crops` | Review sheets: overview grids, before/after tiles at 1:1, directions side by side, crop boards. |
| `contrast-audit.mjs --tag T` | Contrast for every visible text and placeholder, measured against the actual pixels behind it (gradients, images, translucency included). WCAG 2 and APCA, worst offenders, `--compare a.json b.json`. |
| `palette-audit.mjs static` | What the source declares: colour literals, custom properties, Tailwind classes. Near-duplicates, families, literals outside tokens. |
| `palette-audit.mjs runtime --tag T` | What the screen shows, by role (surfaces, text, borders, icons, gradients, shadows), weighted by area. Also renders a palette card PNG. |
| `focus-sheet.mjs --tag T` | Tabs through each page and crops every focus stop at 2x. Flags stops with no visible focus or a weak one (under 3:1 change contrast). |
| `login.mjs` | Saves a signed-in session from `config.login` steps, for apps behind auth. |

Shorthand below: `S=<this skill's dir>/scripts`.

## Phase 0: Frame the job → `brief.md`

- Read the repo's AGENTS.md/CLAUDE.md, contributing docs, theme/token files,
  component library and package manifest. Note repo rules for visible changes.
  Some repos require refreshed documentation screenshots or run their own
  visual tests. Follow those as well as this skill.
- Write `brief.md`:
  - the user's words verbatim
  - the bar, described concretely
  - scope: routes, themes/modes, states, viewports
  - out of scope
  - constraints
  - other agents' files to avoid
  - isolation: worktree, branch, port
  - delivery
- If users or admins can customise colours (accent pickers, theme presets,
  custom tokens), put the defaults plus a few presets and extremes in scope.
  Derived colours (text on accent, focus rings) must hold across that range.
- Ask the user only when the bar or scope is ambiguous and the choice is
  consequential. Otherwise write your assumption down, and repeat it in the PR.

## Phase 1: Harness and baseline

- Run the app locally with disposable data (see `visual-qa` if installed).
  Never point captures at production. Seed realistic content: full, empty,
  long text, errors, permissions, many items.
- Write `config.json`:
  - every route
  - interactive states as their own routes with `actions` (open menus,
    dialogs, toasts, form errors, hover menus)
  - states (themes, modes, presets, special modes)
  - viewports
  - `crops`/`autoCrops` for component detail
  - `mask` for live data and `hide` for dev overlays
- If the app needs a login, run `node $S/login.mjs`.
- Baseline:
  ```sh
  node $S/capture.mjs --tag before
  node $S/contrast-audit.mjs --tag before --viewports all
  node $S/palette-audit.mjs static --tag before
  node $S/palette-audit.mjs runtime --tag before
  node $S/focus-sheet.mjs --tag before
  node $S/sheet.mjs grid --tag before && node $S/sheet.mjs crops --tag before
  ```
- Read `shots/before/index.json` for console errors and failed requests. Note
  the pre-existing ones, so you don't later mistake them for your regressions.
- If the bar is another theme or screen, capture it too (as its own tag or
  state) so you can put it side by side with the target.

## Phase 2: Audit → `audit.md`

- Look at every sheet yourself, at full size. Go through
  `references/audit-checklist.md`.
- Write numbered findings. Each one names the place, the problem, why it
  breaks the bar, the evidence (sheet path, crop, numbers, selector) and the
  root cause (a token, a component, a stray literal).
  - Bad: "the colours feel off".
  - Good: "Panels are `rgba(20,13,7,.9)` brown on a navy sky, so every panel
    edge is a warm/cold seam (home, about, blog)".
- Summarize the palette as measured: families, near-duplicates, roles, which
  literals bypass the tokens. Then the contrast stats, the focus failures and
  the states that look unfinished.
- For large UIs, an independent auditor (finish-reviewer brief) at this stage
  catches what your eye has already normalized.

## Phase 3: Directions → `directions/`

- Draft 2–4 genuinely different directions that answer the root causes.
  `references/directions.md` explains how to vary them. Write each as a
  token-override stylesheet in `directions/<name>.css`. Don't edit source yet.
- Capture each with `--css` on the hardest pages and states. Contrast-audit
  each. Build `sheet.mjs compare --tags before,dir-a,dir-b,...`.
- Pick one against the bar and the product's identity. Write one line on why
  each loser lost; it goes in the PR. If two are close, get a blind judgement
  (direction-judge brief).

## Phase 4: Implement

- Tokens first: semantic surface levels, text levels, accent roles, borders,
  focus, state colours. Map existing usages onto them. Remove the literals the
  palette audit flagged. Derive hover/active/disabled/focus from tokens. Cover
  every mode and preset in scope.
- Keep the diff to colour and finish unless a finding requires more. Build and
  run the repo's tests as you go.

## Phase 5: The loop → `loop-log.md`

Each round:

1. **Capture** everything in scope as `--tag rN`. Build `pairs --a before --b rN`
   and crop boards.
2. **Measure:**
   - `contrast-audit --tag rN`, then `--compare` against before
   - `palette-audit` (static + runtime)
   - `focus-sheet`

   Nothing may regress. No new text below AA unless decorative or disabled,
   no lost focus rings, no new console errors.
3. **Review:** split the sheets into disjoint sets. Give 3 reviewers the
   finish brief (fewer for small UIs) and 1 the regression brief, from
   `references/reviewer-brief.md`. Zoom in as rounds progress:
   - round 1: whole pages (system level: palette, surfaces, hierarchy)
   - round 2: component crops (buttons, inputs, menus, tables, dialogs)
   - round 3 onward: 2x detail (1px borders, ring offsets, icon alignment,
     placeholder text, disabled and empty states)
4. **Triage** in `loop-log.md`. Severity is high, medium or low. Verify each
   finding against the evidence before acting (reviewers misread crops), and
   record rejected ones with the reason. Fix root causes, not symptoms.
5. **Fix** highs and mediums, plus cheap lows, then re-capture what changed.

**Exit** when a full round (all sheets, fresh reviewers) reports no high or
medium findings and the metrics hold. Also stop after 4 rounds (the default;
the user can set another number) and report what remains honestly. Don't loop
on taste: if reviewers disagree on a low, the bar decides, and if the bar is
silent, leave it.

## Phase 6: Deliver

- Write the PR body from `references/pr-template.md`, in the owner's voice and
  following their attribution rules. Include:
  - the palette card (`metrics/palette-<tag>.png`)
  - the directions sheet
  - before/after for every page and state
  - the metrics table and the review rounds
- Host images the way the repo already does (assets branch, attachments), and
  check every URL loads.
- Follow the repo's process for visible changes (docs screenshots, visual
  tests). Use `pr-follow-through` for CI and review-bot feedback. Don't merge
  unless authorized.
- Leave a short handoff in `.agent-artifacts/visual-polish/HANDOFF.md`:
  branch, PR, head, what's left, how to resume.

## Working alongside other agents

- Size work to the machine: by default one heavy build at a time and at most
  two browser workers. Run capture states one after another rather than in
  parallel. Reviewer
  subagents cost model calls, not CPU, so run them in parallel.
- Use your own worktree, branch and port. Never touch other agents' servers,
  harnesses or files.
- Subagents:
  - Claude Code: the Agent tool, or the host's delegation tool when it has one
  - Codex: `spawn_agent`
  - Without subagents: follow the single-agent review note in
    `reviewer-brief.md`, and say so in the PR
- Commits and PR text follow the user's global rules, including any rules on
  attribution and voice.
Files in this package (15)
  • SKILL.md 12 KB
  • assets/config.example.json 2 KB
  • references/audit-checklist.md 5 KB
  • references/config.md 4 KB
  • references/directions.md 3 KB
  • references/pr-template.md 2 KB
  • references/reviewer-brief.md 3 KB
  • references/worked-example.md 5 KB
  • scripts/capture.mjs 7 KB
  • scripts/contrast-audit.mjs 14 KB
  • scripts/focus-sheet.mjs 8 KB
  • scripts/lib.mjs 20 KB
  • scripts/login.mjs 1 KB
  • scripts/palette-audit.mjs 19 KB
  • scripts/sheet.mjs 8 KB

Versions

RepositoryScoreLicence
This page · FlintSH/tinderbox100MPL-2.0
qml780/visual-polish-loop-skill100MIT

Database snapshot: 13.11.2026 · package version ab4efe11b0fb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100polish
    Applies visual polish and UI refinements to elevate aesthetic quality before deployment. This skill should be used when the user asks to "run visual polish", "polish the UI", "run Stage 6P", "fix visual defects", "enhance the UI", "improve the app aesthetics", "run UI…
  • 90design-audit
    Systematic visual UI/UX audit that produces phased, implementation-ready design plans, plus focused single-objective refinement passes ("lenses"). Use when the user asks to audit a UI, improve or polish an app's visual design, review design consistency, fix visual hierarchy, or…
  • 100quality-loop
    Loop UI work until quality gates pass — judge/build, test, audit, fix, repeat. Use for “rapihin sampai bagus”, polish until audit passes, fix Critical/High design findings, or /polish. Do not use for one-shot “rapihin detail”, copy-only rewrites, or “rapikan kode”.
  • 100team-ui-polish
    Unified team skill for UI polish. Auto-discover and fix UI design issues using Impeccable design standards. Anti-AI-slop detection, color/typography/spacing quality, motion, interaction states, visual hierarchy. Uses team-worker agent architecture. Triggers on "team ui polish",…
  • 100team-ui-polish
    Unified team skill for UI polish. Auto-discover and fix UI design issues using Impeccable design standards. Anti-AI-slop detection, color/typography/spacing quality, motion, interaction states, visual hierarchy. Uses team-worker agent architecture. Triggers on "team ui polish",…
  • 100polish
    Fixes the visual layer of an admin dashboard, tokens first - it screenshots home, index, detail and settings pages at 1440/1024/768/390 px, runs the visual-audit skill (spacing scale, type scale, colour use, computed contrast, radius, borders and shadows, icons, disabled and…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.