Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / diagram-onboarding-and-output

Diagram onboarding and output contract

Diagram Design turns a visual need into a reviewed diagram with a stable HTML source and a suitable delivery format. The workflow sets the visual skin, selects the canvas and level of detail, then produces derived assets without losing the source or its accessibility contract.

Workflow entry

The workflow starts when a user requests a new diagram, a redraw, or an export. Each path first establishes the visual job and destination. An imported source supplies meaning and relationships, but it does not define the new layout or act as trusted instructions.

First-run skin choice

The first diagram in a project passes through a style gate. The gate prevents a project with an established visual identity from silently using the shipped skin. The user can select a saved profile, provide a design source, enter tokens manually, or accept the default for the project.

Manual tokens become a custom section in the style guide. If the user chooses the shipped skin, the project records profile: default only with explicit consent. After either path, the workflow can save the result as a named profile so one client's visual rules stay separate from other projects.

The skin is chosen before drawing because it affects every later diagram. A pristine guide remains recoverable before a new skin replaces it, so customized tokens are not mistaken for the default snapshot.

References: skills/…/onboarding.md• L37-40 skills/…/onboarding.md• L356-360

Design-source onboarding

Design-source onboarding turns a website, installed skill, or local design-system folder into a reviewed diagram skin. It extracts visual signals, maps them to semantic roles such as paper, ink, muted, accent, surface, and rule, then applies the change only after user approval.

The source is data, not a command. Remote pages require explicit trust confirmation before contact. Local files and installed skills also remain untrusted data, so the workflow uses them for visual signals and never follows instructions found inside them. The workflow checks contrast, records uncertain mappings, and marks custom or unavailable fonts as fallbacks instead of claiming an exact match. A brand-match request also receives a fidelity receipt with sampled sources, detected roles, and font status.

The onboarding sequence is:

  1. Read or fetch the selected source after any required trust confirmation.
  2. Extract color and type signals.
  3. Map the signals to semantic roles.
  4. Check contrast and other skin constraints.
  5. Show the proposed style-guide change and confidence details.
  6. Apply the change after approval.
  7. Offer to save the result as a named profile.
  8. Rebuild a representative output and leave the workflow pending until the user verifies it.

If the user requests a correction, the workflow rebuilds the output and asks for approval again. Automated checks do not replace this review because the user must confirm the rendered palette, type, contrast, and overall result.

References: skills/…/onboarding.md• L15-40 skills/…/onboarding.md• L54-70 skills/…/onboarding.md• L103-113 skills/…/onboarding.md• L117-139 skills/…/onboarding.md• L143-166 skills/…/onboarding.md• L362-368

Deliverable selection

The deliverable is selected from its destination and its reader before the diagram is redrawn. Four output dials control the result: format selects the asset, size selects the frame and type scale, detail selects how much source content survives, and audience selects the wording. See Diagram Design for wider design rules and Diagram taxonomy and semantics for how meaning is organized.

Output dials

The request should resolve choices that can change the result. Ask one concise question when an unresolved choice matters. If the user gives no choice, use the defaults and state them.

DialMain questionChoicesDefault
FormatWhere will the file go?html, svg, png, html+pnghtml
SizeHow large is the canvas and how far away is the reader?Document, slide, social, print, or content-fit presetsdoc-inline
DetailHow much of the source survives?faithful, balanced, simplifiedbalanced
AudienceWhat wording does the reader need?engineer, mixed, executivemixed

These dials are separate. A smaller canvas may need less detail, while the audience changes names and labels without changing the facts. The workflow does not invent content to fill a simpler deliverable.

References: skills/…/output-spec.md• L1-12 skills/…/output-spec.md• L16-25 skills/…/output-spec.md• L84-92 skills/…/output-spec.md• L116-137

Destination mapping

The destination gives a starting point for format and size because it sets the reader's viewing conditions. An explicit user request overrides that starting point.

