How to Create a Sequence Diagram with a Token Refresh Example in Diagram-Design

Diagram-Design renders sequence diagrams as self-contained HTML files, using an alt combined fragment to model the happy path (valid token → 200) and failure path (401 → refresh → retry) in OAuth Bearer token flows.

The cathrynlavery/diagram-design repository provides a specialized skill for generating publication-ready sequence diagrams from natural language or explicit commands. This guide walks through creating a token-refresh sequence diagram that visualizes authentication failures and recovery patterns.

Selecting the Sequence Diagram Type

Diagram-Design determines the visual layout through its type guide system. For sequence diagrams, the skill loads skills/diagram-design/references/type-sequence.md, which defines:

• Lifelines: Dashed vertical lines representing participants
• Activation bars: Thin rectangles showing method execution
• Message arrows: Styled with arrow-link, arrow-accent, or arrow-open markers
• Combined fragments: alt, opt, loop, and other UML constructs

The type guide specifies that alt fragments use a tabbed frame with guard conditions to separate alternative flows—exactly what's needed for token-refresh logic.

Describing the Token Refresh Scenario

You can trigger diagram generation through natural language prompts or slash commands. Both methods automatically structure the OAuth Bearer flow with proper UML semantics.

Natural Language Prompt

Make me a sequence diagram of a bearer API call that refreshes the token on a 401 response.

The agent parses this request, maps it to the Sequence type, and constructs an alt fragment with two guarded regions:

• [token valid] — Success path returning HTTP 200
• [else · 401] — Failure path triggering token refresh and retry

Explicit Slash Command (Pi)

/diagram-design:make sequence \
  --title "Bearer call with refresh" \
  --description "Client calls API with a bearer token. On 401 the client refreshes the token and retries." \
  --fragment alt \
  --guard "[token valid]" \
  --else "[else · 401]"

Both approaches produce identical output: a standalone HTML file with embedded SVG following the accessibility and styling contracts defined in skills/diagram-design/SKILL.md.

Rendering and Visual Structure

The SVG generator in Diagram-Design assembles diagrams from semantic primitives documented in the type-sequence reference:

1. Lifelines for Client, Auth Server, and API Server
2. Activation bars spanning the duration of each request/response
3. Synchronous messages (solid arrows) for API calls
4. Return messages (dashed arrows) for responses
5. ALT frame with tab label enclosing both branches

Colors and typography are pulled from skills/diagram-design/references/style-guide.md or from brand-specific tokens loaded during onboarding. The visual hierarchy distinguishes:

• Primary flows with accent-colored arrows
• Error paths with standard link styling
• Frame boundaries with subtle borders and background fills

Accessibility and Export

Generated diagrams satisfy the accessibility contract specified in SKILL.md. The root <svg> element includes:

• role="img" for screen-reader recognition
• aria-labelledby linking to a <title> element ("Bearer call with refresh")
• <desc> element summarizing the complete flow

Using the Built-In Template

For manual customization, start from the minimal template:

cp skills/diagram-design/assets/template.html token-refresh.html

# Replace the <svg> block with content from example-sequence-oauth.html

Export Commands

Convert to raster or vector formats via the export system documented in skills/diagram-design/references/export.md:

# Export to PNG at 3x resolution for crisp printing

/export-diagram token-refresh.html --png-only --scale=3

# Export to SVG for embedding in documentation

/diagram-design:export token-refresh.html --svg-only

Key Source Files

Understanding these repository locations enables precise customization:

Purpose	File Path
Sequence layout specification and alt fragment syntax	skills/diagram-design/references/type-sequence.md
Working OAuth example with full SVG implementation	skills/diagram-design/assets/example-sequence-oauth.html
Command surface and accessibility requirements	skills/diagram-design/SKILL.md
Design tokens (colors, fonts)	skills/diagram-design/references/style-guide.md
Export procedures for HTML → SVG/PNG	skills/diagram-design/references/export.md

Summary

• Sequence diagrams in Diagram-Design are rendered as self-contained HTML with embedded SVG
• Token refresh flows use alt combined fragments to separate success ([token valid]) and failure ([else · 401]) paths
• Three input methods work: natural language prompts, explicit slash commands, or template-based manual editing
• Accessibility is automatic: role, aria-labelledby, and <desc> elements satisfy WCAG requirements
• Export options include PNG (with scaling) and SVG via commands in references/export.md

Frequently Asked Questions

What UML standard does Diagram-Design follow for sequence diagrams?

Diagram-Design implements UML 2.x sequence diagram semantics as documented in type-sequence.md. This includes lifelines, execution specifications (activation bars), synchronous and asynchronous messages, and combined fragments (alt, opt, loop, par). The OAuth example demonstrates the alt fragment for exclusive alternatives—standard UML notation with guard conditions in square brackets.

Can I customize colors and fonts in my sequence diagram?

Yes. The SVG generator consumes design tokens from skills/diagram-design/references/style-guide.md by default. For branded outputs, the skill supports overriding these tokens during the onboarding step or by editing the CSS variables in the generated HTML. The example-sequence-oauth.html file shows the default token application.

How do I modify an existing diagram after generation?

Three approaches exist: (1) Regenerate from an updated natural language prompt, (2) Edit the inline SVG directly in the HTML file using the template at skills/diagram-design/assets/template.html, or (3) Use the slash command with modified --guard or --else parameters to rebuild with different branch conditions. The HTML format preserves full editability without external dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}