Visuals

Asking the person: every question is one speech-bubble line, the last prose line of the message, > 💬 **The question?**, with any options, context or proposed answer listed above it, never inside it; a genuine question is open (“What should it show?”), never “X, or Y?”; a check the person runs, its expected result already written above, asks whether that result happened (“Did the import finish and say how many were saved?”), never an open recall question (“What does the finished line say?”); when options are in hand (open work, known routes, candidates), list them above the question with one recommendation; a question that chooses among them (which work, which route) asks about that recommendation (“Start with the export fix?”), never an open question that ignores the list, while a missing fact, a pick-several choice and Switch In’s fixed arrival question keep their own question; ask with no list only when none are in hand; where the host offers one, a native picker may follow the bubble carrying those same options and always leaving a free-form answer open, never replacing or preceding it — see the question form.

Putting a decision to the person: a consequential question — its answer commits to work, spends real effort, releases or deletes something, or reverses a ruling — comes after a decision block: Problem, Facts (with how we know the problem is real and how strong that evidence is), Known options (or “needs study”), Recommendation, Why, Cost, What we lose, Input (who else checked it, or nobody yet). Its bubble is the Recommendation sentence ending “— approve?”, every operation included, or one genuine question the recommendation depends on; never a smaller or softer question than the real decision, and never without the block. A factual question or a small, easily undone step stays one line — see the question form.

Showing the person: when they ask to see something, and whenever a proposal carries two or more connected parts, a branch, an ownership boundary or a before → after change, the answer carries a saved, rendered view drawn with diagram-design or Archify — never hand-rolled ASCII in a code fence, never an offer question, no quota; only a single action or a factual answer stays text, and being easy to describe in words does not make it one — see showing the work.

A lightweight Kerd adaptation of Cathryn Lavery's diagram-design. See sources and adaptation. No CI, hooks, seals, branding onboarding or diagram approval schema is required.

Draw the relationship the person needs to understand

Use during understanding as well as design, delivery and final review. An early before/after view, audience map or scope boundary can clarify a question before the full direction exists. Label partial/proposed content; do not infer missing requirements to complete a picture. Inline prose, a list or a table supplements the rendered artifact; it never stands in for one, and spatial detail being easy to describe in words is not a reason to skip the view. No visual quota per topic.

Use the current work agreement and conversation. Identify the question the picture must answer, then read the matching section of the local pattern guide before drawing. Do not ask the person to choose a diagram type or repeat facts already supplied.

Start at product level: people, capabilities, work and outcomes. Technical architecture is a deeper view when useful, not the default vocabulary. Symbols, file names, line numbers, and type or protocol names belong in a subordinate evidence layer, never in the main relationship. The invariant, for every view: remove every code reference, and the main relationship must still be understandable to a reader who has not opened the source. A solution, proposal or correction view carries more — stripped of those references it must still show what the person can and cannot do today, where the responsibility sits, what changes, and any material cost or boundary that exists. Content decides which applies, never the title or diagram type: any view that depicts or recommends a change takes the fuller test, and only a view limited to present facts uses the invariant alone. If removing them leaves the view unreadable, it was drawn at the wrong level. A deliberately technical deep-dive may use engineering vocabulary throughout, provided its title and summary still pass that removal test. A box means a component, action or boundary; containment means inclusion; an arrow means a particular flow or relationship. Paragraphs in panels are not a diagram.

Show one useful main relationship. Group details or make an additional view when needed; never delete a meaningful constraint just to meet a node quota. Name what was simplified if it could affect the user's decision. Distinguish existing facts from proposed behavior and unresolved choices.

Make it directly usable

Default to one self-contained HTML file with inline SVG/CSS and system fonts, saved with the work. Start from the worked flow for an appropriate flowchart, replacing its facts rather than inheriting them. Use the same visual style for related views; use known project branding when available without an extra setup conversation. Static first; add interaction only when it helps explain the work.

Use clear grouping, restrained emphasis and readable labels. Prefer simple horizontal/vertical connections with clear endpoints; route around unrelated nodes. Avoid line/label collisions. Make the title and SVG description explain the actual subject, and name the project, product or repository inside the render itself, as the first words of the top heading — the first line of text in the render, whatever the tool calls it (eyebrow, kicker, title): the name in capitals and a colon, then the subject, kind and status (KERD: Invoice export · proposal from notes.md · not built). A name elsewhere in the picture does not satisfy this; the reader must see whose it is before anything else. Where a template supplies an eyebrow naming the diagram type or status, replace it with this line; a colon, not a dot, follows the name. A filename, browser tab, surrounding message or filesystem path sits outside the picture and does not satisfy this, because the view travels without them; where more than one name could apply, the repository name is the floor. Do not rely on colour alone. Give each state its own look that differs in more than one way: what exists today in a solid outline, what is proposed in a dashed outline, and the change the view is about on plain paper with a solid accent border, heavier than the rest (no tinted fill; the Kerd look marks the focal item by its stroke alone). Two states that differ only by colour, or only by dash, read as the same thing at a glance. Every box takes its state, including a result that exists only once the change ships: that result is proposed, so it is dashed. Draw for a desktop or laptop screen first: that is where Kerd's readers look. Never shrink text into illegibility to fit a narrower screen. A theme that draws a full-size sheet (Intersect) keeps it at full size and a narrow screen scrolls sideways; never stack, narrow or strip such a sheet for a phone, and never brief a drawer to. Only without such a theme may a wide diagram be split into readable parts.

