Choose the Meaning Before the Shape
The important choice in Diagram Design happens before a box, line, or circle appears. This chapter focuses on the system's separation between semantic patterns and visual types: first identify the behavior or relationship a reader must understand, then choose the layout grammar that can express it without making a stronger claim than the evidence allows. That sequence gives a reader a practical way to select a diagram and recognize a convincing-looking mismatch.
A pattern describes behavior; a type arranges information
A visual type answers a layout question. Should components sit in zones? Should messages descend between lifelines? Should states connect through guarded transitions? Should values be compared along an axis? A semantic pattern answers a different question: what is the system doing, and what behavior must remain visible even when the figure is simplified?
That distinction matters because ordinary shapes are poor at carrying behavior by themselves. A rectangle can stand for a service, a step, a store, or a team. A dashed line can mean an optional path, an asynchronous message, a security boundary, or a visual connector that happens to be secondary. The same visual vocabulary can support very different explanations. Diagram Design therefore asks the author to name the behavior first when behavior, state, enforcement, risk, or traceability is load-bearing.
The repository currently describes eight such patterns. They cover situations such as many sources competing for finite capacity, repeated semantic slots across stages, loose conversation becoming a durable record, two policy traces diverging, routes crossing a trust boundary, controls grouped by enforcement surface, defenses that leave residual risk, and a hierarchy whose blocks need stable identifiers and implementation links. These are not eight new canvases. They are eight ways to decide what a static figure must show.
A fan-in queue pattern, for example, cannot be satisfied by drawing several arrows into an ordinary processing box. The reader needs distinct sources, visible queue slots or a count, the service capacity, and both admitted and deferred or rejected outcomes. Without those elements, the picture may show convergence but not contention. A paired policy trace similarly needs the same ordered rules on both sides, explicit statuses such as PASS, FAIL, SKIPPED, and NOT REACHED, and a marker for the first divergence. Two colored paths would not explain why the outcomes differ.
The selected visual type then supplies the layout grammar. A queue pattern normally routes to Data Flow, while a process-dominated case may use Process. A secure paved road routes to Architecture because the figure is still about components and routes, but the pattern adds trust boundaries, permitted ingress, blocked bypasses, a privileged gate, and an isolated runtime. The pattern supplies meaning-specific requirements; Architecture supplies zones, node treatment, elbow routing, and page structure.
This division prevents two opposite mistakes. The first is to force a behavior into a new type every time the repository encounters a new use case. That would make the catalog grow until its selection guide became another problem. The second is to treat an existing type as a complete semantic answer. It is not enough to say “use Architecture” if the point is which paths are allowed across a trust boundary. The pattern sharpens what the architecture must prove.
A selection decision starts with the reader's question
The practical sequence is short:
The first question should be concrete. “I need an architecture diagram” is a destination or a broad category, not yet a semantic claim. “I need to show why requests with two similar policies receive different outcomes” is a question. It points toward paired policy-evaluation traces and therefore toward a Flowchart layout. “I need to show where an order record lives and which service writes it” points toward an Architecture figure. “I need to show the exact foreign key and deletion behavior in a database” points toward Database Schema.
This approach also helps when several descriptions seem plausible. Suppose a team wants to document a data platform with administrators, engineers, scientists, and consumers. If the reader mainly needs the organizational roles and handoffs, a Swimlane-like process can work. If the reader needs to see typed payloads moving from raw files to tables and reports, Data Flow is a better fit. The subject has not changed; the load-bearing relationship has.
The same logic applies to a request lifecycle. If the important fact is that messages pass between actors in time, use Sequence. If the important fact is the finite set of statuses and the events that move an object between them, use State Machine. If the important fact is a decision with exclusive branches, use Flowchart. Calling all three a “workflow diagram” hides the very distinction the reader needs.
A pattern has its own budget because adding semantic requirements can make a figure dense faster than adding ordinary nodes would suggest. The queue pattern needs room for sources, visible capacity, a bottleneck, and outcomes. The paired trace pattern must show two comparable paths and their statuses. The traceable block pattern adds stable IDs and a metadata record but does not grant permission to exceed the tree's structural limits. The stricter of the pattern and type budgets applies. If both are needed in full, the repository's answer is to split the explanation.
Near-neighbor types make opposite claims
The most reliable way to learn the taxonomy is to compare types that look as if they could substitute for one another. Their differences are not stylistic. Each one binds a different visual property to a different question.
Architecture and Deployment
Architecture explains logical components and their relationships: clients, gateways, services, stores, and the paths between them. Deployment answers where software actually runs. Its zones represent environments or network boundaries; its infrastructure nodes represent hosts, virtual machines, pods, or managed services; its artifact chips identify what is installed and which version is running; replica badges compress repeated copies into one node.
Adding hostnames to an architecture drawing does not make it a deployment diagram. If the figure does not help a reader decide which artifact runs on which host, behind which boundary, at what replica count, the physical details are probably decoration. Conversely, a deployment diagram with unversioned artifact chips omits the reason to care about placement. Diagram Design's type reference makes the boundary explicit because the two figures support different decisions.
ER and Database Schema
An ER or data-model diagram is a conceptual conversation about entities and relationships. Lines join entity boxes and carry cardinality. A physical database schema is a conversation about implementation behavior: SQL types, constraints, indexes, and foreign keys that land on specific column rows. A box-to-box line cannot tell a reviewer which column is referenced or what happens on deletion.
That distinction is especially important when a diagram is used to reason about change. “Customer has orders” is a domain relationship. “Deleting a customer cascades into these rows” is a physical consequence. Substituting one diagram for the other can make a claim appear more precise while leaving the decisive detail unrepresented.
Tree and Dependency Graph
A Tree works when each child has one parent and the hierarchy has no backward edge. Its elbow connectors and parent-to-children structure make a decomposition easy to scan. A Dependency Graph is needed when a node has several parents or when a cycle exists. It ranks nodes by dependency depth and uses fan-in badges to expose concentration. Its one highlighted cycle is not a decorative loop; it is the exceptional dependency that changes the system's risk or maintenance story.
Drawing a shared library as a tree duplicates the library or assigns it to an arbitrary parent, either of which falsifies the structure. Drawing a simple hierarchy as a dependency graph adds machinery without adding information. The selection rule is not “which diagram looks more technical?” It is “does the data obey the structural assumptions of the type?”
Sankey and Waterfall
Quantitative types make the distinction even sharper because geometry itself states a number. A Sankey uses band thickness to show a quantity splitting and merging across a small number of stages. Its flows must conserve the amount at each node; a band that disappears or appears without explanation is not a minor drawing error. A Waterfall shows one sequential running total: a start anchor, signed bridges, optional subtotal, and end anchor. Every bridge must span the two running levels produced by the preceding values.
A narrowing sequence without splits or merges is a funnel or process, not a Sankey. Two endpoints with a meaningful gap may be a dumbbell, not a Waterfall. A Waterfall that does not reconcile is wrong even if its bars look balanced. These boundaries keep a shape from borrowing the authority of an encoding it does not actually implement.
The same principle appears in Treemap and Polar. Treemap area represents a part of a whole, so a small cell cannot simply be enlarged to make its label readable without changing the data. Polar uses one shared linear radius for one series across a meaningful cyclic order; it does not use filled sectors, multiple series, or a non-zero inner baseline to create visual drama. When geometry is the data, “make it look clearer” can be a request to make it less true.
Semantic patterns keep the catalog from exploding
Diagram Design's taxonomy policy follows from this distinction. A new behavior should normally add a pattern and a routing row, not a new layout grammar. This lets the system express a queue, a policy trace, or a governance catalog through an existing type while keeping the type count stable and the selection guide learnable.
A new type is justified only when the arrangement itself is genuinely new. The repository's decision records use this test for Sankey, Fishbone, Wardley Map, Kanban, User Journey, Deployment, Dependency Graph, UML Class, Story Map, Database Schema, Polar, and Waterfall. Each was admitted because an existing layout could not carry its defining relationship: ribbon thickness, angled causes, value chain against evolution, state census without connectors, sentiment across stages, physical placement, multi-parent dependency, typed class relationships, release slices, column-level foreign keys, cyclic angle plus radius, or a conserved running total.
The admission rule also explains why several familiar labels remain covered by existing types. “C4” is treated as a zoom-level convention over Architecture rather than a new geometry. “AI architecture” is a semantic use case over existing component-and-flow layouts. A decision tree is Flowchart. A data-flow diagram is Data Flow. A UML activity diagram can be expressed with Swimlane and Flowchart when those are the actual relationships being shown. The repository is not claiming that every convention is unimportant; it is asking whether the convention changes the visual grammar.
This policy has a practical benefit for readers. They learn a smaller set of layout languages while gaining more precise ways to describe the behavior each figure must carry. It also imposes a responsibility on pattern authors: a pattern cannot merely be a theme or a label. It must say what primitives are required, what a static fallback includes, what anti-patterns would mislead the reader, and where its budget ends.
Traceable block decomposition is a useful boundary case. It needs stable dotted IDs, noun-phrase block names, and per-block inputs, outputs, constraints, assumptions, and implementation paths. Yet it still uses Tree's parent-child structure, and the extra metadata lives on the nodes and in an on-demand registry rather than becoming a second visible grammar. The repository explicitly says this is SysML-informed vocabulary, not formal SysML or IDEF0 conformance. That qualification is part of the design, not an apology after it.
The type tells you what not to draw
A good selection is partly a choice of exclusions. Architecture excludes physical-placement details unless they matter. Deployment excludes logical topology that has no placement decision. A state machine excludes a long narrative sequence. A Journey Map excludes an internal system flow with no person or sentiment. A Story Map excludes state columns and sentiment curves because its rows represent release slices, not workflow status or feelings.
These exclusions protect the reader from mixed grammars. Combining a tree, a timeline, and a dependency graph on one canvas may appear comprehensive, but it makes the meaning of position unstable. A line can no longer be read as time, a hierarchy, or a dependency without a new legend for every local exception. When two full grammars are both necessary, separate figures let each one remain honest.
The final check is therefore not whether the selected type can be made to contain the requested nouns. Almost any type can be filled with nouns. The check is whether its visual encodings, budgets, and omissions support the relationship the reader came to understand. Once that relationship is named, the taxonomy becomes a tool for reasoning rather than a menu of templates.
The next test is to make this choice as a whole: start with a communication problem, select the relationship, choose the pattern and grammar, and then ask whether the result remains within its visual and evidence boundaries. A reader who can do that no longer needs to begin with a familiar shape.