DSDS Guidelines Document Block

2 definitions in this file:

guidelines
guidelineEntry

The guideline rules. Each item is a guidance statement paired with a rationale. Order matters, so tools SHOULD display guidelines in this order. Authors SHOULD order by importance or group by category.
Min items: 1

Identifies this document block as a guidelines spec.

References:

guidelineEntry

{ "kind": "guidelines", "items": [ { "guidance": "Use at most one primary (filled) button per visible surface.", "rationale": "Multiple primary buttons dilute visual hierarchy.", "level": "must", "category": "visual-design", "criteria": [ { "identifier": "single-primary-action", "title": "Single Primary Action", "statement": "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.", "level": "must", "category": "accessibility", "criteria": [ { "identifier": "touch-target-minimum", "title": "Touch Target Minimum", "statement": "Every interactive element exposes a hit area of at least 44×44 CSS pixels." } ], "references": [ { "url": "https://www.w3.org/TR/WCAG22/#target-size-minimum", "label": "WCAG 2.5.8 Target Size (Minimum)" } ] } ] }

The guidance statement. MUST be concrete and unambiguous. Avoid vague phrases like 'use sparingly' or 'when possible'.

How strictly the guideline should be followed, named for RFC 2119 requirement levels: 'must' (non-compliance is a defect), 'should' (follow in most cases; exceptions need justification), 'should-not' (avoid unless justified), 'must-not' (violations are defects). Agents treat must/must-not entries as hard constraints when generating or reviewing code.

Why this guidance exists. Cite evidence, accessibility standards, or user research when available. MUST NOT restate the guidance.

Quantitative or empirical backing for this guideline: test run data, audit findings, issue references, or cited sources. Keeping evidence separate from rationale lets tools tell test-derived rules apart from conventional guidance. Example: '9/10 agent test runs failed touch-target minimums when height was overridden below 36px.'

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.

Testable success criteria that verify this guideline. Each criterion pairs a stable identifier with an objectively verifiable statement. This lets tooling and agents check implementations against the rule and report pass/fail. Attach criteria only when the success condition is objectively verifiable. Observed results belong in evidence.
Min items: 1

External standards this guideline addresses (e.g., WCAG success criteria, MDN or platform guidelines). Each entry cites a URL with an optional display label.
Min items: 1

Examples showing encouraged and discouraged approaches.

Freeform keywords that relate guidelines across categories and disciplines (e.g., 'rtl', 'localization', 'validation', 'contrast').

References: richText, conformanceLevel, criterion, reference, 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.", "level": "must", "category": "visual-design", "criteria": [ { "identifier": "single-primary-action", "title": "Single Primary Action", "statement": "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" }, "outcome": "pass" }, { "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" }, "outcome": "fail" } ], "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.", "level": "must", "category": "accessibility", "criteria": [ { "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" ] } ], "references": [ { "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.", "level": "must", "category": "accessibility", "references": [ { "url": "https://www.w3.org/TR/WCAG22/#contrast-minimum", "label": "WCAG 1.4.3 Contrast (Minimum)" } ] } ]