Diagram Design Is a Translation System
cathrynlavery/diagram-design is the subject of this series: a repository that packages an Agent Skill, a visual design system, and the supporting rules for producing technical and product diagrams. The question here is not how to draw one more attractive box. It is how a system can translate meaning into a restrained, branded, accessible artifact without losing the relationship the diagram was meant to reveal. Understanding that translation lets a reader judge when Diagram Design is useful, what its constraints protect, and where its own evidence stops.
The subject is larger than a gallery
The repository is easy to misunderstand because its most visible output is a gallery of diagrams. Open the examples and the immediate impression is visual: pale paper, dark ink, a single orange accent, compact labels, fine lines, and a set of familiar forms. But the gallery is only the visible edge of a larger system.
The underlying package is shared across several agent hosts, including Claude Code, Codex, Factory Droid, and Pi. Its ordinary output is a self-contained HTML file with CSS and inline SVG. That choice matters. A generated figure is not treated as a screenshot trapped in a design tool, nor as a fragment that depends on a project-wide runtime. It is intended to open on its own, be embedded in a document, or become a vector or raster export later. The same subject therefore has to survive several contexts: an agent's generation step, a reader's browser, a slide or document, and an accessibility tree.
The repository's organization reflects this larger purpose. A compact routing document tells the host when the skill is relevant. Separate references describe semantic patterns, visual types, animation, imports, exports, profiles, and primitives. Examples and a gallery make the result inspectable. Contributor documentation and continuous-integration workflows then treat those documents as part of the product rather than as decoration around the code.
There is even a small but instructive inconsistency in the current public surface. The README still describes 39 visual types, while the current skill, contributor guide, decision records, and type-reference set describe 40, with Waterfall as the latest admitted grammar. That disagreement should not become the subject's headline. It does show why a careful reader must distinguish a repository's declared design from a perfectly synchronized public surface. Diagram Design provides strong first-party evidence for what its rules intend; it does not, by that fact alone, prove user adoption, universal readability, or comparative superiority.
The real problem is not a shortage of shapes
The problem that motivated the project is more ordinary and more consequential than a missing diagram primitive. The repository describes a recurring experience: ask an agent for an architecture sketch, a flowchart, or a pyramid, and receive a generic rounded-box composition. The result may contain the requested nouns, yet still fail as communication. It has no clear hierarchy, no obvious focal point, and no reason for one line to exist rather than another. It resembles a diagram without helping the reader decide what to notice.
This is a failure of translation. The source request contains a subject, a relationship, and an intended audience, but a generic renderer often jumps directly from nouns to shapes. It treats “frontend,” “database,” and “service” as equivalent boxes; it treats every connection as equally important; and it uses color as decoration or as a vague substitute for explanation. The output may be technically populated while remaining editorially empty.
Diagram Design responds by treating a figure as an argument. Each node should stand for a distinct idea. Each connector should carry information. An accent should identify one or two focal elements, not announce that half the canvas is important. If two nodes always travel together, they may be one idea. If a relationship is already obvious from a disciplined arrangement, the line that repeats it can go.
That philosophy produces a deliberately uncomfortable test: would a paragraph, table, or list communicate the same thing more clearly? The system explicitly says not to draw when the answer is yes. A list of items is not improved merely by putting each item in a rectangle. A simple before-and-after comparison may be clearer as a table. A single labeled shape may be a sentence wearing a border. The diagram earns its place only when arrangement exposes a relationship that linear prose would make harder to see.
The payoff is not minimalism for its own sake. Removing irrelevant marks gives the remaining marks more semantic weight. A queue can visibly be a bottleneck instead of a generic pipeline. A decision can have a real branch instead of two arbitrary arrows. A deployment figure can distinguish physical placement from logical communication. A chart can make a running total reconcile rather than merely display bars at different heights. Restraint is what makes those claims legible.
A diagram is a chain of commitments
The system's central idea can be expressed as a chain:
The first commitment is semantic. What must the reader understand: components and connections, decisions and branches, events over time, ownership and handoffs, quantity splitting and merging, or a hierarchy? This is more specific than asking for “a diagram.” It names the relationship that makes the visual worthwhile.
The second commitment is grammatical. Diagram Design has many visual types, but they are not interchangeable costumes. Architecture arranges components and connections. Deployment adds zones, hosts, artifacts, versions, and replicas because physical placement is the question. A conceptual entity model is not the same as a physical database schema, where a foreign key must land on a particular column row. A tree assumes a single-parent hierarchy; a dependency graph exists precisely when shared parents or a cycle make that assumption false.
The third commitment is presentational. The same semantic model must fit a destination and an audience. A slide needs a different type ramp and safe area from an inline document. A technical reader may need a protocol and port; an executive reader may need the capability or outcome instead. The system's skin supplies semantic roles such as paper, ink, muted, accent, and link, rather than asking every diagram author to invent a new palette. Typography also has a job: human-readable names use a sans face, technical values use a mono face, and the page title or editorial aside uses a serif face.
The fourth commitment is operational. A self-contained file still has to render correctly, remain intelligible to assistive technology, and avoid turning a small layout defect into a false relationship. That is why the rules reach down to details that can look fussy in isolation: connectors use rounded orthogonal elbows when nodes are off-axis; labels receive opaque masks and space away from their strokes; multiple connections fan out along a shared edge; arrows are painted before boxes; the SVG has a first-child title, a description, and namespaced IDs. These are not arbitrary signs of style. They protect the reader's ability to trace what connects to what.
At the same time, not every rule is universal. A Sankey ribbon needs thickness to encode quantity, so its curved area is not an ordinary connector. A fishbone's angled bones are its cause-to-effect grammar. A journey map's curve expresses ordinal sentiment. The important distinction is that an exception is scoped to the meaning it carries. The system does not abandon constraints; it explains which constraint has been replaced and why.
The practical judgment begins before drawing
This chain changes the first question an author or agent asks. Instead of “Which template looks closest?”, ask “What relationship would the reader lose if this were written as prose?” Then ask what the subject can actually support.
If the answer is a structure, choose a structure-bearing grammar. If it is behavior, select a semantic pattern before selecting the nearest layout. If it is a quantity, make sure the chosen geometry really encodes that quantity. If it is only a list, stop and use a list. The repository's limits are useful here because they force a decision that generic generation postpones. Above the normal complexity budget, the recommended answer is not smaller labels or more colors; it is an overview plus a detail figure.
That decision also preserves the status of the subject. A pattern such as “secure paved road” is not a replacement for the architecture being described. It tells the author which boundaries, permitted routes, blocked paths, identities, and privileged gates must remain visible. “Traceable block decomposition” does not turn a tree into a formal SysML artifact; it adds stable identifiers and metadata to a tree while explicitly declining claims of standard conformance. The behavior or documentation need sharpens the view, but it does not erase the thing being studied.
The same discipline governs evidence. A repository can document a rule, a limit, or a validation contract with precision. That supports saying what Diagram Design is designed to do. It does not support saying that every reader will find every figure clearer, or that the taxonomy covers every useful visual language. The difference is important for a tool whose purpose is to make claims visible: the artifact should not be more confident than its source.
This series will keep returning to that relationship between meaning and constraint. It will examine how deletion creates hierarchy, how behavior is separated from layout, how source files are redrawn without importing their accidental geometry, how output choices disclose loss, and how validation, profiles, and motion extend the artifact without becoming a second source of truth. Those are not separate features. They are successive points at which semantic intent can either be preserved or quietly distorted.
The opening question
Diagram Design is best understood neither as a universal replacement for Figma or a promise that an agent can solve visual communication automatically. It is a disciplined translation and publishing system. Its distinctive bet is that a diagram becomes more useful when the author limits what it can claim, gives every visual signal a job, and carries the result through a self-contained, accessible, reviewable artifact.
That bet creates the next problem. If the system wants every mark to earn its place, how does it decide what deserves space without making the figure incomplete? The answer begins with its most demanding rule: the highest-quality move is usually deletion.