.impeccable.md

• Every node represents a distinct idea. Two nodes that always travel together are one node.
• Every connection carries information. If the relationship is obvious from layout, remove the line.
• The active accent is editorial, not a flag. Use it on 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal.
• The schematic isn't done when everything is added. It's done when nothing can be removed.

• Editorial for restrained documentation, product, data, and quantitative visuals across all types.
• Technical-color architecture for cloud, infrastructure, network, security, and topology maps; this is the merged former

  architecture-diagram

  skill.
• Technical-color process flow for numbered workflows, approvals, automation, onboarding, and runbooks; this is the merged former

  process-flow-diagram

  skill.

• Quick unicode diagrams → use wiretext.
• Lists of things → table or bullets.
• Simple before/after → table.
• One-shape "diagrams" → just write the sentence.

• If a 3-column table communicates the same thing, pick the table.
• If you're combining two types, pick the dominant axis — don't hybridize grammars.
• If you're past the complexity budget (§7), split into an overview + detail.

references/type-*.md

assets/illustration-themes.yml

.github/illustration-theme.yml

references/style-guide.md

paper

ink

muted

accent

link

When specs or type references mention a semantic role, use the current resolver output. Resolved project tokens override every literal color or font shown in a historical example.

• Title — resolved

  serif

  , 1.75rem, 400 — H1 only
• Node name — resolved

  sans

  , 12px, 600 — human-readable labels
• Sublabel — resolved

  mono

  , 9px — ports, URLs, field types
• Eyebrow / tag — resolved

  mono

  , 7–8px, uppercase, tracked — type tags, axis labels
• Arrow label — resolved

  mono

  , 8px — annotation on arrows
• Editorial aside — resolved

  serif

  italic, 14px — callouts only

remote_css_url

font_loading

remote

references/type-*.md

• Editorial callouts → primitive-annotation.md
• Hand-drawn variant → primitive-sketchy.md
• Icon set (laptop, server, DB, K8s, Docker, AWS, …) → primitive-icons.md. Browse the gallery at

  assets/icons.html

  .
• Terminal / CLI-window variant → primitive-terminal.md
• Merged Architecture Diagram family, templates, and examples → technical-color-architecture.md
• Merged Process Flow Diagram family, templates, and examples → technical-color-process-flow.md

1. Rounded right-angle (orthogonal) connectors are mandatory. Never use diagonal

   <line>

   or straight slanted paths between nodes that don't share an x or y axis. Every bend must be a quarter-arc with

   r=8

   (or

   r=6

   minimum for tight layouts). See

   references/type-architecture.md

   for the elbow-path formula. Reserve plain straight

   <line>

   only for connections whose endpoints share the same x or y coordinate. Diagonal connectors are an automatic fail.
2. Label-to-connector margin: 6–10px gap, always. A label must never sit on its arrow — the connector must remain visible. Place the label centered above (or beside, for vertical segments) the line with a minimum 6px gap between the bottom of the label's mask rect and the connector stroke. The opaque mask rect prevents the arrow from bleeding through, but the visible gap between mask edge and line preserves the reader's ability to trace the connection. If the label is large enough that 6px feels cramped, push it to 8–10px. Never let the mask rect touch or overlap the stroke.
3. No overlapping connectors. Two connectors must never share the same stroke path, run parallel on top of each other, or be drawn on top of each other for any segment. When two orthogonal arrows must cross at a single point, apply the bridge / hop primitive (see

   references/type-architecture.md

   § Crossing arrows). When two arrows naturally want to overlap, offset their routing by ≥12px so each line is independently traceable. If you find yourself stacking connectors, redesign the layout — it means two nodes are too close, or the diagram is over budget (split into overview + detail).
4. Shared edge → fan the attach points. When two or more connectors enter or exit the same edge of a box, each must have its own distinct attach point along that edge — no two connectors may share a single point on a box. Spread the attach points evenly along the edge with ≥12px between adjacent points (8px minimum for very small boxes). Routing rules:
   • For N connectors on an edge of length L, attach point

     k

     (1..N) sits at offset

     L * k / (N + 1)

     from the edge's leading corner.
   • When the connectors fan out to destinations on different sides, route each one orthogonally from its own attach point — no merging strokes near the box.
   • When two parallel connectors run in the same direction, keep them ≥12px apart along their entire length, not just at the attach point. Each arrow must remain independently traceable end-to-end.
   No connector may hide another. If you can't tell two arrows apart at a glance, the layout has failed.
5. A connector must not pass behind a box that isn't its source or destination — except when the box is geometrically unavoidable on a direct orthogonal path. Reroute around intervening boxes by default. The only legitimate exception is when a cross-cutting node (e.g., a footer service, a horizontal layer bar) physically sits between the connector's source and destination on the only straight path between them — for example, a

   METRICS

   arrow exiting an

   Observability

   footer bar and rising into a zone above must cross the

   Active Directory

   footer bar that sits between them. In that exception:
   • The stroke must be dashed (e.g.,

     stroke-dasharray="4,3"

     ) to signal "transit, not interaction" — it tells the reader the intervening box is not an endpoint.
   • The label sits at the visible end of the connector (typically near the source) so it doesn't fall behind the intervening box.
   • No marker (arrowhead) may land on the intervening box's edge — the marker resolves at the true destination only.
   When in doubt, reroute. The exception exists for the narrow case where rerouting is geometrically impossible, not as a shortcut to avoid layout work.

