borghei/Claude-Skills / engineering/interface-refinement
interface-refinement
VerifiedRefine 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.
references/surface-modes.md
View on GitHub# Surface modes
A mode names what success looks like for the visitor on one surface. Choose it per surface, from
the visitor's goal, never from the product category, and record it in the context file's
Surfaces list. Every command scales its ambition by mode.
| Mode | The visitor is... | Success | Typical surfaces |
|------|------------------|---------|------------------|
| **Persuade** | deciding whether to act | they understand the offer and take the one action | landing, pricing, campaign, sign-up |
| **Operate** | doing a task | the task is done fast and correctly, state is never in doubt | app screens, dashboards, editors, settings, admin |
| **Read** | trying to understand | they find the answer and can keep reading comfortably | docs, help, articles, changelogs, guides |
| **Showcase** | looking at the work itself | the artifact leads and the interface recedes | portfolios, galleries, case studies, demos |
Examples that trip people up: a developer tool's homepage is **persuade**, not operate; a luxury
brand's help centre is **read**, not showcase; a docs index page is **read**; a pricing calculator
inside the app is **operate**.
## What each mode allows
| Decision | Persuade | Operate | Read | Showcase |
|----------|----------|---------|------|----------|
| Expression | full: composition, display type and colour may carry the voice | through precision: type, palette, density, one signature detail | in the frame (masthead, rail, headings); the column stays calm | the work leads; chrome is minimal |
| Layout | asymmetric, uneven, one dominant element per viewport | predictable grid, stable density, familiar controls | one reading column (60-75 characters), clear wayfinding | full-bleed work, generous space |
| Motion | one authored moment | feedback and continuity only | almost none | transitions between works |
| Copy | the hook in one line, an action that names its outcome | verb + object labels, specific states | headings that answer questions | captions and credits |
| Density | low to medium | medium to high, by expertise | low | low |
| Typical detector hits that matter most | gradient text, kicker, italic-serif hero, violet gradients, identical card rows | chip soup, nested cards, faint grey, removed focus | tight leading, wide tracking, justified text, tiny text | glows, marquee, decorative pulse |
## How commands read the mode
- **quieter:** persuade means more air and fewer simultaneous effects; operate means less colour
on containers and fewer borders and shadows.
- **bolder:** belongs to persuade and showcase. On operate it means a sharper type scale or a
committed shell colour, never effects. The router drops it on operate/read unless asked.
- **typeset:** persuade may use a display face and responsive sizes; operate and read favour one
family with a fixed role scale.
- **layout:** persuade may break the grid for one lead element; operate keeps the grid as an
affordance.
- **animate:** persuade gets one focal sequence; operate gets fast feedback; read gets almost
nothing.
- **delight:** operate and read concentrate it at completion and recovery moments only.
## A grey screen is not restraint
On operate surfaces the common failure is not too much expression but none: a grey shell with one
blue accent is the category default without the category leader's polish. Colour has jobs here
too: a committed shell colour, state colours, data series, selection. Restraint is a decision
about where colour goes, not its absence.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |