@commercetools/nimbus-mcp 3.5.0 → 3.6.0

package/data/docs/routes/home-getting-started-collaboration.json

@@ -0,0 +1,657 @@
+{
+  "meta": {
+    "id": "Home-Collaboration",
+    "title": "Collaboration",
+    "description": "How to collaborate with the nimbus team, understand governance processes, and work effectively with the design system.",
+    "order": 8,
+    "repoPath": "packages/nimbus/src/docs/home-collaboration.mdx",
+    "menu": [
+      "Home",
+      "Getting Started",
+      "Collaboration"
+    ],
+    "route": "home/getting-started/collaboration",
+    "tags": [
+      "guide",
+      "governance",
+      "collaboration"
+    ],
+    "toc": [
+      {
+        "value": "Why this document exists",
+        "href": "#why-this-document-exists",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Foundational principles",
+        "href": "#foundational-principles",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "1. System first",
+        "href": "#1-system-first",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "2. Ask, don't assume",
+        "href": "#2-ask-dont-assume",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "3. Collaborate early",
+        "href": "#3-collaborate-early",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "4. Slow core, fast surface",
+        "href": "#4-slow-core-fast-surface",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "5. Own your recipes",
+        "href": "#5-own-your-recipes",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Categorizing incoming work",
+        "href": "#categorizing-incoming-work",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Bugs",
+        "href": "#bugs",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Design discrepancies",
+        "href": "#design-discrepancies",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Features",
+        "href": "#features",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Recipes",
+        "href": "#recipes",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Ownership boundaries",
+        "href": "#ownership-boundaries",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Nimbus core",
+        "href": "#nimbus-core",
+        "depth": 3,
+        "numbering": [
+          1,
+          4,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Shared product libraries",
+        "href": "#shared-product-libraries",
+        "depth": 3,
+        "numbering": [
+          1,
+          4,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Application components",
+        "href": "#application-components",
+        "depth": 3,
+        "numbering": [
+          1,
+          4,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Governance workflow",
+        "href": "#governance-workflow",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Does this belong in nimbus?",
+        "href": "#does-this-belong-in-nimbus",
+        "depth": 3,
+        "numbering": [
+          1,
+          5,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Step by step",
+        "href": "#step-by-step",
+        "depth": 3,
+        "numbering": [
+          1,
+          5,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Figma governance",
+        "href": "#figma-governance",
+        "depth": 2,
+        "numbering": [
+          1,
+          6
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Collaboration guidelines",
+        "href": "#collaboration-guidelines",
+        "depth": 2,
+        "numbering": [
+          1,
+          7
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "What the nimbus team commits to",
+        "href": "#what-the-nimbus-team-commits-to",
+        "depth": 2,
+        "numbering": [
+          1,
+          8
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Real-world examples",
+        "href": "#real-world-examples",
+        "depth": 2,
+        "numbering": [
+          1,
+          9
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Recipe absorbed into the system",
+        "href": "#recipe-absorbed-into-the-system",
+        "depth": 3,
+        "numbering": [
+          1,
+          9,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Where a conversation would have helped",
+        "href": "#where-a-conversation-would-have-helped",
+        "depth": 3,
+        "numbering": [
+          1,
+          9,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Discoverability gap",
+        "href": "#discoverability-gap",
+        "depth": 3,
+        "numbering": [
+          1,
+          9,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Valid recipe",
+        "href": "#valid-recipe",
+        "depth": 3,
+        "numbering": [
+          1,
+          9,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "The happy path",
+        "href": "#the-happy-path",
+        "depth": 3,
+        "numbering": [
+          1,
+          9,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "What's next",
+        "href": "#whats-next",
+        "depth": 2,
+        "numbering": [
+          1,
+          10
+        ],
+        "parent": "root"
+      }
+    ],
+    "icon": "Group",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Nimbus Governance, Collaboration, and Ownership\n\n## Why this document exists\n\nDesign systems that do not clearly define governance tend to fail in one of two\nways, either they calcify because teams cannot get what they need so they stop\ntrying, or they fragment when teams build around the system and consistency\nslowly erodes. How do we — engineers, designers, decision-makers — all work\nwith/in nimbus without falling into these foreseeable traps?\n\nThis document's answer is to establish a lightweight, shared understanding\nof how we work together on nimbus: How to surface needs, how to decide what\nbelongs in the system, who owns what, and how product-level work feeds back into\nthe shared library. The goal is to keep nimbus **coherent** while keeping product\nteams **unblocked**.\n\nThis is an invitation to collaborate, not a set of rules imposed from above.\nNimbus exists to serve the products built on it, and the governance process\nexists to make that relationship work well for everyone.\n\n## Foundational principles\n\nFive principles guide how we make decisions together.\n\n### 1. System first\n\nIf nimbus provides a component, token, or pattern that solves the problem,\n**use it**. The design system exists to provide tested, accessible, consistent\nsolutions. Building a custom alternative when a system solution already exists\ncreates fragmentation, increases maintenance burden, and undermines the\nconsistency that nimbus is here to provide.\n\nDivergence from the system is an exception that requires justification, not a\nstarting position.\n\n### 2. Ask, don't assume\n\nBefore building something custom, check what already exists. The\n[documentation site](https://nimbus-documentation.vercel.app/home),\n[Storybook](https://nimbus-storybook.vercel.app), the\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system),\nand the\n[MCP server](https://nimbus-documentation.vercel.app/home/getting-started/mcp-server-overview)\nare all searchable entry points. If you're still unsure after checking, ask in\nthe #ask-nimbus-anything\n[Slack channel](https://commercetools.slack.com/archives/C0ACFBKAHTM), or open a\n[GitHub discussion](https://github.com/commercetools/nimbus/discussions).\n**Don't assume the answer is \"no\" and build around the system**.\n\nMany perceived \"gaps\" turn out to be discoverability problems that a quick search\nor a single message would resolve. Public questions also help other teams who\nhave the same question, and they help the nimbus team understand where\ndocumentation or discoverability needs improvement.\n\n### 3. Collaborate early\n\nWhen your team's work touches shared UI patterns or surfaces a potential nimbus\ngap, loop in the nimbus team early. A five-minute conversation at the start of a\nfeature is worth more than a thirty-minute review at the end. **Early alignment\nprevents drift; late alignment creates rework**.\n\nThe same applies within product teams: designers and engineers should be in\nconversation from the start of any UI work, not just at handoff.\n\n### 4. Slow core, fast surface\n\n**Nimbus moves slower than products, and that's intentional**. Quality,\naccessibility, and cross-product consistency require deliberate engineering. The\nsystem is infrastructure: it prioritizes durability over speed.\n\nProduct teams are the fast layer. They innovate, experiment, and ship on their\nown timelines. They should never be blocked waiting for nimbus. When the system\ncan't deliver what a product team needs right now, the product team builds what\nit needs (see principle 5) and the system catches up when the pattern is proven.\n\nBoth speeds are correct. The tension between them is productive, not a problem to\nsolve.\n\n### 5. Own your recipes\n\nCompositions of nimbus components built for domain-specific use cases belong to\nthe product team that built them. These are \"recipes\": they use nimbus\ningredients (tokens, primitives, components) but serve a specific product\ncontext.\n\n**Recipes are not second-class**. They are the correct answer when domain\nrequirements diverge from what a general-purpose system should provide. Nimbus\nprovides ingredients; products assemble meals.\n\n## Categorizing incoming work\n\nNot every request is the same kind of work. Categorizing what's being asked for\nhelps route it to the right people and set the right expectations. These\ncategories apply equally to code components and Figma library assets.\n\n### Bugs\n\nA nimbus component (code or Figma) doesn't work as documented.\n\n**Owner:** Nimbus team\n**Priority:** Urgent\n**Examples:** An accordion fails to expand. A color contrast violation in a\nnimbus component. A Figma component is missing an interactive state that the code\ncomponent supports.\n\nTeams won't trust or use a system that's broken. Bug reports are always welcome\nand always prioritized.\n\n### Design discrepancies\n\nA gap between the Figma library and the coded component library.\n\n**Owner:** Nimbus team investigates\n**Priority:** High\n**Examples:** A designer uses a Button variant in a mockup that doesn't exist in\ncode. A coded component supports a prop that has no Figma equivalent. A\ndesigner's mockup uses a pattern that looks like a nimbus component but differs\nin subtle ways.\n\nWhen a discrepancy is found, the first question is whether the mismatch is a bug\n(one side is out of date) or a signal that the component needs to evolve. The\nnimbus team investigates and resolves.\n\n### Features\n\nA new component, variant, or capability that belongs in nimbus.\n\n**Owner:** Nimbus team, after evaluation\n**Priority:** Roadmap\n**Examples:** A request for a CopyableInput component. A new variant of an\nexisting component that would benefit multiple products.\n\nFeatures go through the governance workflow described below. Not every feature\nrequest becomes a nimbus component; some are better served as recipes.\n\n### Recipes\n\nA composition of nimbus components built for a specific product domain.\n\n**Owner:** Product team\n**Priority:** Product team's call\n**Examples:** A chat message renderer. A domain-specific form layout. A custom\nstepper for a multi-step wizard embedded in a chat interface.\n\nRecipes live in the product repo, are maintained by the product team, and don't\nrequire nimbus team involvement (though the nimbus team is available for\nguidance). If a recipe proves valuable across multiple products, it can be\nproposed for promotion into the system.\n\n## Ownership boundaries\n\nThree tiers of UI code, with clear ownership at each level.\n\n### Nimbus core\n\n**Owned by:** Nimbus team\n\nTokens, primitives, components in\n[`@commercetools/nimbus`](https://github.com/commercetools/nimbus/tree/main/packages/nimbus),\nicons in\n[`@commercetools/nimbus-icons`](https://github.com/commercetools/nimbus/tree/main/packages/nimbus-icons),\nthe\n[Figma component library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system),\nand the\n[documentation site](https://nimbus-documentation.vercel.app/).\n\nThe nimbus team is responsible for:\n\n- API design\n- Accessibility\n- Cross-browser support\n- Performance\n- Figma/code parity\n- Documentation\n- Release management\n\nChanges to nimbus core follow the nimbus team's development process.\n\n### Shared product libraries\n\n**Owned by:** Product teams, with nimbus consulted\n\nLibraries that compose nimbus components to serve a specific product family. For\nexample,\n[`@commercetools-internal/commerce-agents-ui-components`](https://github.com/commercetools/commerce-agents/blob/main/shared/ui/components/package.json)\nprovides shared chat infrastructure for the commerce-agents product family.\n[`@commercetools/merchant-center-shared-ui`](https://github.com/commercetools/merchant-center-frontend/blob/main/packages-shared/ui/package.json)\nprovides shared patterns for the Merchant Center.\n\n**These libraries are maintained by the product teams that built them**. The\nnimbus team is available for architecture guidance, especially around\naccessibility and token usage, but does not maintain these packages just because\nit maintains nimbus core.\n\n### Application components\n\n**Owned by:** Product teams\n\nDomain-specific UI built from nimbus primitives for a single application. No\nnimbus team involvement is needed unless promoting a component to a higher tier.\n\n## Governance workflow\n\n### Does this belong in nimbus?\n\nWhen evaluating whether a component should live in nimbus core or remain a\nrecipe, ask four questions:\n\n1. **Is it domain-agnostic?** No business logic, no product-specific data\n   shapes, no assumptions about the consuming application's context.\n2. **Would two or more unrelated products benefit from it?** If only one product\n   needs it, it's a recipe.\n3. **Does it extend a nimbus primitive in a way that's generally useful?** A\n   specialized variant of an existing component that serves a broad need is a\n   stronger candidate than a novel pattern.\n4. **Is the API surface stable enough to commit to?** Nimbus components carry a\n   maintenance and compatibility commitment. If the design is still evolving, it\n   may be too early.\n\nIf all four answers are yes, it's a feature candidate. Otherwise, it's a recipe,\n**and that's fine**.\n\n<img\n  src=\"/images/getting-started/governance-workflow.png\"\n  alt=\"Governance workflow: identify a need, check existing resources, ask in Slack or GitHub, categorize as bug/discrepancy/feature/recipe, then route to nimbus team (bugs, discrepancies, features) or product team (recipes) for resolution\"\n  width=\"100%\"\n/>\n\n### Step by step\n\n1. **Start with nimbus.** Check the\n   [documentation site](https://nimbus-documentation.vercel.app/home),\n   [Storybook](https://nimbus-storybook.vercel.app), the\n   [Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system),\n   and the\n   [MCP server](https://nimbus-documentation.vercel.app/home/getting-started/mcp-server-overview)\n   for existing solutions.\n2. **If you're unsure, ask publicly.** Post in the #ask-nimbus-anything\n   [Slack channel](https://commercetools.slack.com/archives/C0ACFBKAHTM) or open\n   a\n   [GitHub discussion](https://github.com/commercetools/nimbus/discussions)\n   before assuming a gap exists. Describe what you're trying to accomplish, not\n   the solution you have in mind.\n3. **Categorize together.** The nimbus team and the requester agree on whether\n   the gap is a bug, design discrepancy, feature, or recipe. This is a\n   conversation, not a form.\n4. **For bugs and design discrepancies:** the nimbus team triages and fixes,\n   tracked in Jira. No additional process needed from the requesting team beyond\n   reporting.\n5. **For features:** evaluate against the four ownership criteria. Open a\n   [GitHub Issue](https://github.com/commercetools/nimbus/issues) using the\n   feature proposal template, or start with a Slack conversation and\n   formalize later. If the scope warrants a more detailed RFC, the teams decide\n   together whether one is needed and who writes it. If nimbus can deliver on the\n   product team's timeline, the nimbus team builds it. If not, the product team\n   builds a recipe now, and nimbus absorbs the pattern when it's proven.\n6. **For recipes:** the product team builds it using nimbus tokens and\n   primitives. The nimbus team is available for architecture guidance (especially\n   around accessibility and token usage). The recipe lives in the product repo.\n7. **Promotion path:** if a recipe proves valuable across multiple products, it\n   can be proposed as a feature through the same workflow. The nimbus team\n   refactors it to meet system standards: API consistency, accessibility,\n   cross-browser support, Figma parity, and documentation.\n\n## Figma governance\n\nThe Figma library is part of nimbus, and the same governance workflow applies. A\nfew additional notes for designers:\n\n- **Reporting Figma/code mismatches:** File as a design discrepancy via GitHub\n  Issue. Include which component, what differs, and a screenshot.\n- **Proposing new Figma components:** Same feature flow as code. The nimbus team\n  maintains Figma/code parity: a component accepted for code will get a Figma\n  counterpart, and vice versa.\n- **Using Figma components not yet in code:** Treat as a design discrepancy. The\n  nimbus team will evaluate whether to add the code implementation or update the\n  Figma library.\n- **Custom Figma compositions:** Designers can build product-specific\n  compositions in their own Figma files using nimbus library components. These\n  are the design equivalent of code recipes: owned by the product team, built\n  from system ingredients.\n\n## Collaboration guidelines\n\nPractical guidance for working with nimbus.\n\n- **Check, then ask, then build.** Before building a custom component, search\n  the [docs](https://nimbus-documentation.vercel.app/home),\n  [Storybook](https://nimbus-storybook.vercel.app), the\n  [Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system),\n  and the\n  [MCP server](https://nimbus-documentation.vercel.app/home/getting-started/mcp-server-overview).\n  If you don't find what you need, ask in the #ask-nimbus-anything\n  [Slack channel](https://commercetools.slack.com/archives/C0ACFBKAHTM). Build\n  custom only after confirming no system solution exists. This applies to both\n  engineers and designers.\n- **Involve both UX and engineering from the start.** Don't design in isolation\n  and hand off, and don't build in isolation and ask for review. Bring designers\n  and engineers together early, especially when the work touches shared patterns\n  or might surface a nimbus gap.\n- **Use nimbus tokens, not hardcoded values.** Even in recipes, use\n  `system.token()` or semantic color values. Hardcoded colors and spacing values\n  create maintenance debt and break when themes change.\n- **Use nimbus primitives as building blocks.** Build recipes from `Box`,\n  `Stack`, `Flex`, `Text`, and other nimbus layout components rather than raw\n  HTML elements. This ensures consistent spacing, responsive behavior, and theme\n  support.\n- **Don't fork nimbus components.** If a nimbus component doesn't work for your\n  use case, that's a conversation to have (bug or feature request), not a reason\n  to rebuild from scratch. Forking creates drift that's expensive to reconcile\n  later.\n- **Architecture reviews for complex recipes.** Before building a large custom\n  component, discuss the approach with the nimbus team. This helps ensure future\n  promotability, avoids accessibility pitfalls, and surfaces opportunities to use\n  existing nimbus capabilities you might not know about.\n- **When you diverge, document why.** If you intentionally deviate from a nimbus\n  pattern, leave a brief note explaining the rationale. This helps future\n  maintainers (and the nimbus team) understand whether the divergence was a\n  deliberate design decision or an oversight.\n\n## What the nimbus team commits to\n\nThis process is a partnership. Here's what the nimbus team is responsible for:\n\n- **Responsive communication.** Questions in the #ask-nimbus-anything\n  [Slack channel](https://commercetools.slack.com/archives/C0ACFBKAHTM) get a\n  timely response. If we don't have an immediate answer, we'll acknowledge the\n  question and follow up.\n- **Triage and acknowledgment.** Bug reports and feature proposals filed as\n  [GitHub Issues](https://github.com/commercetools/nimbus/issues) are triaged\n  and acknowledged promptly. You'll know whether your report is being\n  investigated, scheduled, or needs more information.\n- **Transparent roadmap.** Accepted features are tracked in Jira, and requesting\n  teams have visibility into where their request stands.\n- **Proactive outreach.** When nimbus ships new components, variants, or patterns\n  that affect product teams, we communicate the changes through release notes and\n  the Slack channel. Teams shouldn't have to discover new capabilities by\n  accident.\n- **Architecture support.** When product teams are building complex recipes,\n  nimbus is available for guidance on accessibility, token usage, and API design.\n  We want recipes to be good, whether or not they end up in the system.\n- **Figma/code parity.** The nimbus team maintains alignment between the Figma\n  library and the coded component library. Discrepancies reported by product\n  teams are treated as high-priority issues.\n\n## Real-world examples\n\nThese examples are drawn from actual patterns in commercetools codebases. They\nillustrate how the governance process applies to real decisions.\n\n### Recipe absorbed into the system\n\n**What happened:** The commerce-agents team needed to render LLM-generated\nmarkdown output in a nimbus-styled UI. They built `AssistantMessageMarkdown`, a\ncustom renderer using `react-markdown` that mapped each markdown element to\nindividual nimbus primitives (`Box`, `Text`, `Heading`, `Table`, etc.).\n\n**What the governance process would say:** This was the right call at the time.\nThe product team needed something now and built a recipe using nimbus ingredients.\nThe pattern proved broadly valuable, and nimbus later absorbed it into a\nfirst-class `Markdown` component in the core library.\n\n**What happens next:** The commerce-agents team migrates from their custom\nrenderer to the nimbus `Markdown` component. The recipe served its purpose and\ncan be retired.\n\n**Principle illustrated:** Slow core, fast surface. Own your recipes.\n\n### Where a conversation would have helped\n\n**What happened:** The commerce-agents intake team needed an alert component with\na left-border accent, inline action buttons, and dismissible status chips. The\nnimbus `Alert` component didn't support these patterns, so the team built a\ncustom `AlertBanner` from scratch using `Box`, `Flex`, `Stack`, `Text`, and\n`IconButton`.\n\n**What the governance process would say:** Before building from scratch, ask in\nthe nimbus Slack channel. The conversation might reveal that Alert can be\nextended to support these patterns (a feature request), or that the specific\nrequirements are domain-specific enough to justify a recipe. Either way, the\nnimbus team learns about the gap.\n\n**What the outcome could have been:** If the need is general enough, nimbus\nexpands the `Alert` API. If it's domain-specific, the recipe approach is\nconfirmed and the team builds it with confidence that they're not duplicating\nexisting functionality.\n\n**Principle illustrated:** Ask, don't assume. Collaborate early.\n\n### Discoverability gap\n\n**What happened:** The Merchant Center frontend team built `McpServerUrlInput`,\na read-only input with a copy-to-clipboard button, using raw clipboard API calls.\nNimbus already provides a `useCopyToClipboard` hook that handles clipboard\naccess, success/error states, and browser compatibility.\n\n**What the governance process would say:** A quick question in the nimbus Slack\nchannel (\"we need a copy-to-clipboard pattern, anything in nimbus for this?\")\nwould have surfaced the existing hook. The remaining question is whether a\ncomposed `CopyableInput` component is worth proposing as a feature\n(domain-agnostic, useful across products) or is better left as a recipe using the\nexisting hook.\n\n**Principle illustrated:** Ask, don't assume. System first.\n\n### Valid recipe\n\n**What happened:** The commerce-agents team built a shared `AgentChatPanel`\ncompound component for agent chat UIs. Later, the intake agent team found that\nthis shared panel didn't fit their interaction model (file uploads,\ndrag-and-drop, multi-screen editing, state machine orchestration). They built\ntheir own custom chat chrome.\n\n**What the governance process would say:** This is exactly right. The shared\n`AgentChatPanel` is itself a recipe within the commerce-agents product family.\nWhen a sibling team's requirements diverge enough that the recipe doesn't fit,\nbuilding a new recipe is the correct answer. Recipes aren't second-class; they're\nthe right tool when domain requirements diverge.\n\n**Principle illustrated:** Own your recipes.\n\n### The happy path\n\n**What happens:** Both the Merchant Center and commerce-agents teams use nimbus\n`DataTable`, `FormField`, `Dialog`, `Button`, and dozens of other components\nextensively and correctly. They import directly from `@commercetools/nimbus`, use\nsemantic tokens for styling, and compose compound components as designed.\n\n**What the governance process would say:** This is the default state the process\nexists to protect. The system provides what's needed, teams adopt it, and\neveryone moves forward. No governance overhead required.\n\n**Principle illustrated:** System first.\n\n## What's next\n\nThis document covers component and Figma governance. Token governance (proposing\nnew tokens, modifying existing ones) may be added as a follow-up once the core\nprocess is established.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Nimbus Governance, Collaboration, and Ownership\n\n## Why this document exists\n\nDesign systems that do not clearly define governance tend to fail in one of two\nways, either they calcify because teams cannot get what they need so they stop\ntrying, or they fragment when teams build around the system and consistency\nslowly erodes. How do we — engineers, designers, decision-makers — all work\nwith/in nimbus without falling into these foreseeable traps?\n\nThis document's answer is to establish a lightweight, shared understanding\nof how we work together on nimbus: How to surface needs, how to decide what\nbelongs in the system, who owns what, and how product-level work feeds back into\nthe shared library. The goal is to keep nimbus **coherent** while keeping product\nteams **unblocked**.\n\nThis is an invitation to collaborate, not a set of rules imposed from above.\nNimbus exists to serve the products built on it, and the governance process\nexists to make that relationship work well for everyone.\n\n## Foundational principles\n\nFive principles guide how we make decisions together.\n\n### 1. System first\n\nIf nimbus provides a component, token, or pattern that solves the problem,\n**use it**. The design system exists to provide tested, accessible, consistent\nsolutions. Building a custom alternative when a system solution already exists\ncreates fragmentation, increases maintenance burden, and undermines the\nconsistency that nimbus is here to provide.\n\nDivergence from the system is an exception that requires justification, not a\nstarting position.\n\n### 2. Ask, don't assume\n\nBefore building something custom, check what already exists. The\n[documentation site](https://nimbus-documentation.vercel.app/home),\n[Storybook](https://nimbus-storybook.vercel.app), the\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system),\nand the\n[MCP server](https://nimbus-documentation.vercel.app/home/getting-started/mcp-server-overview)\nare all searchable entry points. If you're still unsure after checking, ask in\nthe #ask-nimbus-anything\n[Slack channel](https://commercetools.slack.com/archives/C0ACFBKAHTM), or open a\n[GitHub discussion](https://github.com/commercetools/nimbus/discussions).\n**Don't assume the answer is \"no\" and build around the system**.\n\nMany perceived \"gaps\" turn out to be discoverability problems that a quick search\nor a single message would resolve. Public questions also help other teams who\nhave the same question, and they help the nimbus team understand where\ndocumentation or discoverability needs improvement.\n\n### 3. Collaborate early\n\nWhen your team's work touches shared UI patterns or surfaces a potential nimbus\ngap, loop in the nimbus team early. A five-minute conversation at the start of a\nfeature is worth more than a thirty-minute review at the end. **Early alignment\nprevents drift; late alignment creates rework**.\n\nThe same applies within product teams: designers and engineers should be in\nconversation from the start of any UI work, not just at handoff.\n\n### 4. Slow core, fast surface\n\n**Nimbus moves slower than products, and that's intentional**. Quality,\naccessibility, and cross-product consistency require deliberate engineering. The\nsystem is infrastructure: it prioritizes durability over speed.\n\nProduct teams are the fast layer. They innovate, experiment, and ship on their\nown timelines. They should never be blocked waiting for nimbus. When the system\ncan't deliver what a product team needs right now, the product team builds what\nit needs (see principle 5) and the system catches up when the pattern is proven.\n\nBoth speeds are correct. The tension between them is productive, not a problem to\nsolve.\n\n### 5. Own your recipes\n\nCompositions of nimbus components built for domain-specific use cases belong to\nthe product team that built them. These are \"recipes\": they use nimbus\ningredients (tokens, primitives, components) but serve a specific product\ncontext.\n\n**Recipes are not second-class**. They are the correct answer when domain\nrequirements diverge from what a general-purpose system should provide. Nimbus\nprovides ingredients; products assemble meals.\n\n## Categorizing incoming work\n\nNot every request is the same kind of work. Categorizing what's being asked for\nhelps route it to the right people and set the right expectations. These\ncategories apply equally to code components and Figma library assets.\n\n### Bugs\n\nA nimbus component (code or Figma) doesn't work as documented.\n\n**Owner:** Nimbus team\n**Priority:** Urgent\n**Examples:** An accordion fails to expand. A color contrast violation in a\nnimbus component. A Figma component is missing an interactive state that the code\ncomponent supports.\n\nTeams won't trust or use a system that's broken. Bug reports are always welcome\nand always prioritized.\n\n### Design discrepancies\n\nA gap between the Figma library and the coded component library.\n\n**Owner:** Nimbus team investigates\n**Priority:** High\n**Examples:** A designer uses a Button variant in a mockup that doesn't exist in\ncode. A coded component supports a prop that has no Figma equivalent. A\ndesigner's mockup uses a pattern that looks like a nimbus component but differs\nin subtle ways.\n\nWhen a discrepancy is found, the first question is whether the mismatch is a bug\n(one side is out of date) or a signal that the component needs to evolve. The\nnimbus team investigates and resolves.\n\n### Features\n\nA new component, variant, or capability that belongs in nimbus.\n\n**Owner:** Nimbus team, after evaluation\n**Priority:** Roadmap\n**Examples:** A request for a CopyableInput component. A new variant of an\nexisting component that would benefit multiple products.\n\nFeatures go through the governance workflow described below. Not every feature\nrequest becomes a nimbus component; some are better served as recipes.\n\n### Recipes\n\nA composition of nimbus components built for a specific product domain.\n\n**Owner:** Product team\n**Priority:** Product team's call\n**Examples:** A chat message renderer. A domain-specific form layout. A custom\nstepper for a multi-step wizard embedded in a chat interface.\n\nRecipes live in the product repo, are maintained by the product team, and don't\nrequire nimbus team involvement (though the nimbus team is available for\nguidance). If a recipe proves valuable across multiple products, it can be\nproposed for promotion into the system.\n\n## Ownership boundaries\n\nThree tiers of UI code, with clear ownership at each level.\n\n### Nimbus core\n\n**Owned by:** Nimbus team\n\nTokens, primitives, components in\n[`@commercetools/nimbus`](https://github.com/commercetools/nimbus/tree/main/packages/nimbus),\nicons in\n[`@commercetools/nimbus-icons`](https://github.com/commercetools/nimbus/tree/main/packages/nimbus-icons),\nthe\n[Figma component library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system),\nand the\n[documentation site](https://nimbus-documentation.vercel.app/).\n\nThe nimbus team is responsible for:\n\n- API design\n- Accessibility\n- Cross-browser support\n- Performance\n- Figma/code parity\n- Documentation\n- Release management\n\nChanges to nimbus core follow the nimbus team's development process.\n\n### Shared product libraries\n\n**Owned by:** Product teams, with nimbus consulted\n\nLibraries that compose nimbus components to serve a specific product family. For\nexample,\n[`@commercetools-internal/commerce-agents-ui-components`](https://github.com/commercetools/commerce-agents/blob/main/shared/ui/components/package.json)\nprovides shared chat infrastructure for the commerce-agents product family.\n[`@commercetools/merchant-center-shared-ui`](https://github.com/commercetools/merchant-center-frontend/blob/main/packages-shared/ui/package.json)\nprovides shared patterns for the Merchant Center.\n\n**These libraries are maintained by the product teams that built them**. The\nnimbus team is available for architecture guidance, especially around\naccessibility and token usage, but does not maintain these packages just because\nit maintains nimbus core.\n\n### Application components\n\n**Owned by:** Product teams\n\nDomain-specific UI built from nimbus primitives for a single application. No\nnimbus team involvement is needed unless promoting a component to a higher tier.\n\n## Governance workflow\n\n### Does this belong in nimbus?\n\nWhen evaluating whether a component should live in nimbus core or remain a\nrecipe, ask four questions:\n\n1. **Is it domain-agnostic?** No business logic, no product-specific data\n   shapes, no assumptions about the consuming application's context.\n2. **Would two or more unrelated products benefit from it?** If only one product\n   needs it, it's a recipe.\n3. **Does it extend a nimbus primitive in a way that's generally useful?** A\n   specialized variant of an existing component that serves a broad need is a\n   stronger candidate than a novel pattern.\n4. **Is the API surface stable enough to commit to?** Nimbus components carry a\n   maintenance and compatibility commitment. If the design is still evolving, it\n   may be too early.\n\nIf all four answers are yes, it's a feature candidate. Otherwise, it's a recipe,\n**and that's fine**.\n\n<img\n  src=\"/images/getting-started/governance-workflow.png\"\n  alt=\"Governance workflow: identify a need, check existing resources, ask in Slack or GitHub, categorize as bug/discrepancy/feature/recipe, then route to nimbus team (bugs, discrepancies, features) or product team (recipes) for resolution\"\n  width=\"100%\"\n/>\n\n### Step by step\n\n1. **Start with nimbus.** Check the\n   [documentation site](https://nimbus-documentation.vercel.app/home),\n   [Storybook](https://nimbus-storybook.vercel.app), the\n   [Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system),\n   and the\n   [MCP server](https://nimbus-documentation.vercel.app/home/getting-started/mcp-server-overview)\n   for existing solutions.\n2. **If you're unsure, ask publicly.** Post in the #ask-nimbus-anything\n   [Slack channel](https://commercetools.slack.com/archives/C0ACFBKAHTM) or open\n   a\n   [GitHub discussion](https://github.com/commercetools/nimbus/discussions)\n   before assuming a gap exists. Describe what you're trying to accomplish, not\n   the solution you have in mind.\n3. **Categorize together.** The nimbus team and the requester agree on whether\n   the gap is a bug, design discrepancy, feature, or recipe. This is a\n   conversation, not a form.\n4. **For bugs and design discrepancies:** the nimbus team triages and fixes,\n   tracked in Jira. No additional process needed from the requesting team beyond\n   reporting.\n5. **For features:** evaluate against the four ownership criteria. Open a\n   [GitHub Issue](https://github.com/commercetools/nimbus/issues) using the\n   feature proposal template, or start with a Slack conversation and\n   formalize later. If the scope warrants a more detailed RFC, the teams decide\n   together whether one is needed and who writes it. If nimbus can deliver on the\n   product team's timeline, the nimbus team builds it. If not, the product team\n   builds a recipe now, and nimbus absorbs the pattern when it's proven.\n6. **For recipes:** the product team builds it using nimbus tokens and\n   primitives. The nimbus team is available for architecture guidance (especially\n   around accessibility and token usage). The recipe lives in the product repo.\n7. **Promotion path:** if a recipe proves valuable across multiple products, it\n   can be proposed as a feature through the same workflow. The nimbus team\n   refactors it to meet system standards: API consistency, accessibility,\n   cross-browser support, Figma parity, and documentation.\n\n## Figma governance\n\nThe Figma library is part of nimbus, and the same governance workflow applies. A\nfew additional notes for designers:\n\n- **Reporting Figma/code mismatches:** File as a design discrepancy via GitHub\n  Issue. Include which component, what differs, and a screenshot.\n- **Proposing new Figma components:** Same feature flow as code. The nimbus team\n  maintains Figma/code parity: a component accepted for code will get a Figma\n  counterpart, and vice versa.\n- **Using Figma components not yet in code:** Treat as a design discrepancy. The\n  nimbus team will evaluate whether to add the code implementation or update the\n  Figma library.\n- **Custom Figma compositions:** Designers can build product-specific\n  compositions in their own Figma files using nimbus library components. These\n  are the design equivalent of code recipes: owned by the product team, built\n  from system ingredients.\n\n## Collaboration guidelines\n\nPractical guidance for working with nimbus.\n\n- **Check, then ask, then build.** Before building a custom component, search\n  the [docs](https://nimbus-documentation.vercel.app/home),\n  [Storybook](https://nimbus-storybook.vercel.app), the\n  [Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system),\n  and the\n  [MCP server](https://nimbus-documentation.vercel.app/home/getting-started/mcp-server-overview).\n  If you don't find what you need, ask in the #ask-nimbus-anything\n  [Slack channel](https://commercetools.slack.com/archives/C0ACFBKAHTM). Build\n  custom only after confirming no system solution exists. This applies to both\n  engineers and designers.\n- **Involve both UX and engineering from the start.** Don't design in isolation\n  and hand off, and don't build in isolation and ask for review. Bring designers\n  and engineers together early, especially when the work touches shared patterns\n  or might surface a nimbus gap.\n- **Use nimbus tokens, not hardcoded values.** Even in recipes, use\n  `system.token()` or semantic color values. Hardcoded colors and spacing values\n  create maintenance debt and break when themes change.\n- **Use nimbus primitives as building blocks.** Build recipes from `Box`,\n  `Stack`, `Flex`, `Text`, and other nimbus layout components rather than raw\n  HTML elements. This ensures consistent spacing, responsive behavior, and theme\n  support.\n- **Don't fork nimbus components.** If a nimbus component doesn't work for your\n  use case, that's a conversation to have (bug or feature request), not a reason\n  to rebuild from scratch. Forking creates drift that's expensive to reconcile\n  later.\n- **Architecture reviews for complex recipes.** Before building a large custom\n  component, discuss the approach with the nimbus team. This helps ensure future\n  promotability, avoids accessibility pitfalls, and surfaces opportunities to use\n  existing nimbus capabilities you might not know about.\n- **When you diverge, document why.** If you intentionally deviate from a nimbus\n  pattern, leave a brief note explaining the rationale. This helps future\n  maintainers (and the nimbus team) understand whether the divergence was a\n  deliberate design decision or an oversight.\n\n## What the nimbus team commits to\n\nThis process is a partnership. Here's what the nimbus team is responsible for:\n\n- **Responsive communication.** Questions in the #ask-nimbus-anything\n  [Slack channel](https://commercetools.slack.com/archives/C0ACFBKAHTM) get a\n  timely response. If we don't have an immediate answer, we'll acknowledge the\n  question and follow up.\n- **Triage and acknowledgment.** Bug reports and feature proposals filed as\n  [GitHub Issues](https://github.com/commercetools/nimbus/issues) are triaged\n  and acknowledged promptly. You'll know whether your report is being\n  investigated, scheduled, or needs more information.\n- **Transparent roadmap.** Accepted features are tracked in Jira, and requesting\n  teams have visibility into where their request stands.\n- **Proactive outreach.** When nimbus ships new components, variants, or patterns\n  that affect product teams, we communicate the changes through release notes and\n  the Slack channel. Teams shouldn't have to discover new capabilities by\n  accident.\n- **Architecture support.** When product teams are building complex recipes,\n  nimbus is available for guidance on accessibility, token usage, and API design.\n  We want recipes to be good, whether or not they end up in the system.\n- **Figma/code parity.** The nimbus team maintains alignment between the Figma\n  library and the coded component library. Discrepancies reported by product\n  teams are treated as high-priority issues.\n\n## Real-world examples\n\nThese examples are drawn from actual patterns in commercetools codebases. They\nillustrate how the governance process applies to real decisions.\n\n### Recipe absorbed into the system\n\n**What happened:** The commerce-agents team needed to render LLM-generated\nmarkdown output in a nimbus-styled UI. They built `AssistantMessageMarkdown`, a\ncustom renderer using `react-markdown` that mapped each markdown element to\nindividual nimbus primitives (`Box`, `Text`, `Heading`, `Table`, etc.).\n\n**What the governance process would say:** This was the right call at the time.\nThe product team needed something now and built a recipe using nimbus ingredients.\nThe pattern proved broadly valuable, and nimbus later absorbed it into a\nfirst-class `Markdown` component in the core library.\n\n**What happens next:** The commerce-agents team migrates from their custom\nrenderer to the nimbus `Markdown` component. The recipe served its purpose and\ncan be retired.\n\n**Principle illustrated:** Slow core, fast surface. Own your recipes.\n\n### Where a conversation would have helped\n\n**What happened:** The commerce-agents intake team needed an alert component with\na left-border accent, inline action buttons, and dismissible status chips. The\nnimbus `Alert` component didn't support these patterns, so the team built a\ncustom `AlertBanner` from scratch using `Box`, `Flex`, `Stack`, `Text`, and\n`IconButton`.\n\n**What the governance process would say:** Before building from scratch, ask in\nthe nimbus Slack channel. The conversation might reveal that Alert can be\nextended to support these patterns (a feature request), or that the specific\nrequirements are domain-specific enough to justify a recipe. Either way, the\nnimbus team learns about the gap.\n\n**What the outcome could have been:** If the need is general enough, nimbus\nexpands the `Alert` API. If it's domain-specific, the recipe approach is\nconfirmed and the team builds it with confidence that they're not duplicating\nexisting functionality.\n\n**Principle illustrated:** Ask, don't assume. Collaborate early.\n\n### Discoverability gap\n\n**What happened:** The Merchant Center frontend team built `McpServerUrlInput`,\na read-only input with a copy-to-clipboard button, using raw clipboard API calls.\nNimbus already provides a `useCopyToClipboard` hook that handles clipboard\naccess, success/error states, and browser compatibility.\n\n**What the governance process would say:** A quick question in the nimbus Slack\nchannel (\"we need a copy-to-clipboard pattern, anything in nimbus for this?\")\nwould have surfaced the existing hook. The remaining question is whether a\ncomposed `CopyableInput` component is worth proposing as a feature\n(domain-agnostic, useful across products) or is better left as a recipe using the\nexisting hook.\n\n**Principle illustrated:** Ask, don't assume. System first.\n\n### Valid recipe\n\n**What happened:** The commerce-agents team built a shared `AgentChatPanel`\ncompound component for agent chat UIs. Later, the intake agent team found that\nthis shared panel didn't fit their interaction model (file uploads,\ndrag-and-drop, multi-screen editing, state machine orchestration). They built\ntheir own custom chat chrome.\n\n**What the governance process would say:** This is exactly right. The shared\n`AgentChatPanel` is itself a recipe within the commerce-agents product family.\nWhen a sibling team's requirements diverge enough that the recipe doesn't fit,\nbuilding a new recipe is the correct answer. Recipes aren't second-class; they're\nthe right tool when domain requirements diverge.\n\n**Principle illustrated:** Own your recipes.\n\n### The happy path\n\n**What happens:** Both the Merchant Center and commerce-agents teams use nimbus\n`DataTable`, `FormField`, `Dialog`, `Button`, and dozens of other components\nextensively and correctly. They import directly from `@commercetools/nimbus`, use\nsemantic tokens for styling, and compose compound components as designed.\n\n**What the governance process would say:** This is the default state the process\nexists to protect. The system provides what's needed, teams adopt it, and\neveryone moves forward. No governance overhead required.\n\n**Principle illustrated:** System first.\n\n## What's next\n\nThis document covers component and Figma governance. Token governance (proposing\nnew tokens, modifying existing ones) may be added as a follow-up once the core\nprocess is established.\n",
+      "toc": [
+        {
+          "value": "Why this document exists",
+          "href": "#why-this-document-exists",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Foundational principles",
+          "href": "#foundational-principles",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "1. System first",
+          "href": "#1-system-first",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "2. Ask, don't assume",
+          "href": "#2-ask-dont-assume",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "3. Collaborate early",
+          "href": "#3-collaborate-early",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "4. Slow core, fast surface",
+          "href": "#4-slow-core-fast-surface",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "5. Own your recipes",
+          "href": "#5-own-your-recipes",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Categorizing incoming work",
+          "href": "#categorizing-incoming-work",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Bugs",
+          "href": "#bugs",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Design discrepancies",
+          "href": "#design-discrepancies",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Features",
+          "href": "#features",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Recipes",
+          "href": "#recipes",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Ownership boundaries",
+          "href": "#ownership-boundaries",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Nimbus core",
+          "href": "#nimbus-core",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Shared product libraries",
+          "href": "#shared-product-libraries",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Application components",
+          "href": "#application-components",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Governance workflow",
+          "href": "#governance-workflow",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Does this belong in nimbus?",
+          "href": "#does-this-belong-in-nimbus",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Step by step",
+          "href": "#step-by-step",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Figma governance",
+          "href": "#figma-governance",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Collaboration guidelines",
+          "href": "#collaboration-guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "What the nimbus team commits to",
+          "href": "#what-the-nimbus-team-commits-to",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Real-world examples",
+          "href": "#real-world-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Recipe absorbed into the system",
+          "href": "#recipe-absorbed-into-the-system",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Where a conversation would have helped",
+          "href": "#where-a-conversation-would-have-helped",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Discoverability gap",
+          "href": "#discoverability-gap",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Valid recipe",
+          "href": "#valid-recipe",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "The happy path",
+          "href": "#the-happy-path",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "What's next",
+          "href": "#whats-next",
+          "depth": 2,
+          "numbering": [
+            1,
+            10
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}