<!-- Mask sits 14px above the arrow (8px text height + 6px gap). Stroke is at ARROW_Y. -->
<rect x="MID_X-18" y="ARROW_Y-20" width="36" height="12" rx="2" fill="#f6f8fc"/>
<text x="MID_X" y="ARROW_Y-11" fill="#6b7a90" font-size="8"
      font-family="'IBM Plex Mono', 'Noto Sans Arabic', monospace" text-anchor="middle" letter-spacing="0.06em">WRITE</text>

• ≤14 characters, all-caps, centered on segment midpoint.
• Mandatory 6–10px gap between the bottom of the mask rect and the arrow stroke. The connector must remain visible — a label that hides its own arrow is a hard fail.
• Never

  writing-mode

  vertical.
• For vertical segments, place the label to the side (not on the line) with the same 6–10px horizontal gap.

1. Header — eyebrow (resolved mono), title (resolved serif), optional subtitle (resolved sans + muted).
2. Diagram container — default: clean, borderless, no background — the SVG sits directly on the page paper. Optional framed variant (for card-heavy layouts or hero placements):

   paper-2

   bg + 1px

   rule

   border + 8px radius +

   1.5rem

   padding +

   overflow-x: auto

   .
3. Summary cards — 2–3 col grid with varied widths (e.g.,

   1.1fr 1fr 0.9fr

   ).
4. Footer — colophon in resolved mono, muted, hairline top border.

<div class="card">
  <p class="eyebrow">SECTION LABEL</p>
  <div class="card-header">
    <span class="card-dot accent"></span>
    <h3>Card Title</h3>
  </div>
  <ul><li>Item</li></ul>
</div>

• background: #ffffff

  (not paper — slight lift without shadow)

• border: 1px solid rgba(45,49,66,0.12)

• border-radius: 6px

  ,

  padding: 1.25rem

• No

  box-shadow

• Card dots: 7px,

  border-radius: 50%

  — ink / muted / accent / link / soft variants

• Right type for what I'm showing? (§3 selection guide)
• Would a table / paragraph do the same job? (If yes — don't draw.)
• Loaded the matching

  references/type-*.md

  ?

• Can I remove any node? (Would a reader still understand?)
• Can I merge any two nodes? (Do they always travel together?)
• Can I remove any arrow? (Is the relationship obvious from layout?)
• Can I remove any label? (Does color or shape already signal it?)

• Active accent used on ≤2 elements? If more, which actually deserve focal status?
• Legend covers every type used — and nothing extra?
• Within the type's complexity budget (§7)?

• Arrows drawn before boxes?
• Every connector between off-axis nodes uses a rounded right-angle elbow (

  r=8

  )? No diagonal

  <line>

  slants?
• Every arrow label has a visible 6–10px gap above its connector? (Mask rect not touching the stroke.)
• No two connectors overlap, share a stroke path, or run on top of each other? Crossings use the bridge/hop primitive?
• When several connectors enter or exit the same edge of a box, each has its own attach point (≥12px apart)? No connector hides another?
• No connector passes behind a non-endpoint box, except the unavoidable-intervening-box case (§6 rule 5) — and in that case, the stroke is dashed and the label sits at the visible end?
• Every arrow label has an opaque rect filled with the resolved

  paper

  token behind it?
• Legend is a horizontal bottom strip, not floating?
• No vertical

  writing-mode

  text?

• viewBox

  expanded for the legend strip (~60px)?
• Every font size, coord, width, height, gap divisible by 4?

• Human-readable names use the resolved sans family, not the mono family?
• Technical sublabels (ports, commands, URLs) use the resolved mono family?
• Page title uses the resolved serif family?
• Annotation callouts use the resolved serif family in italic? (see primitive-annotation.md)
• No blanket JetBrains Mono unless the technical-color family was explicitly selected?

1. Resolve

   .github/illustration-theme.yml

   ; initialize Cobalt when the project has no selection.
2. Choose editorial, merged technical-color architecture, or merged technical-color process flow.
3. Load

   references/type-<name>.md

   for editorial output; load the matching

   technical-color-*.md

   reference for either merged family.
4. Copy the closest template/example, replace its content, and apply every resolved color and font token while preserving the selected family's visual and export grammar.
5. Run

   illustration_theme.py validate

   , audit the output for stale default literals, then run the §9 taste gate.

.html

• Embedded CSS (no external except Google Fonts)
• Inline SVG (no external images)
• Editorial variants require no JavaScript; technical-color variants preserve their pinned export scripts