{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://designsystemdocspec.org/v0.15.2/entities/guide.schema.json",
"title": "Guide definitions",
"description": "A guide is long-form guidance not tied to one component, token, foundation, or pattern — a getting-started walkthrough, contribution guide, tutorial, overview, or migration guide. It holds identity and metadata; the `category` field says what kind of guide it is. Its docs are sections, procedures (steps), guidelines, and use-cases.",
"$defs": {
"guide": {
"type": "object",
"description": "A long-form document meant to be read: a getting-started walkthrough, a contribution guide, a tutorial, an overview, or a migration guide. Other entities each document one thing (a component, token, foundation, pattern); a guide fills the gap for a journey or a concept instead. Its identity is `identifier`, `name`, and `description`. Use `category` (ex: 'getting-started', 'tutorial', 'migration') to classify it, and `tags` for discovery. Its docs cover sections, steps, guidelines, use-cases, imports, accessibility, and content.",
"required": [
"kind",
"identifier",
"name"
],
"properties": {
"kind": {
"type": "string",
"const": "guide",
"description": "Identifies this entity as a guide."
},
"identifier": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*$",
"description": "Machine-readable identifier for the guide (ex: 'getting-started', 'contributing', 'theming-tutorial', 'migrating-to-v2'). MUST be lowercase kebab-case and unique within its entity group."
},
"name": {
"type": "string",
"description": "Display name shown in docs (ex: 'Getting started', 'Contributing', 'Theming tutorial', 'Migrating to v2')."
},
"description": {
"$ref": "../common/rich-text.schema.json#/$defs/richText",
"description": "What this guide covers, who it is for, and what the reader will accomplish. CommonMark supported."
},
"metadata": {
"$ref": "../metadata/metadata.schema.json#/$defs/entityMetadata",
"description": "Optional metadata (see metadata/metadata.schema.json). Use `category` to classify the guide (ex: 'getting-started', 'tutorial', 'migration')."
},
"relationships": {
"$ref": "../common/relationship.schema.json#/$defs/relationships",
"description": "Links from this guide to the entities it covers or depends on. Tools derive the reverse edges. Use `links` metadata for external resources instead."
},
"documentBlocks": {
"type": "array",
"description": "All structured docs for this guide, in order. Accepts `steps`, the reused `imports` kind for setup, and every general kind — `sections` is the backbone. A guide reads top to bottom, so tools SHOULD keep this order. Put external links in `links` metadata or a section's `links`; point at other entities through `relationships`.",
"items": {
"$ref": "../document-blocks/document-blocks.schema.json#/$defs/guideDocumentBlock"
},
"minItems": 1
},
"agentDocumentBlocks": {
"type": "array",
"description": "Docs for agents (AI/LLM) only, using the same block kinds as `documentBlocks`. Put anything a human needs in `documentBlocks` — that's the default. Use this only for things that would be noise to a person: hard must/must-not rules, notes that correct a mistake agents commonly make (like picking a similar but wrong entity), evidence-backed constraints, and machine-checkable criteria. A rule humans need too still belongs in `documentBlocks`. This adds to the human docs, it never replaces them. Tools MUST NOT show these blocks to humans. Agents SHOULD read both arrays, human docs first.",
"items": {
"$ref": "../document-blocks/document-blocks.schema.json#/$defs/guideDocumentBlock"
},
"minItems": 1
},
"$extensions": {
"$ref": "../common/extensions.schema.json#/$defs/extensions"
}
},
"additionalProperties": false
}
}
}Identifies this entity as a guide.Machine-readable identifier for the guide (ex: 'getting-started', 'contributing', 'theming-tutorial', 'migrating-to-v2'). MUST be lowercase kebab-case and unique within its entity group. Pattern: ^[a-z][a-z0-9-]*$Display name shown in docs (ex: 'Getting started', 'Contributing', 'Theming tutorial', 'Migrating to v2').What this guide covers, who it is for, and what the reader will accomplish. CommonMark supported.Optional metadata (see metadata/metadata.schema.json). Use category to classify the guide (ex: 'getting-started', 'tutorial', 'migration').Links from this guide to the entities it covers or depends on. Tools derive the reverse edges. Use links metadata for external resources instead.All structured docs for this guide, in order. Accepts steps, the reused imports kind for setup, and every general kind — sections is the backbone. A guide reads top to bottom, so tools SHOULD keep this order. Put external links in links metadata or a section's links; point at other entities through relationships. Min items: 1Docs for agents (AI/LLM) only, using the same block kinds as documentBlocks. Put anything a human needs in documentBlocks — that's the default. Use this only for things that would be noise to a person: hard must/must-not rules, notes that correct a mistake agents commonly make (like picking a similar but wrong entity), evidence-backed constraints, and machine-checkable criteria. A rule humans need too still belongs in documentBlocks. This adds to the human docs, it never replaces them. Tools MUST NOT show these blocks to humans. Agents SHOULD read both arrays, human docs first. 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:richText, entityMetadata, relationships, guideDocumentBlock, extensions{
"kind": "guide",
"identifier": "getting-started",
"name": "Getting started",
"description": "Install the Acme design system, theme your app, and render your first component.",
"metadata": {
"status": "stable",
"category": "getting-started",
"tags": [
"onboarding",
"setup",
"install",
"getting-started",
"provider",
"first-component"
]
},
"documentBlocks": [
{
"kind": "sections",
"items": [
{
"title": "Overview",
"anchor": "overview",
"body": "The Acme design system is a shared library of components, tokens, and patterns. This guide takes you from an empty project to a themed app with a working component in three steps."
},
{
"title": "Prerequisites",
"anchor": "prerequisites",
"body": "You need Node.js 18 or later and a React 18 project. No design tooling is required to follow this guide."
}
]
},
{
"kind": "imports",
"items": [
{
"platform": "react",
"package": "@acme/ui",
"code": "import { Button, ThemeProvider } from '@acme/ui'"
}
]
},
{
"kind": "steps",
"title": "Set up your app",
"ordered": true,
"items": [
{
"instruction": "Add the UI package to your project.",
"examples": [
{
"presentation": {
"kind": "code",
"language": "bash",
"code": "npm install @acme/ui"
}
}
],
"expectedResult": "`@acme/ui` appears in your `package.json` dependencies.",
"label": "Install the package"
},
{
"instruction": "Mount the `ThemeProvider` at the root so every component inherits the theme.",
"examples": [
{
"presentation": {
"kind": "code",
"language": "tsx",
"code": "import { ThemeProvider } from '@acme/ui'\n\nexport default function App({ children }) {\n return <ThemeProvider>{children}</ThemeProvider>\n}"
}
}
],
"expectedResult": "Components render with Acme's default light theme.",
"label": "Wrap your app in the provider"
},
{
"instruction": "Drop a `Button` anywhere inside the provider.",
"examples": [
{
"presentation": {
"kind": "code",
"language": "tsx",
"code": "<Button tone=\"primary\">Save changes</Button>"
}
}
],
"expectedResult": "A themed primary button renders and responds to hover and focus.",
"label": "Render your first component"
}
]
},
{
"kind": "guidelines",
"items": [
{
"guidance": "Import components from the package root, not from deep internal paths.",
"rationale": "Deep imports bypass the public API and break when internal file structure changes.",
"level": "must",
"category": "development"
},
{
"guidance": "Render every Acme component inside a single ThemeProvider.",
"rationale": "Components read theme values from context; outside the provider they fall back to unstyled defaults.",
"level": "must",
"category": "development"
}
]
},
{
"kind": "use-cases",
"items": [
{
"stance": "recommended",
"description": "Starting a new Acme product or prototype from scratch."
},
{
"stance": "discouraged",
"description": "Migrating an existing app from v1 — follow the migration guide instead."
}
]
}
],
"agentDocumentBlocks": [
{
"kind": "use-cases",
"purpose": "Guide a developer through installing the design system and rendering a first themed component.",
"items": [
{
"description": "Getting started is for new projects; the migration guide is for upgrading an existing app between major versions.",
"stance": "discouraged",
"alternative": {
"identifier": "migration guide"
}
}
]
},
{
"kind": "guidelines",
"items": [
{
"guidance": "Always wrap the app in ThemeProvider before using any component.",
"level": "must"
},
{
"guidance": "Do not import from deep internal package paths.",
"level": "must-not"
}
]
}
]
}