# How to Create a Sequence Diagram with a Token Refresh Example in Diagram-Design > Learn to create a sequence diagram with a token refresh example in Diagram-Design. Model OAuth token flows, including happy and failure paths, in self-contained HTML. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-08-14 --- **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`](https://github.com/cathrynlavery/diagram-design/blob/main/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 ```text 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) ```bash /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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md). The root `` element includes: - `role="img"` for screen-reader recognition - `aria-labelledby` linking to a `` element ("Bearer call with refresh") - `` element summarizing the complete flow ### Using the Built-In Template For manual customization, start from the minimal template: ```bash cp skills/diagram-design/assets/template.html token-refresh.html # Replace the 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md): ```bash # 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md) | | Working OAuth example with full SVG implementation | [`skills/diagram-design/assets/example-sequence-oauth.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-sequence-oauth.html) | | Command surface and accessibility requirements | [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | | Design tokens (colors, fonts) | [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | | Export procedures for HTML → SVG/PNG | [`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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 `` elements satisfy WCAG requirements - **Export options** include PNG (with scaling) and SVG via commands in [`references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.