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/review-protocol.md

View on GitHub
# Review protocol: isolated assessments, finish review, waivers

## Why two assessments

Deterministic findings anchor judgment. A reviewer who has seen "14 findings, 3 nested cards"
reviews the 14 findings and stops looking at hierarchy, specificity and fit. So a critique runs
two assessments that never see each other until synthesis:

- **A — design review:** source and rendered page, judged as a design lead would.
- **B — detector:** `ui_slop_detector.py` output, each hit checked against the source line.

When subagents are available, run A and B as two separate subagents in parallel (for a desktop app
with one window, run A, wait, then B, so they do not fight over the window). Without subagents,
finish and write down A before running B, and say `single context: <reason>` in the report's
first line. A degraded run that does not say so is a failed run.

### Brief for subagent A (paste and fill)

```
Review <target path> as a design lead. Product context: <path to interface-context.md>.
Surface mode: <mode>. Do not run any detector or linter and do not read detector output.
Return: specificity verdict (could another product ship this unchanged? why), heuristic scores
0-4 with one-line evidence each (n/a allowed with reason), 2-3 things that work, 3-5 priority
issues tagged P0-P3 with file:line or rendered evidence, persona red flags for 2-3 personas,
and 2 provocative questions. Edit nothing.
```

### Brief for subagent B

```
Run: python3 <skill>/scripts/ui_slop_detector.py <target> [--context <interface-context.md>] --format json --fail-on advisory
Then open every finding's file:line and mark it confirmed or false positive with one line of
reasoning. Return counts by rule and severity, the confirmed list, the false positives, and any
file the detector could not read. Edit nothing.
```

## Heuristics scoring guide (0-4)

| # | Heuristic | 4 looks like | 0-1 looks like |
|---|-----------|--------------|----------------|
| 1 | Visibility of state | every action acknowledged within 100ms; progress shown for waits | silent saves, spinners with no context |
| 2 | Match with the real world | the user's words, real-world order | internal codes and jargon |
| 3 | Control and freedom | undo, cancel, back everywhere | destructive actions with no way out |
| 4 | Consistency | same words and controls for the same things | three button styles for one action |
| 5 | Error prevention | constraints and defaults stop mistakes | free text where a picker belongs |
| 6 | Recognition over recall | options visible, recent items offered | users must remember codes between screens |
| 7 | Flexibility | shortcuts and bulk actions for experts | eight clicks for the daily task |
| 8 | Minimal design | every element earns its place | equal-weight clutter, decoration |
| 9 | Error recovery | errors say what, why, what now | "Something went wrong" |
| 10 | Help | contextual help where questions arise | none, or a PDF |

Heuristics 7 and 10 may be `n/a` on persuade and showcase surfaces. The total's maximum is 4 x the
number scored. Most real interfaces land between 55% and 80% of their maximum; a 4 means
genuinely excellent.

## Personas for red flags

Pick two or three by surface: a **power user** (keyboard, bulk work, impatience), a **first-timer**
(no product vocabulary, low confidence), a **keyboard and screen-reader user**, a **stress tester**
(long names, empty data, slow network, double clicks), a **one-handed phone user** (outdoors,
interrupted). Add one from the context file's Users section. For each, walk the primary task and
list what broke, by element. No generic persona prose.

## Severity

- **P0 blocking:** a task cannot be completed, data can be lost, state is misleading.
- **P1 major:** WCAG AA failure or significant difficulty.
- **P2 minor:** an annoyance with a workaround.
- **P3 polish:** no real user impact. Keep these few.

## Finish review (after a refine plan)

A fresh reviewer, outside the thread that did the work, reads the before/after screenshots, the
diff, the context file and the craft floor, and returns one word first:

| Disposition | When |
|-------------|------|
| `re-evidence` | screenshots are missing, blank, the wrong surface or the wrong width |
| `rework` | the change replaced the identity, or broke scope (edits outside the target) |
| `fix` | one or more material fixes remain; list them, most material first, at most eight |
| `ship` | no material fixes and no floor refusal visible |

The word is derived from the checks, never felt. A refused element from the craft floor is a
material fix even if the owner's mock-up contained it.

## Waivers (inline ignores)

The detector honours `ui-refine-ignore <rule> -- <reason>` (this line and the next) and
`ui-refine-ignore-file <rule|*> -- <reason>`. A waiver without a reason is rejected and reported.

1. **Real problem:** fix it. Never waive to get a gate green.
2. **Confident false positive or confirmed exception:** waive the narrowest scope (one line, one
   rule) and name the evidence in the reason: `-- owner confirmed: literal ball-bounce animation`.
   Write "owner confirmed" only when the owner did.
3. **Unsure:** leave the finding standing and say why in one line.

File-wide waivers are for fixtures, generated files and deliberate before/after demos. Never use
`*` on a real product surface.
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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall