A styleguide two models can be held to

Before writing any style, read the project's tokens and the three nearest existing components.

Check

The change adds no color, size or spacing literal that an existing token already covers.

Why

Reading existing tokens avoids competing definitions.

Rests on

House convention.

Where the project and this guide disagree, follow the project and say so in the change description.

Check

The description names the rule id being set aside.

Why

A guide that overrides a working codebase produces two styles instead of one.

Rests on

House convention.

When a style decision is not obvious, cite the rule id in the commit or pull request.

Check

A change that introduces a new visual pattern has a rule id in its description.

Why

A cited rule can be argued with. An uncited preference can only be reverted.

Rests on

House convention.

Do not restyle what the task did not ask about.

Check

Every changed selector is reachable from the task's stated scope.

Why

Drive-by restyling is how two agents end up reformatting each other's work forever.

Rests on

House convention.

When two agents disagree about a rule, neither edits the other's output; the disagreement is filed as an objection and the text stands until both sign a replacement.

Check

No revert-and-restyle commit pair between agents on the same file within one change.

Why

A style argument carried out in diffs has no record and no end.

Rests on

House convention.

Use at most two type families plus one monospace.

Check

Count the distinct first-choice families across all font-family declarations.

Why

Every added family is a download, a rhythm and a decision the next contributor has to guess at.

Rests on

House convention.

Enforced by

css.families (source)

Use a computed body and form-control text size of at least 16px at default settings; verify the actual size rather than assuming 1rem always equals 16px.

Check

Computed font-size of running text and of input, select and textarea is 16px or more at default settings.

Why

Smaller body text is the commonest reason a page is zoomed, and iOS zooms the viewport on focus for controls under 16px.

Rests on

House convention, not a WCAG minimum font size.

Enforced by

css.body-size (source, warns), css.input-size (source, warns)

Set font sizes in rem, or a clamp() built on rem, never in px. The root element keeps the reader's default: its font-size is 100 percent or unset, never a px or percentage value that rescales it.

Check

No font-size declaration in px, and the root font-size is 100 percent or unset.

Why

A px size ignores the default text size a reader has set in their browser. Page zoom does scale px text, so this is a rule of this guide, not a conformance failure.

Rests on

Convention. WCAG 2.2 SC 1.4.4 Resize Text (AA) is met by page zoom and does not require relative units, so do not report a px font-size as a WCAG defect.

Enforced by

css.font-px (source), css.root-size (source)

Take every size from one scale of at most eight steps.

Check

The stylesheet declares eight or fewer distinct font-size values.

Why

A ninth size is almost always a mistake nobody wanted to look up.

Rests on

House convention.

Enforced by

css.size-count (source)

Hold running text to between 45 and 75 characters a line.

Check

Prose containers set max-width between 45ch and 75ch.

Why

Past about 80 characters the eye loses the start of the next line.

Rests on

WCAG 2.2 SC 1.4.8 Visual Presentation (AAA) caps width at 80 characters; 45 to 75 is the older typographic convention

Line-height is unitless: 1.5 to 1.7 for running text, 1.05 to 1.3 for headings.

Check

No line-height carries a length unit, and running text computes to at least 1.5.

Why

A line-height with a unit does not scale when the font size does, and lines collide.

Rests on

WCAG 2.2 SC 1.4.8 Visual Presentation (AAA) asks for line spacing of at least space-and-a-half within paragraphs. Not SC 1.4.12, which governs the reader's own overrides: see type.spacing-override.

Enforced by

css.leading-units (source)

Text survives the reader's own spacing: no text is clipped when line height is set to 1.5 times the font size, paragraph spacing to 2 times, letter spacing to 0.12em and word spacing to 0.16em.

Check

Apply all four user spacing overrides and confirm no text or functionality is lost.

Check

Fixed block sizes with overflow hidden/clip warrant inspection; source cannot prove actual clipping. Scrolling overflow and growing min-height containers may work. For intentionally truncated text, verify that its full form remains available through an accessible action.

Why

A box fitted to default typography may clip text when a reader increases spacing.

Rests on

WCAG 2.2 SC 1.4.12 Text Spacing (AA). The allowance for truncated text whose full form is available is from the W3C's Understanding document for this criterion.

Enforced by

css.clipped-text (source, warns)

Never justify text.

Check

No text-align: justify.

Why

Browsers justify without hyphenation control, which opens rivers of white through the paragraph.

Rests on

