Design · How to use a skill

review-ui-against-design-guidelines

Reviews web UI code against a practical interface checklist - interactions, forms, loading and error states, navigation, motion, layout, typography and dark mode - and reports each problem as file, line, issue and fix. Use when the user wants a UI or UX review, asks to check a page against web design guidelines, or wants the interface to feel polished and professional.

Version 1.0 · Updated 2026-10-31

View raw SKILL.md

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/review-ui-against-design-guidelines/raw' -o ~/'.claude/skills/review-ui-against-design-guidelines/SKILL.md'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/review-ui-against-design-guidelines/raw' -o '.cursor/skills/review-ui-against-design-guidelines/SKILL.md'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/review-ui-against-design-guidelines/raw' -o '.agents/skills/review-ui-against-design-guidelines/SKILL.md'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

Review UI against design guidelines

A polished interface is mostly many small details done right. This skill reads the UI code, checks it against the list below, and reports what to fix. It reviews behaviour and feel. For a full accessibility and speed audit, use audit-accessibility-and-performance.

When to use

• A page works but feels rough, and you want a list of concrete fixes.
• You want a UI review of a pull request or a set of components.
• Before a launch or a demo, to catch missing loading, empty and error states.

Steps

1. Pick the scope. Ask which pages or files to review if it is not clear. Read those files and run the app if you can.
2. Interactions.

• Everything clickable is a real <button> or <a href>, reachable with Tab, with a visible :focus-visible style.
• Click and tap targets are at least 24×24 pixels (44×44 on mobile). Icons-only buttons have an aria-label.
• Nothing important works only on hover.
• Dangerous actions ask for confirmation or offer undo.

1. Forms.

• Every input has a label. Enter submits a single-field form.
• Inputs use the right type, inputmode and autocomplete (email, tel, one-time-code).
• Never block paste, especially into password and code fields.
• Errors appear next to the field, in words, and focus moves to the first error.
• The submit button stays enabled until the request starts, then shows progress and blocks double submits.

1. States. Every view that loads data has a loading state, an empty state with a next step, and an error state with a retry. Short loads avoid a flashing spinner. Status messages use aria-live so screen readers hear them.
2. Navigation and state.

• Links that change page are links, so open-in-new-tab works.
• Filters, tabs, search and pagination live in the URL, so back, refresh and sharing work.
• Scroll position and form input survive going back where possible.

1. Motion. Animate only transform and opacity. Keep UI transitions short (about 150–300 ms). Respect prefers-reduced-motion. Never animate in a way that moves content under the pointer.
2. Layout. Check 320 px wide, a common phone, a tablet and a wide screen. No horizontal scroll on phones. Images and embeds have fixed sizes so nothing jumps. Respect safe areas on phones with notches.
3. Content and typography. Use the real ellipsis (…) and curly quotes. Use tabular-nums for numbers that change or line up in tables. Long text truncates or wraps without breaking the layout. Headings can use text-wrap: balance. Dates and numbers use the user's locale.
4. Dark mode and theming. If there is dark mode, set color-scheme and a matching theme-color. Check contrast in both themes. Native controls (scrollbars, selects) match the theme.
5. Report. List findings grouped by file, most serious first, one per line: path:line - issue - fix. Then offer to apply the fixes. Do not rewrite the design without asking.

Gotchas

• Do not report taste as a rule. Keep "I would prefer" notes separate from real problems.
• Disabling a button with no explanation is a common anti-pattern. Show why, or validate on submit instead.
• A spinner on every tiny action makes an app feel slower. Use optimistic updates when the action rarely fails.
• Fixing one component may not fix the pattern. Point out shared components and design tokens to fix once.

Safety

• Error messages should not show stack traces, database errors, API keys or other private details to users. Log those on the server instead.
• Screenshots or examples in the report must not include real customer data or personal information.

Works with other stacks

The checklist is about HTML, CSS and behaviour, so it works with any framework: React, Vue, Svelte, Angular or plain HTML. With a component library such as shadcn/ui, check the shared components first, then the pages that use them.

Done when

• Every in-scope file was checked against steps 2 to 9.
• The report lists each finding as path:line - issue - fix, most serious first.
• The user has the report, or the agreed fixes are applied and the app still builds.

Credits

Written by TheSkillVault in our own words, CC BY 4.0. The concept of an agent skill that checks UI code against interface guidelines comes from Vercel's web-design-guidelines skill (vercel-labs/agent-skills). That repository has no licence file, so nothing from it was copied.

Example prompt

"Review the checkout page and the settings form against good web design guidelines and give me a list of fixes with file and line numbers."

Licence: CC BY 4.0. Attribution when you reuse it: From TheSkillVault, https://theskillvault.ai, CC BY 4.0