DSDS Agent Context Collection

Root Properties

Named agent context blocks. Each key is a scope identifier — a component name, a concern area, or a workflow phase. Each value is a full agents block validated against the agents schema. Keys should be lowercase kebab-case for consistency with DSDS entity naming.

The version of this collection file. Use for your own versioning — not tied to the DSDS spec version.

URI of the schema this file conforms to. Tools can use this for auto-detection and validation.

Human-readable name for this collection (e.g., 'Sanity UI Pre-Generation Checklist', 'Material Design Migration Guide').

What this collection covers, who it's for, and how agents should use it.

ISO date when this collection was last updated.

Where this collection was derived from — a test suite, an audit, a design system package, or a documentation site.

{ "version": "1.0.0", "schema": "https://designsystemdocspec.org/v0.2.1/common/agent-collection.schema.json", "name": "Acme Design System — Agent Pre-Generation Checklist", "description": "Cross-cutting agent guidance for generating UI with the Acme Design System. Covers component selection, accessibility defaults, and the most common anti-patterns surfaced during agent test runs. Consumed by code-generation tools and review agents before they emit JSX.", "updated": "2026-05-30", "source": "agent-test-run-2026-05-30", "sections": { "button": { "intent": "Trigger the primary action on a surface — submit, confirm, save, or commit a destructive change.", "constraints": [ { "rule": "Use at most one primary (filled) button per visible surface.", "level": "must" }, { "rule": "Provide an accessible label when the button has only an icon.", "level": "must" } ], "disambiguation": [ { "entity": "link", "distinction": "Use a button when the action changes application state. Use a link when the action navigates to a URL." } ], "antiPatterns": [ { "description": "Wrapping a button in an anchor element to make it navigate.", "instead": "Use the link component for navigation." } ], "examples": [ { "description": "Primary submit button in a form.", "code": "<Button variant=\"primary\" type=\"submit\">Save changes</Button>", "language": "jsx" } ], "keywords": [ "button", "action", "submit", "cta" ] }, "form-layout": { "intent": "Compose accessible, consistent form layouts that respect the system's spacing scale and field-state conventions.", "constraints": [ { "rule": "Wrap every input in a FormField component so labels, helper text, and error states render consistently.", "level": "must" }, { "rule": "Place the submit button at the end of the form using the system's primary variant.", "level": "should" } ], "antiPatterns": [ { "description": "Rendering raw <input> elements alongside FormField-wrapped inputs in the same form.", "instead": "Always use FormField. It ensures uniform error styling and screen-reader announcements.", "evidence": "Raised in 9/10 agent iterations that generated multi-field forms." } ], "examples": [ { "description": "Two-field form with primary submit.", "code": "<form>\n <FormField label=\"Email\" name=\"email\" required />\n <FormField label=\"Password\" name=\"password\" type=\"password\" required />\n <Button variant=\"primary\" type=\"submit\">Sign in</Button>\n</form>", "language": "jsx" } ], "keywords": [ "form", "layout", "input", "field", "submit", "validation" ] }, "accessibility-defaults": { "intent": "Apply the design system's accessibility defaults so generated UI satisfies WCAG 2.2 AA without manual review.", "constraints": [ { "rule": "Every interactive element must have an accessible name (text label, aria-label, or aria-labelledby).", "level": "must" }, { "rule": "Touch targets must be at least 44×44 CSS pixels on mobile viewports.", "level": "must", "context": "WCAG 2.5.5 (AAA) and 2.5.8 (AA, draft)." }, { "rule": "Color must not be the only means of communicating information.", "level": "must", "context": "WCAG 1.4.1." } ], "keywords": [ "a11y", "accessibility", "wcag", "aria", "contrast", "touch target" ] } } }