Polish Skill

What is the Impeccable polish skill?

Polish is one of 24 commands inside Impeccable, a design skill for AI coding agents. You run it as /impeccable polish on a feature, page or flow. It loads reference/polish.md, a final-pass playbook.

Its first rule is that polish is refinement, never concealed redesign. It preserves your visual world, content and behavior. If the concept itself is wrong, it says so and recommends redesign or bolder. If structure or type is the problem, run layout or typeset first.

What polish changes

• Broken, blocked and misleading states get fixed before any cosmetic work starts.
• Missing loading, empty, error, success, disabled and permission states are added.
• One-off values are replaced with your tokens and shared components.
• Hierarchy, spacing, type, color, icons and motion are made consistent across the whole path.
• Leftover code, redundant values and temporary artifacts are removed in a final source diff.

How polish works, in order

1. Read DESIGN.md, representative tokens, shared components and neighbouring flows to learn the quality bar.
2. Classify each drift: missing token, one-off implementation, conceptual mismatch or local defect.
3. Read the latest critique snapshot if one exists, then triage in a fixed five-step order.
4. Polish the whole path, not one corner, then verify with mouse, keyboard and touch.
5. Finish with a source diff and close the critique snapshot only if every priority issue is cleared.

Who Impeccable polish is for

Best for

• A feature that works but feels unfinished next to the rest of the product.
• The step right after critique, when you hold a ranked list of priority issues.
• Cleaning up AI-generated UI before it ships, including states nobody built.
• Teams with a DESIGN.md or tokens that new screens keep drifting away from.

Not for

• Changing the concept or visual identity. That is redesign or bolder.
• Rewriting factual copy. The reference says to ask before changing claims.
• Producing WordPress output. It edits front-end code in your project.

Use it with UiChemy

Polish finishes the build. When that build must live in WordPress, UiChemy AI to WordPress imports an existing AI build as an editable page, so the finished states come with it. Click Get Started on uichemy.com.

How to install Polish

npx impeccable install

1. Run the installer from your project root

   Run npx impeccable install. It lists the agent folders it detects, such as ~/.claude, ~/.codex or a project-local .cursor, lets you keep or change the set, then asks whether to install for this project or globally.

2. Skip the prompts in scripts

   Pass --providers=claude,codex,cursor and --scope=project (or global) to choose without questions. On Claude Code, Cursor, Codex, GitHub Copilot and Grok Build the installer also writes the provider-native design hook for the current project.

3. Reload your agent

   Restart or reload the harness so it picks up the new skill. In Codex, open /skills or type $impeccable.

4. Run init once

   Run /impeccable init. It reads the project, asks only for missing product facts, and writes PRODUCT.md so later commands know the audience, purpose and constraints.

5. Run polish

   Run /impeccable polish the signup flow. The target is optional and can be a page, a component or a file. /impeccable pin polish creates a standalone /polish shortcut.

Check that it loaded

Type /impeccable on its own. It shows the command list, and polish should be in it.

Read the official instructions on GitHub

Key features

• Refine, never redesignPolish preserves the incumbent visual world, content, behavior and everything outside scope. A wrong concept gets reported with a recommendation to redesign or go bolder, not a quiet replacement.
• Learns your quality barBefore changing anything it reads DESIGN.md, representative tokens, shared components, patterns and neighbouring flows. Without a formal system it follows the project's own conventions.
• Drift classificationEach inconsistency is labelled a missing token, a one-off implementation, a conceptual mismatch or a local defect, so the fix lands at the narrowest correct level.
• Critique snapshot inputimpeccable critique-storage latest returns the newest critique body. Polish names the snapshot it read and picks up the P0 and P1 findings. It exits 2 if none exists or the target changed, and polish then does an independent pass.
• Five-step triageOrder of work: broken or blocked tasks and data loss, missing states, flow and hierarchy and responsive drift, visual and motion inconsistencies, then code and asset cleanup. No corner is perfected while the rest stays rough.
• Whole-path coverageThe pass covers flow and hierarchy, layout and type, color and imagery, interaction states and content. It prevents image layout shift, keeps visible focus and logical tab order, and checks contrast in every state.
• Eight interaction statesDefault, hover, focus, active, disabled, loading, error and success are all expected to exist and look related, not just the default screen.
• Three-input verificationThe path is walked again with mouse, keyboard and touch. It checks console errors, layout shift, interaction latency and image loading, plus long-content and missing-content states.
• Asks before touching claimsTerminology, capitalization and punctuation are made consistent, but factual copy is not changed without asking. Binding system principles that cannot be inferred also trigger a question.
• Clean closeThe pass ends with a source diff that removes accidental churn and orphaned code. The critique snapshot is closed only when every priority issue it took is cleared.

Frequently asked questions