Render and inspect the actual output at desktop width. A phone check, when the view is likely to be opened on one, is secondary and never reshapes a themed sheet. Use an available browser or image-capable preview; do not require a specific test framework. If inspection is unavailable, disclose that limitation instead of claiming visual validation. Check meaning as well as layout: the project leading the top heading, states that look different at a glance, source facts, arrow direction, ownership and the visible distinction between proposed and delivered work.

Help the decision; do not invent another gate

Show the rendered artifact with a short explanation of what it clarifies. When Conductor needs agreement, its question includes the outcome, boundaries and meaningful tradeoffs—not “approve this diagram” without context. The user's actual agreement belongs in the work record, not in a seal or fingerprint.

Offer deeper detail without forcing the person to read it. Do not pause for routine colour, layout, type or export choices. If the drawing exposes an important unresolved product decision, ask that decision rather than guessing.

For Kerd's rendered views, diagram-design and Archify are required, not one option among several: a view goes through one of them. Choose the tool that best explains this work; honor the person's preference. Diagram-design carries broad static layouts — processes, timelines, responsibilities, scope, comparisons; Archify carries exploration, focused paths and comparing changes. These are tendencies, not a rigid technical/nontechnical split. Either can support user agreement, and a work package may use both when each view adds something. Do not ask the person to select a tool before understanding the outcome. Archify never reads diagram-design's style guide, so when the active style guide (below) is a look the person chose (a project's profile, or a theme or profile they made the installed guide, Intersect included), draw with diagram-design; use Archify only when the person asks for it or its exploration is the point, and then say the view is in Archify's own look, not theirs. The starter patterns bundled here do not satisfy the rule on their own — they are neither the full diagram-design catalogue nor a substitute for it; they help choose the view, and the view itself is drawn with one of the two required tools. Disclose unavailable capabilities; do not silently substitute or start a preview server.

A diagram-design view takes its colours, type and shapes from the active style guide: the profile the project's .diagram-design file names, otherwise diagram-design's installed style guide, which may be a theme the person made their default; a theme asked for one diagram is that diagram's guide. Read that guide before drawing, and name its path when briefing a drawer. Never hand-pick a palette, paper or font, or restyle the view into a look of your own; drawing with the tool in another look still bypasses the person's choice. Before delivering, check the rendered view against that guide; a view in another look is redrawn, not delivered.

Themes: the opt-in Intersect look

Kerd ships one opt-in diagram theme, Intersect: a photocopied engineering schematic in white, toner black and one red, all capitals, with pin tags, chevron banners and studded buses. It is a diagram-design profile; it never replaces anyone's default unless they ask. Archify keeps its own look; say so when an Archify view is asked for in it. Match the scope the person names, and say which one you used:

• One diagram (“draw this in the intersect theme”): read the shipped theme file as the style guide for that drawing only. No profile or setting is changed; the next diagram is back to their default.
• This project (“use the intersect diagram theme”, “switch to intersect theme”): copy the shipped file to ~/.diagram-design/profiles/intersect.md (if one is already there and differs, ask before replacing it), then ask before writing the project's .diagram-design file with exactly profile: intersect, which is a file in their repository. If that file already names another profile, say which, so it can be restored, and ask before replacing it.
• Projects without their own selection, on this machine (“make intersect my default”): save it as above, then copy it over diagram-design's installed style guide, never through a project's .diagram-design file, which this scope does not touch; a project that has one keeps its own selection, and a diagram-design update reverts the installed copy. First say what the installed copy is now: a saved profile by name; the untouched shipped default, which you snapshot as default.md first by diagram-design's own recovery-snapshot step; or an unsaved custom guide, which you offer to save as a named profile before replacing it; with neither saved nor agreed, stop.

Switching back follows the same scope and restores what was there, never a guess: nothing to undo for one diagram; for a project, put back the profile its .diagram-design named before, or remove the file Kerd added; for the machine, copy the profile you named before switching back over the installed style guide, never through a project's .diagram-design file. When that previous look is unknown, say so and ask which saved profile to load; never substitute default for it. Never delete the person's other profiles. The theme's own rules (one red thing, capitals, shapes rather than colours) apply only while it is in use.

When a required tool is not available here

Keeping one of the two tools working is part of the job, not an extra. The source record still distinguishes this bundled diagram-design adaptation from the full upstream catalogue and from Archify's own runtime.

If a required tool is missing on this host, or the second one would materially improve the view, set it up: name the benefit, source, install location and any dependencies, network use or preview service. Use current upstream instructions and the host's supported installer. Installing anything still needs approval unless existing authority explicitly covers that installation; ordinary diagram approval does not. Once setup is approved, perform it and verify the tool can produce a usable view. Continue the original diagram task without another routine “shall I install?” turn. The offer is to do the work, not hand the person a list of commands. Report any genuine access or host limitation. If setup is declined or blocked, fall back to the other required tool, saying so; when that means Archify while a chosen look is active, say the view loses that look and ask before drawing it there; if neither can run here, say plainly that the view is not rendered and what that costs, rather than substituting a hand-drawn picture. Do not repeat an install question when the tool is already available. Record the selected tool/version beside the work only when it matters for reproduction.