web-design-guidelines

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: web-design-guidelines
description: UI/UX best practices and accessibility audit. Use when reviewing UI code, checking accessibility, running accessibility audits, auditing forms, or ensuring web interface best practices. Triggers on "audit accessibility", "check WCAG", "review UI", "check accessibility", "audit design", "review UX", or "check best practices".
license: MIT
metadata:
  author: agent-skills
  version: "2.1.0"
---

# Web Design Guidelines

WCAG accessibility, semantic HTML, keyboard navigation, forms, and performance patterns for inclusive web interfaces. Contains 23 rules across 4 categories. Supports both **coding reference** and **audit mode**.

## Metadata

- **Version:** 2.1.0
- **Rule Count:** 23 rules across 4 categories
- **License:** MIT

## How to Audit

When the user asks to "audit accessibility", "check WCAG compliance", or "review accessibility" — run the checklist below against their codebase.

### Step 1: Determine Scope

- If arguments provided (`$ARGUMENTS`): audit only those files or components
- If no arguments: audit all UI components and pages in the codebase

### Step 2: Detect Stack

Check the project for:
- `.tsx`/`.jsx` files → React
- `.vue` files → Vue
- `.blade.php` files → Laravel Blade
- `.html` files → Static HTML

### Step 3: Run Accessibility Checklist

Work through every item below. For each, output:
- **PASS** — brief confirmation of what was verified
- **FAIL** — exact `file:line`, description of the issue, and fix recommendation
- **N/A** — if the check does not apply to this project

#### Semantic HTML & Structure
- [ ] Pages use semantic elements (`<header>`, `<main>`, `<nav>`, `<footer>`, `<article>`, `<section>`) — not `<div>` soup
- [ ] Heading hierarchy is sequential (`h1` → `h2` → `h3`) — no skipped levels
- [ ] One `<h1>` per page
- [ ] Skip link exists to bypass navigation (`<a href="#main-content">Skip to content</a>`)
- [ ] Landmark regions are labelled when duplicated (`aria-label` on multiple `<nav>` elements)

#### Keyboard Navigation
- [ ] All interactive elements are reachable via Tab key
- [ ] Focus order follows visual order (no positive `tabindex` values)
- [ ] Focus indicator is visible on all focusable elements (not removed with `outline: none` without replacement)
- [ ] Modal dialogs trap focus and return focus on close
- [ ] Custom components (dropdowns, tabs, accordions) support expected keyboard patterns (Arrow keys, Escape, Enter)

#### Images & Media
- [ ] All `<img>` elements have `alt` attributes — descriptive for content images, empty (`alt=""`) for decorative
- [ ] Complex images (charts, diagrams) have extended descriptions
- [ ] Video content has captions or transcripts

#### Color & Contrast
- [ ] Text meets WCAG AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
- [ ] Information is not conveyed by color alone (e.g., error states use icons + text, not just red)
- [ ] UI components and focus indicators meet 3:1 contrast ratio against background

#### Forms
- [ ] Every input has an associated `<label>` (not just placeholder text)
- [ ] Required fields indicated with both visual cue and `aria-required="true"`
- [ ] Error messages linked to inputs via `aria-describedby`
- [ ] Error messages use `role="alert"` or `aria-live="assertive"` for screen reader announcement
- [ ] Correct `type` attributes on inputs (`email`, `tel`, `url`, `number`)
- [ ] `autocomplete` attributes present on common fields (name, email, address, credit card)

#### ARIA & Screen Readers
- [ ] ARIA labels on icon-only buttons (`aria-label="Close"`)
- [ ] Dynamic content updates use `aria-live` regions
- [ ] Loading states announced to screen readers (`aria-busy="true"`, status messages)
- [ ] Decorative elements hidden from screen readers (`aria-hidden="true"`)

#### Motion & Animation
- [ ] `prefers-reduced-motion` respected — animations disabled or reduced
- [ ] No auto-playing video or audio without user control
- [ ] No content that flashes more than