docs-diagrams

name	docs-diagrams
description	Add or refine diagrams in documentation, especially Mermaid workflow diagrams in apps/docs. Use when a docs page explains actor handoffs, phase gates, failure paths, state transitions, or multi-step flows that are clearer as a diagram.
metadata	{"short-description":"Create or refine docs diagrams"}

Docs Diagrams

Use this skill when updating apps/docs/content/docs/**/*.mdx and the page would benefit from a visual explanation.

Default Approach

1. Keep it simple. Prefer 1-2 diagrams with short titles and one-sentence captions.
2. Use the local Mermaid wrapper at apps/docs/components/mermaid.tsx rather than raw Mermaid fences.
3. For actor workflows, use actorIcons={{ Human: "human", Agent: "robot" }} when those roles are present.
4. Keep diagram labels short. Put detail in the prose below the diagram.
5. Validate with bun run --cwd apps/docs build.

In This Repo

• Mermaid wrapper: apps/docs/components/mermaid.tsx
• Good sequence-diagram example: apps/docs/content/docs/primitives/gate.mdx
• Supporting docs that cross-link into the pattern: apps/docs/content/docs/getting-started.mdx and apps/docs/content/docs/agent-sdk.mdx

Pick The Right Diagram

Use a sequence diagram for:

• agent and human handoffs
• approval gates
• failure and recovery flows
• API or service interactions

Use a flow or state diagram only when the page is really about: