DSDS Guide Definitions

Identifies this entity as a guide.

Machine-readable identifier for the guide (e.g., '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 (e.g., '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 fields, keyed by name: status, since, lastUpdated, category, tags, aliases, summary, thumbnail, preview, extends, and links. Use category to classify the guide (e.g., 'getting-started', 'contribution', 'tutorial', 'concept', 'migration').

Typed dependency edges from this guide to the entities it documents or depends on. Inverse edges are derived by tooling. Use the links metadata field for external resources.

All structured docs for this guide, as an ordered array of typed document block objects. It accepts the guide-specific kinds (sections, steps) plus reused kinds (imports for setup instructions, guidelines, useCases, accessibility, content). The kind property on each entry sets its shape. A guide reads top to bottom, so order matters and tools SHOULD keep it for display. Put links to other entities and external resources in the links metadata field or a section's links, not in document block entries.

Structured docs for agents (AI/LLM) only — a separate space that accepts the same block kinds as documentBlocks. documentBlocks is the default: put anything a human reader needs there. Use agentDocumentBlocks only for content that helps an agent build correctly but is noise for humans. For example: hard MUST/MUST-NOT rules an agent should treat as firm limits; notes that correct a mistake an agent is likely to make, such as reaching for this entity when a confusable one fits better; constraints backed by test-run evidence; and machine-checkable criteria with verification modes. A hard rule that humans also need (such as an accessibility requirement) belongs in documentBlocks, not here. Agent blocks add to the human docs — they never replace or duplicate them. Tools MUST NOT render these blocks in human-facing docs. Agents SHOULD read both arrays, human blocks first.

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": [ { "title": "Install the package", "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." }, { "title": "Wrap your app in the provider", "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." }, { "title": "Render your first component", "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." } ] }, { "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": "useCases", "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": "useCases", "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" } ] } ] }