adobe · GarthDB · May 14, 2026
diff --git a/docs/scenarios.md b/docs/scenarios.md
@@ -0,0 +1,106 @@
+# Scenarios
+
+The design-data spec and tooling support two primary workflows. This page is a self-serve entry point for designers and engineers who want to evaluate or adopt the system.
+
+> Both scenarios share the same substrate: a normative spec, JSON schemas, 31 SPEC validation rules, a Rust CLI (`design-data`), an MCP server, and a Claude Code skill. The only thing that changes between them is what you bring to the table.
+
+***
+
+## Scenario A — Prototype against an existing system (Spectrum)
+
+You are a designer or engineer on a product team. Spectrum is your design system. You want to build a prototype, evaluate a change, or answer a design question without waiting on a person in the middle.
+
+### What you get on day one
+
+* **Live token graph** at [opensource.adobe.com/spectrum-design-data/s2-visualizer](https://opensource.adobe.com/spectrum-design-data/s2-visualizer/) — search, click any token, walk the cascade chain, toggle dimension context (light/dark × desktop/mobile × regular/high-contrast)
+* **81 fully-declared Spectrum components** with anatomy, states, accessibility (role, intents, WCAG citations), and token bindings — all machine-readable
+* **Programmatic access** via the `design-data` CLI to query, validate, and inspect
+
+### Common tasks
+
+**See what a component declares:**
+
+```bash
+design-data component button --components-dir packages/design-data-spec/components
+```
+
+**Find all tokens used by a component:**
+
+```bash
+design-data query packages/design-data-spec --filter "component=button"
+```
+
+**Validate a change to the dataset:**
+
+```bash
+design-data validate packages/design-data-spec --strict
+```
+
+**Open a primer for an agent session:**
+
+```bash
+design-data primer packages/design-data-spec
+```
+
+### Talking to the system through an agent
+
+Install the `@adobe/design-data-agent-mcp` MCP server or the Claude Code skill. The agent can answer questions like:
+
+* *"What tokens does the button component use in its hover state, and what do they resolve to in dark mode?"*
+* *"Which components declare a `dialog` accessibility role?"*
+* *"Draft a new component declaration for a banner that follows the patterns alert-banner uses."*
+
+The agent reads the live spec — not a stale doc, not a copy in someone's repo.
+
+***
+
+## Scenario B — Start a blank design system
+
+You are a team launching a new product or design system. You want a contract that catches design-system mistakes before they ship, that designers and engineers can both author against, and that an agent can participate in.
+
+### What the spec gives you on day one
+
+* **A normative format** for tokens, components, anatomy, states, accessibility, and document blocks (see the [spec chapters](../packages/design-data-spec/spec/index.md))
+* **13 JSON schemas** (draft 2020-12) for structural validation
+* **31 SPEC validation rules** for semantic validation — reference integrity, alias resolution, cascade coverage, naming consistency, accessibility completeness, deprecation lifecycle
+* **A CLI** for validating, querying, diffing, migrating, and exporting to Figma
+* **An MCP server + Claude Code skill** so agents can author and validate alongside humans
+
+### What a minimal valid component looks like
+
+See [tools/demo/clean-component-example.json](../tools/demo/clean-component-example.json) — a complete declaration with identity, options, anatomy, states (with accessibility-aware fields), a top-level accessibility role + WCAG citations, and a typed prose block. This is the contract a new system targets.
+
+### Authoring loop
+
+1. Author a component or token declaration as JSON, following the schemas
+2. Validate locally:
+   ```bash
+   design-data validate <your-spec-dir> --strict
+   ```
+3. SPEC rules catch mistakes — alias targets, missing accessibility data, ambiguous cascade resolution, naming drift — at authoring time, not at runtime
+4. Ship the dataset; consumers (build pipelines, agents, visualizers) read it through the same contract
+
+### Agent-authored declarations
+
+With the MCP installed, a designer can describe a new component in plain language. The agent reads the spec, drafts a conformant declaration, runs `design-data validate` on the draft, and surfaces the result. The spec is what makes that loop safe.
+
+***
+
+## What's shared between the scenarios
+
+Both rely on the same three guarantees:
+
+1. **One source of truth** — schema + spec rules + CLI. There is no second interpretation layer between the design system and its consumers.
+2. **Continuous validation** — every change is checked against 31 rules. Drift fails loud.
+3. **Agent-readable** — the spec is structured so an agent can participate in authoring, querying, and review without bespoke integration work.
+
+***
+
+## References
+
+* [Spec index](../packages/design-data-spec/spec/index.md) — all normative chapters
+* [SPEC rule catalog](../packages/design-data-spec/rules/rules.yaml) — all 31 validation rules with messages and spec cross-references
+* [CLI](../sdk/cli/) — `validate`, `resolve`, `diff`, `query`, `migrate`, `figma`, `primer`, `component`, `write`
+* [Component declarations](../packages/design-data-spec/components/) — 81 declared Spectrum components
+* [Agent surface](../packages/design-data-agent-mcp/) — MCP server for agent integrations
+* [s2-visualizer](https://opensource.adobe.com/spectrum-design-data/s2-visualizer/) — live token graph for Spectrum
diff --git a/tools/demo/README.md b/tools/demo/README.md
@@ -0,0 +1,13 @@
+# Director Review Demo Materials
+
+Self-contained demo assets for the design director review. Print `scenarios.md`, keep it next to the laptop, copy-paste from `demo-commands.sh`.
+
+| File                               | Purpose                                                                                                                                                                                                             |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scenarios.md`                     | The narration. Both demo flows with the exact commands and what to say at each step.                                                                                                                                |
+| `demo-commands.sh`                 | Copy-paste cheat sheet. Each command preceded by what to say. Not auto-executable — run commands one at a time so the audience can read the output.                                                                 |
+| `clean-component-example.json`     | A minimal valid component declaration. Used to show the spec contract at its smallest: identity, anatomy, states (with accessibility-aware fields), top-level accessibility role + WCAG citations, document blocks. |
+| `broken-token-example.tokens.json` | A token file with a dangling alias `$ref` — triggers SPEC-001 (`alias-target-exists`). Used for the "validator catches mistakes live" moment.                                                                       |
+| `agent-questions.md`               | The prepared Claude Code question, exact wording, expected answer shape.                                                                                                                                            |
+
+These materials are for the May 15 2026 review with Sean Voisen, Aaron Brownlee, Allison Shaw, and Shawn Cheris.
diff --git a/tools/demo/agent-questions.md b/tools/demo/agent-questions.md
@@ -0,0 +1,48 @@
+# Prepared Agent Demo Questions
+
+Use one of these in Claude Code with the `design-data` MCP enabled. The first is the primary; the others are backups.
+
+***
+
+## Primary question
+
+> Using the design-data MCP, look up the button component and tell me:
+>
+> 1. What its accessibility role and keyboard intents are
+> 2. Which states it declares
+> 3. Which token resolves the default background color in the dark color scheme
+>
+> Show the answers with citations from the spec, not a guess.
+
+**What success looks like**: the agent calls `mcp__design-data__component` (or equivalent) to read `button`, then `mcp__design-data__resolve` (or the CLI) for the dark-mode color. It quotes the actual `role`, `keyboardIntents`, the list of state names, and the resolved hex/rgb value.
+
+**Why this lands**: the audience sees the design system answering a multi-part question directly. No human reads the spec, opens Figma, runs a build, and reports back — the agent does it from one source in seconds.
+
+***
+
+## Backup question (if the primary is too long)
+
+> Using the design-data MCP, what does `accent-background-color-default` resolve to in dark mode on mobile with high contrast?
+
+**Why this works**: smaller surface, single fact, demonstrates dimensional resolution. Good if time is tight in the demo block.
+
+***
+
+## Stretch question (if Demo A is going well and time allows)
+
+> Using the design-data MCP, draft a new component declaration for a "demo-banner" component that has a dismiss button, an icon slot, and follows the accessibility patterns used by alert-banner. Don't write it to disk — show me the JSON.
+
+**Why this is interesting**: shows the agent authoring against the spec, not just reading. Demonstrates the "agent participates in design" story directly. Only run this if Demo A felt strong — it's higher variance.
+
+***
+
+## If the MCP is not connected
+
+Fall back to running these directly in the terminal — the answers are equivalent, just less theatrical:
+
+```bash
+design-data component button --components-dir packages/design-data-spec/components
+design-data resolve accent-background-color-default \
+  --color-scheme dark --scale mobile --contrast high \
+  packages/design-data-spec
+```
diff --git a/tools/demo/broken-token-example.tokens.json b/tools/demo/broken-token-example.tokens.json
@@ -0,0 +1,10 @@
+[
+  {
+    "name": { "property": "demo-accent-color" },
+    "value": "rgb(50, 100, 200)"
+  },
+  {
+    "name": { "property": "demo-button-background-color-default" },
+    "$ref": "this-token-does-not-exist"
+  }
+]
diff --git a/tools/demo/clean-component-example.json b/tools/demo/clean-component-example.json
@@ -0,0 +1,65 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/demo-toggle.json",
+  "specVersion": "1.0.0-draft",
+  "name": "demo-toggle",
+  "displayName": "Demo Toggle",
+  "description": "A minimal valid component declaration. Shows the spec contract at its smallest: identity, meta, options, anatomy, states (with accessibility-aware state fields), top-level accessibility declaration, and a typed document block.",
+  "meta": {
+    "category": "inputs",
+    "documentationUrl": "https://example.com/design-system/demo-toggle"
+  },
+  "options": {
+    "isOn": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether the toggle is in the on position."
+    },
+    "size": {
+      "type": "string",
+      "enum": ["s", "m", "l"],
+      "default": "m"
+    }
+  },
+  "anatomy": [
+    {
+      "name": "track",
+      "description": "The background rail the handle slides along."
+    },
+    { "name": "handle", "description": "The draggable indicator." },
+    { "name": "label", "description": "Visible text label." }
+  ],
+  "states": [
+    { "name": "hover", "trigger": "interaction", "precedence": 50 },
+    {
+      "name": "focus",
+      "trigger": "interaction",
+      "precedence": 60,
+      "layered": true
+    },
+    {
+      "name": "disabled",
+      "trigger": "prop",
+      "precedence": 100,
+      "announce": "Toggle disabled",
+      "communicates": "disabled",
+      "blocksInteraction": true
+    }
+  ],
+  "accessibility": {
+    "role": "switch",
+    "intents": ["choose"],
+    "focusable": true,
+    "keyboardIntents": ["activate"],
+    "wcag": [
+      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+    ]
+  },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Demo Toggle lets a user turn a setting on or off with a single tap or keypress."
+    }
+  ]
+}
diff --git a/tools/demo/demo-commands.sh b/tools/demo/demo-commands.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Director Review Demo — copy-paste cheat sheet
+# Do NOT execute as a script. Run commands one at a time so the audience can read the output.
+# See ./scenarios.md for the narration.
+
+# Expects to be run from the repo root: /Users/garthdb/Spectrum/spectrum-design-data
+# `design-data` CLI must be on PATH (or use `cargo run --manifest-path sdk/Cargo.toml --bin design-data --`)
+
+# ─── Demo A — Prototype against Spectrum ────────────────────────────────────
+
+# A1. (no command — visualizer in browser)
+# Say: "Same data the spec validates, rendered live."
+
+# A2. Component lookup — agent-readable surface (Phase 8)
+# Say: "Anatomy, states, accessibility, token bindings — all machine-readable."
+design-data component button \
+  --components-dir packages/design-data-spec/components
+
+# A3. Query the design system
+# Say: "A designer asks 'what tokens does the button use?' One CLI call. Same answer for the engineer."
+design-data query packages/design-data-spec --filter "component=button"
+
+# A4. (no command — switch to Claude Code, ask the question from agent-questions.md)
+
+# ─── Demo B — Blank system ──────────────────────────────────────────────────
+
+# B1. (no command — open clean-component-example.json in the editor)
+
+# B2. Validate a broken token file — triggers SPEC-001 alias-target-exists
+# Say: "Dangling alias reference. The validator catches it at authoring time."
+design-data validate tools/demo/broken-token-example.tokens.json
+
+# B3. Show the agent-readable primer — the agent's session-start view
+# Say: "This is what the agent reads when it opens the system."
+design-data primer packages/design-data-spec
+
+# ─── Bonus / safety net ────────────────────────────────────────────────────
+
+# Validate the full Spectrum dataset (use if someone asks "does this really work at scale?")
+design-data validate packages/design-data-spec --strict
diff --git a/tools/demo/scenarios.md b/tools/demo/scenarios.md
@@ -0,0 +1,95 @@
+# Demo Scenarios — Director Review
+
+Print this. Keep it next to the laptop. Each section is what to do, what to say, and what to expect.
+
+***
+
+## Setup (before walking in)
+
+* Terminal at large font, prompt clean, in `/Users/garthdb/Spectrum/spectrum-design-data`
+* Browser tab open to `https://opensource.adobe.com/spectrum-design-data/s2-visualizer/`
+* Claude Code open in this repo with the design-data MCP enabled
+* This document open on a second screen or printed
+* `design-data` CLI built: `cargo build --release --manifest-path sdk/Cargo.toml`
+
+***
+
+## Demo A — Prototype against an existing system (Spectrum)
+
+**The frame**: "A team wants to prototype a feature using Spectrum. Today they fight bespoke tooling, drift between Figma and code, and live debate about what a token means. Here's the new path."
+
+### A1. Live token graph (visualizer)
+
+Open `https://opensource.adobe.com/spectrum-design-data/s2-visualizer/`.
+
+* Search for `button-background-color-default`
+* Click the node — show the cascade chain
+* Toggle dimensions: **dark** + **mobile** + **high-contrast**
+* **Say**: "Same data the spec validates, rendered live. The token resolves across dimension contexts — color scheme, scale, contrast — automatically. Designer and engineer are looking at the same source."
+
+### A2. What does the button declare? (machine-readable surface)
+
+```bash
+design-data component button \
+  --components-dir packages/design-data-spec/components
+```
+
+* **Say**: "The component declaration is the contract. Anatomy, states, accessibility intent (role, keyboard intents, WCAG citations), exactly which tokens it binds. The agent reads this. The build reads this. The visualizer reads this. One source."
+
+### A3. Filter the design system by query
+
+```bash
+design-data query packages/design-data-spec --filter "component=button"
+```
+
+* **Say**: "A designer asks 'what tokens does the button use?' This used to be a code-archaeology task. Now it's one CLI call. Same answer for the engineer."
+
+### A4. Agent answers a real question
+
+Switch to Claude Code. Ask the question from `agent-questions.md`.
+
+* **Say**: "The MCP exposes the spec to the agent. The designer asks a question in English; the agent reads the live spec and answers. No middleware. No drift."
+
+***
+
+## Demo B — Starting a blank design system
+
+**The frame**: "A new product wants its own design system. Today they re-invent token naming, accessibility metadata, and validation. Here's what the spec gives them on day one."
+
+### B1. The contract
+
+Open `tools/demo/clean-component-example.json` in the editor.
+
+* **Say**: "This is a complete, valid component declaration. Identity, options, anatomy, states with accessibility-aware fields, a semantic accessibility role + WCAG citations, and a typed prose block. The schema enforces the structure; 31 SPEC rules enforce the semantics. A new team gets all of this on day one — they don't reinvent it."
+
+### B2. Validation catches real mistakes
+
+```bash
+design-data validate tools/demo/broken-token-example.tokens.json
+```
+
+Expect: `error: ... [SPEC-001] Alias target not found for $ref: this-token-does-not-exist`
+
+* **Say**: "A token that aliases something that doesn't exist. Easy to miss in review. The validator catches it before it ships. There are 30 more rules like this one — covering naming, cascade, accessibility, deprecation lifecycle. The contract is enforced."
+
+### B3. The agent as participant
+
+```bash
+design-data primer packages/design-data-spec
+```
+
+* **Say**: "This is what the agent reads when it opens the system — categories, conformance scope, the validation rules in play, how to author. A designer describes a new component in plain language; the agent uses the MCP to author a schema-conformant declaration, runs validate, opens a PR. The spec is the contract that lets the agent participate safely."
+
+***
+
+## Backup if anything fails
+
+* **Visualizer down** → run `pnpm dev` in `docs/s2-visualizer/` for a local copy
+* **CLI command fails** → cut to the screen recording in `tools/demo/recordings/` (if recorded)
+* **Agent demo fails** → fall back to showing `design-data primer packages/design-data-spec` — same information, no live network dependency
+
+***
+
+## Closing line for the demo block
+
+*"Designer, engineer, agent — same source, same answer, validated continuously. That's the live system."*