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.
| Concern | System rule |
|---|---|
| Background | Clean paper is the default. Dotted paper and framed containers are opt-in. |
| Emphasis | Use accent for one or two focal elements. Use size, weight, or position for other emphasis. |
| Text | Use serif for titles and editorial asides, sans for names, and mono for technical labels. |
| Shape | Use a small stroke and radius scale with a four-unit alignment grid. |
| Connections | Use 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. |
| Accessibility | Text roles must meet contrast needs for their actual background. Essential marks must remain visible without color alone. |
| Font source | Use 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 concept | Purpose |
|---|---|
| Profile library | Stores named profiles under ~/.diagram-design/profiles/. |
| Working copy | Holds the install-local style guide when no project marker controls selection. |
| Project marker | Binds one project to a valid profile slug. |
default profile | Recovery copy of the pristine shipped style guide. |
| Effective style guide | The 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.
| Element | Visual role |
|---|---|
| Page and window | Charcoal surfaces replace ordinary paper. |
| Title bar | Provides terminal chrome with three dots. One dot uses the accent. |
| Prompt | Makes the command-line context clear. The prompt sign uses the accent. |
| Diagram body | Uses terminal equivalents of paper, ink, muted, soft, and accent roles. |
| Typography | Uses 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.
| Need | Primitive or style |
|---|---|
| Shared branded look | Semantic style roles or a client profile |
| Command-line or developer-tool context | Terminal skin |
| Essay or working-sketch feel | Sketchy filter |
| Quick recognition of common systems or actors | Monochrome icon |
| Short marginal explanation | Annotation 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
defaultprofile 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
| Trigger | Consequence | Guard |
|---|---|---|
| Several accent colors are used | The focal signal disappears. | Reserve one accent for one or two focal elements. |
| A project marker names a missing profile | The 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 copy | The 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 slot | The 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-cased | The label no longer matches the physical item or source record. | Preserve the exact printed string. |
| Text is placed inside the sketchy filter | Labels become warped and hard to read. | Filter shapes only and keep text in a sibling group. |
| Terminal skin is mixed with onboarded brand tokens | The output loses the fixed terminal register. | Treat terminal as a separate opt-in skin. |
| An annotation leader looks like a flow arrow | Readers may interpret commentary as system behavior. | Use a dashed leader, landing dot, and margin placement. |
Key files
| File | Why to read it |
|---|---|
| skills/…/style-guide.md | Defines semantic tokens, typography, geometry, node treatments, language rules, and skin limits. |
| skills/…/profiles.md | Defines named client skins, project selection, profile storage, and recovery behavior. |
| skills/…/onboarding.md | Explains how an external design source becomes a semantic diagram skin. |
| skills/…/primitive-terminal.md | Defines the fixed terminal-window presentation and its use boundaries. |
| skills/…/primitive-sketchy.md | Defines the hand-drawn treatment and its legibility limits. |
| skills/…/primitive-icons.md | Provides the reusable icon vocabulary and source notes. |
| skills/…/primitive-annotation.md | Defines editorial callouts and how they differ from primary diagram connections. |
| skills/…/SKILL.md | Connects the style system and optional primitives to diagram selection and production. |