4 definitions in this file:
The guidance statement. MUST be concrete and unambiguous. Avoid vague phrases like 'use sparingly' or 'when possible'.
How strictly the guideline should be followed. Values align with RFC 2119: 'required' (MUST — non-compliance is a defect), 'encouraged' (SHOULD — follow in most cases; exceptions need justification), 'informational' (MAY — advisory only), 'discouraged' (SHOULD NOT — avoid unless justified), 'prohibited' (MUST NOT — violations are defects). Defaults to 'informational'.
Default: "informational"
Why this guidance exists. Cite evidence, accessibility standards, or user research when available. MUST NOT restate the guidance.
The discipline this guideline belongs to. Used to group guidelines by concern. Standard values: 'visual-design' (color, typography, spacing, layout), 'interaction' (behavior, animation, transitions, gestures), 'accessibility' (inclusive design, assistive tech, WCAG), 'content' (text, imagery, tone, voice, labeling), 'motion' (animation timing, easing, reduced-motion), 'development' (implementation patterns, performance, code conventions). Custom values are allowed and SHOULD be lowercase kebab-case.
The anatomy part or content area this guideline applies to (e.g., 'label', 'icon', 'helper-text'). When omitted, the guideline applies to the whole artifact.
Criteria this guideline addresses or defines. Each entry is either an external reference (citing a published standard such as WCAG) or an internal criterion (defining a testable success condition owned by this design system). External references cite an authoritative external rule. Internal criteria support WCAG-style governance: a stable, author-owned identifier anchors the criterion across edits, and tooling can derive citable display codes from those identifiers via a persistent registry. Authors SHOULD attach internal criteria only to guidelines whose success condition is objectively verifiable.
Examples showing encouraged and discouraged approaches.
Freeform keywords that relate guidelines across categories and disciplines (e.g., 'rtl', 'localization', 'validation', 'contrast').
References:
richText, criterionReference, criterionDefinition, example
[
{
"guidance": "Use at most one primary (filled) button per visible surface.",
"rationale": "Multiple primary buttons on the same surface dilute visual hierarchy and confuse users about which action is most important.",
"kind": "required",
"category": "visual-design",
"criteria": [
{
"kind": "criterion",
"identifier": "single-primary-action",
"title": "Single Primary Action",
"successCriterion": "A surface contains at most one element with `variant=\"primary\"`. Verifiable by static AST scan of the rendered tree.",
"techniques": [
"Use `variant=\"primary\"` for the most important action and `variant=\"secondary\"` for the next-most-important.",
"When two actions appear adjacent (e.g., Save / Cancel), assign primary to Save and secondary to Cancel."
],
"failures": [
"Rendering two or more elements with `variant=\"primary\"` inside the same form, dialog, or card."
],
"examples": [
{
"title": "Correct — single primary action",
"presentation": {
"kind": "code",
"code": "<ButtonGroup>\n <Button variant=\"secondary\">Cancel</Button>\n <Button variant=\"primary\">Save</Button>\n</ButtonGroup>",
"language": "jsx"
}
},
{
"title": "Incorrect — two primary actions on the same surface",
"presentation": {
"kind": "code",
"code": "<ButtonGroup>\n <Button variant=\"primary\">Cancel</Button>\n <Button variant=\"primary\">Save</Button>\n</ButtonGroup>",
"language": "jsx"
}
}
],
"tags": [
"visual-hierarchy",
"governance"
]
}
]
},
{
"guidance": "Maintain a minimum tap target of 44×44 CSS pixels for all button sizes.",
"rationale": "Touch devices require larger targets to prevent mis-taps. WCAG 2.5.8 requires 24×24px minimum and recommends 44×44px.",
"kind": "required",
"category": "accessibility",
"criteria": [
{
"kind": "criterion",
"identifier": "touch-target-minimum",
"title": "Touch Target Minimum",
"successCriterion": "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"
]
},
{
"kind": "reference",
"url": "https://www.w3.org/TR/WCAG22/#target-size-enhanced",
"label": "WCAG 2.5.5 Target Size (Enhanced)"
}
]
},
{
"guidance": "Button label text must meet a minimum 4.5:1 contrast ratio against the button background.",
"rationale": "Text contrast ensures readability for users with low vision. Failing this criterion is a documented WCAG AA failure.",
"kind": "required",
"category": "accessibility",
"criteria": [
{
"kind": "reference",
"url": "https://www.w3.org/TR/WCAG22/#contrast-minimum",
"label": "WCAG 1.4.3 Contrast (Minimum)"
}
]
}
]
Identifies this entry as a reference to an external standard.
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 derive a label from the URL.
{
"kind": "reference",
"url": "https://www.w3.org/TR/WCAG22/#contrast-minimum",
"label": "WCAG 1.4.3 Contrast (Minimum)"
}
Identifies this entry as an internal success criterion defined by this design system.
Stable, author-owned identifier scoped to the parent entity. MUST be lowercase kebab-case, MUST be unique within the parent entity, and MUST NOT change once published. Tooling SHOULD derive the display code (e.g., 'BTN-2.1', 'A11Y-1.4.3') from this identifier via a persistent registry. Changing the identifier breaks every citation that points at the criterion, so treat renames as deprecation plus replacement.
Pattern: ^[a-z][a-z0-9-]*$
A short display title for the criterion (e.g., 'Touch Target Minimum', 'Single Primary Action'). Tools SHOULD render this beside the display code when surfacing the criterion in docs or audit output.
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'. Mirrors the role of a WCAG Success Criterion (e.g., 'The visual presentation of text has a contrast ratio of at least 4.5:1, except for large text, incidental text, and logotypes').
Ways to satisfy this criterion. Each entry is a richText description of a sufficient technique (e.g., 'Apply min-height: 44px to every interactive element', 'Use the <Button> component without overriding its default height'). Maps to WCAG's 'Sufficient Techniques' list.
Conditions that count as a failure of this criterion. Each entry is a richText description of a known failure mode (e.g., 'Setting height below 44px on an interactive element', 'Removing aria-label from an icon-only button'). Maps to WCAG's 'Common Failures' list.
External standards this internal criterion aligns with or derives from (e.g., a matching WCAG success criterion, an internal accessibility audit, a platform guideline). Each entry mirrors the shape of an external criterionReference.
Examples that illustrate the criterion. Typically a before/after pair: one passing and one failing implementation.
Freeform keywords that relate criteria across guidelines (e.g., 'a11y', 'contrast', 'touch-target', 'governance').
References:
richText, example
{
"kind": "criterion",
"identifier": "touch-target-minimum",
"title": "Touch Target Minimum",
"successCriterion": "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"
]
}
The guideline rules. Each item is a guidance statement paired with a rationale. Order matters: tools SHOULD display guidelines in this order. Authors SHOULD order by importance or group by category.
Min items: 1
Identifies this as a guideline spec.
AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.
References:
guidelineEntry, agents
{
"kind": "guideline",
"items": [
{
"guidance": "Use at most one primary (filled) button per visible surface.",
"rationale": "Multiple primary buttons dilute visual hierarchy.",
"kind": "required",
"category": "visual-design",
"criteria": [
{
"kind": "criterion",
"identifier": "single-primary-action",
"title": "Single Primary Action",
"successCriterion": "A surface contains at most one element with `variant=\"primary\"`."
}
]
},
{
"guidance": "Maintain a minimum tap target of 44×44 CSS pixels for all button sizes.",
"rationale": "Touch devices require larger targets to prevent mis-taps.",
"kind": "required",
"category": "accessibility",
"criteria": [
{
"kind": "criterion",
"identifier": "touch-target-minimum",
"title": "Touch Target Minimum",
"successCriterion": "Every interactive element exposes a hit area of at least 44×44 CSS pixels."
},
{
"kind": "reference",
"url": "https://www.w3.org/TR/WCAG22/#target-size-minimum",
"label": "WCAG 2.5.8 Target Size (Minimum)"
}
]
}
],
"agents": {
"intent": "Enforce the design system's governance criteria for the Button component.",
"constraints": [
{
"rule": "Surface BTN-1 violations as build errors; surface BTN-2 violations as accessibility audit findings.",
"level": "must"
}
],
"keywords": [
"governance",
"audit",
"wcag",
"criteria"
]
}
}
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub