Flowfile SVG Diagrams

Flowfile docs SVG diagrams — authoring, wiring, verification

When NOT to use this skill

• Screenshots, gifs, raster captures — never create or edit those (flowfile-docs-review §1.11); ship a labeled placeholder (§8) and track the capture in DOCS_IMAGE_TODO.md.
• Page prose, alt-text register rules, and fact-checking doctrine → flowfile-docs-review (this skill owns the image file; that one owns the page around it).
• Site build mechanics beyond the §9 verification recipe → flowfile-docs-and-writing.

0. What these are

Hand-authored, fully self-contained SVGs — no external refs (an SVG loaded via ![]() cannot fetch anything), no icon fonts, no rasters, no drop shadows. Directories:

Healthy size is 5–17 KB. The one 82 KB outlier (concepts/positioning-spectrum.svg) carries a ~44 KB base64 PNG of the logo in a 60×64 slot — a known anti-pattern, not a license. That file (and recipe-to-flow) also predates the house root-element pattern; new files follow §2, not those two.

1. Design doctrine — decide before drawing

• Color hierarchy is the message. In the concept register, brand identity is carried by the single gradient hero and the cyan accent — supporting cards stay white with grey strokes even when they depict Flowfile-owned things; grey-vs-brand contrast is reserved for the argument (the old painful way vs the Flowfile way). In the technical register, Flowfile boxes take #1D76D6 strokes and neighbors/bypasses go grey.
• One cyan path carries the eye — the hero edge, the refresh loop, the publish arrow. A symmetric fan of same-meaning spokes counts as one path and may be all-cyan (catalog-fan-out); when the diagram also has a distinct action edge, that edge takes the cyan and the fan stays grey (connection-store, the rotate-credential arrow). Never two competing accents.
• Contrast of complexity sells the argument. The "before/painful/many copies" side: small, muted, tangled. The Flowfile side: clean, gradient, single. Left→right reading.
• Label budget: concept diagrams ship at 25–55 words of visible text; technical diagrams run ~60–160 (process-map is the ceiling at ~160). Per element: 1–3-word bold title, ≤4-word grey subtitle, 1–3-word arrow labels. Fake data in preview tables is dash lines, never words (§5).
• Restraint. Resist the fifth icon, the extra source logo, the second legend row. Every redraw in the history (§10) was a removal.
• Pick a composition pattern from the shipped catalog rather than inventing one:

2. The file contract

Root element, exactly this shape — nothing more:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 W H" role="img" aria-label="...">

• W: 880–980 (typically 940) for concept diagrams; 940–1340 for technical (wider = denser). H: whatever the content needs (shipped range 330–900). Never set width, height, or preserveAspectRatio; no <title>/<desc>.
• aria-label is one long declarative sentence that argues the diagram — entities, relationships, takeaway — mirroring the markdown alt text (§9). Not a description of shapes.
• Order: <defs> (gradients, markers) → <style> (class system) → content. Section banner comments split the body: <!-- ============ CATALOG HUB ============ -->; inline comments annotate semantics (<!-- struck duplicate row -->).
• One <g> per card/node/section; icons as nested <g class="ic" transform="translate(x,y)"> groups drawn on a ~24-unit grid; ids short lowercase (brand, ah, ahc); classes 1–5 lowercase letters (.box .chip .ic .t .s .arw .arwc .albl).
• Arrows are drawn before cards (they run behind), labels last within each group.

3. Palette — exact values

The brand gradient, declared identically in every post-redraw file that uses a gradient (19 of 22 — sheet-vs-flow, system-boundary, and node-palette-annotated have none or per-node ones only):

<linearGradient id="brand" x1="0" y1="0" x2="1" y2="1">
  <stop offset="0" stop-color="#2DD5D3"/><stop offset="0.55" stop-color="#26A8E0"/><stop offset="1" stop-color="#1D76D6"/>
</linearGradient>

Navy #233588 is ink, not a gradient stop: titles, storage styling, dark accents. (The 4-stop cyan→navy gradient belongs to the landing page hero in docs/index.html; extra.css defines the four brand hexes as variables plus a 2-stop card-border gradient. Diagrams use the 3-stop version above.)

The two canvases. Transparent SVGs render on light #fff and slate ≈#1e2129 (Material hsla(225,15%,14%,1); extra.css does not override the background). The default technique is opaque surfaces + mid-tone floating text: put text on white cards or on the gradient (#ffffff / #eaf6ff), and keep the few free-floating labels in mid-greys #6b7280/#8a93a3, which pass on both canvases. When a diagram carries a lot of floating grey text (kickers, captions, dimmed labels), add the paired dark-mode CSS inside <style> — media query plus the Material theme attribute, both required because the toggle sets data-md-color-scheme independently of the OS:

