Diagram design skill
The diagram-design skill is the central instruction set for turning a communication need into a clear diagram artifact. It guides type selection, semantic modeling, visual design, optional motion, and final checks so that each output is useful to its audience, readable without explanation, and safe to reuse. It also defines how to redraw imported diagrams and when to produce explicit PNG or SVG exports.
System purpose
Instruction set
The skill treats a diagram as an editorial explanation rather than a collection of shapes. It first asks whether a visual adds more value than prose, a table, or a list. When a diagram is justified, it reduces the source to one main story and produces a self-contained HTML figure with inline SVG and CSS. Static meaning is the baseline. Motion and requested PNG or SVG exports are controlled extensions of that artifact rather than automatic side effects. See Diagram onboarding and output contract for the user-facing entry points and output rules.
The skill covers 51 visual types. Semantic patterns describe behavior, while visual types provide the layout grammar. This separation keeps a process, state, trust, enforcement, or risk story from being expressed only through a shape arrangement. The visual set also includes comparison views such as architecture delta, where stable identities and explicit change records explain topology changes.
References: skills/…/SKILL.md• L9-13 skills/…/SKILL.md• L50-81 skills/…/SKILL.md• L83-143 skills/…/SKILL.md• L345-370
Design flow
The workflow moves from the reader’s question to a bounded visual answer. Each decision narrows the next one: the story determines the semantic meaning, the meaning determines the layout grammar, and the destination determines the form of the deliverable.
The following diagram shows how the skill moves from communication need to a checked artifact.
flowchart LR
Need[Reader need] --> Fit{Visual adds value?}
Fit -- No --> Text[Use prose, table, or bullets]
Fit -- Yes --> Story[Name the main story]
Story --> Pattern[Choose semantic pattern when behavior matters]
Pattern --> Type[Choose visual type]
Type --> Scope[Set audience, size, and detail]
Scope --> Design[Apply style and layout rules]
Design --> Output[Create static self-contained artifact]
Output --> Check[Run self-validation]
Check --> Deliver[Deliver or revise]
References: skills/…/SKILL.md• L50-81 skills/…/SKILL.md• L147-149 skills/…/SKILL.md• L261-315
Diagram selection
Communication fit
The skill starts with the learning goal, not with a preferred chart or diagram style. It rejects visuals that only restate a list, a simple comparison, or a single concept. When the visual is justified, the author removes nodes, links, and labels that do not help the reader follow the main story.
The standard target is a technically complete figure with moderate density. The usual budget is no more than nine nodes and twelve arrows, with no more than two focal coral elements and two annotation callouts. Motion has its own limits and does not justify a denser static figure. A larger story becomes an overview plus detail instead of a crowded single canvas.
References: skills/…/SKILL.md• L35-61 skills/…/SKILL.md• L239-251 skills/…/SKILL.md• L265-286
Semantic patterns and visual types
The skill separates semantic patterns, which describe what the system does, from visual types, which describe how the information is arranged. When behavior, state, trust, or risk carries the meaning, the author chooses one primary semantic pattern first. The nearest visual type then supplies the layout grammar.
The semantic choices cover common constraints such as bottlenecks, staged governance, conversion of unstructured input into a durable artifact, paired policy traces, trust boundaries, control layers, traceable decomposition, and lifecycles. The 51 supported visual types then cover system structure, decisions, messages, state, data relationships, time, ownership, quantitative comparison, planning, security, migration, and related communication needs. A pattern may add behavior-specific marks, but it does not create a second competing layout. See Diagram taxonomy and semantic patterns for the supported choices and their limits.
The architecture delta type uses two synchronized topology snapshots and a change ledger. It keeps retained identities stable so that added, removed, changed, moved, and rewired elements remain readable as one comparison rather than two unrelated drawings.
The author loads the selected type reference before drawing. If two types appear useful, the author selects the dominant axis. If the source exceeds the budget, the author splits it into overview and detail.
References: skills/…/SKILL.md• L65-145 skills/…/SKILL.md• L345-370 skills/…/semantic-patterns.md• L1-19 skills/…/semantic-patterns.md• L119-147 skills/…/type-architecture-delta.md• L1-37
Scope and audience
The skill shapes a diagram for its destination before drawing it. Imported work uses four decisions: format, canvas size, detail level, and audience. These choices control how much source content survives and how technical the labels are, so they are not cosmetic changes made after layout. The size preset also sets the viewBox and type scale, while faithful detail can exceed the normal node budget only within defined bounds.
The source remains the boundary. The author may merge or omit content according to the selected detail level, but does not invent components or silently remove meaningful source content. Before rendering, the author states the selected type, size, and planned cuts, along with the semantic pattern when one applies, so the user can redirect the plan or the assumptions remain visible.
References: skills/…/SKILL.md• L147-149 skills/…/SKILL.md• L345-356
Diagram production
Style onboarding
The first diagram in a project passes through a style-guide gate. The skill first resolves a project marker or saved profile. A resolved profile selects the project skin and bypasses the gate; otherwise the skill checks whether the shared style guide still has its shipped defaults and asks whether to customize them or explicitly keep them. A custom unsaved skin also skips the gate and can be saved as a named profile.
Onboarding can read a website, an installed skill, or a local design-system folder. It maps the design source to semantic roles such as page paper, primary ink, muted text, focal accent, and borders. It proposes the token changes for approval before writing them, then offers to save the result as a named client profile. A project marker or leading profile header selects which saved profile applies. See Diagram style and visual primitives for the visual system and profile behavior.
References: skills/…/SKILL.md• L17-31 skills/…/SKILL.md• L176-203 skills/…/onboarding.md• L1-38 skills/…/onboarding.md• L44-125 skills/…/profiles.md• L1-42
Visual construction
The author starts from the output form that matches the destination and replaces its editorial content with the selected diagram story. The design system uses shape, color, typography, spacing, and line style as semantic cues rather than decoration. Deletion remains the main quality tool: each node must represent a distinct idea, each connection must carry information, and focal color must remain limited.
Layout uses a consistent 4px structural grid and a restrained hierarchy. Connectors use rounded right-angle routing with visible label gaps, separate attachment points, and clear z-order. The legend stays outside the main diagram area. Universal anti-patterns reject decorative glow, blanket monospaced text, identical boxes, shadows, vertical arrow text, and other treatments that add style without meaning. See Diagram style and visual primitives for the shared visual vocabulary.
The standard deliverable is one self-contained HTML file with embedded CSS and complete inline SVG. External resources are not required except for permitted Google Fonts. The SVG includes a first-child accessible title and description with diagram-specific IDs. PNG and standalone SVG exports are manual exports that contain the diagram SVG without the editorial wrapper. See Diagram onboarding and output contract for output structure and export behavior.
References: skills/…/SKILL.md• L153-231 skills/…/SKILL.md• L235-257 skills/…/SKILL.md• L319-344 skills/…/SKILL.md• L372-385 skills/…/layout-budget.md• L5-69
Source redraws
When the input is Mermaid, draw.io, Excalidraw, or PlantUML, the skill treats it as a source of meaning rather than a finished layout. The author extracts the source structure, selects the target type and four output dials, and redraws the content in the editorial system. Source coordinates, colors, themes, and renderer quirks do not define the result.
This approach preserves meaningful components, relationships, groups, and direction while making every merge, collapse, or omission visible. Extracted labels, links, directives, and metadata are treated as untrusted source data rather than instructions. The output dials set format, size, detail, and audience before drawing; faithful detail may exceed the normal budget only when the source is zoned and remains within its limit. Import-specific procedures live outside this central page. The shared rule is simple: extract, set the output decisions, redraw, and report the fidelity of the result.
References: skills/…/SKILL.md• L332-356
Optional behavior
Animation layer
Motion is an optional presentation layer over a complete static diagram. The static frame must contain every meaningful node, label, relationship, state, and outcome before motion starts. Animation can clarify order or change over time, but it cannot repair missing meaning or justify a denser diagram.
The skill supports none, reveal, step, and loop modes. Only the loop repeats. Reduced-motion, print, no-JavaScript, and export states show the complete static result. Motion does not increase the diagram’s complexity budget. See Diagram animation for the allowed modes, controls, and accessibility rules.
References: skills/…/SKILL.md• L319-320 skills/…/animation.md• L1-48
Quality control
Self-validation gate
Before delivery, the skill checks both communication quality and artifact safety. The taste gate confirms that the selected type fits the story, the figure stays within its budget, unnecessary content was removed, focal signals remain limited, and the SVG has the required accessible naming.
Validation also covers style and typography, geometry, static behavior, and requested motion. Type-specific contracts can add checks; for example, an architecture delta must keep stable identities, synchronized snapshots, and a complete change ledger. Geometry verification checks connector routing, label gaps, attachment points, transit paths, and masks. A failed check means the author revises the diagram or its scope rather than hiding the problem with styling. The local checks also protect single-file output and the required no-JavaScript fallback for animated work. See Diagram self-validation for the local checks and source-extraction helpers. For repository-level troubleshooting, see Diagram diagnostics.
References: skills/…/SKILL.md• L261-301 skills/…/SKILL.md• L370-385 skills/…/type-architecture-delta.md• L39-89 skills/…/type-architecture-delta.md• L118-124
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to semantic patterns or visual types can alter the routing guidance, complexity limits, and links to the taxonomy page.
- Changes to stable IDs, snapshot rules, status vocabulary, or change ledgers must stay aligned with architecture-delta authoring and validation.
- Changes to style roles, fonts, profile headers, or client-profile resolution can affect onboarding, templates, and every newly generated diagram.
- Changes to output formats, size presets, detail levels, or audience rules can change both the redraw plan and the fidelity report.
- Changes to the layout grid or per-type budgets can alter type references, responsive layout, and the split rule.
- Changes to motion behavior must preserve the complete static frame, reduced-motion behavior, print behavior, and exported output.
- Changes to connector rules, anti-patterns, or geometry checks must stay aligned with the visual primitives and self-validation pages.
- Changes to the taste gate or accessible-SVG contract must stay aligned with generated artifacts and the self-validation flow.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A diagram is selected when prose or a table would communicate the same point | The reader gets extra visual complexity without extra meaning | Apply the visual-fit question before choosing a type |
| Behavior is encoded only through a visual type | State, policy, trust, or risk meaning becomes unclear or incomplete | Select one semantic pattern before the layout type |
| The complexity budget is exceeded on one canvas | Connectors and hierarchy become hard to follow | Remove content in the defined order or split overview and detail |
| Default tokens are used in a branded project without a deliberate choice | The artifact does not match the project’s visual language | Resolve the style gate or obtain explicit approval to use defaults |
| Source coordinates or renderer styling are copied during an import | The result keeps source layout problems instead of gaining an editorial layout | Extract content, then redraw from a fresh layout |
| Architecture-delta identities or ledger entries do not match the two snapshots | The comparison cannot show which objects changed or whether a relationship was rewired | Keep stable IDs across retained objects and validate the complete change ledger |
| Motion hides semantic content or changes the meaning of the static frame | No-JavaScript, reduced-motion, print, and export users receive an incomplete figure | Make the static frame complete and keep motion as enhancement only |
| A connector or label fails the geometry rules | Relationships cannot be traced reliably | Run the taste gate and geometry checks before delivery |
| The SVG lacks its required title, description, or unique IDs | Assistive technology receives incomplete or incorrect figure context | Apply the accessible SVG contract before delivery |
Key files
| File | Why to read it |
|---|---|
| skills/…/SKILL.md | Central workflow, selection rules, design principles, output contract, and pre-output gate |
| skills/…/semantic-patterns.md | Meaning-first routing for behavior, state, enforcement, risk, decomposition, and lifecycle |
| skills/…/type-architecture-delta.md | Synchronized topology comparison, stable identities, change vocabulary, and validation contract |
| skills/…/output-spec.md | Format, size, detail, audience, and fidelity decisions for deliverables |
| skills/…/style-guide.md | Shared semantic color, typography, spacing, and node-treatment vocabulary |
| skills/…/layout-budget.md | Structural grid, per-type limits, page layout, and summary-card rules |
| skills/…/onboarding.md | How a project derives a skin from a design source |
| skills/…/profiles.md | How named client profiles, markers, and profile headers affect style selection |
| skills/…/animation.md | Static-first motion modes, accessibility behavior, and playback constraints |
| skills/…/import-plantuml.md | PlantUML source extraction and redraw boundaries |
| skills/…/template.html | Minimal light output starting point |
| skills/…/template-motion.html | Motion output starting point when animation is requested |
| skills/…/self_check.py | Skill-local artifact check used before delivery |
| skills/…/verify_geometry.py | Connector and label geometry check used by the pre-output gate |
| skills/…/plantuml_extract.py | Structural input for PlantUML redraws |