AI for Designers (UX, Product, Brand)
Proficient · M14 · lesson 14 of 27 · queued
Preview — browse every lesson free. Enroll to mark lessons complete, open partner links and save your progress. Login & enroll →
System-Level WCAG 2.2 Compliance With a Token-Level Audit
📖
now learning

System-Level WCAG 2.2 Compliance With a Token-Level Audit

15 min

Auditing a screen for accessibility fixes one screen. Auditing the design system fixes every screen that will ever be built from it, including the ones that do not exist yet. This is the leap from L2 to L3: you stop chasing contrast failures frame by frame and instead audit the token layer those frames inherit from, so that compliance becomes a property of the system rather than a manual pass you re-run forever. The work is specific and checkable - every semantic-color token pair tested against the 4.5:1 and 3:1 ratios, every interactive-element token tested against the 2.5.8 target-size minimum of 24 by 24 CSS pixels, and the focus-appearance token tested against 2.4.11's 3:1 minimum. AI does the high-volume math; you decide the targets, judge the edge cases, and own the sign-off. You walk away with a token-level accessibility report and a fix PR the design-system team can merge, which is the difference between flagging an accessibility problem and ending a whole class of them.

Why the Screen-by-Screen Audit Never Ends

At L2 you learned to audit a five-screen flow for contrast in three minutes. It works, and it is also a treadmill. Every new screen is a new audit. Every redesign re-opens the audit. Every team building from the same system runs their own audit, finds the same failures, and fixes them locally in their own files, so the same low-contrast secondary text gets discovered and patched a dozen times across a dozen surfaces and is never actually fixed at the source. The per-screen audit treats symptoms forever because it operates downstream of the cause.

The cause lives in the tokens. A modern design system defines color, spacing, sizing, and focus as named tokens - text-secondary, surface-default, button-min-height, focus-ring - and every screen built from the system inherits its accessibility characteristics from those tokens. If text-secondary on surface-default resolves to a 3.9:1 ratio, then every single screen that uses that pairing fails contrast, and there could be hundreds. Fix the token once and every screen that inherits it passes, including screens that have not been designed yet. This is the entire argument for moving the audit up a level: the token layer is the single point where a fix propagates to everything, and the per-screen audit is the single point where a fix propagates to nothing but that screen.

The shift in mindset is from "is this screen accessible?" to "can an inaccessible screen even be built from this system?" A system whose tokens are all compliant makes accessibility the default and inaccessibility the exception that requires actively going off-system. That is a categorically stronger position than a system that is accessible only where someone remembered to check, and it is the position a senior IC is expected to put their team in.

The Three Token Classes and Their Named Criteria

A token-level audit is not vague. It tests three specific classes of token against three specific, named WCAG 2.2 criteria, and knowing exactly which criterion governs which token is what makes the report defensible rather than an opinion.

Semantic-Color Token Pairs Against 4.5:1 and 3:1

The first class is the semantic-color layer: tokens like text-primary, text-secondary, text-on-accent, border-default, icon-default, paired against the surface tokens they appear on. Every foreground-background pairing the system permits is a contrast test. Text tokens against their surfaces must hit 4.5:1 for normal text and 3:1 for large text (1.4.3). Non-text tokens that carry meaning - the border of an input, a meaningful icon, the boundary of a UI component - must hit 3:1 (1.4.11). The audit enumerates every valid pairing and tests each, which is exactly the kind of high-volume deterministic math you hand to a tool, because a system with thirty semantic-color tokens and ten surfaces has hundreds of potential pairings and no human checks them all without error.

Interactive-Element Tokens Against 2.5.8 Target Size

The second class is the sizing tokens that govern how big interactive things are: button-min-height, icon-button-size, touch-target-min, tap-area. WCAG 2.2 added criterion 2.5.8 Target Size (Minimum), which requires that interactive targets be at least 24 by 24 CSS pixels (with specific exceptions for inline targets, spacing, and equivalents). The audit tests every token that sizes an interactive element against that 24-by-24 floor. This is the criterion most often missed, because designers think of accessibility as a color problem, and a 20-pixel icon button looks fine and fails a real user with a motor impairment or a thumb on a phone. Testing it at the token level means no interactive element built from the system can be too small, because the token that sizes it is already verified.

The Focus-Appearance Token Against 2.4.11

The third class is a single critical token: the focus indicator. WCAG 2.2's 2.4.11 Focus Appearance requires the focus indicator to meet a minimum, and a key part of it is a 3:1 contrast against the colors the indicator is shown over, in both the focused and unfocused adjacent states. The focus-ring token - its color, its thickness, its offset - is tested against this 3:1 minimum across every surface it can appear on. This is the token most likely to fail silently, because focus states are invisible until someone navigates by keyboard, and a faint focus ring that no one notices in a mockup locks out every keyboard and switch user. Verifying the focus token once protects every interactive element in the system, which is leverage no per-screen audit can match.

