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

View on GitHub
# optimize — make the interface load and move without stutter

**Job:** remove the front-end causes of slow first paint, layout jumps and janky motion on the
named target, without changing how it looks.

**Run when:** the detector reports `image-missing-dimensions`, `font-display-missing`,
`layout-property-motion` or `transition-all`; someone says "slow", "laggy", "jumps when it loads";
field data shows poor loading, interaction or layout-stability numbers.

## By mode

- **Persuade:** the first screen is the budget. The largest image or headline must paint fast, and
  nothing above the fold may move after it appears.
- **Operate:** interaction speed matters more than first paint. Long lists, heavy re-renders and
  input lag are the usual causes.
- **Read:** fonts and images. Text must be readable before the web font arrives.

## Diagnose first (static signals this skill can read)

| Symptom | Static cause to look for | Fix |
|---------|-------------------------|-----|
| Content jumps while loading | `<img>` / `<video>` / embeds without width and height or aspect-ratio | add intrinsic dimensions; reserve space for late banners and ads |
| Blank text on slow networks | `@font-face` without `font-display`; four or more font files on the first screen | `font-display: swap`; subset; preload the one or two faces above the fold |
| Janky transitions | transitions or keyframes on width, height, top, left, margin, padding; `transition: all` | animate `transform` and `opacity`; name the properties |
| Slow largest paint | hero image lazy-loaded, unsized or served at full camera resolution | eager-load and size the hero; serve responsive `srcset` and a modern format |
| Sluggish scroll | `background-attachment: fixed`, large `filter: blur()` or `backdrop-filter` on scrolling layers, `will-change` on many elements | drop or confine the effect; set `will-change` only during the animation |
| Long lists stall | hundreds of rows rendered at once in source | paginate or window the list; keep row markup flat |

What needs a browser or field data (actual paint times, interaction delay, bundle size) is out of
reach of a static scan: measure it with the project's own tooling and record the numbers.

## Change

- Markup attributes (dimensions, `loading`, `decoding`, `fetchpriority`, `srcset`), font loading,
  animated properties, and list rendering inside the target.

## Do not touch

- The look. Every optimisation must be invisible in a side-by-side screenshot, except that things
  stop moving.
- Content and copy.
- Build tooling and dependencies, unless the owner asks; propose the change instead.

## Steps

1. Record a baseline: the detector's `--scope layout,motion,type` findings on the target, plus any
   field or lab numbers the team already has.
2. Fix layout shift first (dimensions, reserved space), then font loading, then motion, then list
   rendering. Shift is the defect people feel most.
3. Recheck after each family; stop when the remaining cost is not on the first screen or the
   primary task.

## Verify

- Detector on the target: no `image-missing-dimensions`, `font-display-missing`,
  `layout-property-motion` or `transition-all` findings left unwaived.
- Before/after screenshots at 360px and 1280px are identical.
- The same measurement as the baseline, rerun, with both numbers in the report.
- Reduced-motion still honoured after any motion change.

## Hand-off

`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: 319kUpdated 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