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/detector-rules.json

View on GitHub
{
  "version": "1.0.0",
  "severities": ["high", "medium", "advisory"],
  "scopes": ["color", "type", "layout", "motion", "surface", "structure", "copy", "interaction"],
  "rules": [
    {"id": "side-stripe-border", "name": "Colored stripe on one side of a card", "family": "generic", "severity": "high", "scope": "surface", "command": "quieter",
     "why": "A thick colored rule down one edge of a rounded card is the most recognisable machine-made card. It adds a color that carries no meaning and fights the corner radius.",
     "fix": "Drop the stripe. If the item needs a status, put a labelled marker or tinted heading inside it; if it needs separation, use spacing or a full 1px border."},
    {"id": "gradient-text", "name": "Gradient-filled text", "family": "generic", "severity": "high", "scope": "type", "command": "typeset",
     "why": "Clipping a gradient into letters makes emphasis decorative and lowers contrast unevenly across the word.",
     "fix": "Set the text in one solid color from the palette and create emphasis with size, weight or placement."},
    {"id": "ai-hue-gradient", "name": "Violet-to-blue or violet-to-cyan gradient", "family": "generic", "severity": "medium", "scope": "color", "command": "colorize",
     "why": "Gradients that sweep from violet into blue, cyan or pink are the default palette of generated interfaces and say nothing about this product.",
     "fix": "Pick hues from the product's own palette roles. If a gradient is wanted at all, keep it within one hue family and give it a job (a surface, a data ramp)."},
    {"id": "glow-shadow", "name": "Colored zero-offset glow", "family": "generic", "severity": "medium", "scope": "surface", "command": "quieter",
     "why": "A chromatic halo with no offset is decoration pretending to be depth; on dark grounds it is the stock 'futuristic' look.",
     "fix": "Use a neutral shadow with a vertical offset and soft blur for elevation, or no shadow. Signal focus and selection with a ring or fill, not a glow."},
    {"id": "hard-offset-shadow", "name": "Hard offset block shadow", "family": "generic", "severity": "advisory", "scope": "surface", "command": "quieter",
     "why": "A zero-blur shadow pushed several pixels out belongs to a deliberate brutalist look. Outside one, it is a costume.",
     "fix": "Keep it only if the design brief chose that style; otherwise replace it with the project's elevation token."},
    {"id": "cream-ground", "name": "Reflex cream or beige page ground", "family": "generic", "severity": "medium", "scope": "color", "command": "colorize",
     "why": "A warm off-white page background has become the default 'tasteful' surface. Chosen by habit it reads as a template.",
     "fix": "Derive the ground from the palette roles in the context file. Keep cream only when the brief names it (paper, print heritage) and record why."},
    {"id": "overused-face", "name": "Overused default typeface", "family": "generic", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "A handful of faces now ship on most generated pages, so they carry no identity of their own.",
     "fix": "Choose a face for a reason the product can state (voice, legibility at its sizes, script coverage) and record it in the type roles. Keep a common face only when the brief binds it."},
    {"id": "default-font-stack", "name": "Bare system font stack as the voice", "family": "generic", "severity": "advisory", "scope": "type", "command": "typeset",
     "why": "A page whose only family is the platform default never made a type decision. Fine for dense tools; weak for a persuade or showcase surface.",
     "fix": "On persuade and showcase surfaces, pick a display or text face. On operate surfaces, keep the system stack but record it as the decision."},
    {"id": "italic-serif-display", "name": "Italic serif hero headline", "family": "generic", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "An oversized italic serif headline is the current generated-startup hero; it reads as borrowed taste.",
     "fix": "Set the headline roman, or move italic to a single word that earns it. Choose the display face from the type roles."},
    {"id": "tiny-text", "name": "Text below 12px", "family": "quality", "severity": "high", "scope": "type", "command": "typeset",
     "why": "Text under 12px is hard to read on most screens and fails people who need larger text first.",
     "fix": "Use 16px for body, 14px for dense UI and at least 12px for captions and labels. Use weight or color, not size, for de-emphasis."},
    {"id": "tight-body-leading", "name": "Tight line height on running text", "family": "quality", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "Line height under 1.3 on paragraphs makes lines collide and readers lose their place.",
     "fix": "Use 1.45 to 1.7 for body copy; tighten only headings and single-line labels."},
    {"id": "wide-body-tracking", "name": "Wide letter spacing on running text", "family": "quality", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "Tracking above 0.05em on lowercase body text breaks word shapes and slows reading.",
     "fix": "Reset body tracking to the face's default; keep wide tracking for short uppercase labels only."},
    {"id": "crushed-tracking", "name": "Letter spacing tighter than -0.04em", "family": "quality", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "Past about -0.04em letters touch and display type turns into a smear.",
     "fix": "Tighten display type between -0.01em and -0.03em and check the rendered word at every breakpoint."},
    {"id": "justified-text", "name": "Justified text without hyphenation", "family": "quality", "severity": "advisory", "scope": "type", "command": "typeset",
     "why": "Justifying a web column without hyphenation opens uneven gaps and rivers.",
     "fix": "Use text-align: start, or add hyphens: auto with a lang attribute and a measure of 60 characters or more."},
    {"id": "low-contrast-pair", "name": "Text and background below WCAG AA", "family": "quality", "severity": "high", "scope": "color", "command": "colorize",
     "why": "The declared text and background colors in one rule fall below 4.5:1 (3:1 for large text).",
     "fix": "Darken the text or lighten the ground until the pair passes; use ui_rules.py --contrast to confirm."},
    {"id": "faint-gray-text", "name": "Light gray text class on a light ground", "family": "quality", "severity": "high", "scope": "color", "command": "colorize",
     "why": "Utility grays at the 200-400 steps sit around 1.5:1 to 2.9:1 on white, below AA for any text.",
     "fix": "Use the 500 step or darker for secondary text on light grounds, or a muted-text token that passes 4.5:1."},
    {"id": "gray-on-color", "name": "Neutral gray text on a colored ground", "family": "quality", "severity": "medium", "scope": "color", "command": "colorize",
     "why": "Gray on a saturated surface looks washed out and often fails contrast.",
     "fix": "Use a darker or lighter shade of the surface hue, or white/near-black, for secondary text on colored surfaces."},
    {"id": "bounce-easing", "name": "Bounce or overshoot easing", "family": "generic", "severity": "advisory", "scope": "motion", "command": "animate",
     "why": "Overshoot and bounce curves read as toy-like and slow the interface down; they belong only where the subject literally bounces.",
     "fix": "Use a decelerating curve such as cubic-bezier(0.2, 0.8, 0.2, 1) and shorten the duration."},
    {"id": "transition-all", "name": "transition: all", "family": "quality", "severity": "medium", "scope": "motion", "command": "animate",
     "why": "Transitioning every property animates things nobody designed (layout, color flashes on theme change) and costs frames.",
     "fix": "List the properties that should move, usually opacity, transform, color or box-shadow."},
    {"id": "layout-property-motion", "name": "Animating layout properties", "family": "quality", "severity": "medium", "scope": "motion", "command": "animate",
     "why": "Animating width, height, top, left, margin or padding forces layout on every frame and stutters on mid-range devices.",
     "fix": "Animate transform and opacity, or use a grid-rows / FLIP technique for size changes."},
    {"id": "missing-reduced-motion", "name": "Animation with no reduced-motion path", "family": "quality", "severity": "high", "scope": "motion", "command": "animate",
     "why": "Keyframe animation ships with no prefers-reduced-motion alternative anywhere in the scanned files.",
     "fix": "Add a prefers-reduced-motion: reduce block (or motion-safe / motion-reduce utilities) that removes movement but keeps state changes visible."},
    {"id": "decorative-pulse", "name": "Pulsing status dot", "family": "generic", "severity": "medium", "scope": "motion", "command": "animate",
     "why": "An endlessly pulsing dot fakes liveness. Unless it tracks data that really changes, it is noise that pulls the eye.",
     "fix": "Use a static, labelled status indicator. Animate only when the underlying state changes."},
    {"id": "marquee-scroll", "name": "Auto-scrolling marquee", "family": "generic", "severity": "medium", "scope": "motion", "command": "animate",
     "why": "Content that scrolls by itself hides half of itself at any moment and cannot be read at the visitor's pace.",
     "fix": "Show the items as a static row or wrap; if motion is essential, add pause on hover and focus and a reduced-motion stop."},
    {"id": "focus-ring-removed", "name": "Focus outline removed with no replacement", "family": "quality", "severity": "high", "scope": "interaction", "command": "harden",
     "why": "Removing the outline without a :focus-visible style leaves keyboard users unable to see where they are.",
     "fix": "Keep outline: none only alongside a :focus-visible ring of at least 2px that contrasts 3:1 with its surroundings."},
    {"id": "repeating-stripes", "name": "Decorative repeating stripes", "family": "generic", "severity": "advisory", "scope": "surface", "command": "quieter",
     "why": "Repeating-gradient stripes as surface texture are a recurring generated signature.",
     "fix": "Leave the surface plain or use a texture that comes from the product's subject."},
    {"id": "grid-line-background", "name": "Decorative grid-paper background", "family": "generic", "severity": "advisory", "scope": "surface", "command": "quieter",
     "why": "Hairline grid overlays belong on canvases, maps and measuring tools. Elsewhere they are filler.",
     "fix": "Remove the grid unless the surface is a canvas or measurement view; let spacing carry structure."},
    {"id": "monotonous-spacing", "name": "One spacing value everywhere", "family": "quality", "severity": "advisory", "scope": "layout", "command": "layout",
     "why": "When one value covers most padding, margin and gap declarations, nothing groups and nothing separates; every block weighs the same.",
     "fix": "Use a scale: tight steps inside groups, larger steps between groups, the largest between sections."},
    {"id": "everything-bold", "name": "Most text set bold", "family": "generic", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "When most text is semibold or heavier, weight stops signalling anything and the page has no hierarchy.",
     "fix": "Return body and secondary text to regular weight; keep heavy weights for headings and the one value per block that matters."},
    {"id": "nested-cards", "name": "Card inside a card", "family": "generic", "severity": "high", "scope": "structure", "command": "distill",
     "why": "Boxes inside boxes add borders, shadows and padding without adding meaning, and squeeze the content.",
     "fix": "Keep the outer container and turn inner cards into rows, sections with headings, or dividers."},
    {"id": "kicker-above-heading", "name": "Eyebrow label above a heading", "family": "generic", "severity": "high", "scope": "type", "command": "typeset",
     "why": "A tiny tracked uppercase label sitting on top of a heading is template scaffolding; the heading should carry itself.",
     "fix": "Delete the label, or fold its information into the heading or the sentence below it."},
    {"id": "icon-tile-stack", "name": "Icon in a rounded tile stacked over a heading", "family": "generic", "severity": "medium", "scope": "layout", "command": "layout",
     "why": "A tinted rounded square holding an icon above each heading is the stock feature-card shape.",
     "fix": "Drop the tile, set the icon inline with the heading, or replace the icon with something only this product can show (a number, a screenshot crop)."},
    {"id": "chip-soup", "name": "Too many pills and badges", "family": "generic", "severity": "medium", "scope": "structure", "command": "distill",
     "why": "When every attribute becomes a rounded chip, status stops standing out and the block turns into confetti.",
     "fix": "Keep one chip for the status that drives a decision; show the rest as plain text or metadata rows."},
    {"id": "identical-card-row", "name": "Row of identical equal-weight cards", "family": "generic", "severity": "medium", "scope": "layout", "command": "layout",
     "why": "Three or more cards with the same classes and the same icon-heading-text recipe give every item equal weight, so nothing leads.",
     "fix": "Decide which item matters most and let it lead (size, position, content); render the rest as a list or a different form."},
    {"id": "emoji-icon", "name": "Emoji or glyph standing in for an icon", "family": "generic", "severity": "medium", "scope": "surface", "command": "polish",
     "why": "Emoji render differently on every platform, ignore the palette and read as placeholder icons.",
     "fix": "Use one drawn icon set with a single stroke and weight, with aria-hidden on decorative icons and a text label on controls."},
    {"id": "vague-control-label", "name": "Control label that does not name its action", "family": "quality", "severity": "medium", "scope": "copy", "command": "clarify",
     "why": "Labels such as Submit, OK or Click here make people read around the control to learn what it does.",
     "fix": "Name the outcome with a verb and object: Save changes, Send invoice, Delete 3 files."},
    {"id": "vague-headline", "name": "Template headline", "family": "generic", "severity": "medium", "scope": "copy", "command": "clarify",
     "why": "Headlines like 'Welcome to X' or 'The all-in-one platform' could sit on any product and tell the visitor nothing.",
     "fix": "State what the product does for whom, using the product's own nouns from the context file."},
    {"id": "skipped-heading", "name": "Heading level skipped", "family": "quality", "severity": "medium", "scope": "structure", "command": "polish",
     "why": "Jumping from h1 to h3 breaks the outline that screen-reader users navigate by.",
     "fix": "Use the next level down and style it to the size you wanted."},
    {"id": "numbered-section-labels", "name": "01 / 02 / 03 section numbering", "family": "generic", "severity": "advisory", "scope": "structure", "command": "distill",
     "why": "Numbering sections that are not a real sequence is editorial costume.",
     "fix": "Remove the numbers unless the reader must follow the order (steps, a procedure)."},
    {"id": "radial-glow", "name": "Coloured radial haze behind a section", "family": "generic", "severity": "medium", "scope": "surface", "command": "quieter",
     "why": "A saturated radial gradient fading to transparent behind a hero or section reads as a coloured cloud floating over the copy. It is a reflex decoration that lights nothing in particular.",
     "fix": "Let the surface stand plain, or shift the ground a step lighter or darker. If a section needs emphasis, give it a real image, a border or more space."},
    {"id": "organic-clip-path", "name": "Blob or torn edge drawn with clip-path", "family": "generic", "severity": "medium", "scope": "surface", "command": "quieter",
     "why": "A polygon with a dozen irregular points, or a curved path(), is code imitating a cut-out, a torn paper edge or a blob. It looks like the cheap version of a material that should have been an image.",
     "fix": "Ship the shape as an image with transparency, or drop it. Keep clip-path for geometry: a cut corner, a diagonal, a hexagon."},
    {"id": "hairline-wide-shadow", "name": "Hairline border plus a wide soft shadow on cards", "family": "generic", "severity": "advisory", "scope": "surface", "command": "quieter",
     "why": "A 1px border and a large diffuse shadow on the same card is two elevation systems at once. On one floating panel it can work; on every card in a grid it is a default nobody chose.",
     "fix": "Pick one edge for the card family: a defined 1px border or a soft shadow with a short vertical offset. Keep both only for a popover or dialog that truly floats."},
    {"id": "blinking-cursor", "name": "Decorative blinking text cursor", "family": "generic", "severity": "advisory", "scope": "motion", "command": "animate",
     "why": "A caret blinking at the end of a headline fakes a typing prompt where nothing can be typed. It borrows a developer-tool look as decoration and keeps the eye moving.",
     "fix": "Remove the fake caret. Real inputs draw their own. If the product is a terminal or editor, show a real one in a product screenshot."},
    {"id": "shape-assembled-illustration", "name": "Illustration assembled from primitive shapes", "family": "generic", "severity": "advisory", "scope": "structure", "command": "distill",
     "why": "A large inline SVG built from a pile of circles and rectangles reads as placeholder clip art. Icons, logos and charts are fine at their size; a hero-sized picture needs real artwork or a product screenshot.",
     "fix": "Replace it with a real screenshot, photograph or commissioned drawing, or remove it and let the copy and layout carry the section."},
    {"id": "oversized-headline", "name": "Long headline set at display size", "family": "generic", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "A full sentence blown up to display size fills the first screen and pushes everything else below the fold. Display sizes suit two or three words, not eight.",
     "fix": "Shorten the headline to the claim, or set long headlines one or two steps smaller and let the lead paragraph carry the detail."},
    {"id": "flat-type-hierarchy", "name": "Heading and body sizes too close together", "family": "generic", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "When every step from body to the largest heading is under 1.25 times the one below, headings do not read as headings. The page looks like one long paragraph with bold lines.",
     "fix": "Open at least one step to 1.25-1.5 times (for example 16, 20, 28) and keep the scale in tokens so every page uses the same steps."},
    {"id": "broken-image", "name": "Image with an empty, missing or placeholder source", "family": "quality", "severity": "high", "scope": "structure", "command": "harden",
     "why": "An img with no src, an empty src, '#' or a placeholder-service URL ships as a broken box or a stock grey rectangle. It tells the visitor the page was never finished.",
     "fix": "Point it at the real asset, or remove the element until the asset exists. Never ship a placeholder-service URL."},
    {"id": "buried-raster", "name": "Image buried under an opaque wash", "family": "quality", "severity": "medium", "scope": "surface", "command": "polish",
     "why": "A background image under a gradient whose stops are all 90% opaque or more never reaches the screen. The page pays the download and shows only the wash.",
     "fix": "Lower the wash below 0.9 alpha, use a blend mode, or delete the image and keep the flat colour you are actually showing."},
    {"id": "all-caps-body", "name": "Running text set in capitals", "family": "quality", "severity": "medium", "scope": "type", "command": "typeset",
     "why": "Long passages in capitals are slow to read: word shapes disappear and every line looks like a shout. Capitals suit short labels, not paragraphs.",
     "fix": "Set running text in sentence case. Keep uppercase for labels of a few words, and add a little tracking when you do."},
    {"id": "image-missing-dimensions", "name": "Image without width and height", "family": "quality", "severity": "medium", "scope": "layout", "command": "optimize",
     "why": "An image with no width and height attributes reserves no space, so the layout jumps when it loads. That shift moves buttons under the pointer and counts against layout-stability budgets.",
     "fix": "Add width and height attributes matching the intrinsic ratio (CSS can still size it), or set aspect-ratio on the element."},
    {"id": "font-display-missing", "name": "Web font without font-display", "family": "quality", "severity": "advisory", "scope": "type", "command": "optimize",
     "why": "An @font-face without font-display leaves text invisible while the font downloads on slow connections. Visitors see a blank page where the words should be.",
     "fix": "Add font-display: swap (or optional for decorative faces) to every @font-face, and preload the one or two faces used above the fold."},
    {"id": "off-system-font", "name": "Typeface outside the context file", "family": "quality", "severity": "medium", "scope": "type", "command": "extract",
     "why": "A face that is not one of the context file's type roles is drift: a second voice the system never chose.",
     "fix": "Use the documented face, or record the new face as a type role in interface-context.md with the reason."},
    {"id": "off-system-color", "name": "Colour outside the context file palette", "family": "quality", "severity": "advisory", "scope": "color", "command": "extract",
     "why": "A literal colour that matches no palette role is drift. Each one is small; together they are why two screens of one product look like two products.",
     "fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."},
    {"id": "off-system-radius", "name": "Corner radius outside the context file", "family": "quality", "severity": "advisory", "scope": "surface", "command": "extract",
     "why": "A radius that is not on the documented scale makes neighbouring components look like they came from different kits.",
     "fix": "Use the control or container radius from the context file, or add the new radius with the component that needs it."},
    {"id": "off-system-font-size", "name": "Font size outside the type roles", "family": "quality", "severity": "advisory", "scope": "type", "command": "extract",
     "why": "A literal font size off the documented ramp creates in-between steps that blur the hierarchy.",
     "fix": "Snap the size to the nearest type role, or add a named role to interface-context.md if the step is intentional."}
  ]
}
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