WCAG 2.2 SC 1.4.8 Visual Presentation (AAA)

Enforced by

css.justify (source)

Keep capitals for labels of three words or fewer, tracked out by at least 0.06em.

Check

Every rule that sets text-transform: uppercase also sets letter-spacing of 0.06em or more.

Why

Untracked capitals set tight and read as shouting; a sentence in capitals loses its word shapes.

Rests on

House convention.

Enforced by

css.caps-tracking (source)

Numbers that change, or that align in a column, use tabular figures.

Check

Tables, counters and timers set font-variant-numeric: tabular-nums.

Why

Proportional figures make a counting number jitter and a column of prices wander.

Rests on

House convention.

Balance headings with text-wrap: balance and never break one by hand.

Check

No <br> inside a heading.

Why

A hand-placed break is correct at exactly one width.

Rests on

House convention.

Every margin, padding and gap is a multiple of 4px, or of 0.25rem, taken from a named scale.

Check

No spacing declaration is a px value that 4 does not divide, or a rem value that 0.25 does not divide, hairlines of 1px and 2px excepted. Values in em, percentages and calc() are not judged.

Why

Off-grid values are how a layout ends up with eleven slightly different gaps.

Rests on

House convention.

Enforced by

css.grid-4 (source)

The parent owns the space between children: use gap, and give components no outer margin.

Check

A component's root selector declares no margin.

Why

A component that carries its own margin is wrong in every context but the one it was drawn in.

Rests on

House convention.

Write base styles for the narrowest screen and add min-width queries upward.

Check

Media queries use min-width; a max-width query carries a comment saying why.

Why

Desktop-first styles ship every override to the device least able to afford them.

Rests on

House convention.

Enforced by

css.max-width-query (source)

The page works at 320 CSS pixels wide with no horizontal scrolling and nothing cut off.

Check

At a 320px viewport, document.documentElement.scrollWidth is 320 or less, and no container hides its overflow to get there.

Exceptions

Content that needs two dimensions to be understood, such as a data table, a map or a diagram, may scroll inside its own region.

Why

320px is a phone in portrait and also a desktop window zoomed to 400 percent.

Rests on

WCAG 2.2 SC 1.4.10 Reflow (AA)

Use logical properties such as margin-inline and padding-block in place of left and right.

Check

No margin-left, margin-right, padding-left or padding-right in new code.

Why

Physical sides are wrong the day the interface is translated into a right-to-left language.

Rests on

House convention.

Enforced by

css.physical-props (source)

Pointer targets are at least 24 by 24 CSS pixels, or are spaced so that a 24px circle centred on each does not touch another target's. Primary and touch-first controls SHOULD reach 44 by 44.

Check

Measure authored pointer targets outside the exceptions. Under 24px in either axis fails unless the criterion's 24px-circle spacing test passes. Record primary or touch-first targets below 44px as SHOULD misses, not AA failures.

Exceptions

The criterion exempts inline or line-height-constrained targets, equivalent controls on the same page, unmodified user-agent targets, and essential or legally required presentation.

Why

Small or crowded targets are difficult to operate precisely; inline text needs different treatment.

Rests on

WCAG 2.2 SC 2.5.8 Target Size (Minimum) (AA, 24px, five exceptions). SC 2.5.5 Target Size (Enhanced) (AAA, 44px) is the SHOULD, not the MUST.

z-index values come from a named scale of at most six layers.

Check

Every z-index is a token read with var(), except 0, 1 and -1 used for local stacking inside one component, and the stylesheet reads six distinct layer tokens or fewer.

Why

z-index: 9999 is an argument somebody lost with a stacking context.

Rests on

House convention.

Enforced by

css.z-index (source)

Every image, video, iframe and embed declares its intrinsic box: width and height attributes, or an aspect-ratio, or a container that reserves the space.

Check

Reserve each img, video, iframe and embed's space before loading: matching width/height attributes, aspect-ratio on the element, or an ancestor with aspect-ratio or fixed block size that the element fills. Missing reservations or a declared ratio that mismatches the file fail.

Why

Missing or incorrect reservations shift the content below a loading element.

Rests on

House convention.

Late content never moves what is being read: no banner, consent bar, ad slot, toast or injected notice is inserted above content that is already painted.

Check

Load the page on a throttled connection and watch above the fold; nothing already painted changes position. Where the project measures it in the field, Cumulative Layout Shift at the 75th percentile is 0.1 or less.

Why

