/web

name: web-design-guidelines
description: Web platform design and accessibility guidelines. Use when building web interfaces, auditing accessibility, implementing responsive layouts, or reviewing web UI code. Triggers on tasks involving HTML, CSS, web components, WCAG compliance, responsive design, or web performance.
license: MIT
metadata:
  author: platform-design-skills
  version: "1.0.0"

Web Platform Design Guidelines

Framework-agnostic rules for accessible, performant, responsive web interfaces. Based on WCAG 2.2, MDN Web Docs, and modern web platform APIs.

---

1. Accessibility / WCAG [CRITICAL]

Accessibility is not optional. Most rules in this section map to WCAG 2.2 success criteria at Level A or AA. A small number of best-practice rules (noted inline) target Level AAA or go beyond WCAG.

1.1 Use Semantic HTML Elements

Use elements for their intended purpose. Semantic structure provides free accessibility, SEO, and reader-mode support.

| Element | Purpose | |---------|---------| | `<main>` | Primary page content (one per page) | | `<nav>` | Navigation blocks | | `<header>` | Introductory content or navigational aids | | `<footer>` | Footer for nearest sectioning content | | `<article>` | Self-contained, independently distributable content | | `<section>` | Thematic grouping with a heading | | `<aside>` | Tangentially related content (sidebars, callouts) | | `<figure>` / `<figcaption>` | Illustrations, diagrams, code listings | | `<details>` / `<summary>` | Expandable/collapsible disclosure widget | | `<dialog>` | Modal or non-modal dialog boxes | | `<time>` | Machine-readable dates/times | | `<mark>` | Highlighted/referenced text | | `<address>` | Contact information for nearest article/body |

<!-- Good -->
<main>
  <article>
    <h1>Article Title</h1>
    <p>Content...</p>
  </article>
  <aside>Related links</aside>
</main>

<!-- Bad: div soup -->
<div class="main">
  <div class="article">
    <div class="title">Article Title</div>
    <div class="content">Content...</div>
  </div>
</div>

**Anti-pattern**: Using `<div>` or `<span>` for interactive elements. Never write `<div onclick>` when `<button>` exists.

1.2 ARIA Labels on Interactive Elements

Every interactive element must have an accessible name. Prefer visible text; use `aria-label` or `aria-labelledby` only when visible text is insufficient (SC 4.1.2).

<!-- Icon-only button: needs aria-label -->
<button aria-label="Close dialog">
  <svg aria-hidden="true">...</svg>
</button>

<!-- Linked by labelledby -->
<h2 id="section-title">Notifications</h2>
<ul aria-labelledby="section-title">...</ul>

<!-- Redundant: visible text is enough -->
<button>Save Changes</button> <!-- No aria-label needed -->

1.3 Keyboard Navigation

All interactive elements must be reachable and operable via keyboard (SC 2.1.1).

• Use native interactive elements (`<button>`, `<a href>`, `<input>`, `<select>`) which are keyboard-accessible by default.
• Custom widgets need `tabindex="0"` to enter tab order and keydown handlers for activation.
• Never use `tabindex` values greater than 0.
• Trap focus inside modals; return focus on close.

// Focus trap for modal
dialog.addEventListener('keydown', (e) => {
  if (e.key === 'Tab') {
    const focusable = dialog.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    const first = focusable[0];
    const last = focusable[focusable.length - 1];
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault();
      last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault();
      first.focus();
    }
  }
});

1.4 Visible Focus Indicators

Never remove focus outlines without providing a visible replacement (SC 2.4.7, enhanced SC 2.4.11 (AA) and SC 2.4.12 (AAA) in WCAG 2.2).

/* Good: custom focus indicator */
:focus-visible {
  outline: 3px solid var(--focus-color, #4A90D9);
  outline-offset: 2px;
}

/* Remove default only when :focus-visible is supported */
:focus:not(:focus-visible) {
  outline: none;
}

/* Bad: removing all focus styles */
/* *:focus { outline: none; } */

WCAG 2.2 requires focus indicators to have a minimum area of the perimeter of the component times 2px, with 3:1 contrast against adjacent colors.

1.5 Skip Navigation Links

Provide a mechanism to skip repeated blocks of content (SC 2.4.1).

<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <nav>...</nav>
  <main id="main-content">...</main>
</body>

.skip-link {
  position: absolute;
  top: -100%;
  left: 0;
  z-index: 1000;
  padding: 0.75rem 1.5rem;
  background: var(--color-primary);
  color: var(--color-on-primary);
}
.skip-link:focus {
  top: 0;
}

1.6 Alt Text for Images

Every `<img>` must have an `alt` attribute (SC 1.1.1).

• **Informative images**: describe the content and function. `alt="Bar chart showing sales doubled in Q4"`.
• **Decorative images**: use `alt=""` (empty string) so screen readers skip them.
• **Functional images** (inside links/buttons): describe the action. `alt="Search"`.
• **Complex images**: use `alt` for short description, link to long description or use `<figcaption>`.

<img src="chart.png" alt="Revenue chart: Q1 $2M, Q2 $2.4M, Q3 $3.1M, Q4 $4.5M">
<img src="decorative-wave.svg" alt="">

1.7 Color Contrast

Maintain minimum contrast ratios (SC 1.4.3, 1.4.6, 1.4.11).

| Content | Minimum Ratio | |---------|--------------| | Normal text (<24px / <18.66px bold) | 4.5:1 | | Large text (>=24px / >=18.66px bold) | 3:1 | | UI components and graphical objects | 3:1 |

Do not rely on color alone to convey information (SC 1.4.1). Pair color with icons, text, or patterns.

/* Check contrast of these tokens */
:root {
  --text-primary: #1a1a2e;    /* on white: ~16:1 */
  --text-secondary: #555770;  /* on white: ~6.5:1 */
  --text-disab