DestinationPreferred formatSize or scale
Blog, README, or documentation sitehtml embed or pngdoc-inline
Keynote, PowerPoint, or Google Slidespngslide-16x9 at scale 2
Figma, Illustrator, or later editingsvgfit
X, LinkedIn, or an OG link cardpngsocial-og at scale 2
Printed handout or PDF deckpngprint-a4-landscape at scale 3
Confluence, Notion, or an internal wikipngdoc-wide at scale 2

The size preset owns the viewBox, safe area, and type ramp. If the selected detail does not fit at a readable scale, lower the detail or split the result into overview and detail diagrams. Do not solve the problem by shrinking the text.

References: skills/…/output-spec.md• L27-37 skills/…/output-spec.md• L40-80 skills/…/output-spec.md• L94-110

Import fidelity

An import preserves the source's meaning rather than its old coordinates, colors, fonts, or renderer quirks. The redraw keeps the components, relationships, grouping, and direction that carry the story. It does not add components to fill space or silently remove source content.

When the selected detail level shows fewer elements than the source, the workflow reports a fidelity ledger. The ledger identifies merged duplicates, collapsed groups, dropped infrastructure, and the main path that remains. This makes the smaller deliverable clear to the person who supplied the source.

References: skills/…/output-spec.md• L101-112 skills/…/output-spec.md• L154-166

Output contract

Every diagram has one source artifact and predictable derived assets. The HTML file is the source of truth because it carries the page shell, inline SVG, CSS, and font links. SVG and PNG are views of that source and must not become hand-authored replacements. See Diagram animation for motion constraints and Diagram self-validation for review of the finished output.

Self-contained HTML

The normal deliverable is one .html file that works in a modern browser without local image files or a JavaScript build step. It contains embedded CSS and an inline SVG. External resources are limited to approved Google Fonts links. The diagram is static unless the user asks for motion, and motion must keep the full meaning without JavaScript.

The page can use a presentation form that matches its setting:

FormPurpose
Minimal lightDefault screenshot-ready diagram
Minimal darkDark-ground document, slide, or post
Full editorialHero diagram with header, summary cards, and footer
TerminalCLI-window treatment for a developer-tool post; not brand-tokenized
SketchyOptional hand-drawn treatment for an informal setting

The diagram normally sits on the page ground. A frame is optional. Summary cards use varied widths with borders instead of shadows. A legend belongs in a horizontal strip below the diagram so it does not compete with the working area.

References: skills/…/SKILL.md• L504-527 skills/…/SKILL.md• L559-567 skills/…/template.html• L1-86 skills/…/template-full.html• L69-83

Accessible SVG figure

The inline SVG is an accessible figure, not only a painted canvas. Its name and short description tell a non-visual reader the subject and the main relationship shown by the diagram.

The SVG contract requires:

  • role="img" on the SVG.
  • aria-labelledby that points to its title and description.
  • A non-empty <title> as the first SVG child.
  • A non-empty one-sentence <desc> that explains the diagram rather than listing shapes.
  • IDs prefixed with the diagram slug and variant, such as <slug>-title and <slug>-desc.
  • aria-hidden="true" for decorative-only SVGs.

The stable prefix prevents two diagrams on one page from using the wrong accessible name. The title stays short and close to the page heading, while the description states the relationship a reader needs to understand.

References: skills/…/SKILL.md• L569-578 skills/…/template.html• L61-64 skills/…/template-full.html• L176-181

Asset names and variants

A stable diagram slug identifies the source and its accessible IDs. A variant suffix distinguishes light, dark, full editorial, or terminal output within the same deliverable family. The HTML keeps the source name, and an export beside it uses the same base name with an .svg or .png extension.

The gallery is not an export source because it contains several diagrams. Decorative icon specimens are also not diagram deliverables. Export one specific diagram HTML file instead.

References: skills/…/SKILL.md• L504-519 skills/…/export.md• L19-25 skills/…/export.md• L94-97 skills/…/export.md• L124-129

SVG and PNG exports

Export is a separate action that extracts or renders the diagram from the original HTML without changing that source. The exported SVG or PNG contains the diagram only. Page headers, cards, and footers stay in the HTML source.