A page that jumps under the reader's thumb turns a tap into the wrong tap.

Rests on

Core Web Vitals: good CLS is at most 0.1 at the field's 75th percentile. A product target, not a source-code verdict.

Use semantic tokens for component colors and keep color literals in palette definitions.

Check

Outside custom-property definitions, prefer var(), currentColor, transparent or inheritance keywords. Other CSS color literals, including named colors and color functions, depart from this default. System colors are allowed in forced-colors and prefers-contrast rules. Judge all color-bearing properties, including borders, shadows, gradients, SVG fills and strokes.

Why

Central definitions make theme changes and contrast reviews easier.

Rests on

House convention.

Enforced by

css.color-literal (source)

Name tokens for their job, such as surface, ink, accent and danger, not for their hue.

Check

No token consumed by a component has a hue word or a palette step in its name.

Why

A token called blue-500 is a lie the first time dark mode makes it a different blue.

Rests on

House convention.

Enforced by

css.token-hue-names (source)

Text meets 4.5 to 1 against its background; text of 24px, or 18.66px bold, and larger meets 3 to 1.

Check

Measure actual foreground/background pairs used by text in every relevant rendered state. Unused token combinations are not conformance failures.

Check

For imagery, gradients and translucent layers, judge the minimum composited contrast beneath the text. For a fixed opaque foreground, text luminance outside a known background-luminance range plus a passing nearer extreme is sufficient, not necessary. Over unpredictable imagery, use a backing with verified worst-case contrast; it may be translucent if every possible composite passes. A few video samples do not establish exhaustive coverage.

Exceptions

SC 1.4.3 exempts text in inactive controls, pure decoration, text invisible to everyone, text within a picture containing significant other visual content, and logos or brand names. Overlaid interface text is not incidental picture text.

Why

Below 4.5 to 1, body text disappears for readers with low vision and for everyone in sunlight. A headline over a photograph is the one that changes ratio with every image the CMS loads.

Rests on

WCAG 2.2 SC 1.4.3 Contrast Minimum (AA)

Enforced by

contrast (a color pair you supply), css.block-contrast (source, warns)

Input borders, focus rings, icons and chart marks that carry meaning meet 3 to 1 against what they touch.

Check

Measure against adjacent colors the visual information needed to identify controls, states and graphics. Do not demand a boundary when sufficiently contrasting visible content already identifies the control.

Exceptions

Inactive controls; unmodified user-agent appearance; graphics whose particular presentation is essential to their information.

Why

A form whose fields cannot be seen is a form that cannot be filled in.

Rests on

WCAG 2.2 SC 1.4.11 Non-text Contrast (AA)

Enforced by

contrast (a color pair you supply)

Color is never the only signal: pair it with text, an icon or a shape.

Check

View the interface in grayscale; every state and status is still distinguishable.

Why

A red and a green of similar lightness are one color to a reader with red-green color blindness.

Rests on

WCAG 2.2 SC 1.4.1 Use of Color (A)

Use one accent hue per product, and keep success, warning and danger colors for status alone.

Check

Interactive emphasis uses a single accent token; status tokens appear only on status.

Why

When everything is highlighted the highlight carries no information.

Rests on

House convention.

Do not set pure black on pure white; soften at least one end.

Check

No rule pairs #000 text with a #fff background, or the reverse.

Why

This is a convention, not a standard: the harshest pair a screen can show buys nothing, since near-black on off-white still clears 15 to 1.

Rests on

Convention

Enforced by

css.pure-bw (source)

Dark mode is the same tokens with different values, switched by prefers-color-scheme, with color-scheme declared. A switch the reader can set by hand is a SHOULD, and a product decision.

Check

No component selector sets a literal color under a dark-mode parent; the root declares color-scheme. A site that follows prefers-color-scheme and offers no toggle is not defective.

Why

A second stylesheet for dark mode is a second interface to keep correct.

Rests on

House convention.

Nothing a person waits on runs past 500ms. The working range for interface transitions is 120 to 320ms.

Check

No transition-duration or animation-duration above 500ms outside a progress indicator.

Why

Past half a second an animation stops explaining and starts being waited for.

Rests on

House convention.

Enforced by

css.duration (source, warns)

Prefer transform and opacity. Color, shadow, filter and clip-path are allowed. Never animate a layout property, and never write transition: all.

Check

