Framework
Web Design Guidelines
Review UI code for web interface best practices: accessibility, responsive design, semantic HTML, color contrast, and keyboard navigation.
Last reviewed Mar 2, 2026
Install
Create this file in your project:
.claude/skills/web-design-guidelines/SKILL.md---
name: web-design-guidelines
description: Use this skill when building web UI, reviewing frontend code for accessibility, or ensuring a website meets web design standards.
---
# Web Design Guidelines
## When to Use
- Building new web pages or UI components
- Reviewing existing UI code for accessibility issues
- Checking responsive design across breakpoints
- Auditing a site for WCAG compliance
## Process
1. **Check semantic HTML** -- Verify correct use of headings (`h1`-`h6` in order), landmarks (`nav`, `main`, `aside`, `footer`), lists, and form labels.
2. **Check accessibility**:
- All images have descriptive `alt` text (or `alt=""` for decorative images).
- All interactive elements are keyboard-accessible (focusable, operable, visible focus indicator).
- Color contrast meets WCAG 2.1 AA (4.5:1 for normal text, 3:1 for large text).
- Form inputs have associated `<label>` elements.
- ARIA attributes are used correctly and only when semantic HTML is insufficient.
3. **Check responsive design**:
- Layout works at 320px, 768px, 1024px, and 1440px widths.
- Touch targets are at least 44x44px on mobile.
- No horizontal scrolling at any standard breakpoint.
- Text remains readable without zooming on mobile.
4. **Check interaction patterns**:
- Focus management for modals, dropdowns, and dynamic content.
- Escape key closes modals and popovers.
- Loading states for async operations.
- Error messages are associated with their form fields.
## Rules
- WCAG 2.1 AA is the minimum standard. Never ship inaccessible UI.
- Use semantic HTML elements before reaching for ARIA. A `<button>` is always better than `<div role="button">`.
- Every interactive element must have a visible focus indicator. Never set `outline: none` without a replacement.
- Test with keyboard-only navigation. If you cannot complete a task without a mouse, it is broken.
- Do not convey information with color alone. Use icons, text, or patterns as secondary indicators.
- Responsive design is not optional. Every page must work on mobile.
- Use relative units (`rem`, `em`, `%`) for typography and spacing, not fixed `px`.What this skill does
Web Design Guidelines provides a structured review checklist for web UI code, focusing on the aspects that most commonly fall through the cracks: accessibility, semantic HTML, keyboard navigation, and responsive design. These aren't optional niceties -- they're requirements for a professional website.
The skill is structured as a series of concrete checks rather than abstract principles. Instead of "make it accessible," it specifies: verify heading hierarchy, check color contrast ratios, confirm keyboard operability, and test at specific breakpoints. This makes the review systematic and repeatable.
The emphasis on semantic HTML over ARIA is deliberate. Overuse of ARIA attributes is a common anti-pattern -- a <button> element provides keyboard handling, focus management, and screen reader announcements for free, while a <div role="button"> requires all of those to be manually reimplemented. The right HTML element is almost always the simplest and most accessible solution.
Example workflow
You ask the agent to review a checkout form. The agent will:
- Verify all form inputs have associated
<label>elements -- find that the credit card field is missing one. - Check color contrast on the error messages -- find that the light red on white fails the 4.5:1 ratio.
- Test keyboard navigation -- find that the "Apply coupon" button is a
<div>with an onClick but no keyboard handler. - Check mobile layout at 320px -- find that the form overflows horizontally.
- Report findings with specific fixes: add the label, darken the error color, convert the div to a button, add
max-width: 100%to the form.
Tips
- Install a browser accessibility checker (axe, WAVE) to complement this skill's code-level review
- The most impactful accessibility fix is usually the simplest: adding missing labels and alt text
- Test with a screen reader at least once per feature -- automated tools catch only about 30% of accessibility issues
- When building new components, get the semantic HTML right first, then add styling
Best with tools
Related MCP servers
- No linked MCP servers yet.