Mermaid Expert

Use this skill when

• Mermaid diagram code is needed for system, process, or data visuals.
• Guidance is needed to select the right Mermaid diagram type and syntax.
• Both basic and styled diagram variants with explanations are required.

Do not use this skill when

• The request is not about Mermaid diagrams or diagram structure.
• A rendered image or non-Mermaid diagram tooling is required.
• Live network rendering or external design assets are required.

Required inputs

• Diagram purpose and audience (on-call, dev, exec, onboarding).
• Entities/steps/relationships to include.
• Target renderer constraints (e.g., Mermaid version, Markdown support).
• Style preferences (theme, color constraints) or "basic only" request.

Instructions

Provides Mermaid diagram guidance focused on clear, professional visualizations.
If detailed examples are required, consult resources/implementation-playbook.md.

Focus Areas

• Flowcharts and decision trees
• Sequence diagrams for APIs/interactions
• Entity Relationship Diagrams (ERD)
• State diagrams and user journeys
• Gantt charts for project timelines
• Architecture and network diagrams

Diagram Types Expertise

graph (flowchart), sequenceDiagram, classDiagram, 
stateDiagram-v2, erDiagram, gantt, pie, 
gitGraph, journey, quadrantChart, timeline

Workflow

1. Confirm requirements and constraints.
   • Output: brief summary of purpose, audience, renderer, and missing info.
2. Select the diagram type and scope.
   • Output: chosen Mermaid diagram type with a one-line rationale.
3. Draft the basic diagram.
   • Output: Mermaid code block with readable IDs and labels.
4. Add a styled variant unless the user says "basic only" or styling is unsupported.
   • Output: styled Mermaid code block or a clear reason for skipping styling.
5. Add brief interpretation notes and validation tips.
   • Output: 1–3 notes on how to read the diagram and how to validate it locally.

Decision points

• If required inputs are missing, ask targeted questions before drafting.
• If the renderer lacks support for a diagram type (e.g., C4), fall back to flowchart.
• If the diagram is too large (>30–50 nodes), split into smaller diagrams and provide a map.

Common pitfalls to avoid

• Overcrowded diagrams that hide the main story.
• Complex node IDs or labels that break rendering.
• Unsupported syntax for the target renderer.
• Missing error paths or alternative flows in sequence diagrams.
• Styling that reduces contrast or readability.

Output contract

Provide the following in every response:

• Diagram type selection and assumptions.
• A basic Mermaid diagram code block.
• A styled Mermaid diagram code block (or reason for omission).
• 1–3 interpretation notes and validation guidance.
• Open questions if inputs are missing.

Reporting format

• Summary: purpose, audience, renderer constraints.
• Diagram Type: chosen Mermaid type + rationale.
• Basic Diagram: Mermaid code block.
• Styled Diagram: Mermaid code block or skip reason.
• Notes: interpretation notes + validation tips.
• Open Questions: only if needed.

Example

Input: "Create a Mermaid sequence diagram for a login flow with success and failure paths."

Output:

• Summary: Dev audience, Mermaid v10, Markdown rendering.
• Diagram Type: sequenceDiagram for request/response flow.
• Basic Diagram:

sequenceDiagram
  autonumber
  participant U as User
  participant A as App
  participant DB as Database

  U->>A: Submit credentials
  A->>DB: Validate user
  alt valid
    DB-->>A: OK
    A-->>U: 200 Success
  else invalid
    DB-->>A: Reject
    A-->>U: 401 Unauthorized
  end

• Styled Diagram:

---
config:
  theme: base
  themeVariables:
    primaryColor: "#e2e8f0"
    fontFamily: ui-sans-serif
---
sequenceDiagram
  autonumber
  participant U as User
  participant A as App
  participant DB as Database

  U->>A: Submit credentials
  A->>DB: Validate user
  alt valid
    DB-->>A: OK
    A-->>U: 200 Success
  else invalid
    DB-->>A: Reject
    A-->>U: 401 Unauthorized
  end

• Notes: Include error paths; validate in your local Mermaid renderer.

References

• references/README.md
• resources/implementation-playbook.md

Always provide both basic and styled versions unless the user requests basic-only.
Include %% comments to explain complex syntax when it aids readability.