Ryan Perez · Accessibility system · WCAG 2.2 AA

Incomplete, not merely non-compliant.

If a person cannot receive the information, understand the interface, operate the controls or recover from an error using their available mode of access, the design is unfinished. This is not a QA layer bolted to the end — it constrains every decision in every other system here, and it outranks brand expression when the two conflict.

Honest scope A passing component library is not a conformant site. Conformance needs automated and human evaluation of the whole experience.

Four stages, in order

Locate → Access → Know → Act

Every element passes through four questions, and the first failure is the one to fix. Jumping to the last stage is why so much remediation adds ARIA to something nobody could find.

Levels

AA is the baseline, not the ambition

Do not claim That a whole site conforms because a template, a component library or an automated scanner passed. Scanners find roughly a third of real issues, and none of the ones about meaning.

The branch

First failure wins

{{ l.t }}

Precedence Where brand expression conflicts with accessibility, accessibility wins. That is a standing decision in this library, not a case-by-case negotiation.

This library, measured

Every pair in use, with its real ratio

Computed from the actual token values, not asserted. Two pairs currently in use across these pages fail AA for normal-size text — they are listed rather than quietly omitted, because a guide that only shows its passing pairs is marketing.

Aa {{ c.label }}

Thresholds

What counts as large text

Large means 24px at normal weight, or 18.66px when bold. The accent clears 3:1 comfortably, so it is safe for display type and for UI graphics — the failure is confined to small text.

Colour-only information

The same status, twice

Use

Shape, word and colour. Any one alone is enough.

Avoid

Three identical dots. Colour is the only carrier.

Colour rules

Nine, including both modes

{{ r.a }}
{{ r.b }}

Do not invert. Shadows, borders, disabled states, charts, focus rings, images and error states each need separate validation in the second mode.

Text spacing tolerance

The same paragraph under user override

A user may force line height 1.5×, paragraph spacing 2×, letter spacing 0.12× and word spacing 0.16×. Nothing may be lost or clipped. These are tolerances the layout must survive, not defaults it must adopt.

Every process has a step that assumes a brain it never met. Rebuild the smallest broken step — the form field, not the org chart.

Focus · tab through these

Four focus treatments, live

Press Tab to move through them. Three are usable; one is the default that most sites ship after someone removed the outline to tidy up a design review.

Library default: a solid ring at least 2px thick with at least 3:1 contrast between the focused and unfocused states — stricter than AA, since the formal Focus Appearance criterion is AAA and the cost of meeting it is nil.

Target size · rendered at true scale

24 is the floor. 44 is the default.

The dashed outline is the hit area, drawn at real size. AA requires 24×24 CSS px with defined exceptions; this library prefers 44×44 wherever it does not damage the interface.

Keyboard

Eight rules

{{ r.a }}
{{ r.b }}

Never A generic container with a click handler where a native link or button gives the correct behaviour for free — role, focusability, keyboard activation and the platform's own conventions.

Links versus buttons

Destination or state change

{{ r.a }}
{{ r.b }}

Accessible names

Typography & structure

Ten rules

{{ r.a }}
{{ r.b }}

Reflow & zoom

320px and 200%

{{ r.a }}
{{ r.b }}

Images & alt text

Error states, rendered

The same failed field, two ways

Both have the same validation logic. One tells a person what went wrong and how to fix it; the other turns a border red and hopes.

Use

2 problems to fix Work email — enter an address including @Budget range — choose one option

Work email (required) We reply from this address within two working days. ryan.perez.ca Enter an address including @ — for example name@company.com

Send enquiry

Avoid

Work email *

Budget range *

Send enquiry Complete all fields to continue

Form rules

Ten, plus the submit-button clause

{{ r.a }}
{{ r.b }}

The disabled-submit trap Do not disable submit before submission if that stops people discovering what is incomplete. Allow the submit, then return an error summary that links to each field. A greyed button with no explanation is a dead end for anyone who cannot scan the whole form at once.

Components

Five patterns, each with its exit condition

{{ r.a }}
{{ r.b }}

Reduced motion

A replacement mode, not a faster one

The most common mistake is halving every duration and calling it done. Reduced motion means the movement is gone — the information it carried has to arrive another way.

Motion rules

Nine, and the flash limit

{{ r.a }}
{{ r.b }}

Hard limit Nothing flashes more than three times per second. This is a seizure-safety criterion, not a taste preference, and there is no design justification that outranks it.

Media

Six rules

{{ r.a }}
{{ r.b }}

Documents & exports

Six rules for decks, ebooks and proposals

{{ r.a }}
{{ r.b }}

WCAG was written for web content. For documents, apply the same principles alongside the W3C's guidance on non-web information and communications technology.

Cognitive

Seven rules

{{ r.a }}
{{ r.b }}

Semantics & ARIA

Seven rules

{{ r.a }}
{{ r.b }}

The rule No ARIA is better than incorrect ARIA. A missing role leaves a native element working. A wrong role actively lies to the assistive technology, and the user has no way to detect it.

Publication gate

Eleven gates, each with required evidence

Evidence, not opinion. A gate is cleared by a named test on a named version — the last column is what gets recorded, so the claim is auditable later.

Gate Required evidence How it is proven

Manual journeys

Eight, minimum

Tested by keyboard alone, then by screen reader, then at 200% zoom. Component-level passes do not substitute for a completed journey.

{{ r.a }}
{{ r.b }}

Agent contract

Machine-readable

{{ l.t }}

Exception record

What a claimed exception must carry

An exception without a remediation date is not an exception. It is a defect with paperwork.

The central rule If a person cannot receive the information, understand the interface, operate the controls or recover from an error using their available mode of access, the design is incomplete — not merely non-compliant.