6 definitions in this file:
Stable identifier for this criterion, unique within the parent entity (e.g., 'touch-target-minimum', 'single-primary-action'). MUST be lowercase kebab-case. Test runs report pass/fail against this identifier, so it SHOULD NOT change once checks depend on it — renaming breaks result history across runs.
Pattern: ^[a-z][a-z0-9-]*$
The testable statement of what success looks like. MUST be objectively verifiable — by inspection, static analysis, or runtime measurement. Avoid vague language like 'feels right' or 'looks balanced' (e.g., 'Interactive elements present a hit area of at least 44×44 px').
A short display name for the criterion (e.g., 'Touch Target Minimum'). Tools SHOULD render it in docs and test reports beside the identifier.
Sufficient ways to satisfy this criterion — the passing patterns (e.g., 'Apply min-height: 44px to every interactive element', 'Use the <Button> component without overriding its default height').
Min items: 1
Known failure modes — conditions that count as failing this criterion (e.g., 'Setting height below 44px on an interactive element', 'Removing aria-label from an icon-only button').
Min items: 1
External standards this criterion aligns with or derives from (e.g., a matching WCAG success criterion, a platform guideline).
Min items: 1
Verification fixtures — typically one passing and one failing implementation, each with a declared outcome.
Min items: 1
Freeform keywords that relate criteria across guidelines and entities (e.g., 'a11y', 'contrast', 'touch-target').
The conformance level of this criterion. A criterion referenced by a guideline SHOULD inherit the guideline's level when omitted; a standalone criterion SHOULD declare its own.
The design system version in which this criterion was introduced (e.g., '1.0.0', '2.3.0'). Criterion identifiers are stable: once published, an identifier MUST NOT be reused for a different requirement — deprecate and mint a new one instead.
References:
richText, reference, criterionFixture, conformanceLevel, verificationMode, criterionCheck
[
{
"identifier": "touch-target-minimum",
"title": "Touch Target Minimum",
"statement": "Every interactive element exposes a hit area of at least 44×44 CSS pixels in all viewports. Verifiable via runtime measurement of bounding rectangles.",
"techniques": [
"Apply `min-height: 44px` and sufficient horizontal padding to every interactive element.",
"Use the `<Button>` component without overriding its default height."
],
"failures": [
"Setting `height` below 44px on an interactive element.",
"Removing default vertical padding from the component's CSS."
],
"references": [
{
"url": "https://www.w3.org/TR/WCAG22/#target-size-minimum",
"label": "WCAG 2.5.8 Target Size (Minimum)"
}
],
"tags": [
"a11y",
"touch-target",
"governance"
]
},
{
"identifier": "icon-button-name-present",
"title": "Icon Button Accessible Name Present",
"statement": "Every icon-only button exposes a non-empty accessible name.",
"level": "must",
"verification": "automated",
"check": {
"scheme": "axe-core",
"rule": "button-name"
},
"since": "2.0.0",
"techniques": [
"Set `aria-label` on the button (e.g., `aria-label=\"Close dialog\"`).",
"Use visually hidden text inside the button instead of `aria-label`."
],
"failures": [
"Rendering an icon-only button whose accessible name resolves to an empty string."
],
"examples": [
{
"title": "Labelled icon button",
"outcome": "pass",
"presentation": {
"kind": "code",
"code": "<Button aria-label=\"Close dialog\"><CloseIcon /></Button>",
"language": "jsx"
}
},
{
"title": "Unlabelled icon button",
"outcome": "fail",
"presentation": {
"kind": "code",
"code": "<Button><CloseIcon /></Button>",
"language": "jsx"
}
}
]
},
{
"identifier": "icon-button-name-length",
"title": "Icon Button Name Is Concise",
"statement": "Icon-only button accessible names are 40 characters or fewer.",
"level": "should",
"verification": "assisted",
"check": {
"scheme": "com.acme.a11y-lint",
"rule": "label-length",
"maxLength": 40
},
"techniques": [
"Name the action, not the icon (e.g., 'Close dialog', not 'X mark symbol button')."
],
"failures": [
"Accessible names that read as sentences rather than action labels."
]
},
{
"identifier": "icon-button-name-describes-action",
"title": "Icon Button Name Describes the Action",
"statement": "Every icon-only button's accessible name describes the action the button performs, not the icon's appearance.",
"level": "must",
"verification": "manual",
"techniques": [
"Name the outcome of activation (e.g., 'Close dialog', 'Copy link', 'Delete row').",
"Review names alongside the rendered UI so the action context is visible."
],
"failures": [
"Names that describe the glyph (e.g., 'X icon', 'Trash can') rather than the action.",
"The same generic name (e.g., 'Button') on multiple buttons that perform different actions."
],
"examples": [
{
"title": "Action-describing name",
"outcome": "pass",
"value": "aria-label=\"Copy link\""
},
{
"title": "Appearance-describing name",
"outcome": "fail",
"value": "aria-label=\"Chain icon\""
}
]
}
]
Allowed values:
- must
- should
- should-not
- must-not
Allowed values:
- automated
- assisted
- manual
Identifier of the rule system or runner this check dispatches to. MUST be lowercase; dots permitted for namespacing (e.g. 'com.acme.contract-tests').
Pattern: ^[a-z][a-z0-9.-]*$
[
{
"scheme": "axe-core",
"rule": "button-name"
},
{
"scheme": "vitest",
"suite": "button.contract.test.ts",
"testName": "renders a minimum 44px hit area"
},
{
"scheme": "com.acme.contract-tests",
"endpoint": "https://ci.acme.com/checks/touch-target"
}
]
A literal value carried by the example. Use it for API property examples, where the content is a concrete value rather than a visual demo. It can display code that reflects the example. Accepts any JSON type: string, number, boolean, object, array, or null. When given without a presentation, this value alone is the example. Do not use value for display text — use title for captions and description for explanations.
The visual or interactive presentation for the example. Required when no value is set. Optional when value is present. Value-only examples are concrete data points that tools render as table rows or inline displays.
Whether this fixture satisfies ('pass') or violates ('fail') the criterion. Replaces encoding pass/fail in title prose, which tools cannot rely on.
A human-readable caption for the example (e.g., 'Primary button in default state'). For API property examples, use value for the literal content and title for the display label.
An explanation of the example — why it is encouraged, discouraged, or notable.
Constraint: At least one of presentation, outcome, value, outcome must be present.
References:
presentationImage, presentationVideo, presentationCode, presentationUrl
[
{
"title": "Icon-only button with an accessible name",
"outcome": "pass",
"presentation": {
"kind": "code",
"code": "<Button aria-label=\"Close dialog\"><CloseIcon /></Button>",
"language": "jsx"
}
},
{
"title": "Icon-only button with no accessible name",
"outcome": "fail",
"presentation": {
"kind": "code",
"code": "<Button><CloseIcon /></Button>",
"language": "jsx"
}
}
]
URL to the external standard or requirement (e.g., 'https://www.w3.org/TR/WCAG22/#contrast-minimum').
A display label for the citation (e.g., '1.4.3 Contrast (Minimum)', 'WCAG 2.5.8 Target Size'). When omitted, tools MAY build a label from the URL.
[
{
"url": "https://www.w3.org/TR/WCAG22/#contrast-minimum",
"label": "WCAG 1.4.3 Contrast (Minimum)"
}
]
Design System Documentation Spec (DSDS) 0.12.0 — Draft Specification
GitHub