Why Good Diagrams Delete Almost Everything
For Diagram Design, the specific problem is not how to make a canvas look full; it is how to make each remaining mark carry a readable piece of meaning. This chapter examines the system's remove test, focal hierarchy, semantic tokens, typography, geometry, and accessible SVG contract so a reader can inspect a figure and tell whether its restraint clarifies the subject or merely leaves information out.
Deletion is a test of meaning
A generic diagram usually fails before anyone debates its colors. It starts with an inventory: a client, a service, a database, perhaps a queue, followed by a line between anything that seems related. Because the inventory is easy to count, the result can feel complete. Yet the reader still has to decide which component is central, which connection changes the outcome, and which marks are only repeating what position already says.
Diagram Design reverses that order. Its philosophy says that every node should represent a distinct idea and every connection should add information. Two nodes that always travel together may be one node. A relationship that is obvious from the arrangement may not need a line. The question is not “What else can be included?” but “What can be removed without damaging the explanation?”
That is a semantic test, not a preference for empty space. Imagine an order platform with a browser, a mobile client, an API gateway, an authentication service, an order service, and three data stores. A one-to-one drawing can preserve all eight names and still obscure the request path. If the main question is how a request enters, is authenticated, and becomes an order record, a logging bucket or a secondary cache may not deserve equal visual weight. Removing them can make the gateway, authentication decision, order write, and primary store easier to follow. If the question is instead how observability works, the same supposedly peripheral components become central and the figure should change. Deletion depends on the question the diagram is answering.
The repository makes this decision concrete with a target density of 4/10 and a normal overview budget of no more than nine nodes and 12 arrows. These are house rules, not universal laws of perception. Their purpose is to force an author to decide whether one canvas is still a coherent explanation. When the content exceeds the budget, the recommended remedy is an overview plus a detail diagram, not eight-point text, a rainbow of treatments, or a nest of lines. A split preserves legibility by giving each figure a narrower claim.
The same rule explains why the system says not to draw when a paragraph, table, or list would do the job better. A list of technologies does not become a relationship merely because each item sits in a rectangle. A before-and-after comparison may need two columns and a few words, not an invented flow. A one-shape “diagram” is often a sentence with a border. The visual medium is justified only when spatial arrangement lets the reader see something that a linear form would hide.
Focal hierarchy is a scarce resource
Once unnecessary material has been removed, the next danger is treating all remaining material as equally important. Diagram Design reserves its accent color for one or two focal elements. In an architecture figure, that might be the integration point or the store that makes the story consequential. In a flowchart, it might be the decisive branch or the happy path. In a chart, it might be one series or one bar. The exact focal object varies with the subject, but the scarcity rule does not.
If five nodes are coral, coral stops being a focal signal and becomes a category color. The reader cannot know whether the color means “important,” “new,” “secure,” “failed,” or simply “the author had five colors available.” Diagram Design therefore uses a mostly neutral ink ramp and asks the author to name the one or two things that deserve the first glance. A legend can explain a treatment, but it cannot rescue a figure whose hierarchy is undecided.
This is also why shape should carry type where shape is the truthful channel. A flowchart uses an oval for start or end, a rectangle for an action, a diamond for a decision, and a small dot for a merge. Color does not replace those distinctions. A decision diamond with four exits is not made clearer by assigning each exit a different hue; it needs to be refactored into smaller decisions. Similarly, a state machine labels transitions with the event, guard, or action that causes movement. A red state without a transition trigger is a warning sign, not an explanation.
Focal scarcity changes how the system handles optional detail. A technical sublabel can name a protocol, port, field type, or URL when that detail changes the reader's decision. It should not be added to every box merely to make the figure look authoritative. An annotation can add an editorial aside, but it belongs in the margin, uses a distinct italic serif voice, and is limited in number. The visual hierarchy remains in the diagram; commentary does not become a second diagram inside it.
The result is a useful distinction between completeness and coverage. A figure can contain every component named in a source and still fail to cover the relationship that matters. Conversely, a smaller figure can be more complete with respect to its stated question if every remaining mark participates in the explanation. Diagram Design's budgets are an attempt to make that distinction unavoidable.
Semantic tokens turn taste into roles
Visual consistency becomes fragile when each diagram author chooses colors directly. One author uses orange for a focal service, another uses it for an error, and a third uses it for an external system. Diagram Design's style guide therefore names semantic roles instead of asking type references to scatter literal color values through their examples. The roles include paper for the page, ink for primary text and strokes, muted and soft for secondary information, rule for hairlines, accent for focal elements, and link for HTTP or external calls.
The point is not that a particular orange is inherently meaningful. Meaning comes from a stable assignment. A focal node receives an accent tint and accent stroke. A backend or ordinary step remains neutral. A store or state uses a quiet ink wash. An external system has a lighter treatment and weaker boundary. Optional or asynchronous elements may use a dashed, low-emphasis treatment. Security boundaries can use a dashed accent family, but the boundary still needs labels and route semantics; color alone cannot declare that a path is trusted.
This role system also makes a dark variant possible without changing the diagram's logic. Paper and ink invert, muted values are adjusted, and the accent becomes brighter, but a focal node is still focal and a technical label is still technical. A brand can replace the semantic tokens through onboarding later, yet the type grammar need not be rewritten. The repository's design system is therefore less like a paint box than a vocabulary for visual responsibility.
A constraint follows from that vocabulary: a brand with eight colors is not invited to use all eight. The guide asks the author to retain a paper, ink, accent, and a restrained set of secondary roles. A “no rainbow” rule protects the same hierarchy as the one-accent rule. If every concern receives a unique hue, the reader has to decode a legend before they can read the structure.
Typography gives each kind of information a register
Diagram Design uses three typographic registers because a name, a technical value, and an editorial aside are different kinds of information. Human-readable node names use a sans face. Ports, protocols, URLs, field types, and other compact technical values use a mono face. The page title and marginal callouts use an Instrument Serif treatment that marks a different editorial voice.
This is not a general rule that technical work should look like a terminal. In the default system, mono is deliberately limited. Writing “Orders Service” in a mono face would make the service name look like a command or identifier. Writing TLS:5432 in a display serif would make a protocol look like prose. The register tells the reader how to interpret a string before they have parsed every character.
The same discipline applies to labels that are easy to over-compress. A technical sublabel is useful when it distinguishes two otherwise similar components or exposes a real interface. It is noise when every node receives a port, version, and implementation note. If the name will not fit, the system's answer is to shorten the name, move to a detail diagram, or change the audience dial—not to shrink the type until the figure is technically present but practically unreadable.
Non-Latin text makes this trade-off visible. The default Latin families do not cover Hangul or Han, so the guide specifies language-appropriate fallbacks and a 12px floor for those names. It also changes the treatment of small eyebrow, arrow, and legend labels when they contain CJK text, because a tiny tracked mono label is not a neutral container that every script can fill. The larger principle is simple: typography is part of the meaning budget. A label that cannot be read has not been preserved.
Geometry is part of the explanation
A diagram's geometry is often dismissed as polish because the underlying nouns and verbs remain in the file. But a reader follows spatial relationships, and a small routing error can change the apparent relationship. Diagram Design consequently makes geometry unusually explicit.
The four-pixel grid governs coordinates, dimensions, gaps, and most font sizes. The grid is not a magical guarantee of good composition, but it limits the accidental drift that makes generated layouts feel unstable. More important are the connector rules. Off-axis connections use rounded right-angle elbows rather than diagonal slants. Labels receive opaque masks so a line does not cut through their text, and the mask must remain visibly separated from the connector. Multiple lines entering one edge of a box use separate attach points. Connectors cannot overlap or pass behind an unrelated box as a shortcut. Arrows are drawn before boxes so the box fill caps the line cleanly.
Consider a label placed near the edge of a service box. If its mask overlaps a node that is painted later in the SVG, the node fill can cover part of the label. The source file still contains the complete text, and a structural linter may still find the expected elements, but the rendered reader sees a fragment sitting on a border. The repository's label-geometry decision record describes exactly this kind of defect: existing gates had passed because they checked colors, fonts, and accessible structure, not the interaction of coordinates and paint order. The response was to make the rule explicit and add a geometric checker with adversarial cases.
That history reveals why the system distinguishes source-level validity from rendered validity. An SVG can be well formed and still paint badly. A connector can have the right endpoints and still be unreadable because it overlaps another path. A mask can be correctly opaque and still be in the wrong place. Geometry is not an after-the-fact beautification pass; it is part of preserving the relation the diagram claims to show.
The relationship in this model matters more than the individual rules. Tokens establish the intended hierarchy; typography keeps categories of information distinct; geometry preserves traceability; accessibility makes the resulting meaning available beyond the visual channel. None of these layers can substitute for the others. A high-contrast diagram with tangled arrows is still hard to read. A beautifully routed diagram with no accessible name is still incomplete.
Accessibility is part of the default artifact
The repository makes every diagram SVG an accessible figure unless it is genuinely decorative. The SVG carries role="img" and an aria-labelledby relationship to a short title and a description. The title is the first child, before definitions, because assistive technology may not reliably find it later. IDs are prefixed by the diagram and variant, so two inline figures do not accidentally resolve to the same title or description. The description explains the content and relationships a reader needs, rather than narrating that one box sits above another.
This contract changes how an author thinks about visual shorthand. If a flow is meaningful only because one line is red, it is not robust enough. The system asks for text, shape, count, outline, or pattern alongside color. A queue can show a numeric count. A policy trace can write PASS, FAIL, SKIPPED, or NOT REACHED. A focal mark can have a distinct stroke and position. These redundant signals help screen-reader users, people viewing a grayscale printout, and readers with color-vision differences.
Accessibility also limits decorative enthusiasm. Icons are marked as hidden when they are specimen or decoration, rather than adding meaningless labels to the accessibility tree. A full editorial wrapper may include summary cards, but the SVG itself still needs to describe the diagram's actual content. The figure cannot outsource its meaning to a surrounding heading that disappears when the SVG is exported.
Where automation stops
The design rules become valuable when they can be checked, but a passing gate is not the same as a good explanation. A linter can detect a missing title, a forbidden shadow, an unsafe script, or a label mask that collides with a later node. A renderer can reveal clipping, overflow, collapsed SVGs, or missing assets. It cannot decide whether the selected focal node is the one a reader should notice, whether a relationship is important enough to draw, or whether the whole subject should have been a table.
The repository is candid about this boundary. Its density target, node ceilings, spacing values, and contrast requirements are house policies designed for repeatable authoring, not a published usability study. Even its own current style guide notes that some pre-baked examples were built under an earlier skin. That does not invalidate the current system; it means a careful reader should distinguish a rule from a measured outcome and a current template from every historical specimen.
The practical inspection therefore has two passes. First ask whether the figure's story is coherent: what is the subject, what is focal, and what would be lost if a node or line disappeared? Then ask whether the artifact preserves that story technically: can the eye trace the connectors, can assistive technology name the SVG, and does the rendered output match the authored geometry? Automation strengthens the second pass and disciplines the first, but it does not eliminate judgment.
The deepest lesson of Diagram Design's visual rules is consequently not “make diagrams sparse.” It is “make the claim narrow enough that every mark can support it.” Once the author has made that claim explicit, the next decision becomes possible: is the figure about a behavior, a structure, a quantity, a state, or some other relationship? That is where meaning must be chosen before shape.