No transition or animation, including any @keyframes block, names all, or any of width, height, inline-size, block-size, top, right, bottom, left, inset, margin, padding, border-width, font-size, or a grid or flex sizing property. Transitions and animations of color, background-color, border-color, box-shadow, filter, opacity, transform and clip-path are allowed.

Why

Layout animation can repeat layout work; transition: all also animates future untested properties. This performance default allows color and shadow feedback.

Rests on

House convention.

Enforced by

css.transition-all (source), css.layout-anim (source)

Every animation has a prefers-reduced-motion: reduce fallback.

Check

For each declared animation, or transition longer than 120ms, that moves, scales, parallaxes or rotates an element, a prefers-reduced-motion: reduce block later in the cascade sets that animation to none, to a non-moving equivalent, or to a duration under 20ms. An empty reduced-motion block, or one that does not reach the animation in question, does not count.

Check

Motion driven from JavaScript reads window.matchMedia for prefers-reduced-motion: reduce before it starts and subscribes to its change event. A motion library is configured from that value at the root, once.

Why

For people with vestibular disorders, parallax and zoom are nausea, not polish. A reduced-motion block that answers for no animation in particular is a comment, not a fallback.

Rests on

House policy covers all animation. WCAG 2.2 SC 2.3.3 (AAA) covers interaction-triggered motion and permits essential motion. Do not call an autoplay fallback omission a 2.3.3 failure; see motion.no-loop for autoplay.

Enforced by

css.reduced-motion (source, warns)

Enter with ease-out, leave with ease-in, and keep linear for progress.

Check

No linear timing on an element that enters or leaves.

Why

Things in the world decelerate into place; linear motion reads as mechanical.

Rests on

House convention.

Automatically moving content that lasts more than five seconds alongside other content can be paused, stopped or hidden unless the movement is essential.

Check

Observe each auto-starting loop alongside other content. If it lasts more than five seconds, verify a pause, stop or hide mechanism, or document why movement is essential. A progress indicator is not exempt merely because its class name says progress.

Why

Perpetual motion pulls the eye from the task the page exists for.

Rests on

WCAG 2.2 SC 2.2.2 Pause, Stop, Hide (A); evaluate its essential-activity exception in the actual context.

Enforced by

css.infinite (source, warns)

If removing an animation loses no information, remove it.

Check

Delete the animation; if a user can still tell what changed, the deletion stands.

Why

Decoration that moves is paid for on every visit by every visitor.

Rests on

House convention.

Design each control's supported states: default, hover, focus, active and disabled where applicable.

Check

Inspect supported states using pointer and keyboard. Native browser states can satisfy this requirement. Do not invent a disabled state for a link or control that never becomes disabled; visible keyboard focus remains required by state.focus.

Why

A missing state is a moment where the interface stops answering.

Rests on

House convention.

Keep keyboard focus visible; prefer a 2px or equivalent high-contrast indicator.

Check

Tab through controls. Each shows a visible indicator. This guide additionally prefers an indicator as large as a 2px perimeter and 3:1 change between focused and unfocused pixels (AAA). Verify 3:1 against adjacent colors where SC 1.4.11 applies. An outline removed without a usable replacement fails; a noninteractive programmatic target may use different focus treatment.

Why

Keyboard users navigate by the focus ring; removing it removes the cursor.

Rests on

WCAG 2.2 SC 2.4.7 Focus Visible (AA). The 2px and the focused-versus-unfocused 3 to 1 are SC 2.4.13 Focus Appearance (AAA); the indicator-against-background 3 to 1 is SC 1.4.11 Non-text Contrast (AA).

Enforced by

css.outline-none (source, warns)

Draw focus rings on :focus-visible, not :focus.

Check

Ring styles are declared on :focus-visible.

Why

Rings that appear on mouse click are why designers asked for outline: none in the first place.

Rests on

House convention.

Enforced by

css.focus-not-visible (source, warns)

Prefer native controls for actions and navigation, and give every interactive control an accessible name.

Check

Use button for an action and a with href for navigation. A custom control must provide the equivalent role, keyboard behavior, focus and state. Every interactive form control has an accessible name; comp.forms owns its visible-label policy. Hidden inputs need no name. Button-like inputs use their native naming mechanism; image inputs need appropriate alt.

Why

Native elements bring keyboard, focus and screen-reader behavior that a div has to fake and usually gets wrong.

Rests on

WCAG 2.2 SC 2.1.1 Keyboard (A) and SC 4.1.2 Name, Role, Value (A). Native-element preference is house policy; a conforming custom control is not automatically a WCAG failure.

