{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://designsystemdocspec.org/v0.15.2/document-blocks/sections.schema.json",
"title": "Sections document block",
"description": "Free-form documentation content, organized into titled sections that can nest. Use it for anything that doesn't fit the structured blocks (api, anatomy, variants) — overviews, explanations, rationale. Each section has a heading, a body, examples, links, and optional sub-sections.",
"$defs": {
"sectionEntry": {
"type": "object",
"description": "One section: a heading, a body, and optionally examples, links, and nested sub-sections. Sub-sections let you build a heading hierarchy (h2 → h3 → h4). Only `title` is required — a section can be just a heading that groups its children.",
"required": [
"title"
],
"properties": {
"title": {
"type": "string",
"description": "The section heading (ex: 'Installation', 'Core concepts')."
},
"anchor": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*$",
"description": "A stable URL fragment for linking to this section (ex: 'installation'). MUST be lowercase kebab-case and unique in the block. Left out, tools MAY derive one from the title."
},
"body": {
"$ref": "../common/rich-text.schema.json#/$defs/richText",
"description": "The section's content, as markdown. Can be omitted when the section only groups sub-sections."
},
"examples": {
"type": "array",
"description": "Examples for this section — code, images, videos, or live links.",
"items": {
"$ref": "../common/example.schema.json#/$defs/example"
},
"minItems": 1
},
"links": {
"type": "array",
"description": "'See also' links for this section. To reference another entity, use `relationships` instead.",
"items": {
"$ref": "../common/link.schema.json#/$defs/link"
},
"minItems": 1
},
"sections": {
"type": "array",
"description": "Sub-sections nested beneath this one, to any depth. Tools SHOULD keep this order.",
"items": {
"$ref": "#/$defs/sectionEntry"
},
"minItems": 1
}
},
"additionalProperties": false
},
"sections": {
"type": "object",
"description": "One or more titled sections of documentation content. Use it for anything a guide needs that the structured blocks don't capture: overviews, concepts, rationale, FAQs.",
"required": [
"kind",
"items"
],
"properties": {
"kind": {
"type": "string",
"const": "sections",
"description": "Identifies this block as sections."
},
"items": {
"type": "array",
"description": "The sections, in order. Tools SHOULD keep this order.",
"items": {
"$ref": "#/$defs/sectionEntry"
},
"minItems": 1
},
"$extensions": {
"$ref": "../common/extensions.schema.json#/$defs/extensions"
}
},
"additionalProperties": false
}
}
}
Identifies this block as sections.The sections, in order. Tools SHOULD keep this order. Min items: 1All 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:sectionEntry, extensions{
"kind": "sections",
"items": [
{
"title": "What is this design system?",
"anchor": "what-is-this",
"body": "A shared library of components, tokens, and patterns that keeps every Acme product visually and behaviorally consistent. Use it to build interfaces faster without reinventing the basics."
},
{
"title": "Who is it for?",
"anchor": "who-is-it-for",
"body": "Product designers and frontend engineers building Acme applications. Designers work from the Figma library; engineers consume the published npm packages."
}
]
}The section heading (ex: 'Installation', 'Core concepts').A stable URL fragment for linking to this section (ex: 'installation'). MUST be lowercase kebab-case and unique in the block. Left out, tools MAY derive one from the title. Pattern: ^[a-z][a-z0-9-]*$The section's content, as markdown. Can be omitted when the section only groups sub-sections.Examples for this section — code, images, videos, or live links. Min items: 1'See also' links for this section. To reference another entity, use relationships instead. Min items: 1Sub-sections nested beneath this one, to any depth. Tools SHOULD keep this order. Min items: 1References:richText, example, link, sectionEntry{
"title": "Core concepts",
"anchor": "core-concepts",
"body": "The design system is built on three layers: **tokens** carry raw values, **foundations** define design domains, and **components** compose both into UI. Understanding this hierarchy makes everything else easier to navigate.",
"examples": [
{
"title": "Importing a component",
"presentation": {
"kind": "code",
"language": "tsx",
"code": "import { Button } from '@acme/ui'"
}
}
],
"links": [
{
"kind": "related",
"label": "Token reference",
"url": "https://designsystemdocspec.org/tokens"
}
],
"sections": [
{
"title": "Tokens",
"anchor": "tokens",
"body": "Tokens are named design values — a color, a spacing step, a duration. Never hard-code a raw value when a token exists."
}
]
}