guidelines
Contrast and accessibility.
Contrast, focus, alt text and reflow, so everyone can read and use the page, in sunlight or with a screen reader. 12 guidelines.
| Guideline | Priority | WCAG 2.2 |
|---|---|---|
| Body text contrast is at least 4.5:1 against its background | Critical | 1.4.3 |
| UI component boundaries and meaningful icons hit 3:1 contrast | High | 1.4.11 |
| Every interactive element shows a visible focus indicator | Critical | 2.4.7 |
| Dialogs trap focus while open, release it on close and close on Escape | Critical | 2.1.2 |
| Anything clickable is a <button> or <a>, operable by keyboard | Critical | 2.1.1 |
| Every image gets alt text for its function, or empty alt if decorative | High | 1.1.1 |
| Headings form a logical outline: one h1, no skipped levels | Medium | 1.3.1 |
| Honor prefers-reduced-motion for every animation | High | 2.3.3 |
| Icon-only buttons carry an accessible name | High | 4.1.2 |
| Declare the page language and give every page a unique title | Medium | 3.1.1 |
| In body text, links are distinguishable without color | Medium | 1.4.1 |
| Content reflows to a 320px viewport with no horizontal scrolling | High | 1.4.10 |
Critical priority
Body text contrast is at least 4.5:1 against its background
WCAG 2.2 success criterion 1.4.3.
Do
Verify every text/background pair: 4.5:1 minimum for normal text, 3:1 for large text (24px, or 18.7px bold); pick a muted token that still passes, like #595959 on #FFFFFF (7.0:1)
Avoid
Ship the fashionable #9CA3AF-on-white caption (2.6:1) - it fails everyone in sunlight and excludes low-vision users entirely
On the Health Report
The report checks this: text contrast is at least 4.5 to 1.
High priority
UI component boundaries and meaningful icons hit 3:1 contrast
WCAG 2.2 success criterion 1.4.11.
Do
Input borders, checkbox outlines, focus rings and informative icons need 3:1 against adjacent colors - #767676 on white (4.5:1) is a safe border floor
Avoid
Draw form fields with #E5E7EB borders on white (1.2:1) so low-vision users cannot find where to click
Critical priority
Every interactive element shows a visible focus indicator
WCAG 2.2 success criterion 2.4.7.
Do
Style :focus-visible with a 2px outline offset from the element, in a color with 3:1 contrast; never remove an outline without replacing it
Avoid
Ship *:focus { outline: none } because the ring clashed with the brand - keyboard users lose their position on the page completely
Critical priority
Dialogs trap focus while open, release it on close and close on Escape
WCAG 2.2 success criterion 2.1.2.
Do
Use <dialog>.showModal(): focus moves in, Tab cycles inside, Escape closes, and focus returns to the trigger - the full contract for free
Avoid
Hand-roll an overlay div where Tab escapes into the page behind, or a trap that ignores Escape - a hard blocker for keyboard users
Critical priority
Anything clickable is a <button> or <a>, operable by keyboard
WCAG 2.2 success criterion 2.1.1.
Do
Use <button> for actions and <a href> for navigation - free focus, Enter/Space activation and correct role; ARIA on a div obligates you to add tabindex, role and key handlers yourself
Avoid
Attach onclick to <div> and <span>: invisible to Tab, dead to Enter and Space, unannounced by screen readers
High priority
Every image gets alt text for its function, or empty alt if decorative
WCAG 2.2 success criterion 1.1.1.
Do
Describe what the image does in context ('Revenue chart: up 12% week over week'); give purely decorative images alt="" so screen readers skip them
Avoid
Omit the alt attribute (readers announce the filename) or write alt="image" on the chart that carries the page's actual argument
On the Health Report
The report checks this: every image has alt text.
Medium priority
Headings form a logical outline: one h1, no skipped levels
WCAG 2.2 success criterion 1.3.1.
Do
Choose heading levels by document structure and restyle with CSS; screen-reader users navigate by heading jumps, so h2 to h3 must reflect real nesting
Avoid
Pick h4 because it 'looks the right size', skip from h1 to h5 or style bold divs as fake headings invisible to heading navigation
On the Health Report
The report checks this: heading levels run in order.
High priority
Honor prefers-reduced-motion for every animation
WCAG 2.2 success criterion 2.3.3.
Do
Wrap non-essential animation in @media (prefers-reduced-motion: no-preference), and swap parallax and zooms for opacity fades when reduce is set - motion triggers real vestibular symptoms
Avoid
Autoplay a parallax hero and scroll-linked zooms with no reduced variant
High priority
Icon-only buttons carry an accessible name
WCAG 2.2 success criterion 4.1.2.
Do
Add aria-label (or visually hidden text) matching the action: 'Close', 'Search', 'Copy code'; the tooltip and the accessible name should agree
Avoid
Ship <button><svg/></button> - announced as just 'button', leaving the action a guessing game
On the Health Report
The report checks this: every button and link has a name.
Medium priority
Declare the page language and give every page a unique title
WCAG 2.2 success criterion 3.1.1.
Do
Set <html lang="en"> (and lang on inline foreign phrases) so screen readers pick the right voice; make <title> name the page, then the site
Avoid
Leave lang off (content gets mispronounced) or reuse <title>Home</title> on all 40 pages so tabs and history are indistinguishable
On the Health Report
The report checks this: every page declares its language.
Medium priority
In body text, links are distinguishable without color
WCAG 2.2 success criterion 1.4.1.
Do
Underline inline links; if you remove underlines, the link color needs 3:1 against the surrounding text plus a non-color cue on hover and focus - in practice, keep the underline
Avoid
Mark links only by a slightly different blue that color-blind readers cannot detect inside a paragraph
High priority
Content reflows to a 320px viewport with no horizontal scrolling
WCAG 2.2 success criterion 1.4.10.
Do
Test at 320px wide (equivalent to 400% zoom on a 1280px desktop): use fluid grids, max-width:100% media and overflow-x:auto only on data tables and code blocks
Avoid
Fix the layout at 1200px so magnification users must pan horizontally to read every single line
On the Health Report
The report checks this: pages fit a 360 px screen. The report loads each page at 360 px, a common phone width. The guideline asks for a layout that still works at 320 px.
See how your website reads on a phone.
Run the free website health check on any site, then keep it easy to read with the Website Health Report each month.