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-critique.md

View on GitHub
# critique — design review of one surface

**Job:** judge whether a surface is clear, specific to this product and well made, and name
the 3-5 problems that matter most. Critique edits nothing.

**Run when:** a surface has never been reviewed; the detector is clean but the page still feels
generic; before a large refine pass; after a redesign lands.

## By mode

- **Persuade / Showcase:** weight specificity, the first viewport, the path to the one action, and
  whether anything on the page could only belong to this product.
- **Operate / Read:** weight task completion, scan order, state coverage, wayfinding and density.
  Expression is judged as precision, not as volume.

## Change

Nothing. The output is a report.

## Do not touch

Source files, the context file, tokens. If you notice a one-line fix, list it; do not apply it.

## Steps

1. **Resolve the target** to a file path or route. A source path beats a dev-server URL because
   ports change and paths do not.
2. **Read the context file** (`interface-context.md`). Note the surface's mode and job. If there is
   no context file, say so in the report header and review against the product's own copy.
3. **Assessment A — design review, blind.** Read the source and, when a browser is available, look
   at the rendered page at a phone width and a desktop width. Do this before any detector output
   is in view; deterministic findings anchor judgment. Cover:
   - Specificity: could a competitor ship this layout, copy and palette unchanged?
   - Hierarchy: squint at it. Is there one obvious first thing, a second, then groups?
   - Task path: can the visitor do the surface's job without hunting? Count decision points with
     more than four visible options.
   - States: loading, empty, error, success, disabled, long content, permission-limited.
   - Copy: does every control name its outcome? Do errors say what failed and what to do?
   - Heuristics: score the ten usability heuristics 0-4 (see the scoring guide in
     `review-protocol.md`), marking any that cannot apply to this mode `n/a`.
4. **Assessment B — detector.** Run `ui_slop_detector.py <target> --context interface-context.md --format json`
   (without `--context` when there is no context file). Keep the output
   out of Assessment A. When subagents are available, run A and B as two separate subagents and
   merge only at synthesis (brief templates in `review-protocol.md`).
5. **Synthesize.** Where A and B agree, the finding is strong. Where B fired and A disagrees,
   check the source: name false positives explicitly. Where A found something B cannot see
   (hierarchy, specificity, copy tone), it stands on A's evidence.
6. **Write the report** from `assets/refinement-report-template.md`: method line, heuristic table,
   specificity verdict, what works (2-3), priority issues (3-5, P0-P3, each with the command that
   fixes it), persona red flags, then questions for the owner.
7. **End with the question.** Ask which issue to fix first. Nothing follows the question.

## Verify

- The report's first line states the method: `two assessments (A, B)` or
  `single context: <reason>` when the assessments could not be isolated.
- Every priority issue cites a file:line, a selector, or a rendered observation.
- Totals use the applicable maximum (4 x heuristics scored), never /40 over a partial set.
- Detector false positives are named, not silently dropped.

## Hand-off

The priority list becomes the plan: route each issue to its command, validate the plan with
`command_router.py --plan`, and finish with `polish`.
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