Audit the screen and you fix one screen. Audit the token and you fix every screen that inherits it, forever, including the ones not yet designed. The token layer is the only place an accessibility fix propagates to everything.

Where AI Does the Work, and Where You Do

The division of labor is the same principle that runs through this whole program, applied to a system. The AI is extraordinary at the part that is high-volume and deterministic: enumerating every valid token pairing, computing the contrast ratio for each, comparing every sizing token against 24 pixels, and flagging the focus token's contrast across surfaces. Feed it the resolved token values - the actual hex colors, the actual pixel sizes - with a structured prompt that states the criteria and their thresholds, and it produces a complete pass over hundreds of pairings in seconds, with zero fatigue and zero arithmetic slips. The contrast math in particular is fully determined by WCAG's formula, so this is computation, not judgment, and the tool genuinely wins.

What the AI does not own is everything that requires knowing your system. It does not know which token pairings are valid - whether text-secondary is ever actually placed on surface-inverse, or whether that combination is forbidden by the system's rules - and testing invalid pairings produces noise while missing the real ones. It does not know which exceptions to 2.5.8 legitimately apply to your inline links. It does not decide what the fixed token value should be, because darkening text-secondary to pass contrast might break the visual hierarchy the token was designed to express, and resolving that tension is a design decision with taste in it. And it does not sign the audit. You feed it the valid pairings, you adjudicate the exceptions, you choose the fixes that hold both accessibility and design intent, and you own the result. The AI is the calculator; you are the system's accessibility owner.

Running the Audit End to End

Here is the workflow on a real token set. It has four stages, and the rigor is front-loaded into setting it up correctly.

Stage one, extract the resolved token values. Pull the semantic-color tokens with their resolved hex values, the sizing tokens with their pixel values, and the focus token's full specification. Resolved is the key word: a semantic token often aliases a primitive (text-secondary points to gray-600 points to #717171), and you test the value at the end of the chain, on the actual surface it renders against, not the alias name.

Stage two, define the valid pairing matrix. This is the human-judgment step that makes the audit accurate. List which foreground tokens are permitted on which surface tokens according to the system's rules, so the audit tests real combinations and not the full cartesian product. This is where your knowledge of the system removes the noise that would otherwise drown the signal.

Stage three, run the AI pass against the three criteria. Feed the resolved values and the valid pairing matrix to the model with a structured prompt: test every color pairing against 4.5:1 (normal) and 3:1 (large / non-text), every interactive-sizing token against 24-by-24, and the focus token against 3:1 across surfaces. It returns a complete table of pass/fail with measured values.

Stage four, verify, adjudicate, and decide fixes. Spot-check the model's arithmetic on the failures (the math is reliable, but you sign it), adjudicate any exceptions, and for each genuine failure decide the fix - the specific new token value that hits the target without breaking hierarchy or brand. The output of this stage is the report and the fix PR.

The Token-Level Accessibility Report