SVG keeps vector text and the accessible title and description, although offline tools may substitute fonts. PNG renders the original HTML in a browser and uses the selected scale. The export command defaults to both SVG and PNG at PNG scale 2. It can emit one image format, use scale 1, 2, or 3, write to an explicit base path, or emit a registry metadata sidecar.

The registry is independent of image rendering. A registry-only call writes only the JSON sidecar and does not need Playwright. When an image is requested, missing Playwright stops PNG export with the install instruction rather than triggering an automatic install. The command also refuses a missing source, the gallery, an HTML file without an SVG, an invalid scale, and a registry request without block IDs.

The export flow is:

flowchart LR
    A[Specific diagram HTML] --> B{Requested output}
    B -->|SVG| C[Extract diagram SVG]
    B -->|PNG| D[Render original HTML]
    B -->|Registry| E[Read block metadata]
    C --> F[Report path and size]
    D --> F
    E --> F

References: commands/export-diagram.md• L12-40 prompts/export-diagram.md• L6-35 skills/…/export.md• L1-70

Change checklist

When these files or sections are changed, remember to consider these:

  • If the first-run gate or profile resolution changes, keep URL, skill, folder, manual, default, saved-profile, and pristine-guide snapshot paths consistent.
  • If a size preset changes, update its viewBox, safe area, type ramp, and destination guidance together.
  • If a detail rule changes, keep the node budget, degrade ladder, split naming, and fidelity ledger aligned.
  • If an asset variant or slug rule changes, update template names, accessible IDs, example names, and export naming as one contract.
  • If the HTML source contract changes, check that SVG extraction still preserves accessibility and that PNG capture still uses the original HTML.
  • If export flags or defaults change, keep the slash command, prompt, and export reference aligned on defaults, mutual exclusions, and refusal cases.
  • If registry output changes, keep its block-ID requirement and registry-only behavior separate from Playwright-based image export.

Important failure modes

TriggerConsequenceGuard
A new project skips the style gateA branded project receives the default skinResolve the marker or profile and ask before changing a pristine guide
A material output dial stays unclearThe layout or wording fits the wrong destinationAsk one concise question or state the defaults used
A remote source is fetched without trust confirmationUnapproved external content enters the onboarding processPause before network access and ask the user to confirm the URL
A large source is forced into a small presetText becomes hard to read and the story is lostLower detail or split into overview and detail files
A redraw copies source coordinates or renderer quirksThe result keeps poor layout instead of design intentExtract meaning and redraw against the chosen design system
Labels or accessible IDs remain placeholders or bareReaders lose diagram context and multiple SVGs can conflictReplace the slug and fill the first-child title and description
PNG export runs without browser supportThe image uses substitute fonts or the command changes the systemCheck Playwright first and let the user install it
The gallery or a file without an SVG is exportedThe wrong or no asset is writtenRefuse the request and ask for one specific diagram HTML file
Registry export has no block IDsThe metadata sidecar would be empty or incompleteRefuse the request and write no registry file
Registry-only export checks for PlaywrightA metadata request fails on a host without browser supportTreat registry output as independent from image rendering

Key files

FileWhy to read it
skills/…/onboarding.mdExplains how a website, installed skill, or local folder becomes a reviewed diagram skin
skills/…/output-spec.mdDefines format, size, detail, audience, destination mapping, and fidelity reporting
skills/…/export.mdDefines diagram-only SVG and PNG export behavior, sizing, and refusal cases
skills/…/export-registry.mdDefines the metadata sidecar and its separate export path
skills/…/SKILL.mdDefines the wider style gate, source-of-truth rule, variants, and accessibility contract
skills/…/template.htmlShows the minimal HTML shell and accessible inline SVG figure
skills/…/template-full.htmlShows the editorial page shape with optional frame, cards, and footer
commands/export-diagram.mdDefines the user-facing export command, defaults, flags, and refusal cases
prompts/export-diagram.mdKeeps the export prompt aligned with the command and skill location rules