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.

Actionable rules for using and adapting the chunk. Each item pairs a guidance statement with a rationale and an RFC 2119 enforcement level. Reuses the shared guideline-entry shape so chunk rules read the same as guidelines elsewhere in the system.
Min items: 1

Scenario-driven use cases describing when this chunk is — or is not — the right choice. Each entry is marked 'recommended' or 'discouraged'. Reuses the shared use-case shape. Authors SHOULD lead with recommended scenarios.
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). The structural counterpart to listing components in links; the graph agents read for impact and alternatives. Inverse edges are derived by tooling.

Optional metadata fields, keyed by name: status, since, lastUpdated, category, tags, aliases, summary, thumbnail, preview, extends, and links. Use the links field to point at the components this chunk composes.

References: richText, guidelineEntry, useCase, 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" }, "useCases": [ { "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." } } ], "guidelines": [ { "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" } ] }