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.
assets/sample_detector_report_flawed.json
View on GitHub{
"summary": {
"files_scanned": 3,
"findings": 113,
"by_severity": {
"high": 23,
"medium": 51,
"advisory": 39
},
"by_command": {
"extract": 28,
"typeset": 20,
"colorize": 13,
"animate": 12,
"quieter": 11,
"layout": 6,
"polish": 6,
"harden": 5,
"clarify": 5,
"distill": 5,
"optimize": 2
},
"fail_on": "medium",
"blocking": 74,
"ignored": 0,
"rejected_waivers": 0,
"verdict": "FAIL"
},
"files_scanned": 3,
"findings": [
{
"file": "assets/sample_ui_flawed.css",
"line": 1,
"rule": "monotonous-spacing",
"severity": "advisory",
"scope": "layout",
"command": "layout",
"name": "One spacing value everywhere",
"evidence": "16px is 12 of 12 spacing values",
"fix": "Use a scale: tight steps inside groups, larger steps between groups, the largest between sections."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 2,
"rule": "cream-ground",
"severity": "medium",
"scope": "color",
"command": "colorize",
"name": "Reflex cream or beige page ground",
"evidence": ":root --bg: #f6f1e7",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 2,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#f6f1e7 is not in the context file's palette roles (3 uses)",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 3,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#7c3aed is not in the context file's palette roles (2 uses)",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 7,
"rule": "overused-face",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Overused default typeface",
"evidence": "font-family: \"Inter\", system-ui, sans-serif",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 7,
"rule": "off-system-font",
"severity": "medium",
"scope": "type",
"command": "extract",
"name": "Typeface outside the context file",
"evidence": "inter is not in the context file's type roles",
"fix": "Use the documented face, or record the new face as a type role in interface-context.md with the reason."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 12,
"rule": "overused-face",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Overused default typeface",
"evidence": "font-family: \"Playfair Display\", Georgia, serif",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 12,
"rule": "off-system-font",
"severity": "medium",
"scope": "type",
"command": "extract",
"name": "Typeface outside the context file",
"evidence": "playfair display is not in the context file's type roles",
"fix": "Use the documented face, or record the new face as a type role in interface-context.md with the reason."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 13,
"rule": "italic-serif-display",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Italic serif hero headline",
"evidence": ".hero h1 {font-style: italic}",
"fix": "Set the headline roman, or move italic to a single word that earns it. Choose the display face from the type roles."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 14,
"rule": "crushed-tracking",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Letter spacing tighter than -0.04em",
"evidence": "letter-spacing: -0.06em",
"fix": "Tighten display type between -0.01em and -0.03em and check the rendered word at every breakpoint."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 18,
"rule": "ai-hue-gradient",
"severity": "medium",
"scope": "color",
"command": "colorize",
"name": "Violet-to-blue or violet-to-cyan gradient",
"evidence": "background: linear-gradient(135deg, #6366f1 0%, #a855f7 50%, #06b6d4 100%)",
"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)."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 18,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#6366f1 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 18,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#a855f7 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 18,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#06b6d4 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 19,
"rule": "glow-shadow",
"severity": "medium",
"scope": "surface",
"command": "quieter",
"name": "Colored zero-offset glow",
"evidence": "box-shadow: 0 0 40px rgba(139, 92, 246, 0.6)",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 23,
"rule": "side-stripe-border",
"severity": "high",
"scope": "surface",
"command": "quieter",
"name": "Colored stripe on one side of a card",
"evidence": "border-left: 4px solid #8b5cf6 [refused in context file]",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 23,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#8b5cf6 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 24,
"rule": "off-system-radius",
"severity": "advisory",
"scope": "surface",
"command": "extract",
"name": "Corner radius outside the context file",
"evidence": "12px is not in the context file's radius scale",
"fix": "Use the control or container radius from the context file, or add the new radius with the component that needs it."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 30,
"rule": "off-system-font-size",
"severity": "advisory",
"scope": "type",
"command": "extract",
"name": "Font size outside the type roles",
"evidence": "11px is not in the context file's type roles",
"fix": "Snap the size to the nearest type role, or add a named role to interface-context.md if the step is intentional."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 31,
"rule": "low-contrast-pair",
"severity": "high",
"scope": "color",
"command": "colorize",
"name": "Text and background below WCAG AA",
"evidence": ".fine-print: #a3a3a3 on #ffffff = 2.52:1 (needs 4.5)",
"fix": "Darken the text or lighten the ground until the pair passes; use ui_rules.py --contrast to confirm."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 31,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#a3a3a3 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 36,
"rule": "off-system-font-size",
"severity": "advisory",
"scope": "type",
"command": "extract",
"name": "Font size outside the type roles",
"evidence": "18px is not in the context file's type roles",
"fix": "Snap the size to the nearest type role, or add a named role to interface-context.md if the step is intentional."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 37,
"rule": "tight-body-leading",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Tight line height on running text",
"evidence": "p line-height: 1.15",
"fix": "Use 1.45 to 1.7 for body copy; tighten only headings and single-line labels."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 38,
"rule": "wide-body-tracking",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Wide letter spacing on running text",
"evidence": "p letter-spacing: 0.08em",
"fix": "Reset body tracking to the face's default; keep wide tracking for short uppercase labels only."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 39,
"rule": "justified-text",
"severity": "advisory",
"scope": "type",
"command": "typeset",
"name": "Justified text without hyphenation",
"evidence": "p text-align: justify",
"fix": "Use text-align: start, or add hyphens: auto with a lang attribute and a measure of 60 characters or more."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 43,
"rule": "transition-all",
"severity": "medium",
"scope": "motion",
"command": "animate",
"name": "transition: all",
"evidence": "transition: all 0.3s cubic-bezier(0.68, -0.55, 0.27, 1.55)",
"fix": "List the properties that should move, usually opacity, transform, color or box-shadow."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 43,
"rule": "bounce-easing",
"severity": "advisory",
"scope": "motion",
"command": "animate",
"name": "Bounce or overshoot easing",
"evidence": "transition: all 0.3s cubic-bezier(0.68, -0.55, 0.27, 1.55)",
"fix": "Use a decelerating curve such as cubic-bezier(0.2, 0.8, 0.2, 1) and shorten the duration."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 44,
"rule": "focus-ring-removed",
"severity": "high",
"scope": "interaction",
"command": "harden",
"name": "Focus outline removed with no replacement",
"evidence": ".button outline: none",
"fix": "Keep outline: none only alongside a :focus-visible ring of at least 2px that contrasts 3:1 with its surroundings."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 49,
"rule": "focus-ring-removed",
"severity": "high",
"scope": "interaction",
"command": "harden",
"name": "Focus outline removed with no replacement",
"evidence": ".button:focus outline: none",
"fix": "Keep outline: none only alongside a :focus-visible ring of at least 2px that contrasts 3:1 with its surroundings."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 53,
"rule": "layout-property-motion",
"severity": "medium",
"scope": "motion",
"command": "animate",
"name": "Animating layout properties",
"evidence": "transition: height 300ms ease",
"fix": "Animate transform and opacity, or use a grid-rows / FLIP technique for size changes."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 60,
"rule": "missing-reduced-motion",
"severity": "high",
"scope": "motion",
"command": "animate",
"name": "Animation with no reduced-motion path",
"evidence": "animation found; no prefers-reduced-motion or motion-reduce anywhere in scan",
"fix": "Add a prefers-reduced-motion: reduce block (or motion-safe / motion-reduce utilities) that removes movement but keeps state changes visible."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 60,
"rule": "decorative-pulse",
"severity": "medium",
"scope": "motion",
"command": "animate",
"name": "Pulsing status dot",
"evidence": ".status-dot {animation: pulse 1.5s infinite}",
"fix": "Use a static, labelled status indicator. Animate only when the underlying state changes."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 64,
"rule": "low-contrast-pair",
"severity": "high",
"scope": "color",
"command": "colorize",
"name": "Text and background below WCAG AA",
"evidence": ".badge-on-brand: #6b7280 on #4f46e5 = 1.30:1 (needs 4.5)",
"fix": "Darken the text or lighten the ground until the pair passes; use ui_rules.py --contrast to confirm."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 64,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#6b7280 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 65,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#4f46e5 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 69,
"rule": "repeating-stripes",
"severity": "advisory",
"scope": "surface",
"command": "quieter",
"name": "Decorative repeating stripes",
"evidence": "background-image: repeating-linear-gradient(45deg, #eee 0 2px, transparent 2px 8px)",
"fix": "Leave the surface plain or use a texture that comes from the product's subject."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 82,
"rule": "layout-property-motion",
"severity": "medium",
"scope": "motion",
"command": "animate",
"name": "Animating layout properties",
"evidence": "@keyframes from {width}",
"fix": "Animate transform and opacity, or use a grid-rows / FLIP technique for size changes."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 83,
"rule": "layout-property-motion",
"severity": "medium",
"scope": "motion",
"command": "animate",
"name": "Animating layout properties",
"evidence": "@keyframes to {width}",
"fix": "Animate transform and opacity, or use a grid-rows / FLIP technique for size changes."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 87,
"rule": "flat-type-hierarchy",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Heading and body sizes too close together",
"evidence": "h1 22px, h2 20px, body 18px; largest step 1.11:1, target 1.25:1",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 87,
"rule": "off-system-font-size",
"severity": "advisory",
"scope": "type",
"command": "extract",
"name": "Font size outside the type roles",
"evidence": "22px is not in the context file's type roles",
"fix": "Snap the size to the nearest type role, or add a named role to interface-context.md if the step is intentional."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 91,
"rule": "default-font-stack",
"severity": "advisory",
"scope": "type",
"command": "typeset",
"name": "Bare system font stack as the voice",
"evidence": "h2 font-family: -apple-system, BlinkMacSystemFont, sans-serif",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 96,
"rule": "hard-offset-shadow",
"severity": "advisory",
"scope": "surface",
"command": "quieter",
"name": "Hard offset block shadow",
"evidence": "box-shadow: 6px 6px 0 #111111",
"fix": "Keep it only if the design brief chose that style; otherwise replace it with the project's elevation token."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 100,
"rule": "grid-line-background",
"severity": "advisory",
"scope": "surface",
"command": "quieter",
"name": "Decorative grid-paper background",
"evidence": "background-image: linear-gradient(#dddddd 1px, transparent 1px), linear-gradient(90deg, #dddddd 1px, transparent 1px)",
"fix": "Remove the grid unless the surface is a canvas or measurement view; let spacing carry structure."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 105,
"rule": "gray-on-color",
"severity": "medium",
"scope": "color",
"command": "colorize",
"name": "Neutral gray text on a colored ground",
"evidence": ".promo-band: #b0b5bd on #3730a3",
"fix": "Use a darker or lighter shade of the surface hue, or white/near-black, for secondary text on colored surfaces."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 105,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#b0b5bd is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 106,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#3730a3 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 110,
"rule": "font-display-missing",
"severity": "advisory",
"scope": "type",
"command": "optimize",
"name": "Web font without font-display",
"evidence": "@font-face has no font-display",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 115,
"rule": "radial-glow",
"severity": "medium",
"scope": "surface",
"command": "quieter",
"name": "Coloured radial haze behind a section",
"evidence": ".hero-halo background: radial-gradient(circle at 50% 0%, rgba(124, 58, 237, 0.45), transparent 60%)",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 119,
"rule": "organic-clip-path",
"severity": "medium",
"scope": "surface",
"command": "quieter",
"name": "Blob or torn edge drawn with clip-path",
"evidence": "clip-path: polygon() with 12 irregular points",
"fix": "Ship the shape as an image with transparency, or drop it. Keep clip-path for geometry: a cut corner, a diagonal, a hexagon."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 123,
"rule": "buried-raster",
"severity": "medium",
"scope": "surface",
"command": "polish",
"name": "Image buried under an opaque wash",
"evidence": ".paper-texture background: linear-gradient(rgba(246, 241, 231, 0.94), rgba(246, 241, 231, 0.96)), url(\"paper.jpg\")",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 127,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#e5e7eb is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 128,
"rule": "off-system-radius",
"severity": "advisory",
"scope": "surface",
"command": "extract",
"name": "Corner radius outside the context file",
"evidence": "14px is not in the context file's radius scale",
"fix": "Use the control or container radius from the context file, or add the new radius with the component that needs it."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 129,
"rule": "hairline-wide-shadow",
"severity": "advisory",
"scope": "surface",
"command": "quieter",
"name": "Hairline border plus a wide soft shadow on cards",
"evidence": ".plan-card: 1px border + 48px shadow blur",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 134,
"rule": "blinking-cursor",
"severity": "advisory",
"scope": "motion",
"command": "animate",
"name": "Decorative blinking text cursor",
"evidence": ".hero-caret::after {animation: blink 1s step-end infinite}",
"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."
},
{
"file": "assets/sample_ui_flawed.css",
"line": 138,
"rule": "all-caps-body",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Running text set in capitals",
"evidence": ".legal p text-transform: uppercase",
"fix": "Set running text in sentence case. Keep uppercase for labels of a few words, and add a little tracking when you do."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 6,
"rule": "overused-face",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Overused default typeface",
"evidence": "font link loads Inter",
"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."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 9,
"rule": "cream-ground",
"severity": "medium",
"scope": "color",
"command": "colorize",
"name": "Reflex cream or beige page ground",
"evidence": "bg-amber-50",
"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."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 12,
"rule": "kicker-above-heading",
"severity": "high",
"scope": "type",
"command": "typeset",
"name": "Eyebrow label above a heading",
"evidence": "\"New for 2026\" above <h1> [refused in context file]",
"fix": "Delete the label, or fold its information into the heading or the sentence below it."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 13,
"rule": "italic-serif-display",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Italic serif hero headline",
"evidence": "h1 {font-style: italic}",
"fix": "Set the headline roman, or move italic to a single word that earns it. Choose the display face from the type roles."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 13,
"rule": "vague-headline",
"severity": "medium",
"scope": "copy",
"command": "clarify",
"name": "Template headline",
"evidence": "<h1> \"Welcome to the future of invoicing for every small team\"",
"fix": "State what the product does for whom, using the product's own nouns from the context file."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 13,
"rule": "oversized-headline",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Long headline set at display size",
"evidence": "<h1> of 10 words at display size",
"fix": "Shorten the headline to the claim, or set long headlines one or two steps smaller and let the lead paragraph carry the detail."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 14,
"rule": "faint-gray-text",
"severity": "high",
"scope": "color",
"command": "colorize",
"name": "Light gray text class on a light ground",
"evidence": "text-gray-400 on a light ground (2.54:1 on white)",
"fix": "Use the 500 step or darker for secondary text on light grounds, or a muted-text token that passes 4.5:1."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 14,
"rule": "gradient-text",
"severity": "high",
"scope": "type",
"command": "typeset",
"name": "Gradient-filled text",
"evidence": "bg-clip-text text-transparent [refused in context file]",
"fix": "Set the text in one solid color from the palette and create emphasis with size, weight or placement."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 14,
"rule": "ai-hue-gradient",
"severity": "medium",
"scope": "color",
"command": "colorize",
"name": "Violet-to-blue or violet-to-cyan gradient",
"evidence": "from-indigo-500 via-purple-500 to-cyan-400",
"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)."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 16,
"rule": "focus-ring-removed",
"severity": "high",
"scope": "interaction",
"command": "harden",
"name": "Focus outline removed with no replacement",
"evidence": "outline-none with no focus-visible style",
"fix": "Keep outline: none only alongside a :focus-visible ring of at least 2px that contrasts 3:1 with its surroundings."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 17,
"rule": "glow-shadow",
"severity": "medium",
"scope": "surface",
"command": "quieter",
"name": "Colored zero-offset glow",
"evidence": "shadow-indigo-500/50",
"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."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 17,
"rule": "vague-control-label",
"severity": "medium",
"scope": "copy",
"command": "clarify",
"name": "Control label that does not name its action",
"evidence": "<button> \"submit\"",
"fix": "Name the outcome with a verb and object: Save changes, Send invoice, Delete 3 files."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 17,
"rule": "everything-bold",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Most text set bold",
"evidence": "14 of 21 text elements are bold",
"fix": "Return body and secondary text to regular weight; keep heavy weights for headings and the one value per block that matters."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 21,
"rule": "identical-card-row",
"severity": "medium",
"scope": "layout",
"command": "layout",
"name": "Row of identical equal-weight cards",
"evidence": "3 <section> siblings share one class list",
"fix": "Decide which item matters most and let it lead (size, position, content); render the rest as a list or a different form."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 22,
"rule": "numbered-section-labels",
"severity": "advisory",
"scope": "structure",
"command": "distill",
"name": "01 / 02 / 03 section numbering",
"evidence": "3 bare section numbers",
"fix": "Remove the numbers unless the reader must follow the order (steps, a procedure)."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 25,
"rule": "identical-card-row",
"severity": "medium",
"scope": "layout",
"command": "layout",
"name": "Row of identical equal-weight cards",
"evidence": "3 <div> siblings share one class list",
"fix": "Decide which item matters most and let it lead (size, position, content); render the rest as a list or a different form."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 26,
"rule": "emoji-icon",
"severity": "medium",
"scope": "surface",
"command": "polish",
"name": "Emoji or glyph standing in for an icon",
"evidence": "<span> \u26a1",
"fix": "Use one drawn icon set with a single stroke and weight, with aria-hidden on decorative icons and a text label on controls."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 26,
"rule": "icon-tile-stack",
"severity": "medium",
"scope": "layout",
"command": "layout",
"name": "Icon in a rounded tile stacked over a heading",
"evidence": "icon tile above <h3>",
"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)."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 28,
"rule": "faint-gray-text",
"severity": "high",
"scope": "color",
"command": "colorize",
"name": "Light gray text class on a light ground",
"evidence": "text-gray-400 on a light ground (2.54:1 on white)",
"fix": "Use the 500 step or darker for secondary text on light grounds, or a muted-text token that passes 4.5:1."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 31,
"rule": "emoji-icon",
"severity": "medium",
"scope": "surface",
"command": "polish",
"name": "Emoji or glyph standing in for an icon",
"evidence": "<span> \ud83d\udd12",
"fix": "Use one drawn icon set with a single stroke and weight, with aria-hidden on decorative icons and a text label on controls."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 31,
"rule": "icon-tile-stack",
"severity": "medium",
"scope": "layout",
"command": "layout",
"name": "Icon in a rounded tile stacked over a heading",
"evidence": "icon tile above <h3>",
"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)."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 33,
"rule": "faint-gray-text",
"severity": "high",
"scope": "color",
"command": "colorize",
"name": "Light gray text class on a light ground",
"evidence": "text-gray-400 on a light ground (2.54:1 on white)",
"fix": "Use the 500 step or darker for secondary text on light grounds, or a muted-text token that passes 4.5:1."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 36,
"rule": "emoji-icon",
"severity": "medium",
"scope": "surface",
"command": "polish",
"name": "Emoji or glyph standing in for an icon",
"evidence": "<span> \ud83d\udcc8",
"fix": "Use one drawn icon set with a single stroke and weight, with aria-hidden on decorative icons and a text label on controls."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 36,
"rule": "icon-tile-stack",
"severity": "medium",
"scope": "layout",
"command": "layout",
"name": "Icon in a rounded tile stacked over a heading",
"evidence": "icon tile above <h3>",
"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)."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 38,
"rule": "faint-gray-text",
"severity": "high",
"scope": "color",
"command": "colorize",
"name": "Light gray text class on a light ground",
"evidence": "text-gray-400 on a light ground (2.54:1 on white)",
"fix": "Use the 500 step or darker for secondary text on light grounds, or a muted-text token that passes 4.5:1."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 47,
"rule": "nested-cards",
"severity": "high",
"scope": "structure",
"command": "distill",
"name": "Card inside a card",
"evidence": "<div> card inside the card opened at line 46 [refused in context file]",
"fix": "Keep the outer container and turn inner cards into rows, sections with headings, or dividers."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 47,
"rule": "side-stripe-border",
"severity": "high",
"scope": "surface",
"command": "quieter",
"name": "Colored stripe on one side of a card",
"evidence": "border-4 border-violet-500 [refused in context file]",
"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."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 47,
"rule": "chip-soup",
"severity": "medium",
"scope": "structure",
"command": "distill",
"name": "Too many pills and badges",
"evidence": "5 chips inside one card [refused in context file]",
"fix": "Keep one chip for the status that drives a decision; show the rest as plain text or metadata rows."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 48,
"rule": "decorative-pulse",
"severity": "medium",
"scope": "motion",
"command": "animate",
"name": "Pulsing status dot",
"evidence": "h-2 w-2 animate-ping",
"fix": "Use a static, labelled status indicator. Animate only when the underlying state changes."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 56,
"rule": "vague-control-label",
"severity": "medium",
"scope": "copy",
"command": "clarify",
"name": "Control label that does not name its action",
"evidence": "<a> \"click here\"",
"fix": "Name the outcome with a verb and object: Save changes, Send invoice, Delete 3 files."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 61,
"rule": "skipped-heading",
"severity": "medium",
"scope": "structure",
"command": "polish",
"name": "Heading level skipped",
"evidence": "h2 followed by h4",
"fix": "Use the next level down and style it to the size you wanted."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 62,
"rule": "marquee-scroll",
"severity": "medium",
"scope": "motion",
"command": "animate",
"name": "Auto-scrolling marquee",
"evidence": "logo-marquee animate-marquee",
"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."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 63,
"rule": "broken-image",
"severity": "high",
"scope": "structure",
"command": "harden",
"name": "Image with an empty, missing or placeholder source",
"evidence": "<img src=\"\">",
"fix": "Point it at the real asset, or remove the element until the asset exists. Never ship a placeholder-service URL."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 64,
"rule": "image-missing-dimensions",
"severity": "medium",
"scope": "layout",
"command": "optimize",
"name": "Image without width and height",
"evidence": "<img src=\"screens/invoice-list.png\"> has no width/height",
"fix": "Add width and height attributes matching the intrinsic ratio (CSS can still size it), or set aspect-ratio on the element."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 65,
"rule": "all-caps-body",
"severity": "medium",
"scope": "type",
"command": "typeset",
"name": "Running text set in capitals",
"evidence": "<p class=\"uppercase\"> with 101 characters",
"fix": "Set running text in sentence case. Keep uppercase for labels of a few words, and add a little tracking when you do."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 66,
"rule": "shape-assembled-illustration",
"severity": "advisory",
"scope": "structure",
"command": "distill",
"name": "Illustration assembled from primitive shapes",
"evidence": "inline <svg> 480x320 built from 13 shapes in 8 fills",
"fix": "Replace it with a real screenshot, photograph or commissioned drawing, or remove it and let the copy and layout carry the section."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 67,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#c7d2fe is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 68,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#a5b4fc is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 69,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#818cf8 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 70,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#fde68a is not in the context file's palette roles (2 uses)",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 72,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#fca5a5 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 73,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#e0e7ff is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 78,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#6366f1 is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.html",
"line": 79,
"rule": "off-system-color",
"severity": "advisory",
"scope": "color",
"command": "extract",
"name": "Colour outside the context file palette",
"evidence": "#4338ca is not in the context file's palette roles",
"fix": "Replace the literal with the nearest palette role token, or add the colour as a named role if it has a job."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 6,
"rule": "tiny-text",
"severity": "high",
"scope": "type",
"command": "typeset",
"name": "Text below 12px",
"evidence": "p font-size: 10px",
"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."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 6,
"rule": "off-system-font-size",
"severity": "advisory",
"scope": "type",
"command": "extract",
"name": "Font size outside the type roles",
"evidence": "10px is not in the context file's type roles",
"fix": "Snap the size to the nearest type role, or add a named role to interface-context.md if the step is intentional."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 17,
"rule": "kicker-above-heading",
"severity": "high",
"scope": "type",
"command": "typeset",
"name": "Eyebrow label above a heading",
"evidence": "\"Most popular\" above <h2> [refused in context file]",
"fix": "Delete the label, or fold its information into the heading or the sentence below it."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 18,
"rule": "gradient-text",
"severity": "high",
"scope": "type",
"command": "typeset",
"name": "Gradient-filled text",
"evidence": "bg-clip-text text-transparent [refused in context file]",
"fix": "Set the text in one solid color from the palette and create emphasis with size, weight or placement."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 18,
"rule": "ai-hue-gradient",
"severity": "medium",
"scope": "color",
"command": "colorize",
"name": "Violet-to-blue or violet-to-cyan gradient",
"evidence": "from-violet-600 to-cyan-500",
"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)."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 18,
"rule": "vague-headline",
"severity": "medium",
"scope": "copy",
"command": "clarify",
"name": "Template headline",
"evidence": "<h2> \"Supercharge your workflow\"",
"fix": "State what the product does for whom, using the product's own nouns from the context file."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 21,
"rule": "nested-cards",
"severity": "high",
"scope": "structure",
"command": "distill",
"name": "Card inside a card",
"evidence": "<div> card inside the card opened at line 16 [refused in context file]",
"fix": "Keep the outer container and turn inner cards into rows, sections with headings, or dividers."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 21,
"rule": "side-stripe-border",
"severity": "high",
"scope": "surface",
"command": "quieter",
"name": "Colored stripe on one side of a card",
"evidence": "border-left: 4px solid #22d3ee [refused in context file]",
"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."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 22,
"rule": "faint-gray-text",
"severity": "high",
"scope": "color",
"command": "colorize",
"name": "Light gray text class on a light ground",
"evidence": "text-slate-400 on a light ground (2.56:1 on white)",
"fix": "Use the 500 step or darker for secondary text on light grounds, or a muted-text token that passes 4.5:1."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 23,
"rule": "emoji-icon",
"severity": "medium",
"scope": "surface",
"command": "polish",
"name": "Emoji or glyph standing in for an icon",
"evidence": "<h3> \u2728 Everything included",
"fix": "Use one drawn icon set with a single stroke and weight, with aria-hidden on decorative icons and a text label on controls."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 25,
"rule": "focus-ring-removed",
"severity": "high",
"scope": "interaction",
"command": "harden",
"name": "Focus outline removed with no replacement",
"evidence": "outline-none with no focus-visible style",
"fix": "Keep outline: none only alongside a :focus-visible ring of at least 2px that contrasts 3:1 with its surroundings."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 25,
"rule": "transition-all",
"severity": "medium",
"scope": "motion",
"command": "animate",
"name": "transition: all",
"evidence": "transition-property: all",
"fix": "List the properties that should move, usually opacity, transform, color or box-shadow."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 25,
"rule": "vague-control-label",
"severity": "medium",
"scope": "copy",
"command": "clarify",
"name": "Control label that does not name its action",
"evidence": "<button> \"ok\"",
"fix": "Name the outcome with a verb and object: Save changes, Send invoice, Delete 3 files."
},
{
"file": "assets/sample_ui_flawed.tsx",
"line": 25,
"rule": "bounce-easing",
"severity": "advisory",
"scope": "motion",
"command": "animate",
"name": "Bounce or overshoot easing",
"evidence": "animate-bounce",
"fix": "Use a decelerating curve such as cubic-bezier(0.2, 0.8, 0.2, 1) and shorten the duration."
}
],
"ignored": 0,
"rejected_waivers": [],
"unreadable": []
}
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 |