{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://designsystemdocspec.org/v0.15.2/document-blocks/steps.schema.json",
"title": "Steps document block",
"description": "The steps a reader follows to complete a task, like getting started, a tutorial, or a migration. Each step has a short label, an instruction, optional examples, and an optional expected result so the reader knows it worked.",
"$defs": {
"stepEntry": {
"type": "object",
"description": "One step: a short label, an instruction for what to do, and optionally examples, an expected result, and whether it can be skipped. Only `label` is required.",
"required": [
"label"
],
"properties": {
"label": {
"$ref": "../common/rich-text.schema.json#/$defs/richText",
"description": "A short label for the step (ex: 'Install the package', 'Wrap your app in the provider', 'Run the validator'). Concise enough to serve as a numbered list item or heading."
},
"instruction": {
"$ref": "../common/rich-text.schema.json#/$defs/richText",
"description": "What the reader should do in this step. Supports markdown by default. MUST be concrete and actionable: describe the action, not the goal."
},
"examples": {
"type": "array",
"description": "Illustrative material for the step: a code snippet, a terminal command, a screenshot, or a live URL. Most procedural steps carry a single code example.",
"items": {
"$ref": "../common/example.schema.json#/$defs/example"
},
"minItems": 1
},
"expectedResult": {
"$ref": "../common/rich-text.schema.json#/$defs/richText",
"description": "What the reader should see once the step succeeds (ex: 'The dev server starts on port 3000', 'A themed button renders'). Lets readers confirm progress and spot problems on their own. Most useful in tutorials and getting-started guides."
},
"optional": {
"type": "boolean",
"default": false,
"description": "Whether the step can be skipped without breaking the procedure. Defaults to false. Tools MAY render optional steps distinctly (ex: an 'optional' label)."
}
},
"additionalProperties": false
},
"steps": {
"type": "object",
"description": "A procedure — the steps a reader works through start to finish, like installation or a migration.",
"required": [
"kind",
"items"
],
"properties": {
"kind": {
"type": "string",
"const": "steps",
"description": "Identifies this block as a procedure."
},
"title": {
"type": "string",
"description": "An optional heading for the whole procedure (ex: 'Installation', 'Build your first component', 'Submitting a contribution')."
},
"ordered": {
"type": "boolean",
"default": true,
"description": "Whether the steps must be done in order. Defaults to true. Set false for independent steps. Tools SHOULD show ordered steps as a numbered list, unordered ones as a checklist."
},
"items": {
"type": "array",
"description": "The steps, in order. Tools MUST preserve this order when `ordered` is true.",
"items": {
"$ref": "#/$defs/stepEntry"
},
"minItems": 1
}
},
"additionalProperties": false
}
}
}
Identifies this block as a procedure.The steps, in order. Tools MUST preserve this order when ordered is true. Min items: 1An optional heading for the whole procedure (ex: 'Installation', 'Build your first component', 'Submitting a contribution').Whether the steps must be done in order. Defaults to true. Set false for independent steps. Tools SHOULD show ordered steps as a numbered list, unordered ones as a checklist. Default: trueReferences:stepEntry{
"kind": "steps",
"title": "Installation",
"ordered": true,
"items": [
{
"instruction": "Add the UI package to your project.",
"examples": [
{
"title": "npm",
"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 of your application 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": "Pass the `dark` scheme to the provider to opt into the dark theme.",
"optional": true,
"label": "Enable dark mode"
}
]
}A short label for the step (ex: 'Install the package', 'Wrap your app in the provider', 'Run the validator'). Concise enough to serve as a numbered list item or heading.What the reader should do in this step. Supports markdown by default. MUST be concrete and actionable: describe the action, not the goal.Illustrative material for the step: a code snippet, a terminal command, a screenshot, or a live URL. Most procedural steps carry a single code example. Min items: 1What the reader should see once the step succeeds (ex: 'The dev server starts on port 3000', 'A themed button renders'). Lets readers confirm progress and spot problems on their own. Most useful in tutorials and getting-started guides.Whether the step can be skipped without breaking the procedure. Defaults to false. Tools MAY render optional steps distinctly (ex: an 'optional' label). Default: falseReferences:richText, example{
"instruction": "Add the UI package to your project with your package manager.",
"examples": [
{
"title": "npm",
"presentation": {
"kind": "code",
"language": "bash",
"code": "npm install @acme/ui"
}
}
],
"expectedResult": "`@acme/ui` appears in your `package.json` dependencies.",
"label": "Install the package"
}