Skip to content

borghei/Claude-Skills / engineering/interface-refinement

interface-refinement

Verified

Refine an existing interface with named commands (critique, polish, distill, typeset, colorize ...), a product and design context file, and a static detector of generic UI patterns. Use when UI looks generic, cluttered or unfinished.

FileKindSize
SKILL.mdskill md22.1 KB
assets/interface-context-template.mdmarkdown2.6 KB
assets/refinement-report-template.mdmarkdown1.5 KB
assets/sample_context.mdmarkdown3.8 KB
assets/sample_context_flawed.mdmarkdown730 B
assets/sample_detector_report.jsonconfig387 B
assets/sample_detector_report_flawed.jsonconfig48.8 KB
assets/sample_refinement_plan.jsonconfig1.7 KB
assets/sample_refinement_plan_flawed.jsonconfig893 B
assets/sample_ui_flawed.cssother2.5 KB
assets/sample_ui_flawed.htmlother4.5 KB
assets/sample_ui_flawed.tsxother1.1 KB
assets/sample_ui_sound.cssother2.3 KB
assets/sample_ui_sound.htmlother2.6 KB
assets/sample_ui_sound.tsxother1.3 KB
references/command-adapt.mdmarkdown2.7 KB
references/command-animate.mdmarkdown2.6 KB
references/command-audit.mdmarkdown3.5 KB
references/command-bolder.mdmarkdown3.2 KB
references/command-clarify.mdmarkdown2.8 KB
references/command-colorize.mdmarkdown2.7 KB
references/command-critique.mdmarkdown3.5 KB
references/command-delight.mdmarkdown1.8 KB
references/command-distill.mdmarkdown2.3 KB
references/command-document.mdmarkdown3.3 KB
references/command-extract.mdmarkdown3.4 KB
references/command-harden.mdmarkdown2.5 KB
references/command-init.mdmarkdown2.9 KB
references/command-layout.mdmarkdown2.3 KB
references/command-onboard.mdmarkdown2.2 KB
references/command-optimize.mdmarkdown3.4 KB
references/command-polish.mdmarkdown2.8 KB
references/command-quieter.mdmarkdown2.3 KB
references/command-typeset.mdmarkdown2.9 KB
references/craft-floor.mdmarkdown3.7 KB
references/detector-rules.jsonconfig22.6 KB
references/detector-rules.mdmarkdown14.5 KB
references/native-platforms.mdmarkdown4.6 KB
references/review-protocol.mdmarkdown5.2 KB
references/surface-modes.mdmarkdown3.4 KB
scripts/class_checks.pyscript12.3 KB
scripts/command_router.pyscript12.7 KB
scripts/context_linter.pyscript13.4 KB
scripts/css_checks.pyscript12.3 KB
scripts/css_parse.pyscript7.6 KB
scripts/extra_checks.pyscript12.7 KB
scripts/markup_checks.pyscript14.6 KB
scripts/system_checks.pyscript9.4 KB
scripts/ui_rules.pyscript12.5 KB
scripts/ui_slop_detector.pyscript12.1 KB

references/command-polish.md

View on GitHub
# polish — the closing pass

**Job:** bring a functionally complete surface up to one consistent finish without changing what
it is. Polish is refinement, never a disguised redesign.

**Run when:** last in every refine plan; before a release; when the detector reports
`emoji-icon`, `skipped-heading` or `buried-raster`; when a critique snapshot lists P2/P3 issues.

## By mode

- **Persuade / Showcase:** the first viewport, the primary action and the imagery get the closest
  look; one authored motion moment at most.
- **Operate / Read:** alignment, state coverage, keyboard path and density consistency across
  neighbouring screens.

## Change

- Drift from the system: classify each one first. A **missing token** (the system needs a value)
  gets a token; a **one-off** gets the shared component; a **local defect** gets fixed in place; a
  **concept mismatch** (flow differs from neighbouring screens) is reported, not patched.
- Alignment and spacing to the scale; optical alignment of icons and numerals.
- Every interactive state: default, hover, focus-visible, active, disabled, loading, error, success.
- The parts the browser draws by default: text selection colour, caret, focus ring, scrollbar on
  scroll regions, link underline offset, tabular numerals in tables.
- Icons: one family, one stroke, one size scale; replace emoji used as icons.
- Heading outline: no skipped levels (restyle a lower level instead).
- Clean-up the pass itself created: dead styles, duplicate values, debug output.

## Do not touch

- The visual identity: palette, type families, layout topology, imagery direction.
- Copy that states facts or claims. Ask before changing it.
- Anything outside the named target. If the concept is wrong, say so and recommend `critique` or
  a redesign instead of smuggling one in.

## Steps

1. Read the context file and the tokens. Find two neighbouring screens for comparison.
2. Use the surface yourself at 360px, ~768px and 1280px (or the platform's device classes).
3. Triage in this order: broken or blocked tasks; missing states; flow and hierarchy drift;
   visual and motion inconsistencies; code clean-up. Do not perfect one corner while the rest stays
   below the bar.
4. Fix at the narrowest correct level (token, shared component, or local).
5. Rerun the detector on the target.

## Verify

- `ui_slop_detector.py <target> --context interface-context.md --fail-on advisory` exits 0 (drop
  `--context` when there is none), or every remaining finding carries a waiver with a reason.
- A keyboard pass reaches every control in visual order with a visible ring.
- Screenshots at each width show no overflow, clipped text or orphaned controls.
- The source diff contains only scoped changes; no accidental churn.

## Hand-off

None; polish closes the plan. If a critique report fed this pass, mark which of its issues are
now closed.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall