gmdiagram — GM Architecture Skill

What This Skill Does

Generate publication-quality diagrams as standalone files. The output can be:

HTML: Single .html file with inline SVG and embedded CSS (default, no JavaScript)
SVG: Standalone .svg file
Mermaid: Mermaid text syntax (paste into GitHub, Notion, etc.)
PNG/PDF: Via the export script at scripts/export.sh

Output Directory Structure

All example files must be output to the correct directory structure:

assets/examples/
├── {example-name}.json      # JSON schema file
├── {example-name}.html      # HTML rendered output (same name as JSON)
└── images/                  # For preview screenshots only
    └── {example-name}-preview.png

Rules

Correct approach:

HTML and JSON files go in the examples/ root directory
Preview images go in the examples/images/ subdirectory
Filenames must be consistent (only extensions differ)

Prohibited approach:

Do NOT put HTML files in the images/ directory
Do NOT generate any non-image files in the images/ directory
Do NOT put JSON files in subdirectories (unless there's explicit categorization need)

Example

For the chrome-architecture example:

assets/examples/chrome-architecture.json
assets/examples/chrome-architecture.html
assets/examples/images/chrome-architecture-preview.png
assets/examples/images/chrome-architecture.html (WRONG: HTML should not be in images/)

Interactive Selection

When the user's request does NOT already specify all three choices (diagram type, style, output format), use the AskUserQuestion tool to let the user choose.

Important: AskUserQuestion supports at most 4 options per question and 4 questions per call. When there are more than 4 choices, split into two calls or use the auto-infer + confirm pattern below.

Selection Strategy

For each dimension, follow this logic:

Can the choice be inferred from the user's description? → Skip asking, use the inferred value directly.
Does the user explicitly state it? → Skip asking, use the stated value.
Still ambiguous? → Ask via AskUserQuestion.

Question 1 — Diagram Type (ask only if ambiguous)

The user's description usually makes the type obvious. Only ask when multiple types could fit.

question: "Which diagram type fits your needs?"
header: "Type"
multiSelect: false
options:
  - label: "Architecture"
    description: "System layers, services, infrastructure, platform maps"
  - label: "Flowchart"
    description: "Process flow, decision tree, branching logic"
  - label: "Mind Map"
    description: "Topic hierarchy, brainstorm, feature tree"
  - label: "Other"
    description: "ER Diagram, Sequence, Gantt, UML Class, Network, or Card"

If the user picks "Other", ask a follow-up:

question: "Which specific type?"
header: "Type"
multiSelect: false
options:
  - label: "ER Diagram"
    description: "Database tables, entities, relationships, data model"
  - label: "Sequence Diagram"
    description: "Message flow, API calls, protocol, interaction between actors"
  - label: "Gantt Chart"
    description: "Project timeline, milestones, task scheduling"
  - label: "Card"
    description: "Social sharing card — knowledge, comparison, quote, or ranked list"
  - label: "More"
    description: "UML Class Diagram or Network Topology"

If the user picks "More", ask a final follow-up:

question: "Which type?"
header: "Type"
multiSelect: false
options:
  - label: "UML Class Diagram"
    description: "OOP design, classes, inheritance, interfaces"
  - label: "Network Topology"
    description: "Servers, routers, subnets, network architecture"

Question 2 — Visual Style (always ask unless user named a style)

Split into three style families. First call asks for family:

First call:

question: "Which style family?"
header: "Style"
multiSelect: false
options:
  - label: "Dark"
    description: "Dark Professional, Cyberpunk Neon, or Terminal Retro"
  - label: "Light / Clean"
    description: "Light Corporate, Minimalist, Warm Cozy, or Notion"
  - label: "Creative"
    description: "Hand-Drawn, Blueprint, Pastel Dream, Material, or Glassmorphism"

Then follow up based on the family:

Dark follow-up:

options:
  - label: "Dark Professional (Recommended)"
    description: "Neon accents, tech articles, docs, presentations"
  - label: "Cyberpunk Neon"
    description: "Catppuccin dark, vivid neon, developer tools"
  - label: "Terminal Retro"
    description: "CRT green-on-black, scanlines, developer blogs"

Light follow-up:

options:
  - label: "Light Corporate"
    description: "Clean white, muted palette, enterprise reviews"
  - label: "Minimalist"
    description: "Monochrome, ultra-thin borders, maximum whitespace"
  - label: "Warm Cozy"
    description: "Warm cream, soft tones, tutorials"
  - label: "Notion"
    description: "Notion-like document aesthetic, system fonts, subtle borders"

Creative follow-up:

options:
  - label: "Hand-Drawn Sketch"
    description: "Warm beige, sketchy borders, whiteboard feel"
  - label: "Blueprint"
    description: "Nord blue, grid lines, engineering specs"
  - label: "Pastel Dream"
    description: "Soft pastels, rounded corners, playful"
  - label: "More"
    description: "Material Design or Glassmorphism"

If user picks "More":

options:
  - label: "Material Design"
    description: "Google Material, bold fills, elevation shadows, Roboto font"
  - label: "Glassmorphism"
    description: "Frosted glass, translucent layers, gradient background"

Question 3 — Output Format (always ask unless user named a format)

question: "Which output format?"
header: "Format"
multiSelect: false
options:
  - label: "HTML (Recommended)"
    description: "Single file with inline SVG, opens in any browser"
  - label: "SVG"
    description: "Standalone SVG for vector editors (Figma, Illustrator)"
  - label: "Mermaid"
    description: "Text syntax, paste into GitHub, Notion, or markdown"
  - label: "PNG / PDF"
    description: "Image export via script (requires Node.js or rsvg-convert)"

How to Combine Questions

Minimize the number of AskUserQuestion calls:

User specified nothing: First call asks Type + Style family + Format (3 questions). Then a follow-up call if they picked "Other" type or "Creative" style.
User specified type only: Ask Style family + Format (2 questions). Follow-up if "Creative" style.
User specified type + style: Ask Format only (1 question, 1 call).
User specified everything: Skip all selection, proceed directly to generation.

Rules

If the user already specified all three, skip selection entirely.
Only ask about dimensions the user hasn't specified.
Put (Recommended) on the default/first option for style and format.
After all selections are made, proceed to the Two-Step Generation Process below.

Density (default: normal, never ask)

Density defaults to "normal". Infer from the user's description — never ask via AskUserQuestion:

"compact" / "dense" / "tight" / "紧凑" → "compact"
"spacious" / "spread out" / "presentation" / "宽松" → "spacious"
Otherwise → "normal"

When density differs from normal, read the "Density Multipliers" section in the corresponding layout reference file to get adjusted spacing constants.

Direction (default: TB, never ask)

Direction defaults to "TB" (top-to-bottom). Only applies to architecture and flowchart. Infer from user description:

"left to right" / "horizontal" / "LR" / "从左到右" → "LR"
Otherwise → "TB"

When direction is "LR", read the "LR Mode" section in the layout reference file for transformed coordinate rules. ER, sequence, and mindmap diagrams always use their inherent layout — ignore direction for these types.

Font and Color Overrides (ask only if user requests)

After all selections, if the user mentions custom colors, fonts, or brand colors, apply overrides from the font and colors fields in the JSON schema.

Font override: When font is set, add a Google Fonts <link> in the HTML <head> and replace all font-family declarations with the user's font as primary.

Color overrides: When colors object is present:

colors.primary replaces the style's primary accent/border color
colors.secondary replaces subtle border and background colors
colors.accent replaces highlight colors
colors.background replaces the page background color
colors.text replaces primary text color

Apply overrides LAST, after all style template values are resolved. Override colors replace corresponding values in type color mapping, connection lines, and legend swatches.

Metadata Version Field

生成 JSON 时，metadata.version 必须遵循以下规则：

格式: 必须符合 SemVer (Semantic Versioning) 格式: major.minor.patch
示例: "0.6.1", "1.2.0", "2.0.0"
禁止的占位符版本: "0.0.0", "1.0", "1.0.0"

推荐的版本策略: 建议使用与插件版本一致的值，但不做强制要求。重要的是保持格式规范。

JSON 示例:

"metadata": {
  "author": "gmdiagram",
  "date": "2026-04-14",
  "version": "0.6.1"
}

验证规则:

必须包含 3 个数字段，用点号分隔
每段必须是纯数字
不允许前导零（如 "01.02.03" 无效）

Two-Step Generation Process

ALWAYS follow these two steps in order. Never skip to output directly.

Step 1: Generate JSON Schema

Read the user's description and extract structure into the JSON schema for the selected diagram type. Each type has its own schema file in assets/:

Diagram Type	Schema File
`architecture`	`assets/schema-architecture.json`
`flowchart`	`assets/schema-flowchart.json`
`mindmap`	`assets/schema-mindmap.json`
`er`	`assets/schema-er.json`
`sequence`	`assets/schema-sequence.json`
`gantt`	`assets/schema-gantt.json`
`uml-class`	`assets/schema-uml-class.json`
`network`	`assets/schema-network.json`

Key rules across all types:

Every component gets a unique id (kebab-case)
Use semantic type values as defined in each schema
If the user doesn't specify a style, use dark-professional
If the user doesn't specify a format, use html
If the user doesn't specify a density, use normal
If the user doesn't specify a direction, use TB (architecture/flowchart only)
Components can reference icons via the "icon" field (see references/icons-catalog.md)

Output the JSON first, then proceed to Step 2.

Step 2: Generate Output

Read the diagram-type reference file for generation instructions:

Choose template: Based on the style field, read the corresponding style reference and template:
- dark-professional → references/style-dark-professional.md → assets/template-dark.html
- hand-drawn → references/style-hand-drawn.md → assets/template-sketch.html
- light-corporate → references/style-light-corporate.md → assets/template-light-corporate.html
- cyberpunk-neon → references/style-cyberpunk-neon.md → assets/template-cyberpunk-neon.html
- blueprint → references/style-blueprint.md → assets/template-blueprint.html
- warm-cozy → references/style-warm-cozy.md → assets/template-warm-cozy.html
- minimalist → references/style-minimalist.md → assets/template-minimalist.html
- terminal-retro → references/style-terminal-retro.md → assets/template-terminal-retro.html
- pastel-dream → references/style-pastel-dream.md → assets/template-pastel-dream.html
- notion → references/style-notion.md → assets/template-notion.html
- material → references/style-material.md → assets/template-material.html
- glassmorphism → references/style-glassmorphism.md → assets/template-glassmorphism.html
Compute layout: Follow the coordinate calculation rules in the diagram-type-specific layout file.
Build SVG: Use the component SVG snippets from the diagram-type-specific components file.

Wrap in HTML (if format=html): Use the corresponding template file as the starting structure.

HTML Language Attribute

根据内容语言设置正确的 <html lang="..."> 属性：

内容语言	lang 属性值	使用场景
英文	`en`	标题、标签、描述均为英文
简体中文	`zh-CN`	标题、标签、描述包含简体中文
繁体中文	`zh-TW`	标题、标签、描述包含繁体中文
日文	`ja`	标题、标签、描述包含日文

自动检测规则

使用以下启发式规则判断内容语言：

检查 title 字段: 如果包含中文字符（\u4e00-\u9fff），使用 zh-CN
检查 subtitle 字段: 如果包含中文字符，使用 zh-CN
检查主要 labels: 如果超过 50% 的标签包含中文，使用 zh-CN
默认: 如果不确定或混合语言，使用 en

示例

中文内容示例:

<html lang="zh-CN">
<head><title>系统架构图</title></head>

英文内容示例:

<html lang="en">
<head><title>Chrome Multi-Process Architecture</title></head>

重要性

正确的 lang 属性有助于：

屏幕阅读器正确发音
浏览器正确渲染字体
SEO 优化

For other formats:

SVG: Follow references/output-svg.md — extract standalone SVG
Mermaid: Follow references/output-mermaid.md — transform JSON to Mermaid text
PNG/PDF: First generate HTML or SVG, then run scripts/export.sh (see references/output-png-pdf.md)

Design Principles

Diagrams should argue, not just display — every element should contribute to understanding
Structure first, aesthetics second — correct relationships matter more than visual polish
Label everything meaningful — connections need labels, components need names
Consistency over creativity — use the defined color system, don't invent new colors
No JavaScript — the output must work without any scripting (HTML/SVG formats)
Escape all user text — HTML-entity-escape <, >, &, ", ' in all labels, titles, and descriptions before inserting into SVG/HTML to prevent XSS

Diagram Type Reference

When the diagram type is clear from context (or after the user selects it), use this mapping:

Diagram Type	Reference File	Schema File
`architecture`	`references/diagram-architecture.md`	`assets/schema-architecture.json`
`flowchart`	`references/diagram-flowchart.md`	`assets/schema-flowchart.json`
`mindmap`	`references/diagram-mindmap.md`	`assets/schema-mindmap.json`
`er`	`references/diagram-er.md`	`assets/schema-er.json`
`sequence`	`references/diagram-sequence.md`	`assets/schema-sequence.json`
`gantt`	`references/diagram-gantt.md`	`assets/schema-gantt.json`
`uml-class`	`references/diagram-uml-class.md`	`assets/schema-uml-class.json`
`network`	`references/diagram-network.md`	`assets/schema-network.json`
`card`	`references/diagram-card.md`	`assets/schema-card.json`

Read the diagram-type-registry at references/diagram-type-registry.md for detailed trigger keywords.

Iteration Workflow

After generating the initial diagram, the user may request changes:

Add/remove components → update JSON, recompute layout
Change a connection → update JSON connections, recompute paths
Change style → switch template, keep same JSON
Change diagram type → re-extract JSON for new type, regenerate
Change output format → regenerate from existing JSON

File Naming Convention

示例文件名必须使用 kebab-case（短横线连接的小写字母）。

命名格式

{context}-{type}[-{variant}].{ext}

context: 场景描述（如 chrome, saas, ecommerce, quarterly-revenue）
type: 图表类型（可选，如 architecture, flowchart, bar-chart）
variant: 变体标识（可选，如 cyberpunk, minimalist, dark）
ext: 文件扩展名（json 或 html）

正确与错误示例

命名风格	示例	状态
kebab-case ✅	`chrome-architecture.json`	正确
kebab-case ✅	`quarterly-revenue.json`	正确
kebab-case ✅	`team-skills-radar.json`	正确
camelCase ❌	`chromeArchitecture.json`	错误
PascalCase ❌	`QuarterlyRevenue.json`	错误
snake_case ❌	`team_skills.json`	错误
空格 ❌	`chrome architecture.json`	错误

规则

全部小写: 文件名中不包含大写字母
单词分隔: 使用连字符 - 分隔单词，不使用下划线或空格
无特殊字符: 仅使用字母、数字和连字符
清晰语义: 文件名应清晰表达示例内容

批量命名示例

对于同一系统的多个风格变体：

architecture-system.json (默认风格)
architecture-system-cyberpunk.json
architecture-system-minimalist.json
architecture-system-terminal.json

Quality Checklist

Before delivering, verify:

gm-architecture

gmdiagram — GM Architecture Skill

What This Skill Does

Output Directory Structure

Rules

Example

Interactive Selection

Selection Strategy

Question 1 — Diagram Type (ask only if ambiguous)

Question 2 — Visual Style (always ask unless user named a style)

Question 3 — Output Format (always ask unless user named a format)

How to Combine Questions

Rules

Density (default: normal, never ask)

Direction (default: TB, never ask)

Font and Color Overrides (ask only if user requests)

Metadata Version Field

Two-Step Generation Process

Step 1: Generate JSON Schema

Step 2: Generate Output

Design Principles

Diagram Type Reference

Iteration Workflow

File Naming Convention

命名格式

正确与错误示例

规则

批量命名示例

Quality Checklist

More from zeroz-lab/gmdiagram

architecture-diagram

gm-data-chart