agentleFS
thewyattbrocatothewyattbrocato/design-and-copy-skills/skills/ui-polish-pass/SKILL.md

ui-polish-pass

Skill2 starsChanged 12 days agoMITView on GitHub

Use whenever an interface should be finished, not just functional, however the ask is worded - "final touches", "make it production-ready", "it looks rough or half-done", "before we ship, anything missing", "what did I forget", "handle the edge cases", "empty, loading and error states", "accessibility pass", "less generic", "clean this up", "demo on Monday", "last two days before launch" - and also when the ask is only a short plain description of a screen, form, list, dashboard or panel to build or complete ("a simple order page", "a small settings screen"), where the unstated wish is that it be good. Covers every state (empty, loading, error, success, disabled, focus), forms, keyboard and screen-reader access, contrast, dark theme, long content, narrow screens and motion, in HTML, CSS, components or a described screen. Leaves what works alone. Not for visual redesigns, scored critiques (design-critique) or one named fix.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Add a dark theme, motion, new features, new copy tone or a new component only if the project already has one or the request names it.

    line 19
  2. Distinctive:

    Do not widen a narrow ask into a sweep.

    line 20
  3. Distinctive:

    If the thing is already in good shape, say so in a sentence, name what works, and change at most a few lines.

    line 21
  4. Distinctive:

    Motion: keep what has a job (feedback, orientation).

    line 36
  5. Distinctive:

    Ask: "change the Submit label on the newsletter form, nothing else".

    line 66

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

UI polish pass

Generated interfaces stop at the happy path. Finishing means the unhappy path works: failure, waiting, nothing to show, too much to show, a keyboard, a small screen. The usual mistakes run the other way too: a polish request turned into a redesign, an unrequested dark theme, a rewritten file, a lecture. Fix what is broken, keep what works, stay in proportion to the ask.

When not to use

  • A new design from nothing: build it, with the focused skills if installed. A judged review or score with no changes: design-critique, if installed.
  • System-level tokens and component libraries: design-system-builder, if installed.
  • One named fix ("change the label", "nothing else"): do exactly that, briefly.

Scope first

  • The existing look is a decision. Keep layout, palette, type, field order and wording unless one is itself the defect. New states and fixes should look like they were always there.
  • Add a dark theme, motion, new features, new copy tone or a new component only if the project already has one or the request names it. If a dark theme exists, check it; do not invent one.
  • Do not widen a narrow ask into a sweep.
  • If the thing is already in good shape, say so in a sentence, name what works, and change at most a few lines. Do not invent problems to look thorough, and do not pad a short list of real ones.
  • An explicit instruction, an existing design system or a platform convention beats every default here. Reuse its tokens and components.

Find the gaps by state

Walk each component in scope through the states for its type and skip any that cannot occur. Check these first, because generated code misses them most:

  • Submit and async actions: acknowledged within about a tenth of a second (busy state, no double-submit), a visible result in words, a failure that keeps what the person typed and offers retry. A silent fetch is the commonest defect.
  • Empty: first use says what the place is for and offers the first action; no results says what was searched and offers to clear it; no dead controls on an empty list.
  • Errors: what happened, why if known, what to do next, in plain words. Beside the field or near the failed action, persistent until fixed, announced to assistive tech, focus on the first problem. Never only a vanishing toast; never "Something went wrong".
  • Disabled: a visible reason beside the control, or enabled and explaining on press.
  • Undo or confirm: reversible actions (archive, remove, move) act now and offer undo for several seconds. Confirm only what cannot be taken back, name the consequence, and put verbs on the buttons ("Delete project", "Keep it"). Leaving (cancel, unsubscribe, export) is never harder than joining.
  • Access floor: every control has an accessible name (repeated "open" links or icon-only buttons name their target); focus is visible on every control and never lost after a deletion or dialog close; the task works by keyboard; meaning never rests on color or hover alone (severity gets a word or icon); text and input borders meet contrast; the layout survives 200% text and a 320-pixel width. Numbers are in the reference. When the page's code is in hand, also check the page itself: skip link, title and h1, order, names, hidden-from-assistive-tech, bottom bars over focus (page and focus access).
  • Long and many: the longest realistic name, long unbroken words and URLs, zero, one and hundreds of items. Wrap or truncate with a route to the full text; never clip a label that names an action. A slow or offline network, a hurried or upset person, one hand: hard moments and conditions.
  • Specific to this screen: labels, empty and error messages, sample values and defaults use this product's own nouns and the person's situation. If the same words would fit any other product, replace them using only facts the request gives. Put the help or detail the person likely needs next (a failed payment, a changed time, a wait) at that point. No mascots, slogans or new features.
  • Motion: keep what has a job (feedback, orientation); frequent paths fast and interruptible; reduced-motion removes movement but keeps the state change visible.

Fix in order of harm

Blocks a task or excludes people (no name, no focus, trapped, lost input), then misleads (silent failure, false success), then degrades (truncation, layout break), then cosmetic. Fix at the source, a token or shared component, once. Re-walk the states you touched, with real text lengths. Then walk the main task once, first screen to result: parts fine alone can still disagree in name, order or wording.

Missing facts

Never invent a retry count, response time, support address, phone number, limit, policy, deadline or other fact the user did not give. Use a visible placeholder like [support link] or a softer true sentence, and still deliver the work. If the real causes, limits or copy are unknown, infer from the material and proceed; ask once only if the chat is interactive and the answer is cheap and changes the work. Never answer with only questions.

Do not produce

  • A redesign, a new visual style, a theme or feature nobody asked for, or copy rewrites where the existing copy works.
  • A checklist, matrix or audit table in place of the fixed code or the ranked findings.
  • "Oops", "Error 500", "No data", "Are you sure?", a spinner with no way out, outline: none with no replacement, an icon button with no name, a confirm where undo would do, a joke, exclamation or confetti in a failure, payment or loss moment.
  • Pre-checked consent, shaming decline wording, a harder cancel than sign-up, fake urgency.
  • A claim that something is accessible or tested when you only read the code. You cannot run a screen reader, a server or a real device here; say what you did not check.

Deliver

  • Lead with the work: the changed code, the screen or the answer. No preamble, no restating the input.
  • Code: return the whole file only when asked for it or when most of it changed; otherwise the changed pieces. Send code only if you changed something. Keep the original's structure, naming and style so the diff stays small.
  • Asked what is rough or worth checking: findings ranked by harm, each with a targeted fix and a one-line reason, not a rewrite. Open with what already works, in a line.
  • Asked for a count or a set (three fixes, the states, a checklist): give exactly that. Honor any word cap and count rather than assert.
  • Then at most two one-line notes: what remains or needs a design decision, and what you did not check.

Example

Ask: "polish this task list for release". Before: a list that renders items only, an icon-only delete, outline: none. After: an empty state with an "Add a task" action; a skeleton while loading and an inline error with Retry that keeps the list; the delete named "Delete: Buy milk" with an Undo bar; focus ring restored; long titles wrapping. Same colors, spacing and type as before. Closing note: "Not tested with a screen reader."

Ask: "change the Submit label on the newsletter form, nothing else". Answer: the new label (for example "Subscribe") and one line of why. No other edits.

For the full state list per component type, thresholds and fast tests, read references/states-and-checks.md. For page titles, headings, source order, focus handling and names in code, read references/page-and-focus-access.md. For a screen that meets money, loss, lockout, urgency or the person's own history, or must work on a poor connection or by more than one route, read references/hard-moments-and-conditions.md. For full procedures use form-design, ui-motion, color-palette, typesetting, spacing-and-grouping, responsive-layout and design-system-builder, each if installed.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.