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-style-and-primitives

Diagram style and visual primitives

The diagram style system gives generated figures a shared visual language while allowing a project or client to choose a different skin. It combines semantic color and type roles with optional treatments for terminal screens, hand-drawn figures, icons, and editorial notes.

Style system

The style system is the visual contract for color, type, borders, spacing, node treatment, and backgrounds. Diagram guidance uses roles such as paper, ink, muted, and accent rather than fixed colors, so a skin can change without changing the meaning of the diagram.

The default skin uses a cool editorial palette. It uses clean paper for the page, dark ink for primary content, one accent for the focal signal, and muted tones for support content. A small series palette is reserved for chart types that must compare several overlapping series.

ConcernSystem rule
BackgroundClean paper is the default. Dotted paper and framed containers are opt-in.
EmphasisUse accent for one or two focal elements. Use size, weight, or position for other emphasis.
TextUse serif for titles and editorial asides, sans for names, and mono for technical labels.
ShapeUse a small stroke and radius scale with a four-unit alignment grid.
ConnectionsUse muted arrows for normal flow, accent arrows for highlighted flow, link blue for HTTP/API or external calls, and dashed strokes for passive or async relations.
AccessibilityText roles must meet contrast needs for their actual background. Essential marks must remain visible without color alone.
Font sourceUse web fonts by default or system-font mode when output must work without a network request.

Semantic roles carry meaning as well as appearance. A focal node receives the accent treatment, while stores, external systems, inputs, optional elements, and security boundaries use distinct low-contrast or dashed treatments.

Typography keeps content types distinct. Human-readable names use sans, technical values use mono, and titles and callouts use serif. The same role split applies in system-font mode.

References: skills/…/style-guide.md• L1-5 skills/…/style-guide.md• L11-31 skills/…/style-guide.md• L33-65 skills/…/style-guide.md• L185-211

Language-aware typography

Language-aware typography keeps labels readable without changing the visual skin. Korean and Han names use a readable sans treatment with a minimum size. Cyrillic labels keep the normal role treatment because the main sans and mono families support them.

The width budget counts each character. Wide characters and full-width punctuation take a full em, Latin characters use the face's normal advance, and marks take no width. Printed Cyrillic labels keep their exact source text rather than being transliterated or re-cased.

Technical sublabels stay Latin and mono. Korean and Han names do not shrink below the readable size floor. Labels in small arrow, eyebrow, or legend slots switch to a larger sans treatment instead. Cyrillic names and technical labels keep the normal role treatment.

References: skills/…/style-guide.md• L125-181

Client profiles

Client profiles preserve a complete visual skin outside the installed skill. They let several projects use separate skins while keeping each project's effective style guide isolated from managed updates.

Profile selection

The effective style guide is the profile or working copy selected for the current generation. A project marker named .diagram-design can select a saved profile directly, so parallel projects do not overwrite one shared working copy.

Profile conceptPurpose
Profile libraryStores named profiles under ~/.diagram-design/profiles/.
Working copyHolds the install-local style guide when no project marker controls selection.
Project markerBinds one project to a valid profile slug.
default profileRecovery copy of the pristine shipped style guide.
Effective style guideThe skin used for one diagram generation.

Profile files contain the full style guide and display metadata. Save and load preserve the style body, while structural checks can fill missing roles from current shipped defaults when an older profile is used. The profile library is separate from the installed plugin, so updates do not erase named client skins.

References: skills/…/profiles.md• L7-23 skills/…/profiles.md• L25-47 skills/…/profiles.md• L65-106

Skin onboarding

Skin onboarding turns a website, installed design skill, or local design-system folder into a proposed semantic skin. It extracts colors and font roles, checks contrast and palette limits, shows the change before writing it, and can save the result as a named profile.

The onboarding flow keeps the diagram grammar stable. It changes the visual skin, not the semantic meaning of a node or connection, and keeps the serif, sans, and mono contrast when a brand provides only one font family.

References: skills/…/onboarding.md• L15-38 skills/…/onboarding.md• L64-125 skills/…/onboarding.md• L312-314

Terminal primitive

The terminal primitive is an optional full-page CLI skin for diagrams about developer tools, command-line workflows, or technical social cards. It wraps the figure in a dark terminal window with title-bar chrome, a prompt, and a mono-only text register.

The terminal skin is fixed and self-contained. It does not inherit client onboarding or the default light/dark palette, so it is a deliberate presentation mode rather than a layer combined with a brand skin.

ElementVisual role
Page and windowCharcoal surfaces replace ordinary paper.
Title barProvides terminal chrome with three dots. One dot uses the accent.
PromptMakes the command-line context clear. The prompt sign uses the accent.
Diagram bodyUses terminal equivalents of paper, ink, muted, soft, and accent roles.
TypographyUses mono for all text and raises the normal type scale for feed-size viewing.

Use this primitive for a CLI launch or developer-focused card. Do not use it for editorial long-form work or brand-matched output.

References: skills/…/primitive-terminal.md• L1-5 skills/…/primitive-terminal.md• L48-64 skills/…/primitive-terminal.md• L66-76 skills/…/style-guide.md• L67-83

Sketchy primitive

The sketchy primitive adds a restrained hand-drawn register without changing the diagram layout. It slightly displaces shapes and paths so a minimal figure can read as a working sketch or editorial figure.

The treatment applies only to shapes and paths. Text stays outside the filtered group so labels remain crisp. Low displacement supports a quiet editorial feel; high displacement makes the structure hard to read.

