{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://designsystemdocspec.org/v0.15.2/entities/chunk.schema.json",
"title": "Chunk definitions",
"description": "A chunk is a ready-to-use block of code — a copy-paste starting point built from the system's components, like a layout or a settings form. A chunk document holds its identity, the code itself, and general docs (guidelines, use-cases, accessibility, and so on). Chunks sit alongside components: a component documents one building block, a chunk documents a composition of them, captured as code.",
"$defs": {
"chunk": {
"type": "object",
"description": "A ready-to-use block of code — a layout, a settings form, a confirmation dialog. It has an identity (`identifier`, `name`, optional `description`), the `code` consumers copy, and `documentBlocks`/`agentDocumentBlocks` for the general kinds (guidelines, use-cases, accessibility, content, sections, checklist). Chunks are simple by design: they document a composition of code, not a full anatomy/API surface like a component does.",
"required": [
"kind",
"identifier",
"name",
"code"
],
"properties": {
"kind": {
"type": "string",
"const": "chunk",
"description": "Identifies this entity as a chunk."
},
"identifier": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*$",
"description": "Machine-readable identifier for the chunk (ex: 'search-bar', 'settings-form', 'confirmation-dialog'). MUST be lowercase kebab-case and unique within its entity group."
},
"name": {
"type": "string",
"description": "Display name shown in docs (ex: 'Search bar', 'Settings form', 'Confirmation dialog')."
},
"description": {
"$ref": "../common/rich-text.schema.json#/$defs/richText",
"description": "What this chunk is, the pattern it captures, and which components it composes. CommonMark supported."
},
"code": {
"description": "The code consumers copy to use the chunk. Give it one of two ways: inline (`code` + `language`) when it travels with the document, or referenced (`src` + `language`) when it lives in an outside file. Referenced code keeps long sources readable and lets a chunk share one file with a live app. `src` is resolved when read — there's no build step.",
"oneOf": [
{
"type": "object",
"title": "Inline code",
"description": "The source travels inside the document as a string.",
"required": [
"code",
"language"
],
"properties": {
"code": {
"type": "string",
"description": "The source code of the chunk — the block consumers copy and adapt."
},
"language": {
"type": "string",
"description": "The programming language or syntax of the code (ex: 'jsx', 'tsx', 'html', 'css', 'vue', 'svelte')."
}
},
"additionalProperties": false
},
{
"type": "object",
"title": "Referenced code",
"description": "The source lives in an external file the consumer resolves at read time.",
"required": [
"src",
"language"
],
"properties": {
"src": {
"type": "string",
"pattern": "^(?![a-zA-Z][a-zA-Z0-9+.\\-]*:)(?!//)(?!/)",
"description": "A relative path to the file holding the chunk's code (ex: './chunks/confirmation-dialog.tsx'). MUST be relative — no absolute paths, protocol-relative paths, or scheme URIs (http:, file:, …). Resolvers SHOULD only fetch from an allow-list, the same rule a `$ref` fileRef follows. The file is read as-is — no build step.",
"minLength": 1
},
"language": {
"type": "string",
"description": "The programming language or syntax of the referenced file (ex: 'jsx', 'tsx', 'html', 'css', 'vue', 'svelte')."
}
},
"additionalProperties": false
}
]
},
"documentBlocks": {
"type": "array",
"description": "Docs for this chunk — the general block kinds only (guidelines, use-cases, accessibility, content, sections, checklist). Chunks document a composition of code, not the anatomy/API surface a component has.",
"items": {
"$ref": "../document-blocks/document-blocks.schema.json#/$defs/generalDocumentBlock"
},
"minItems": 1
},
"agentDocumentBlocks": {
"type": "array",
"description": "Docs for AI agents only, using the same general block kinds as `documentBlocks`. Agent-only content: hard must/must-not rules, verification checklists, and constraints an agent needs when adapting this chunk into an app. Guidance for humans belongs in `documentBlocks`.",
"items": {
"$ref": "../document-blocks/document-blocks.schema.json#/$defs/generalDocumentBlock"
},
"minItems": 1
},
"relationships": {
"$ref": "../common/relationship.schema.json#/$defs/relationships",
"description": "Links from this chunk to the entities it uses — mainly 'composes' the components it's built from (mark `required` true for the essential ones). Tools derive the reverse edges."
},
"metadata": {
"$ref": "../metadata/metadata.schema.json#/$defs/entityMetadata",
"description": "Optional metadata (see metadata/metadata.schema.json). Declare the components this chunk uses as `relationships`, not links."
},
"$extensions": {
"$ref": "../common/extensions.schema.json#/$defs/extensions"
}
},
"additionalProperties": false
}
}
}Identifies this entity as a chunk.Machine-readable identifier for the chunk (ex: '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 (ex: 'Search bar', 'Settings form', 'Confirmation dialog').The code consumers copy to use the chunk. Give it one of two ways: inline (code + language) when it travels with the document, or referenced (src + language) when it lives in an outside file. Referenced code keeps long sources readable and lets a chunk share one file with a live app. src is resolved when read — there's no build step.What this chunk is, the pattern it captures, and which components it composes. CommonMark supported.Docs for this chunk — the general block kinds only (guidelines, use-cases, accessibility, content, sections, checklist). Chunks document a composition of code, not the anatomy/API surface a component has. Min items: 1Docs for AI agents only, using the same general block kinds as documentBlocks. Agent-only content: hard must/must-not rules, verification checklists, and constraints an agent needs when adapting this chunk into an app. Guidance for humans belongs in documentBlocks. Min items: 1Links from this chunk to the entities it uses — mainly 'composes' the components it's built from (mark required true for the essential ones). Tools derive the reverse edges.Optional metadata (see metadata/metadata.schema.json). Declare the components this chunk uses as relationships, not links.All vendor-specific extensions . Keys MUST use a namespace of at least two dot-separated segments (reverse domain recommended), Example: 'com.figma', 'acme.tooling'; the pattern is case-tolerant. Tools that don't recognize an extension MUST keep it. Extension data SHOULD NOT duplicate core schema fields.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"
}
]
}
]
}