interface-refinement
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
Install / Use
npx skills add borghei/Claude-Skills --skill interface-refinementInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of interface-refinement
interface-refinement scores 89/100 on our quality scale, 1707th of 4,698 Development & Engineering skills we index (top 37%).
Its SKILL.md is 22 KB long, well organised into 30 sections with 1 code example: a thorough specification that gives an agent plenty to work with.
It has 817 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so interface-refinement is actively maintained.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
interface-refinement compared with similar skills
All 4 of these similar skills score higher than interface-refinement; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| interface-refinement (this skill)by borghei | 89 | 817 | 56d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
Frequently asked questions
- How do I install interface-refinement?
- Run
npx skills add borghei/Claude-Skills --skill interface-refinement. The install tabs above show the steps for each supported agent. - Which AI agents does interface-refinement work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is interface-refinement safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is interface-refinement still maintained?
- The repository was last updated about 2 months ago, so interface-refinement is actively maintained.
Skill content
View source on GitHubname: interface-refinement description: > 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. license: MIT + Commons Clause metadata: version: 1.0.0 author: borghei category: engineering domain: design-engineering updated: 2026-11-08 tags: [ui-refinement, design-critique, design-review, generic-ui, typography, color, motion, accessibility]
Interface Refinement
A shared vocabulary for improving interfaces that already exist. Each command names one kind of
change (distill removes, typeset fixes type, colorize gives colour a job, harden survives
real content), says what it may change and what it must leave alone, and ends with a check that
produces evidence. A context file records the product and its visual system so commands decide
from facts. A static detector finds the patterns that make an interface look assembled from
defaults: side stripes on rounded cards, gradient text, violet-to-cyan gradients, cream page
grounds, eyebrow labels over headings, cards inside cards, chip soup, rows of identical cards,
emoji icons, radial hazes, clip-path blobs, faint grey text, removed focus rings, broken images,
template headlines and vague button labels. Given the context file, it also reports every literal
colour, face, size and radius that has drifted outside the recorded system.
The agent reads the context file and the craft floor before any edit, keeps every change inside the named target, and never calls a refinement done without the evidence its command reference asks for: a rerun scan, a contrast ratio, a keyboard pass, screenshots at real widths.
Two rules hold across every command:
- Refinement preserves. Identity, behaviour, copy and everything outside the named target stay as they are. If the concept itself is wrong, say so and recommend a redesign; do not smuggle one into a polish pass.
- Scope is the contract. Every edit step lists what changes, what must not be touched, and how
the result is verified.
command_router.py --planrefuses plans that skip any of the three.
When to use this skill
- "This looks generic / AI-made / like every other SaaS page" on an existing page or app
- Critique or audit a surface before release, with scores and a prioritised fix list
- A focused pass: typography, colour and contrast, spacing and hierarchy, motion, UX copy, edge cases and focus, responsive adaptation, first-run and empty states
- "Tone it down" / "make it bolder" on a named section without restyling the rest
- Gate a pull request that touches markup or styles on generic-pattern and quality findings
- Write or check the project context file (product brief + design brief) that steers later work
- Native screens: platform conformance review for iOS and Android
Use engineering/design-auditor for letter grades and landing-page template detection,
engineering/a11y-audit for a WCAG scan of alt text, labels and landmarks. To choose a visual
direction or build a new site from nothing, use a design-direction or frontend-build skill; this
one refines what exists.
Clarify First
The target and its mode change every recommendation. Settle these before editing. When one is missing or vague and would change the result, ask; when it would not, use a sensible default and say which one you used.
- Target: the file, component or route, and what is out of scope. Refinement edits only the named target.
- Surface mode: persuade, operate, read or showcase (see
references/surface-modes.md). "Quieter" on a dashboard and on a landing page are different jobs. - Context file: does
interface-context.mdexist and pass the linter? If not, offerinitfor anything bigger than a one-line fix; do not block a narrow fix on it. - Binding brand decisions: faces, colours or devices the owner chose on purpose. They override detector findings (waive with a reason).
- Platform: web, iOS, Android or cross-platform; the web detector does not read native code.
Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.
Quick Start
# 1. Scan for generic and quality patterns (exit 1 on findings at or above medium)
python3 engineering/interface-refinement/scripts/ui_slop_detector.py \
engineering/interface-refinement/assets/sample_ui_flawed.* --format text
# 2. Route the findings to the next commands (exit 1 when access-blocking work exists)
python3 engineering/interface-refinement/scripts/ui_slop_detector.py src/ --format json > detector.json
python3 engineering/interface-refinement/scripts/command_router.py --report detector.json --mode operate
# 3. Validate the refinement plan before editing
python3 engineering/interface-refinement/scripts/command_router.py \
--plan engineering/interface-refinement/assets/sample_refinement_plan.json
# 4. Check shipped values against the recorded visual system (off-system-* rules, refusals fail)
python3 engineering/interface-refinement/scripts/ui_slop_detector.py src/ \
--context engineering/interface-refinement/assets/sample_context.md --format text
# 5. Lint the project context file
python3 engineering/interface-refinement/scripts/context_linter.py \
--input engineering/interface-refinement/assets/sample_context.md
Tools Overview
| Tool | Input | Output | Exit codes |
|------|-------|--------|------------|
| ui_slop_detector.py | files or directories (HTML, JSX, TSX, Vue, Svelte, Astro, CSS, SCSS, LESS); optional --context | findings with file:line, rule, severity, evidence, fix, owning command; summary by command | 0 clean at --fail-on, 1 findings, 2 bad input |
| command_router.py --report | detector JSON + mode + platform | 2-3 next commands in triage order, then polish; a plan skeleton | 0 routed, 1 access-blocking work found, 2 bad input |
| command_router.py --plan | refinement plan JSON | errors and warnings per step | 0 valid, 1 errors (warnings with --strict), 2 malformed |
| context_linter.py | interface-context.md | errors and warnings by section | 0 pass, 1 errors (warnings with --strict), 2 not a context file |
| ui_rules.py | --list [--scope S] or --contrast FG BG | rule catalog, or a WCAG ratio (translucent colours composited over white; pass the opaque ground for dark UIs) | 0 ok / ratio passes, 1 ratio fails, 2 bad colour, scope or catalog |
| system_checks.py | --context file + files | off-system values only (drift report for document and extract) | 0 / 1 / 2 |
| css_checks.py, markup_checks.py, class_checks.py, extra_checks.py | stylesheets, markup, or one class list | the detector's layers run alone, for debugging a rule | 0 / 1 / 2 |
| css_parse.py | one file | the CSS blocks and declarations the detector reads, for debugging a parse | 0 parsed, 2 bad input |
All tools are stdlib-only, offline, deterministic, and support --format text|json. Waive a
finding inline with ui-refine-ignore <rule> -- <reason>; waivers without a reason are rejected.
Commands
| Group | Command | Job | Detector rules routed here | Reference |
|-------|---------|-----|----------------------------|-----------|
| Evaluate | critique | design review, heuristic scores, 3-5 priority issues | none (judgment) | references/command-critique.md |
| Evaluate | audit | five-dimension technical score out of 20 | all, as evidence | references/command-audit.md |
| Context | init | write the product half of the context file | none | references/command-init.md |
| Context | document | record the shipped visual system | none | references/command-document.md |
| Context | extract | turn drift into tokens and shared components | off-system-color, off-system-font, off-system-radius, off-system-font-size | references/command-extract.md |
| Refine | polish | closing pass: states, alignment, browser surfaces | emoji-icon, skipped-heading, buried-raster | references/command-polish.md |
| Refine | distill | remove what does not earn its place | nested-cards, chip-soup, numbered-section-labels, shape-assembled-illustration | references/command-distill.md |
| Refine | quieter | lower the volume, keep the point of view | side-stripe-border, glow-shadow, radial-glow, organic-clip-path, hairline-wide-shadow, hard-offset-shadow, repeating-stripes, grid-line-background | references/command-quieter.md |
| Refine | bolder | raise one flat section with the system's own moves; "all-out" requests too | none (critique only) | references/command-bolder.md |
| Refine | harden | focus, overflow, i18n, errors, edge content | focus-ring-removed, broken-image | references/command-harden.md |
| Refine | clarify | labels, headlines, errors, empty states | vague-control-label, vague-headline | references/command-clarify.md |
| Enhance | typeset | roles, scale, reading comfort, a type decision | gradient-text, kicker-above-heading, italic-serif-display, overused-face, default-font-stack, tiny-text, all-caps-body, oversized-headline, flat-type-hierarchy, tight-body-leading, wide-body-tracking, crushed-tracking, justified-text, everything-bold | references/command-typeset.md |
| Enhance | colorize | colour roles, contrast, reflex palettes | low-contrast-pair, faint-gray-text, gray-on-color, ai-hue-gradient, cream-ground | references/command-colorize.md |
| Enhance | layout | lead element, grouping, rhythm, order | identical-card-row, icon-tile-stack, monotonous-spacing | references/command-layout.md |
| Enhance | animate | motion that explains, reduced-motion paths | missing-reduced-motion, transition-all, layout-property-motion, bounce-easing, decorative-pulse, marquee-scroll, blinking-cursor | references/command-animate.md |
| Enhance | optimize | no layout jumps, readable before fonts load, smooth motion | image-missing-dimensions, font-display-missing (and the motion rules it shares with animate) | references/command-optimize.md |
| Enhance | adapt | restructure for phone, tablet, print, email, other platforms | none (audit, critique) | references/command-adapt.md |
| Enhance | onboard | first run, empty states, time to first value | none (critique) | references/command-onboard.md |
| Enhance | delight | one considered, product-specific moment | none (owner request) | references/command-delight.md |
Routing
- No command named: run the detector, then
command_router.py --reportand offer its two or three picks with one-line reasons. Never auto-run; the user confirms the pick. - A command named or clearly implied ("fix the type", "it's too loud"): load that command's reference and follow it. If two fit, ask once.
- A clean scan: recommend
critique. The detector proves the floor, not the design. - Missing context file: a narrow fix proceeds on the existing code; offer
initafterwards. Anything wider (a redesign, a new surface, more than a few files) starts withinit. - Native platform:
critiqueandauditagainstreferences/native-platforms.md; skip the web detector.
Workflows
Workflow 1 — Refine a surface
- Settle target, mode and scope (Clarify First). Read
interface-context.mdif it exists. - Scan the target and the global styles together, so project-level rules (focus-visible,
reduced motion) see everything:
python3 engineering/interface-refinement/scripts/ui_slop_detector.py src/pages/invoices.tsx src/styles --format json > detector.json - Route:
command_router.py --report detector.json --mode operate. Access-blocking work (contrast, tiny text, focus, reduced motion) comes first. - Write the plan JSON: one step per command with
changes,must_not_touch,
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