One primary action per view.

Check

Count elements styled as the primary button in any single view; the answer is one.

Why

Two primary buttons is a decision handed back to the user.

Rests on

House convention.

Give user-editable fields a persistent visible label and an accessible name; a placeholder is never the only label.

Check

For input other than hidden, submit, reset, button and image, and for select and textarea, use a wrapping label or matching for/id. An exception may use aria-labelledby referring to persistent visible text for a search field beside a Search button or a table field whose row and column context identifies its purpose. State the exception in the change description and verify its computed name. A fieldset legend names a group, not every field; each control still needs its own identifying label.

Check

For a field collecting information about the user whose purpose is in the WCAG input-purpose list, supply the matching HTML autocomplete token. Do not apply this criterion indiscriminately to every application field.

Why

Placeholders vanish during entry. Detached labels do not reliably name controls for assistive technology.

Rests on

WCAG 2.2 SC 3.3.2 Labels or Instructions (A), SC 1.3.1 Info and Relationships (A), SC 1.3.5 Identify Input Purpose (AA). Persistent labels and the limited aria-labelledby exceptions are house policy stricter than those standards.

An error says what happened and what to do, sits next to the field, and is announced to assistive technology.

Check

Each error is tied to its field with aria-describedby and contains an instruction, not only a verdict.

Why

Invalid input tells a person they failed. Enter a date after today tells them how to succeed.

Rests on

WCAG 2.2 SC 3.3.1 Error Identification (A) and SC 3.3.3 Error Suggestion (AA)

Every view of data has a designed empty state, loading state and error state.

Check

Each data component renders three named non-happy states, and each is reachable in a test.

Why

The empty state is the first thing every new user sees.

Rests on

House convention.

Match focus behavior to modality: modal surfaces contain focus and block the background; non-modal surfaces leave the page reachable.

Check

Open a modal from the keyboard. Place focus at a meaningful starting point, contain Tab and Shift+Tab, make the background inert and provide an accessible close action including Escape. On close, return focus to the invoker, or a logical next step if it disappeared or the workflow moved on. Prefer dialog.showModal(), then verify naming, initial focus and return focus.

Check

A non-modal drawer or panel does not trap focus or make the background inert. Move focus when the task continues inside it; leave it on the trigger for an ordinary disclosure. Follow the applicable widget keyboard pattern. A command palette is modal only if its behavior blocks the page.

Why

A modal that leaves focus on the page behind it is a modal only for people who can see it, and a hand-built focus loop with no exit is a keyboard trap.

Rests on

WCAG 2.2 SC 2.1.2 No Keyboard Trap (A), SC 2.4.3 Focus Order (A), and the WAI-ARIA APG modal-dialog pattern. APG is implementation guidance, not an additional WCAG success criterion.

A message reporting the result of an action, such as saved, copied, deleted or four results found, is announced without moving focus.

Check

Each such message renders into a container that was already in the DOM, carrying a role of status or aria-live set to polite; the container is not created at the moment the message arrives. A message that stops the user takes a role of alert.

Why

A toast is silent to a screen reader unless something tells it to speak, and a live region added at the same instant as its text usually says nothing at all.

Rests on

WCAG 2.2 SC 4.1.3 Status Messages (AA)

Content that appears on hover or focus is dismissible, hoverable and persistent.

Check

With the tooltip or popover open: Escape dismisses it without moving pointer or focus; the pointer can travel onto the content without it closing; it stays until pointer or focus leaves, the user dismisses it, or its information stops being valid. It never closes on a timer.

Exceptions

Taken from the criterion: content that communicates an input error, or that does not obscure or replace other content, need not be dismissible; and content whose presentation the user agent controls and the author has not modified, such as a native title tooltip, is outside the rule.

Why

A tooltip that vanishes when you move toward it cannot be read by anyone using magnification.

Rests on

WCAG 2.2 SC 1.4.13 Content on Hover or Focus (AA)

Anything operated by dragging also works with single clicks or taps, without dragging.

Check

For each non-exempt drag interaction, complete the same task using a single pointer without dragging. Offer clickable move controls, a slider track or numeric input, or a file picker. Test keyboard operability separately under a11y.keyboard; arrow keys alone do not satisfy this rule.

Exceptions

Dragging that is essential, such as freehand drawing, and unmodified user-agent functionality are exempt. Map panning can use clickable direction controls or search and is not inherently exempt.

Why

