DSDS Chunk Definitions

Identifies this entity as a chunk.

Machine-readable identifier for the chunk (e.g., 'search-bar', 'settings-form', 'confirmation-dialog'). MUST be lowercase kebab-case and unique within its entity group.
Pattern: ^[a-z][a-z0-9-]*$

Display name shown in docs (e.g., 'Search bar', 'Settings form', 'Confirmation dialog').

The pre-composed block of code consumers copy to use the chunk. Provide it in exactly one of two forms: inline (code + language) when the source travels with the document, or referenced (src + language) when it lives in an external source file. The referenced form keeps long sources readable and lets a chunk share one canonical file with a live app. Consumers resolve src at read time — no build step inlines it.

What this chunk is, the pattern it captures, and which components it composes. CommonMark supported.

Structured docs for this chunk, as an ordered array of general document blocks (guidelines, use-cases, accessibility, content, sections, checklist). Chunks accept the general kinds only — they document a code composition, not the anatomy/API surface a component carries.
Min items: 1

Structured docs for AI agents consuming this chunk, using the same general block kinds as documentBlocks. Content here is agent-only: hard MUST/MUST-NOT rules, verification checklists, and adaptation constraints an agent needs when copying the chunk into an application. Human-facing guidance belongs in documentBlocks.
Min items: 1

Typed dependency edges from this chunk to other entities — chiefly 'composes' the components it is built from (mark required true for essential ones). This is the graph agents read for impact and alternatives. Inverse edges are derived by tooling.

Optional metadata: the shared entityMetadata fields (see metadata/metadata.schema.json). Declare the components this chunk composes as relationships edges, not links.

References: richText, generalDocumentBlock, relationships, entityMetadata, extensions

{ "kind": "chunk", "identifier": "confirmation-dialog", "name": "Confirmation dialog", "description": "A modal that asks the user to confirm or cancel a destructive action before it runs. Composes Dialog, Stack, Text, and Button to present a clear question and two explicit choices.", "relationships": [ { "relation": "composes", "target": "dialog", "role": "Hosts the confirmation in a modal surface", "required": true }, { "relation": "composes", "target": "button", "role": "Renders the confirm and cancel actions", "required": true }, { "relation": "depends-on", "target": "color-critical", "role": "Tones the destructive confirm action" } ], "metadata": { "status": "stable", "tags": [ "modal", "confirm", "destructive", "dialog" ] }, "code": { "language": "tsx", "src": "./chunks/confirmation-dialog.tsx" }, "documentBlocks": [ { "kind": "use-cases", "purpose": "Ask the user to confirm or cancel a destructive action before it runs.", "items": [ { "description": "Guard a destructive or irreversible action — deleting, archiving, or overwriting — so the user confirms intent before it runs.", "stance": "recommended" }, { "description": "Confirm low-stakes, easily reversible actions where an undo affordance would serve the user better.", "stance": "discouraged", "alternative": { "identifier": "toast", "rationale": "A toast with an undo action keeps reversible flows fast and avoids interrupting the user with a modal." } } ] }, { "kind": "guidelines", "items": [ { "guidance": "Label the confirm button with the action it performs (e.g. 'Delete') rather than a generic 'OK'.", "rationale": "An action-specific label tells the user what will happen, reducing accidental confirmations.", "level": "should", "category": "content" }, { "guidance": "Give the destructive confirm button the 'critical' tone and keep the cancel action visually quieter.", "rationale": "Tone and weight signal the consequence and steer the user toward the safe default.", "level": "should", "category": "visual-design" }, { "guidance": "Move focus into the dialog on open and return it to the trigger on close.", "rationale": "Keyboard and screen reader users lose their place when focus is not managed across the modal lifecycle.", "level": "must", "category": "accessibility" } ] } ], "agentDocumentBlocks": [ { "kind": "checklist", "title": "Adapting this chunk", "items": [ { "label": "Keep the confirm and cancel actions as Button components — do not replace them with raw button elements.", "level": "must" }, { "label": "Replace the placeholder question and confirm label with copy naming the specific action being confirmed.", "level": "must" }, { "label": "Preserve the focus-management wiring when restructuring the dialog contents.", "level": "must" } ] } ] }