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:
- Read or fetch the selected source after any required trust confirmation.
- Extract color and type signals.
- Map the signals to semantic roles.
- Check contrast and other skin constraints.
- Show the proposed style-guide change and confidence details.
- Apply the change after approval.
- Offer to save the result as a named profile.
- 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.
| Dial | Main question | Choices | Default |
|---|---|---|---|
| Format | Where will the file go? | html, svg, png, html+png | html |
| Size | How large is the canvas and how far away is the reader? | Document, slide, social, print, or content-fit presets | doc-inline |
| Detail | How much of the source survives? | faithful, balanced, simplified | balanced |
| Audience | What wording does the reader need? | engineer, mixed, executive | mixed |
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.
| Destination | Preferred format | Size or scale |
|---|---|---|
| Blog, README, or documentation site | html embed or png | doc-inline |
| Keynote, PowerPoint, or Google Slides | png | slide-16x9 at scale 2 |
| Figma, Illustrator, or later editing | svg | fit |
| X, LinkedIn, or an OG link card | png | social-og at scale 2 |
| Printed handout or PDF deck | png | print-a4-landscape at scale 3 |
| Confluence, Notion, or an internal wiki | png | doc-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:
| Form | Purpose |
|---|---|
| Minimal light | Default screenshot-ready diagram |
| Minimal dark | Dark-ground document, slide, or post |
| Full editorial | Hero diagram with header, summary cards, and footer |
| Terminal | CLI-window treatment for a developer-tool post; not brand-tokenized |
| Sketchy | Optional 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-labelledbythat 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>-titleand<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
| Trigger | Consequence | Guard |
|---|---|---|
| A new project skips the style gate | A branded project receives the default skin | Resolve the marker or profile and ask before changing a pristine guide |
| A material output dial stays unclear | The layout or wording fits the wrong destination | Ask one concise question or state the defaults used |
| A remote source is fetched without trust confirmation | Unapproved external content enters the onboarding process | Pause before network access and ask the user to confirm the URL |
| A large source is forced into a small preset | Text becomes hard to read and the story is lost | Lower detail or split into overview and detail files |
| A redraw copies source coordinates or renderer quirks | The result keeps poor layout instead of design intent | Extract meaning and redraw against the chosen design system |
| Labels or accessible IDs remain placeholders or bare | Readers lose diagram context and multiple SVGs can conflict | Replace the slug and fill the first-child title and description |
| PNG export runs without browser support | The image uses substitute fonts or the command changes the system | Check Playwright first and let the user install it |
| The gallery or a file without an SVG is exported | The wrong or no asset is written | Refuse the request and ask for one specific diagram HTML file |
| Registry export has no block IDs | The metadata sidecar would be empty or incomplete | Refuse the request and write no registry file |
| Registry-only export checks for Playwright | A metadata request fails on a host without browser support | Treat registry output as independent from image rendering |
Key files
| File | Why to read it |
|---|---|
| skills/…/onboarding.md | Explains how a website, installed skill, or local folder becomes a reviewed diagram skin |
| skills/…/output-spec.md | Defines format, size, detail, audience, destination mapping, and fidelity reporting |
| skills/…/export.md | Defines diagram-only SVG and PNG export behavior, sizing, and refusal cases |
| skills/…/export-registry.md | Defines the metadata sidecar and its separate export path |
| skills/…/SKILL.md | Defines the wider style gate, source-of-truth rule, variants, and accessibility contract |
| skills/…/template.html | Shows the minimal HTML shell and accessible inline SVG figure |
| skills/…/template-full.html | Shows the editorial page shape with optional frame, cards, and footer |
| commands/export-diagram.md | Defines the user-facing export command, defaults, flags, and refusal cases |
| prompts/export-diagram.md | Keeps the export prompt aligned with the command and skill location rules |