Use it for essays, blogs, newsletters, or figures that represent an idea in progress. Avoid it in technical documentation and dense layouts unless the rendered result has been checked.

References: skills/…/primitive-sketchy.md• L1-5 skills/…/primitive-sketchy.md• L24-34 skills/…/primitive-sketchy.md• L36-43

Icon primitive

The icon primitive provides a monochrome vocabulary for common people, compute, network, data, Kubernetes, action, DevOps, brand, and data-stack concepts. It gives familiar actors or systems a consistent symbol without changing the diagram grammar.

Icons share a 24×24 view and inherit currentColor from the parent SVG. Generic icons use strokes, while brand silhouettes use filled shapes. The node label remains the source of meaning because an icon identifies a category, not the full behavior of a component.

Choose an icon when it adds fast recognition to a node. The catalog includes generic concepts and named technologies with source and license notes beside each entry.

References: skills/…/primitive-icons.md• L1-9 skills/…/primitive-icons.md• L11-20 skills/…/primitive-icons.md• L67-103 skills/…/primitive-icons.md• L179-251 skills/…/primitive-icons.md• L430-502

Annotation primitive

The annotation primitive adds a short editorial aside that points to a detail without becoming part of the main diagram grammar. It uses italic serif text with a dashed leader and a small landing dot, which separates the note from normal labels and solid flow arrows.

Place callouts in an open margin and limit them to two per diagram. Use a neutral, focal, or muted color by intent. Do not use a callout for an element that should have its own direct label.

References: skills/…/primitive-annotation.md• L1-16 skills/…/primitive-annotation.md• L18-36 skills/…/style-guide.md• L89-98

Primitive selection

Visual primitives are presentation choices layered onto a semantic diagram type. Select the type and semantic pattern first, then add only the treatment that helps the intended audience read the figure.

NeedPrimitive or style
Shared branded lookSemantic style roles or a client profile
Command-line or developer-tool contextTerminal skin
Essay or working-sketch feelSketchy filter
Quick recognition of common systems or actorsMonochrome icon
Short marginal explanationAnnotation callout

The default editorial skin is the safe base. Terminal and sketchy variants change the register more strongly, while icons and annotations add local cues without changing the main layout. For diagram type and semantic pattern choices, see Diagram taxonomy and semantic patterns. For motion choices, see Diagram animation. For project entry and deliverable rules, see Diagram onboarding and output. The parent page is Diagram design skill.

References: skills/…/SKILL.md• L65-79 skills/…/SKILL.md• L212-220 skills/…/primitive-terminal.md• L66-76 skills/…/primitive-sketchy.md• L36-43

Change checklist

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

  • Keep semantic role names and typography roles aligned between the style guide, skill guidance, type references, onboarding, profile checks, and the skin linter.
  • Preserve the one-accent rule, contrast targets, clean-paper default, and the distinction between technical mono labels and human-readable sans names.
  • Preserve fallback stacks, the readable size floor for Korean and Han labels, the per-character width budget, and exact printed Cyrillic labels.
  • Preserve marker-first project isolation and recovery through the default profile when profile selection or storage changes.
  • Update terminal role mappings with terminal tokens. Do not make terminal output inherit onboarding by accident.
  • Keep each icon entry's visual style, semantic description, source, and license note together.
  • Keep text outside the displaced shape group when sketchy filtering changes.
  • Preserve the distinction between dashed annotation leaders and solid primary connectors.
  • Keep dotted-paper and framed-container variants opt-in.

Important failure modes

TriggerConsequenceGuard
Several accent colors are usedThe focal signal disappears.Reserve one accent for one or two focal elements.
A project marker names a missing profileThe project can use the wrong skin or fail to resolve its client style.Validate the marker and profile slug. Report a missing profile instead of falling back silently.
A customized style guide overwrites the recovery copyThe shipped recovery skin is lost.Create or verify the pristine default profile before destructive changes.
A Korean or Han label is forced into a tiny mono slotThe label becomes muddy or unreadable.Keep technical sublabels Latin and use the readable sans register with its size floor for localized names.
A printed Cyrillic label is transliterated or re-casedThe label no longer matches the physical item or source record.Preserve the exact printed string.
Text is placed inside the sketchy filterLabels become warped and hard to read.Filter shapes only and keep text in a sibling group.
Terminal skin is mixed with onboarded brand tokensThe output loses the fixed terminal register.Treat terminal as a separate opt-in skin.
An annotation leader looks like a flow arrowReaders may interpret commentary as system behavior.Use a dashed leader, landing dot, and margin placement.

Key files

FileWhy to read it
skills/…/style-guide.mdDefines semantic tokens, typography, geometry, node treatments, language rules, and skin limits.
skills/…/profiles.mdDefines named client skins, project selection, profile storage, and recovery behavior.
skills/…/onboarding.mdExplains how an external design source becomes a semantic diagram skin.
skills/…/primitive-terminal.mdDefines the fixed terminal-window presentation and its use boundaries.
skills/…/primitive-sketchy.mdDefines the hand-drawn treatment and its legibility limits.
skills/…/primitive-icons.mdProvides the reusable icon vocabulary and source notes.
skills/…/primitive-annotation.mdDefines editorial callouts and how they differ from primary diagram connections.
skills/…/SKILL.mdConnects the style system and optional primitives to diagram selection and production.