Dragging needs a sustained, accurate press that many people cannot make, and it is the interaction that fails first on a trackpad.

Rests on

WCAG 2.2 SC 2.5.7 Dragging Movements (AA)

Signing in does not depend on an unsupported cognitive test.

Check

Credential fields accept paste and password-manager autofill. Use current-password, new-password and one-time-code as appropriate; verify the actual flow.

Check

A cognitive test has a non-cognitive alternative, an assisting mechanism, an object-recognition-only test or identification of the user's own provided content, as SC 3.3.8 permits. A cross-device code must have a supported route such as paste or autofill.

Why

Remembering and retyping credentials excludes people who depend on assistive mechanisms.

Rests on

WCAG 2.2 SC 3.3.8 Accessible Authentication (Minimum) (AA). Object recognition and personal content satisfy this level; they do not satisfy SC 3.3.9 (AAA).

Sentence case everywhere: headings, buttons, labels and menus.

Check

No Title Case string in interface copy apart from proper nouns.

Why

Sentence case reads faster and ends the argument about which words to capitalize.

Rests on

House convention.

A button is a verb and its object, such as Save draft, and never OK, Submit or Click here.

Check

Every button label begins with a verb and names what it acts on.

Why

A button should be understandable with the rest of the dialog covered up.

Rests on

House convention.

Link text names its destination and makes sense read alone.

Check

No link reads here, this, more or read more without its object.

Why

Screen-reader users pull up a list of links; ten of them saying here is no list.

Rests on

House convention requiring standalone link purpose, stricter than WCAG 2.2 SC 2.4.4 (A), which allows programmatically determined context. Standalone purpose is SC 2.4.9 (AAA), subject to its exceptions. Do not report a contextual link as a Level A failure.

Make consequential quantities and dates unambiguous in their visible context.

Check

For prices, measurements, deadlines and event times, verify that units, currency, full dates and relevant timezone can be determined without guessing. Spell the month or use an unambiguous date format when the locale is not established. A number may inherit its unit from an associated table header or label.

Why

03/04 is two different days depending on which side of an ocean it is read from.

Rests on

House functional requirement: a reader must identify the same quantity or instant the product means.

No lorem ipsum, no Welcome to, and no exclamation marks in system text.

Check

Search shipped strings for lorem, Welcome to and an exclamation mark.

Why

Placeholder text that ships says nobody read the screen before release.

Rests on

House convention.

Interface sentences stay under 20 words and lead with the point.

Check

Count words per sentence in any text longer than a label.

Why

Nobody reads an interface; they scan it for the next thing to do.

Rests on

House convention.

One h1 per page, and heading levels never skip.

Check

First, every string presented as a heading is a heading element: a div, p or span styled large or bold in that role is a defect. Then list the heading elements in document order: there is exactly one h1, and no level is jumped on the way down.

Why

Headings are the table of contents a screen reader navigates by, and a heading that is only bold text is not in it.

Rests on

WCAG 2.2 SC 1.3.1 Info and Relationships (A) requires that a visual heading be marked up as one. The single h1 and the unskipped levels are this guide's convention, not Level A, so do not report them as WCAG failures.

Use header, nav, main and footer, with exactly one main.

Check

The page has one main element and its navigation is inside nav.

Why

Landmarks let a keyboard user skip the menu they have already heard forty times.

Rests on

House convention.

Every image has an alt attribute, and a decorative image has an empty one.

Check

No img without alt; decorative images carry an empty alt.

Why

A missing alt makes a screen reader read out the file name.

Rests on

WCAG 2.2 SC 1.1.1 Non-text Content (A)

Everything works from the keyboard in visual order, with no positive tabindex.

Check

Tab through the page without a mouse; search the markup for tabindex values above 0.

Why

A positive tabindex reorders the page for keyboard users and for nobody else.

Rests on

WCAG 2.2 SC 2.1.1 Keyboard (A) and SC 2.4.3 Focus Order (A)

No sticky header, footer, toolbar or floating panel hides the focused element entirely. It SHOULD not cover any part of it.

Check

Tab through the page at 320px and at desktop width with every sticky region present. At each stop, some part of the focused element and its focus ring is visible: none visible is a defect, partly covered is a SHOULD miss. Where a sticky header exists, the scroll container sets scroll-padding-block-start to at least its height, which satisfies both.

Why

A focus ring behind a sticky header is the same as no focus ring, and it is the failure a keyboard user meets first.

Rests on