/* .kick = 12.5px grey kicker · .cap = 11px grey caption · .hd = 12.5px w600 NAVY floating heading */
@media (prefers-color-scheme: dark) {
  .kick, .cap { fill:#aeb6c0; }
  .hd { fill:#c7cfd8; }
}
[data-md-color-scheme="slate"] .kick, [data-md-color-scheme="slate"] .cap { fill:#aeb6c0; }
[data-md-color-scheme="slate"] .hd { fill:#c7cfd8; }

Rule: any floating navy text (a heading not sitting on a card) must carry an .hd-style dark override — navy ink vanishes on slate. (Shipped in flow-assembly-line.svg and node-palette-annotated.svg, each with its own class list; never var(--md-...).)

4. Typography

Stack: font-family:Roboto,Arial,sans-serif on text classes (never on the root). The ladder:

Monospace appears where the content is code or ports, in either register: process-map.svg has .mono { font-family:'Roboto Mono',Menlo,Consolas,monospace; font-size:9px; fill:#5b6470; } for env vars and CLI strings, and the concept files code-canvas-duality.svg (.code, and a 12px/700 #1D76D6 monospace .albl) and team-deployment-architecture.svg (.port) use ui-monospace-first stacks. Short code identifiers (spawn_flow_run, GET /api/data/{slug}) usually stay in the proportional face. Beware: vlookup-to-join.svg has a class named .mono that is actually proportional. Separate label fragments with · (·).

5. Component library — copy from the shipped files, don't reinvent

Arrow markers (identical geometry everywhere; recolored clones for variants — ahb #1D76D6, ahn #233588; caution: the id ahm collides across files — dimmed #c7cdd5 in dev-vs-performance but manage-royal #1D76D6 in sharing-model, so check the target file's <defs> before reusing it):

<marker id="ah" markerWidth="10" markerHeight="10" refX="7.5" refY="4.5" orient="auto"><path d="M1,1 L8,4.5 L1,8 Z" fill="#9aa8b6"/></marker>
<marker id="ahc" markerWidth="11" markerHeight="11" refX="7.8" refY="5" orient="auto"><path d="M1,1.2 L8.6,5 L1,8.8 Z" fill="#2DD5D3"/></marker>

The canonical concept-register <style> block (shared by the shipped concept files — start from this, don't reconstruct it from the tables):

.box  { fill:#ffffff; stroke:#9aa0a6; stroke-width:1.4; }
.chip { fill:#eef0f2; }
.ic   { fill:none; stroke:#5b6470; stroke-width:1.7; stroke-linecap:round; stroke-linejoin:round; }
.icw  { fill:none; stroke:#ffffff; stroke-width:1.8; stroke-linecap:round; stroke-linejoin:round; }
.t    { font-family:Roboto,Arial,sans-serif; font-weight:600; font-size:14px; fill:#233588; }
.s    { font-family:Roboto,Arial,sans-serif; font-size:10.5px; fill:#6b7280; }
.kick { font-family:Roboto,Arial,sans-serif; font-size:12.5px; fill:#6b7280; }
.albl { font-family:Roboto,Arial,sans-serif; font-size:11px; fill:#6b7280; }
.arw  { fill:none; stroke:#b3bcc9; stroke-width:1.8; }
.arwc { fill:none; stroke:#2DD5D3; stroke-width:3; }

Card with icon chip — the universal building block (white rect rx 10–12 + chip square rx 7–10 + stroke icon + .t/.s text):

<g>
  <rect class="box" x="70" y="95" width="165" height="84" rx="11"/>
  <rect class="chip" x="83" y="117" width="40" height="40" rx="8"/>
  <g class="ic" transform="translate(91,125)">
    <path d="M4,15 L9,9 L14,13 L20,6"/>
    <circle cx="4" cy="15" r="1.7" fill="#5b6470"/><circle cx="9" cy="9" r="1.7" fill="#5b6470"/>
    <circle cx="14" cy="13" r="1.7" fill="#5b6470"/><circle cx="20" cy="6" r="1.7" fill="#5b6470"/>
  </g>
  <text class="t" x="132" y="133">Flows</text>
  <text class="s" x="132" y="150">shape the data</text>
</g>

Icons are bespoke ~24×24 stroke drawings (fill:none; stroke-width:1.7; round caps/joins) — never icon-font glyphs, never filled MDI path data (that exists only in the legacy positioning-spectrum.svg).

• Canvas flow node: <circle r="21" fill="url(#brand)"/> + white icon (.icw, stroke 1.8) + 9.5px label below; mini 44×26 preview beneath. Or scale a 100-unit master node (sheet-vs-flow uses scale(0.46)).
• Mini preview table: white rect + tinted header strip (#eaf3fc/#eef0f2) via the double-rect trick; data is dash lines (#9cc4ea headers, #a9b2bd/#c4cad2 cells), with semantics drawn in: struck duplicate row, cyan-tinted new column + fx, highlighted join column #eaf3fc+#7fb2e6, Σ totals band.
• Hero emphasis: heavier outline (stroke-width:2.3) or gradient fill + white text/icon + translucent chip; optional all-caps .tag kicker (9px w700 letter-spacing:1px fill:#d3f7f6).

Technical-register devices (do not use in concept diagrams):

• Cluster container: fill:#eef5fd; stroke:#1D76D6; stroke-width:1.7; rx 16 + 14px w700 title ("Core process · FastAPI :63578").
• Decision diamonds: raw 4-point <polygon>. Plain: white fill, #1D76D6 stroke 1.5, navy 11px question text. Hero gate: fill="url(#brand)" + white 15px w700 text, grey 10px condition fine-print below, yes/no as .albl at the exits.
• Notes/callouts: dashed white rects stroke:#b9c2d0; stroke-dasharray:5 4; rx 8 with 10.5px navy title + 10px grey body. Dashed rect stroke = annotation/exception/soft grouping.
• Dash vocabulary for edges: dashed = data movement or background machinery (5 5 Arrow IPC/Delta, 6 6 shared-volume, dotted 1.5 5 return callback), solid grey = control calls, solid cyan = the one primary path. Legend top-right: 32–34px sample strokes + 11–12px #6b7280 labels.
• Numbered execution paths: Unicode circled digits ①–⑤ (①–⑤) inline in bold 11.5px labels (#2489cf, cyan variant #12a8c2) — not drawn circles. Drawn r="12" gradient badges are for table markers (X/Y); pill counters (rx 8.5, #eef0f2) for bounds ("≤ 5").