DSDS Sections Document Block

2 definitions in this file:

sections
sectionEntry

Identifies this document block as narrative sections.

The sections, in display order. Each item is a titled section with optional body, examples, links, and sub-sections. Ordering is significant, so tools SHOULD keep it.
Min items: 1

References:

sectionEntry

{ "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 (e.g., 'Installation', 'Core concepts', 'Why semantic tokens'). Concise enough to render as a heading and to anchor a deep link.

A stable, URL-safe fragment identifier for deep-linking to this section (e.g., 'installation', 'core-concepts'). MUST be lowercase kebab-case and unique within the parent block. When omitted, tools MAY derive an anchor from the title.
Pattern: ^[a-z][a-z0-9-]*$

The prose content of the section. Supports markdown by default. May be omitted when the section exists only to group sub-sections under a heading.

Illustrative examples for this section: code snippets, images, videos, or live URLs. Useful for showing a concept in practice within explanatory prose.

Related links surfaced with this section: 'see also' references, source material, or pointers to other entities and external resources.

Nested sub-sections beneath this one. Each item is itself a sectionEntry, allowing an arbitrarily deep heading hierarchy. Ordering is significant, so tools SHOULD render sub-sections in this order.

References: 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." } ] }