WCAG 2.2 SC 2.4.11 Focus Not Obscured (Minimum) (AA) is the MUST: not entirely hidden. SC 2.4.12 Focus Not Obscured (Enhanced) (AAA), no part of the component hidden, is the SHOULD.

An icon-only control has an accessible name.

Check

Verify each icon-only button or link's computed accessible name. Valid sources include aria-label, aria-labelledby, an image's alt, SVG naming and visually hidden text; an attribute alone does not prove the computed name.

Why

An unnamed icon button is announced as button and nothing else.

Rests on

WCAG 2.2 SC 4.1.2 Name, Role, Value (A)

The html element declares its language.

Check

The root element has a lang attribute.

Why

Without it a screen reader pronounces the page in whatever voice was used last.

Rests on

WCAG 2.2 SC 3.1.1 Language of Page (A)

Text resizes to 200 percent without loss, and the viewport never disables zoom.

Check

Resize text to 200 percent and verify content and functionality remain available. Check that viewport settings allow zoom; absence of restrictive metadata alone does not prove the rendered result.

Why

Disabling pinch-zoom takes away the one accommodation every phone ships with.

Rests on

WCAG 2.2 SC 1.4.4 Resize Text (AA)

Define shared design tokens as CSS custom properties at the scope where they apply.

Check

Shared tokens have a clear definition site; theme and component overrides are intentional and documented. A scoped override is not automatically a defect.

Why

A token needs an identifiable owner; CSS inheritance and local overrides are useful parts of that design.

Rests on

House convention.

Avoid !important unless it implements an accessibility override, a required third-party override or an intentional utility.

Check

Outside reduced-motion and forced-colors overrides, put a comment beside the declaration naming code.no-important and its reason. Review that reason against the actual cascade.

Why

Escalating specificity makes later changes harder; some overrides nevertheless need to win.

Rests on

House convention.

Enforced by

css.important (source)

Keep selectors to two classes of specificity and never style by id.

Check

No id selector in a stylesheet, and no selector chained more than three deep.

Why

High specificity is debt that is paid back with !important.

Rests on

House convention.

Enforced by

css.id-selector (source)

No inline style attribute except for a value computed at runtime.

Check

Search the markup for style= and confirm each one carries a computed value.

Why

Inline styles cannot be themed, overridden or found.

Rests on

House convention.

Breakpoints are named, number four or fewer, and live in one place.

Check

Count the distinct widths used across media queries.

Why

A fifth breakpoint is usually a component that should have been flexible.

Rests on

House convention.

Enforced by

css.breakpoint-count (source)

Delete styles with the markup they served, and leave no commented-out CSS behind.

Check

No comment contains a CSS declaration.

Why

Commented-out code is a question nobody will ever answer.

Rests on

House convention.

Enforced by

css.commented-code (source)

Prefer self-hosted fonts, font-display: swap or optional, and no more than four font files on first paint.

Check

Inspect every @font-face font-display value. Missing, auto, block or fallback departs from this house default. A comment naming code.fonts and a specific reason, such as an icon font, produces an unverified warning requiring review; the comment is not proof. Verify hosting and the first-paint file count in the network panel; the CSS check reads only font-display.

Why

A font that blocks rendering hides the text from the people with the slowest connections.

Rests on

House performance convention; font-display choice is not a WCAG verdict.

Enforced by

css.font-display (source)

Objection

Twenty-seven rules said Enforced by and named a checker the document never defined: no location, no way to run it, nothing about what it reads.

What happened

A new section, The checks, defines them and says what each one reads. The director's proposed command-line checker was declined, because no such program exists and naming one would have been the same fault in a new place. In round two the director agreed: You were right and my proposal was wrong.

Objection

The Basis was overstated: SC 1.4.4 Resize Text is met by browser zoom, which scales px text. The rule also could not be satisfied together with type.body-size under a rescaled root.

What happened

The Basis is now Convention, with an instruction not to report a px font-size as a WCAG defect, and the root stays at 100 percent.

Objection

It cited SC 1.4.12, which governs the reader's own spacing overrides, not the author's line-height. The 1.5 figure belongs to SC 1.4.8 (AAA).

What happened

The Basis moved to SC 1.4.8, and a new rule, type.spacing-override, carries the real 1.4.12 requirement.

Objection

Two floors, 44px and 24px, gave no verdict for a 32px control, and the check ignored all five of the criterion's exceptions, so it failed every link inside a sentence.

