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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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.
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.
<!-- Good --><main><article><h1>Article Title</h1><p>Content...</p></article><aside>Related links</aside></main><!-- Bad: div soup --><divclass="main"><divclass="article"><divclass="title">Article Title</div><divclass="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 --><buttonaria-label="Close dialog"><svgaria-hidden="true">...</svg></button><!-- Linked by labelledby --><h2id="section-title">Notifications</h2><ularia-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.
Identify and describe errors in text (SC 3.3.1). Link error messages to inputs with aria-describedby or aria-errormessage.
<labelfor="email">Email</label><inputid="email"type="email"aria-describedby="email-error"aria-invalid="true"><pid="email-error"role="alert">Enter a valid email address, e.g. name@example.com</p>
1.10 ARIA Live Regions
Announce dynamic content changes to screen readers (SC 4.1.3).
<!-- Polite: announced when user is idle --><divaria-live="polite"aria-atomic="true">
3 results found
</div><!-- Assertive: interrupts current speech --><divrole="alert">
Your session will expire in 2 minutes.
</div><!-- Status messages --><divrole="status">
File uploaded successfully.
</div>
Use aria-live="polite" by default. Reserve role="alert" / aria-live="assertive" for time-sensitive warnings.
1.11 ARIA Role Quick Reference
Role
Purpose
Native Equivalent
button
Clickable action
<button>
link
Navigation
<a href>
tab / tablist / tabpanel
Tab interface
None
dialog
Modal
<dialog>
alert
Assertive live region
None
status
Polite live region
<output>
navigation
Nav landmark
<nav>
main
Main landmark
<main>
complementary
Aside landmark
<aside>
search
Search landmark
<search> (HTML5)
img
Image
<img>
list / listitem
List
<ul>/<li>
heading
Heading (with aria-level)
<h1>-<h6>
menu / menuitem
Menu widget
None
tree / treeitem
Tree view
None
grid / row / gridcell
Data grid
<table>
progressbar
Progress
<progress>
slider
Range input
<input type="range">
switch
Toggle
<input type="checkbox">
Rule: Prefer native HTML over ARIA. Use ARIA only when no native element exists for the pattern.
1.12 Label in Name (WCAG 2.5.3 Level A)
When an interactive element has visible text, its accessible name must contain that visible text as a substring (SC 2.5.3). Voice control users (Dragon NaturallySpeaking, macOS Voice Control) speak the visible label to activate controls. If aria-label replaces or contradicts the visible text, voice commands fail.
<!-- Correct: aria-label contains visible text as substring --><buttonaria-label="Delete item from cart">Delete</button><!-- Correct: no aria-label needed — visible text is the accessible name --><button>Save Changes</button><!-- Correct: icon button — no visible text, aria-label is fine --><buttonaria-label="Close dialog"><svgaria-hidden="true">...</svg></button>
<!-- Incorrect: aria-label overrides visible text with different text --><buttonaria-label="Remove">Delete</button><!-- Incorrect: aria-label does not contain visible "Submit" --><buttonaria-label="Proceed to next step">Submit</button>
Rule: When visible text is present, aria-label must include that visible text (verbatim, case-insensitively). Prefer no aria-label at all when visible text is sufficient.
2. Responsive Design [CRITICAL]
2.1 Mobile-First Approach
Write base styles for the smallest viewport. Layer complexity with min-width media queries.
Minimum 44x44 CSS pixels for touch targets (WCAG SC 2.5.5 AAA; SC 2.5.8 requires only 24x24px at AA). Provide at least 24px spacing between adjacent targets.
button, a, input, select, textarea {
min-height: 44px;
min-width: 44px;
}
/* Enlarge tap area without changing visual size */.icon-button {
position: relative;
width: 24px;
height: 24px;
}
.icon-button::after {
content: "";
position: absolute;
inset: -10px; /* expands clickable area */
}
Validate on blur (not on every keystroke). Show success and error states.
<divclass="field"data-state="error"><labelfor="username">Username</label><inputid="username"type="text"aria-describedby="username-hint username-error"aria-invalid="true"><pid="username-hint"class="hint">3-20 characters, letters and numbers only</p><pid="username-error"class="error"role="alert">Username must be at least 3 characters</p></div>
Indicate required fields visually and programmatically. Use required attribute and visible markers.
<labelfor="name">
Full name <spanaria-hidden="true">*</span><spanclass="sr-only">(required)</span></label><inputid="name"type="text"requiredautocomplete="name">
If most fields are required, indicate which are optional instead.
3.7 Submit Button State
Do not disable the submit button. Instead, validate on submit and show errors.
<!-- Good: always enabled, validate on submit --><buttontype="submit">Create Account</button><!-- Bad: disabled button with no explanation --><!-- <button type="submit" disabled>Create Account</button> -->
Disabled buttons fail to communicate why the user cannot proceed. If you must disable, provide a visible explanation.
3.8 Keep Instructions Near the Field
Place format examples, constraints, and recovery text next to the relevant field via hint and error text. Never explain requirements only once in introductory copy and expect users to remember them later.
4. Typography [HIGH]
4.1 Font Stacks
Use system font stacks for performance, or web fonts with proper fallbacks.
/* System font stack */body {
font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
}
/* Monospace stack */code, pre, kbd {
font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
}
/* Web font with fallbacks and size-adjust */@font-face {
font-family: "CustomFont";
src: url("/fonts/custom.woff2") format("woff2");
font-display: swap;
font-weight: 100900;
}
body {
font-family: "CustomFont", system-ui, sans-serif;
}
4.2 Relative Units
Use rem for font sizes and spacing. Use em for component-relative sizing.
Body text line height of at least 1.5 (SC 1.4.12). Paragraph spacing at least 2x font size.
body {
line-height: 1.6;
}
h1, h2, h3 {
line-height: 1.2;
}
p + p {
margin-top: 1em;
}
4.4 Maximum Line Length
Limit line length to approximately 75 characters for readability.
.prose {
max-width: 75ch;
}
/* Or for a content column */.content {
max-width: 40rem; /* roughly 65-75ch depending on font */margin-inline: auto;
}
4.5 Typographic Details
Use real quotes, proper dashes, and tabular numbers for data.
/* Smart quotes */q { quotes: "\201C""\201D""\2018""\2019"; } /* curly double then single *//* Tabular numbers for aligned data */.data-tabletd {
font-variant-numeric: tabular-nums;
}
/* Oldstyle numbers for running prose (optional) */.prose {
font-variant-numeric: oldstyle-nums;
}
/* Proper list markers */ul { list-style-type: disc; }
ol { list-style-type: decimal; }
4.6 Heading Hierarchy
Use h1 through h6 in order. Never skip levels. One h1 per page.
<!-- Good --><h1>Page Title</h1><h2>Section</h2><h3>Subsection</h3><h2>Another Section</h2><!-- Bad: skipping h2 --><h1>Page Title</h1><h3>Subsection</h3><!-- Where is h2? -->
If you need visual styling that differs from the hierarchy, use CSS classes:
<h2class="text-lg">Visually smaller but semantically h2</h2>
5. Performance [HIGH]
5.1 Lazy Load Below-Fold Images
Use native lazy loading for images not visible on initial load.
After a user action, acknowledge the new state immediately. If work cannot finish within a brief moment, show progress, skeletons, optimistic UI, or aria-busy feedback instead of leaving the interface unchanged.
6. Animation and Motion [MEDIUM]
6.1 Respect prefers-reduced-motion
Always provide a reduced-motion alternative (SC 2.3.3, Level AAA).
/* Define animations normally */.fade-in {
animation: fadeIn 300ms ease-out;
}
@keyframes fadeIn {
from { opacity: 0; transform: translateY(8px); }
to { opacity: 1; transform: translateY(0); }
}
/* Remove or reduce for users who prefer it */@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms!important;
animation-iteration-count: 1!important;
transition-duration: 0.01ms!important;
scroll-behavior: auto !important;
}
}
// Check in JavaScriptconst prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
6.2 Compositor-Friendly Animations
Animate only transform and opacity for smooth 60fps animation. These run on the GPU compositor thread.
/* Or use CSS filter for simple cases */@media (prefers-color-scheme: dark) {
.decorative-img {
filter: brightness(0.9) contrast(1.1);
}
}
7.6 Respect prefers-contrast
Honor the user's contrast preference using @media (prefers-contrast: more) and @media (prefers-contrast: forced). prefers-contrast: more responds to macOS/iOS "Increase Contrast" in System Settings; prefers-contrast: forced responds to Windows High Contrast Mode — a distinct OS feature that overrides colors entirely.
/* Default theme */:root {
--color-text: #555770;
--color-border: #d1d1e0;
--color-bg: #ffffff;
}
/* High contrast mode: stronger text and border colors */@media (prefers-contrast: more) {
:root {
--color-text: #1a1a2e; /* Darker text for higher ratio */--color-border: #1a1a2e; /* Stronger borders */--color-bg: #ffffff;
}
/* Ensure interactive elements are clearly delineated */button, input, select, textarea {
border: 2px solid currentColor;
}
}
/* Forced colors (Windows High Contrast mode) */@media (prefers-contrast: forced) {
/* Use system color keywords to respect OS color palette */:root {
--color-text: ButtonText;
--color-bg: ButtonFace;
--color-border: ButtonBorder;
}
}
8. Navigation and State [MEDIUM]
8.1 URL Reflects State
Every meaningful view should have a unique URL. Users should be able to bookmark, share, and reload any state.
// Update URL without full page reloadfunctionupdateFilters(filters) {
const params = newURLSearchParams(filters);
history.pushState(null, '', `?${params}`);
renderResults(filters);
}
// Restore state from URL on loadconst params = newURLSearchParams(location.search);
const initialFilters = Object.fromEntries(params);
Set lang on the <html> element. Use dir="auto" for user-generated content.
<htmllang="en"dir="ltr"><!-- User-generated content: let browser detect direction --><pdir="auto">User-submitted text here</p><!-- Explicit override for known RTL content --><blockquotelang="ar"dir="rtl">...</blockquote>
10.2 Intl APIs for Formatting
Use the Intl API for locale-aware formatting. Never hard-code date or number formats.
Text in images cannot be translated, resized, or read by screen readers. Use HTML/CSS text with background images when a styled text overlay is needed.
10.4 CSS Logical Properties
Use logical properties instead of physical ones to support both LTR and RTL layouts.
/* Physical (breaks in RTL) *//* margin-left: 1rem; padding-right: 2rem; border-left: 1px solid; *//* Logical (works in LTR and RTL) */.sidebar {
margin-inline-start: 1rem;
padding-inline-end: 2rem;
border-inline-start: 1px solid var(--color-border);
}
.stack > * + * {
margin-block-start: 1rem;
}
/* Logical shorthands */.box {
margin-inline: auto; /* left + right */padding-block: 2rem; /* top + bottom */inset-inline-start: 0; /* left in LTR, right in RTL */border-start-start-radius: 8px; /* top-left in LTR, top-right in RTL */
}
Physical
Logical
left / right
inline-start / inline-end
top / bottom
block-start / block-end
margin-left
margin-inline-start
padding-right
padding-inline-end
border-top-left-radius
border-start-start-radius
width
inline-size
height
block-size
text-align: left
text-align: start
10.5 RTL Layout Support
Test layouts in RTL mode. Flexbox and Grid handle RTL automatically with logical properties.
/* This layout works in both LTR and RTL without changes */.layout {
display: flex;
gap: 1rem;
}
/* Icons that indicate direction need flipping */[dir="rtl"].arrow-icon {
transform: scaleX(-1);
}
11. Progressive Web Apps [MEDIUM]
PWAs allow web apps to be installed and run offline. When building an installable web app, the following rules ensure the experience is consistent and reliable.
11.1 Provide a Complete Web App Manifest
Include a manifest.json linked from <head> with all required fields for installability. Missing fields silently prevent install prompts.
{"name":"My App"// Missing start_url, display, and icons — app is not installable}
11.2 Set theme_color and background_color
theme_color tints the browser chrome and the OS task switcher. background_color fills the splash screen before the app loads. Both must match your brand colors.
11.3 Register a Service Worker for Offline Support
A service worker is required for installability and offline capability. Cache critical assets on install; respond from cache when offline.
// In your main entry pointif ('serviceWorker'in navigator) {
navigator.serviceWorker.register('/sw.js');
}
// sw.js — cache on install, serve from cache when offlineconstCACHE = 'v1';
constPRECACHE = ['/', '/index.html', '/app.js', '/app.css'];
self.addEventListener('install', e =>
e.waitUntil(caches.open(CACHE).then(c => c.addAll(PRECACHE)))
);
self.addEventListener('fetch', e =>
e.respondWith(
caches.match(e.request).then(hit => hit ?? fetch(e.request))
)
);
11.4 Meet Installability Criteria
For the browser install prompt to appear: the app must be served over HTTPS, have a registered service worker with a fetch handler, and include a manifest with name, icons, start_url, and display: standalone (or fullscreen/minimal-ui).
11.5 Use display Mode Appropriately
Value
Use When
standalone
App replaces browser UI; most common choice
fullscreen
Games or media apps needing the entire screen
minimal-ui
Retain minimal browser controls (back, reload)
browser
No installation behavior; opens in browser tab
Evaluation Checklist
Use this checklist when building or reviewing web interfaces.
Accessibility
All images have appropriate alt text
Color contrast meets 4.5:1 (text) and 3:1 (UI components)
All interactive elements are keyboard accessible
Focus indicators are visible (3:1 contrast, 2px minimum perimeter)
Skip navigation link is present
Form inputs have associated labels
Error messages are linked to their inputs
Dynamic content updates use ARIA live regions
No content flashes more than 3 times per second
Page has proper heading hierarchy (h1-h6, no skips)
Landmarks are used correctly (main, nav, header, footer)
Responsive
No horizontal scrolling at 320px width
Touch targets are at least 44x44px
Viewport meta tag is present (no user-scalable=no)
Layout works on mobile, tablet, and desktop
Text is readable without zooming on mobile
Forms
All inputs have visible labels
Autocomplete attributes are set for common fields
Correct input types trigger correct mobile keyboards
Error messages are clear and specific
Required fields are indicated
Submit button is not disabled
Performance
Below-fold images use loading="lazy"
Images have explicit width and height
Critical fonts are preloaded
Third-party origins use preconnect
Large JS bundles are code-split
Motion and Theming
prefers-reduced-motion is respected
Animations use only transform and opacity
Dark mode maintains contrast ratios
color-scheme meta tag is present
Theme uses CSS custom properties
prefers-contrast: more increases text and border contrast
prefers-contrast: forced uses system color keywords
Internationalization
lang attribute on <html>
CSS logical properties used (not physical)
Dates/numbers formatted with Intl APIs
No text embedded in images
Layout tested in RTL mode
Progressive Web App
Web App Manifest linked from <head> with name, icons, start_url, and display
theme_color and background_color match brand palette
Service worker registered with a fetch handler for offline support
App served over HTTPS
Common Anti-Patterns
Anti-Pattern
Fix
<div onclick="...">
Use <button>
outline: none without replacement
Use :focus-visible with custom outline
placeholder as label
Add a <label> element
tabindex="5"
Use tabindex="0" or natural order
user-scalable=no
Remove it
font-size: 12px
Use font-size: 0.75rem
Animating width/height/top/left
Animate transform and opacity
Disabling submit button
Validate on submit, show errors
Color alone for status
Add icon, text, or pattern
margin-left / padding-right
Use margin-inline-start / padding-inline-end
<img> without dimensions
Add width and height attributes
Hover-only disclosure
Add :focus-within and click handler
Credits & Attribution
This skill is based on the excellent work by
ehmo.
Special thanks to ehmo for their generous open-source contributions, which helped shape this skill collection.
Adapted by webconsulting.at for this skill collection