The first artifact is a report structured by token, not by screen, because the token is now the unit of fix. Each row names the token or token pairing, the criterion it was tested against, the measured value, the required value, pass or fail, and the proposed fix. A failing row reads: Token pairing: text-secondary (#717171) on surface-default (#FFFFFF). Criterion: 1.4.3 normal text. Measured: 4.4:1. Required: 4.5:1. Status: FAIL. Fix: redefine text-secondary to #707070 for 4.54:1, preserving the gray hierarchy.

Notice what the token framing buys you. That one failing row, fixed once, corrects every screen in the product that uses secondary text on the default surface - which is most of them. The report's power is that its rows are not one-screen problems; they are system-wide problems with system-wide fixes, and a report with fifteen failing token rows might be silently fixing thousands of screen-level failures across every team building from the system. The report also states its own scope explicitly: which tokens were audited, which pairings were treated as valid, and which criteria were applied, so a reviewer can see the coverage and trust it.

The report is also where you carry the WCAG criterion citations honestly, the same discipline as the L2 contrast report scaled up: every row names its criterion (1.4.3, 1.4.11, 2.5.8, 2.4.11) so the failure is defensible against the standard, not against your taste. When the system team pushes back on a fix, you point to the row and the named criterion, and the conversation is about the standard, not about whether you think the gray looks too light.

The Fix PR the System Team Can Merge

The second artifact is what separates flagging from fixing: an actual pull request against the design system's token source that the system team can review and merge. A report that lands in someone's inbox is a request; a PR with the corrected token values, each change annotated with its criterion and its before/after ratio, is a fix that is one approval away from propagating to every consumer of the system. This is the senior-IC move - you do not file a ticket asking the system team to figure out and apply the fix; you do the work, propose the exact token changes, and let them review and merge.

The PR's structure matters. Each token change carries a one-line justification tied to the report row: "text-secondary: #717171 to #707070, fixes 1.4.3 contrast on surface-default (4.4:1 to 4.54:1), preserves gray-scale hierarchy." Grouped by token class, with the report attached as the evidence, the PR gives the system team everything they need to merge with confidence: the failure, the criterion, the fix, the ratio after, and the assurance that you considered the design impact. A well-built PR like this often merges same-day, because you have removed every reason to hesitate and the change is self-evidently a net improvement that breaks nothing.

There is a coordination reality to name here too. Because a token change propagates everywhere, the PR has to be reviewed for unintended visual impact across surfaces - darkening a token fixes contrast but changes appearance on every screen, and the system team owns that blast radius. The right PR anticipates this: it notes which surfaces are affected, confirms the change is within the design's tolerance, and where a fix would genuinely break something, it flags the tension for a design conversation rather than forcing it. The leverage of a token fix is also its risk, and a senior IC's PR respects both.

When a Token Fix Is Not Enough

Be honest about the boundary, because the token layer is powerful but not total. Some accessibility failures are not token-level and a token audit will not catch them. Keyboard focus order is a structural property of a screen, not a token. Whether a meaningful icon has an accessible label is a per-component decision. Whether the reading order matches the visual order is a layout property. The token audit closes the entire class of failures that live in token values - contrast, target size, focus appearance - which is a large and high-frequency class, and it leaves the structural and per-component failures to other audits in the chapter. Claiming a token audit makes the system fully accessible would be exactly the kind of fabricated-compliance error this program warns about; claiming it makes a specific, named, large class of failures impossible to build is true and worth everything.

The honest framing is layered defense. The token audit is the foundation: it guarantees the values every screen inherits are compliant, so no screen can fail on contrast, target size, or focus appearance by accident. On top of that, per-screen and per-component audits catch the structural failures tokens cannot express. Each layer covers what the others cannot, and a senior IC knows which layer owns which failure, so the token report can state precisely what it guarantees and precisely what it does not - which is the difference between a defensible accessibility posture and an overclaimed one.

Why This Is the L3 Version of Accessibility

The through-line of L3 is operating at the system level and shipping artifacts that are real, reviewable, and propagate. The token-level audit is accessibility expressed that way. An L1 designer spots a low-contrast button. An L2 designer audits a flow and produces a contrast report with fix coordinates. An L3 designer audits the token layer the whole organization builds from, produces a report whose every row is a system-wide fix, and ships a PR that ends the failure class at its source. Same underlying skill - knowing the named ratios and criteria cold - applied at the level where it stops being a recurring chore and becomes a structural guarantee.

And it is the version that scales the designer rather than the work. The per-screen audit means accessibility costs more as the product grows, because there are more screens to check. The token audit means accessibility cost is roughly fixed regardless of product size, because you audit the tokens, not the screens, and the screens inherit. In an organization shipping at AI-augmented speed, where the number of screens is exploding precisely because generation is cheap, the only accessibility strategy that keeps up is the one that operates where the screens come from. That is the token layer, and owning it is how a senior IC keeps a fast-growing product accessible without the audit work growing with it. The AI computes the hundreds of ratios; you make the system itself accessible-by-default; and the result is a guarantee that holds for every screen the system will ever produce.

Key Takeaways

  • The per-screen audit is a treadmill: it fixes one screen, the same failures get re-discovered across every surface and team, and it operates downstream of the cause. Auditing the token layer fixes every screen that inherits the token, including ones not yet designed, because the token is the single point where a fix propagates to everything.
  • A token audit tests three specific classes against three named criteria: semantic-color token pairings against 4.5:1 normal text / 3:1 large and non-text (1.4.3, 1.4.11), interactive-sizing tokens against the 24-by-24 CSS-pixel minimum (2.5.8), and the focus-appearance token against the 3:1 minimum (2.4.11).
  • The AI owns the high-volume deterministic math - enumerating and computing hundreds of pairings, comparing sizes, checking the focus token across surfaces - because contrast is a fixed formula and the tool does not tire or slip. You own what requires knowing the system: which pairings are valid, which exceptions apply, what the fixed value should be, and the sign-off.
  • Run it in four stages: extract resolved token values (test the end of the alias chain, not the name), define the valid pairing matrix (the human step that removes noise), run the AI pass against the three criteria, then verify, adjudicate exceptions, and choose fixes that hold both accessibility and design intent.
  • The token-level report is structured by token, not screen, and every row names its criterion so failures are defensible against the standard. One failing token row, fixed once, can silently correct thousands of screen-level failures across every team building from the system.
  • The fix PR is what separates flagging from fixing: corrected token values against the system source, each annotated with criterion and before/after ratio, anticipating the visual blast radius a token change propagates everywhere. A well-built PR often merges same-day because it removes every reason to hesitate.
  • Be honest about the boundary: the token audit closes a large class (contrast, target size, focus appearance) but not structural failures (focus order, accessible labels, reading order), which other audits own. Claim what it guarantees and what it does not - layered defense, not total coverage. It scales the designer instead of the work, which is the only strategy that keeps a fast-growing product accessible.