What happened

24px is the MUST with the spacing test and the exceptions taken from the criterion. 44px is a SHOULD.

Objection

Cumulative Layout Shift is a field measurement at the 75th percentile. An agent cannot fail it from a change.

What happened

Split into layout.box (MUST) and layout.shift (SHOULD). The proposed Enforced by line was declined: the checker reads stylesheets and cannot see an img element.

Objection

The check named hex, rgb() and hsl() and missed named colors, oklch(), color-mix() and the rest.

What happened

The check now lists every literal form and every color-bearing property, and the checker knows all 148 CSS named colors.

Objection

A token-pair check cannot see text drawn over an image, a gradient or a translucent layer, which is the commonest real failure. The criterion's exceptions were missing.

What happened

A second check covers text over imagery, and the exceptions were added.

Objection

The rule said transform and opacity only while its check allowed color and shadow. An agent reading the rule would strip every hover fade.

What happened

The rule now says what the check says: never animate a layout property.

Objection

The check cannot fail. An empty prefers-reduced-motion block anywhere in the file satisfied it.

What happened

The check is per animation, and the checker now requires the block to set a motion property.

Objection

A blanket ban contradicted motion.reduced, because the standard reduced-motion reset needs !important. Both were MUST.

What happened

Three named exceptions, each carrying a comment that names the rule.

Objection

The check failed the :focus-visible pattern the guide recommends, and the 3 to 1 figure was attached to the wrong pair: SC 2.4.13 measures the same pixels focused and unfocused.

What happened

The check and the Basis were rewritten, and the checker accepts a paired :focus-visible rule.

Objection

The check filed false defects against event delegation, hidden inputs and submit inputs.

What happened

Check replaced.

Objection

The check tested that a label is visible and never that it is attached. SC 1.3.5 Identify Input Purpose (AA) appeared nowhere in the guide.

What happened

The label must come from a label element, and a second check requires autocomplete tokens.

Objection

The Basis claimed Level A for one h1 and unskipped levels, which SC 1.3.1 does not require, and the check could not see a div doing a heading's job.

What happened

The check starts from what is presented as a heading, and the Basis says which part is this guide's convention.

Objection

Of the criteria WCAG 2.2 itself added, the guide carried one, while citing AAA criteria to back MUST rules.

What happened

Three new rules: a11y.focus-not-covered, comp.drag-alternative and comp.hover-content.

Objection

Nothing in 65 rules governed a dialog or where focus goes, and nothing required a status message to be announced.

What happened

Two new rules: comp.dialog and comp.status.

Objection

The new closed allowlist made CSS system color keywords a defect, which made forced-colors support impossible while code.no-important anticipated it.

What happened

System color keywords are allowed inside forced-colors and prefers-contrast blocks, and only there.

Objection

The rule offered three ways to reserve the box and the check accepted two, so the standard aspect-ratio wrapper failed. A wrong declared ratio also passed.

What happened

Check replaced.

Objection

The director's own round-one check was too absolute: it flagged a 64px app bar and a scrolling listbox, neither of which clips anything.

What happened

Rescoped to clipping. The worker declined an absolute ban on clamped text: the W3C's Understanding document for SC 1.4.12 allows truncated text whose full form is one activation away.

Objection

SC 2.5.7 exempts dragging that is essential, such as drawing or signing. Without the exception a drawing surface was a defect.

What happened

Exceptions added from the criterion.

Objection

The one rule the worker added without being asked overclaimed: a password is a memory test, and it conforms because a password manager is the permitted mechanism.

What happened

The rule now states the criterion's four satisfiers. The same class of error as round one's miscitations, made in the one place nobody had reviewed.

Objection

The rule demanded fully visible, which is SC 2.4.12 (AAA), while citing SC 2.4.11 (AA), which requires only not entirely hidden. This was the director's own round-one text.

What happened

AA is the MUST and AAA the SHOULD, on the pattern of layout.targets.

Objection

The accepted check read transitions only, so a layout property animated from @keyframes was forbidden by the rule and invisible to its check.

What happened

The check covers animations and keyframes, and the checker now parses keyframe steps.

Objection

The guide said A finding is a violation, while the checker had begun reporting patterns that source alone cannot settle, such as clamped text whose full form may be one click away.

What happened

A finding and a warning are now different things, in the text and in the checker. Nine checks are marked as warning only. One the director expected to warn, css.grid-4, was kept a finding by making its rule decidable from source.