The Diagram Engine

The bet, in one breath

Okta and Hightouch don't make "nice diagrams" — each runs a system: a tight set of color, type, spacing and shape rules, plus a handful of signature patterns, applied with discipline every single time. That's why they look expensive and consistent.

So we don't build "a diagram maker." We build a token-driven diagram engine where three things plug together — a client's brand, a chosen visual style, and a diagram type — and a finished, editable, on-brand diagram comes out the other side. Re-branding the same diagram for a different client becomes a one-click swap. That swap is the whole product.

Decisions locked

Your three answers point at exactly one architecture — they're mutually reinforcing.

• Internal (Brightbase) operates it → we optimize for a skilled operator's speed and control, not a foolproof public UI. Lower UX burden, faster to ship.
• Per-client branding → branding must be data (a swappable file of colors, fonts, logos), never hard-coded. This is the single most important design constraint.
• Editable vector (SVG / Figma) → we render to clean SVG. SVG scales infinitely, drops into decks, docs and the web, and imports into Figma as real editable layers. It's also the format we can fully control pixel-for-pixel.

Reference teardown

We pulled both brands apart down to the hex values and signature moves. They are two different aesthetics with shared DNA — and that contrast is a gift, not a problem.

The shared DNA (this is what we actually build)

• Strict scales, never freehand. Both lock radius, type size and spacing to a fixed ladder. Discipline is the secret.
• Real logos in uniform containers. Both drop brand marks into same-size tiles so heterogeneous logos read as one system.
• Semantic color. Color means something (which actor / which role) — it's never decorative.
• Restraint + one accent. Mostly neutral, one electric highlight, ruthless alignment, generous white space.
• The product lives in a node. Okta and Hightouch each put their own logo inside the diagram — the diagram is the pitch.

Atomic elements of a diagram

Every diagram in this space is assembled from the same small kit. This kit becomes our component library — build each piece once, reuse forever.

The engine — the core idea

Four inputs combine into one output. Change any one input and the diagram updates — that separation is the entire design.

• Brand tokens are the differentiator. Swap Acme's file for Globex's, press render, and every diagram we've ever made is now in Globex's brand. This is "per-client at scale" made literal.
• Style packs are reusable looks. We start with two (the Okta and Hightouch teardowns above), add more over time.
• Archetypes are reusable layouts with smart auto-arrangement, so the operator never nudges boxes by hand.
• The spec is the only thing that's truly per-diagram — and it's the part an AI assistant drafts from a plain-English brief.

How we build it

We researched every realistic approach against five tests: can it look Okta/Hightouch-grade, can it repeat, can it re-brand per client, can an AI drive it, and can it export clean vectors. One path wins; one stays in the back pocket; the rest are traps.

The recommended stack, in plain terms

• A component library — every atomic element from §4, built once as a branded, theme-able vector piece.
• A layout brain — an automatic arrangement engine places nodes and routes lines cleanly, so diagrams look hand-tuned without hand-tuning.
• An AI author — turns a plain-English brief ("show SSO from Okta into the client's app") into the structured spec the engine renders.
• A token system — the per-client brand file the whole thing reads from.

The fast lane (kept in reserve)

For quick, internal, "good enough" diagrams we keep a diagram-as-code fast lane (a tool called D2): the AI writes a few lines, a per-client theme is applied, and it batch-renders. It gets ~80% of the polish for ~20% of the effort — useful for volume drafts, not for the showcase pieces.

What we deliberately avoid

• Mermaid (the common default) — its brand ceiling is too low; it will never look like Okta or Hightouch.
• Building the core in Figma's API — gorgeous fidelity, wrong tool for headless mass-production. We reserve Figma as an export target (our SVG imports into Figma as editable layers) and for the occasional bespoke hero diagram.

The workflow, end to end

What it actually feels like for a Brightbase operator to make one diagram — and then ten.

Phased build plan

Each phase ends in something you can see. We prove the magic on one real diagram early, then widen.

Open decisions for you

Three calls I want your read on before I lock the plan and start Phase 0. Each has my recommendation — reply with a number + your pick, or just "go with your recs."