Diagram skill

Scope: This skill generates diagrams from text descriptions — it is NOT for data visualization (charts, graphs from datasets) or image editing. For PDF generation, see pdf.

Prerequisites

• GEMINI_API_KEY environment variable set
• jq installed (brew install jq)

Usage

/diagram "Linear issue lifecycle pipeline flow"
/diagram "three-tier architecture with Next.js, Supabase, Vercel" --output docs/architecture.png
/diagram "org chart for CTO department" --beside standards/reference/org-chart.md

Arguments:

Arg	Purpose
$1 (required)	Text description of the diagram
--output <path>	Explicit output path
--beside <file>	Place diagram alongside this file, auto-named <doc-slug>-<descriptor>.png
--aspect <ratio>	Aspect ratio: 16:9 (default), 1:1, 4:3, 9:16

---

Pipeline

Step 0: Resolve environment

[ -n "$GEMINI_API_KEY" ] && echo "GEMINI_API_KEY: set" || echo "GEMINI_API_KEY: MISSING"

If missing, stop and tell the user to set it in ~/.claude/settings.json under env.

Step 1: Build the prompt

Read the design system file at tools/explorer/DESIGN.md for the canonical color palette and style rules. Combine the user's description with the Lumina style guide below. If --beside is used, read the target document for context (headings, section structure).

Prompt template:

Generate a diagram: [USER DESCRIPTION]

IMPORTANT — follow this design system exactly (Lumina Framework):
- Background: #F8F9FF (cool-white page canvas)
- Text color: #0B1C30 (never pure black)
- Secondary text: #45464D
- Primary accent: Teal #0D9488 (highlights, success states, interactive elements)
- Secondary accent: Amber #F9A825 (warnings, attention indicators)
- Neutral: Slate #64748B (secondary text, subtle elements)
- Cards/containers: White #FFFFFF with whisper-soft shadow (0 12px 40px rgba(11,28,48,0.06))
- NO solid 1px borders — use background color shifts for separation
- Surface Low: #EFF4FF for section backgrounds and grouping
- Corners: 8px rounded (12px for large containers)
- Typography: Bold sans-serif for headings (Manrope-like), regular sans-serif for body (Inter-like)
- Generous spacing (3-4rem between sections)
- Delete/negative items: soft warm red fill #FEE2E2
- Overall feel: premium editorial, sophisticated, trustworthy — polished presentation slide, NOT a hand-drawn sketch
- Use these colors for Linear statuses if applicable:
  (pastel fills: Triage=#FDCFBF, Backlog=#E2E6EB, To-Do=#EAECEE, In Design=#F5F5F5,
   In Process=#FFF0C2, In Review=#C8F5D0, Preview Testing=#C8F5D0,
   Done=#D8DBF5, Cancelled=#E2E6EB)
- Every visual element serves communication — no decorative elements

Layout: [SELECT FROM TEMPLATES BELOW]

Step 2: Generate the image

Run the generation script:

SKILL_DIR="<framework-root>/.claude/skills/diagram"
bash "$SKILL_DIR/generate-diagram.sh" "[FULL PROMPT]" "/tmp/diagram-preview.png" "16:9"

Step 3: Show the image to the user

Read the generated file to display it inline.

Step 4: Ask for feedback

Use AskUserQuestion: "Does this look right? Any changes you'd like?"

Step 5: Iterate if needed

If the user provides feedback, append it as a revision instruction:

[ORIGINAL PROMPT]

REVISION: [USER FEEDBACK]

Re-generate with the revised prompt. Repeat steps 3-5 until the user approves.

Step 6: Place the final image

• If --output was specified, copy to that path
• If --beside was specified, name it <doc-slug>-<descriptor>.png in the same directory
• Otherwise, save to ~/Desktop/diagram.png

Add the image reference to the document if --beside was used:

![Alt text describing what the diagram shows](<filename>.png)

---

Style guide

Visual aesthetic — Lumina Framework

Premium editorial documentation aesthetic. Polished, sophisticated, trustworthy. Like a slide from a high-end tech presentation — NOT a hand-drawn whiteboard sketch.

The canonical design system lives at tools/explorer/DESIGN.md. Read it for the full specification.

Color palette

Element	Color	Hex
Background	Cool-white canvas	#F8F9FF
Text (primary)	Deep navy	#0B1C30
Text (secondary)	Dark gray	#45464D
Accent (primary)	Teal	#0D9488
Accent (secondary)	Amber	#F9A825
Neutral	Slate	#64748B
Cards/containers	White	#FFFFFF
Surface Low	Soft blue-white	#EFF4FF
Destructive/delete	Soft red	#FEE2E2
Code blocks	Light blue	#D3E4FE

Key rules:

• Never use pure black (#000000) for text
• No 1px solid borders — use tonal layering (background color shifts) to separate sections
• Shadows: whisper-soft 0 12px 40px rgba(11,28,48,0.06)
• Corners: 8px default, 12px for large containers

For Linear status colors, see the prompt template above or standards/core/linear-lifecycle.md § Status colors.

Layout templates

Pipeline flow (horizontal): Boxes left-to-right connected by arrows. Best for: issue lifecycles, CI/CD pipelines, data flows.

Architecture diagram (3-tier): Three horizontal layers stacked vertically (Client → Server → Data). Best for: system architecture, deployment topology.

Org chart (vertical tree): Root node at top, children branching downward. Best for: team structures, component hierarchies.

Sequence diagram (vertical lanes): Vertical swim lanes with horizontal arrows between them. Best for: API interactions, request flows, event sequences.

---

File naming

Follow the document formatting standard:

• <doc-slug>-<descriptor>.png
• Examples: linear-lifecycle-pipeline-flow.png, sdlc-eight-phases.png, org-chart-cto.png
• Alt text is required: describe what the diagram shows, not just its title

---

Related

• tools/explorer/DESIGN.md — Lumina Framework design system (canonical color palette, typography, shapes)
• standards/reference/document-formatting.md — Diagram placement and naming rules
• standards/core/linear-lifecycle.md § Status colors — Hex codes for Linear statuses
• /pdf skill — PDF generation with the clean.typ template