Canvas Look & Branded Connectors — Cards That Survive Dark Mode

The canvas paints node cards and the canvas floor from the same colour token, so a card has never been delineated by its surface in either theme — light mode gets away with it because a black drop shadow reads on white, and dark mode has nothing left at all. Fixing that is a four-token change; looking like n8n is a separate, smaller job about spending colour once per card instead of five times, rounding a port that has been square on every read-only screen since it shipped, and giving a grown switch card something to say.

1 · The two complaints, taken separately

The owner's report bundles a bug and a taste judgement, and they have different causes and different costs:

What this page owns, and what it does not

Three agents are on this surface at once, so the division matters:

2 · Root cause: one token, used against the wrong contract

The live canvas, same 7-node graph in both themes (trigger, a 4-arm switch, four transforms, an approval). These are captures of the deployed product, not mockups:

live · light — edges present but thin

live · dark — no card edges at all

Four separate defects are visible in these two frames: no card edge in dark; the switch card grown tall and left empty; wires slanting; and the port marks rendering as grey squares. Each is treated below — §2 the edge, §3 the slant and the empty switch, §4 the squares.

The canvas wrapper is painted bg-card (GovernedCanvas.tsx:799). The idle node card is painted bg-card too, with STATUS_BORDER.idle = "border-border-subtle" (GovernedCanvas.tsx:392, :82). So card-against-floor is 1.00:1 by construction, in both themes — the surface contributes exactly nothing, and the whole box rests on a 1px border plus Tailwind's shadow-sm.

Measured off the deployed canvas rather than read off the stylesheet: card fill rgb(15,19,28), card border rgb(24,31,43) at 1px — a 9-to-15 delta per channel — and the elevation shadow is rgba(0,0,0,0.1), byte-identical in both themes. That last fact makes these two independent failures, not one: a border chosen against the wrong reference, and a shadow that was never themed at all.

Those two remaining cues fail differently per theme, which is why the bug reads as dark-mode-only:

A black-alpha shadow has no ground to darken on a near-black surface. Light mode is carried by the one cue dark mode cannot have, so the palette's dark block was never wrong on its own terms — it simply removed the only working cue and left a token that was never meant to do this job.

The token-level statement

--border-subtle is a divider token, sized to disappear against --background. It is being used as a card edge, a job that requires contrast against --card. No token in the palette carries the contract "visible against --card" — that missing contract is the bug. Nor can dark mode borrow elevation instead: --card #0f131c against --background #0b0e14 is 1.04:1, because the whole dark palette lives inside a ~4% luminance band near black. In dark mode the edge has to carry delineation alone.

Both panes are the real token values. Only the chip, the accent bar and the type locate the dark card — the box itself has no edge, which is precisely the complaint.

What !737 already does, and the two gaps left

The fix for the bug half is in flight as !737, and it is structurally the right shape — this page should not fork it. It does three things:

1. Repoints the idle card from border-border-subtle to border-border-strong.GovernedCanvas.tsx STATUS_BORDER.idle
2. Themes the elevation properly — --shadow-cast (black 10% light, 55% dark) plus --shadow-rim (transparent light, white 6% dark) composed into --shadow-raised with an inset 0 0 0 1px. The rim is the cue a near-black surface can actually carry.index.css, per-theme
3. Adds card-delineation.test.tsx, which parses the palette blocks and asserts the card's border is not the ground's colour and does read against --card in every theme — the enforcing test, not a screenshot.canvas/card/card-delineation.test.tsx

Measured, that lands the dark card at 1.62:1 border (up from 1.12:1) plus a rim at 1.15:1 — a real fix, and the shadow work is exactly right. Two gaps remain, and they are this page's contribution rather than a disagreement:

Sequencing follows from that: !737 should merge as-is because the current state is a bug; the threshold and the dedicated token are a follow-up that makes the class of defect unrepeatable rather than merely repaired. The 18 further shadow-sm uses carrying the same dead-elevation defect are already tracked as #489 — including two on the node card itself (the hover toolbar's duplicate/delete buttons), which would otherwise leave the reviewed surface visibly half-finished.

3 · Edge geometry: straight wires are the baseline, not a proposal

The diagonal wires in §2's captures have a cause independent of colour. Layout stacks each layer by card top, while a single-port card's port sits at 50% of its own height. Two connected cards of unequal height therefore have ports at unequal Y, and the wire slants. n8n looks tidy here partly for a reason we cannot copy: its nodes are uniform-height, so top-alignment and port-alignment coincide for free.

#485 is already fixing it the right way — port-axis alignment: a single-inbound node aligns to the exact port feeding it, arm-aware for switch arms, and a join centres on the mean of its inbound ports. This page treats that as shipped and states only what it must not break.

Uniform-height cards: explicitly declined

The tempting aesthetic principle here is "make every card the same height and the wires go straight by construction". This design declines it, and the reason is that the product has already committed the other way:

Uniform heights would forbid all three. So straightness must be height-independent, which is exactly what port-axis alignment delivers and what height uniformity only fakes. The obligation this places on the card system is narrower and worth stating as a rule: a card must expose a stable, computable port axis. Two consequences for the layout in §6:

• The name clamps at two lines (-webkit-line-clamp: 2, full text in the existing title). Not for tidiness — an unbounded name makes card height a function of string length, which is the one input the layout cannot know before render.
• Nothing may move the port axis after first paint. A chip that grows on hover, or a meta line that appears on selection, would re-slant every wire into the card. States change colour, never height.

The grown switch card is empty — fill it with the arms

Visible in both captures: the 4-arm switch is a tall box whose content occupies only the top ~40px, and its arm names (gold, silver, bronze, default) float as pills on the wires instead. The growth is correct — it is what keeps each port band above the 24px aim floor — but it currently buys dead space and pushes the labels onto the canvas.

The n8n-grade answer is to spend the height on the information the wires are carrying: one labelled arm row per port band, each row vertically centred on its own port. The card then explains its own fan-out, the floating pills become redundant, and the rows are already exactly where #485's arm-aware alignment expects the ports to be. This also gives PD009's per-arm split ports somewhere to land.

It also removes a live bug at the root rather than treating it. #488 reports two arm labels overprinting into an unreadable blob when a switch's arms converge on a nearby target: an edge label sits at its path's midpoint, and arms leaving adjacent ports for the same close target have nearly the same midpoint. Worse with more arms, and worse since #477 pushed arm ports closer together in screen space at the zoom floor. Any fix that keeps labels on the wires is collision avoidance — offsetting, staggering, hiding one. Moving the label onto its own row inside the card makes the collision impossible, because two rows cannot occupy one band. #488 should take the cheap positional fix now; arm rows are what retire it.

Same total height, same port bands, same 28px minimum. The arm row is the port's own label, so a reader no longer traces a wire to a floating pill to learn which arm it is.

4 · A read-only canvas draws square ports

Look again at §2's captures: the port marks are grey squares. The editor's are round. Same graph, two shapes, and the cause is a missing class on one branch:

The live branch renders a child <span> carrying rounded-full, so the editor gets a 12px dot. The read-only branch has no child — the Handle div is the visual, and it never receives a radius. Nor does it inherit one: the canvas imports @xyflow/react/dist/base.css, whose .react-flow__handle rule sets only position, min-size and background. The rounded appearance lives in style.css (border-radius: 100%), which this app deliberately does not import.

So every read-only surface — the workflow list card, the published-graph view, the approval preview, the run view — has always drawn 10px squares of --border-strong, and only the editor draws dots. It is a one-class fix, and it is a large share of the "clumsy" the brief names: a reader sees two different port vocabularies depending on which screen they are on.

A read-only port stays non-interactive — no 32px hit box, no hover growth. Only its shape and colour join the editor's vocabulary.

5 · The card system, retokenized

Four new tokens, added to :root, .dark, and each of the three named templates in apps/ui/src/index.css. Kind hues, status hues and text colours are not touched — this is not a repaint.

Two non-token changes travel with them, and both are load-bearing:

• The shadow is already solved — adopt !737's tokens verbatim. --shadow-raised, composed from --shadow-cast and --shadow-rim, with the rim doing the work in dark (white 6% inset) and resolving to a no-op in light where the cast reads on its own. This page proposes no alternative shadow naming; a second scheme for the same job would be its own defect.
• The port dot's ring follows the surface. The 12px dot is ringed border-2 border-card (GovernedCanvas.tsx:69). When the card surface becomes --card-raised, that ring must move with it or every port grows a halo of the old colour.

Asymmetric on purpose. A single 3:1-both-themes rule is available and would put light mode's edge at #8b93a6 — defensible, but a visibly more outlined card than the n8n look the brief asks for. Recommending the asymmetry; flagging the one-rule alternative as the owner's call.

6 · Why it reads as clumsy: colour spent five times

An n8n node spends colour once, on the icon tile. Ours spends it five times on a card that is 240×68:

1. Kind hue on the 24px icon chipNodeKindChip.tsx:99
2. The same kind hue again, as a 3px full-bleed barGovernedCanvas.tsx:425 KindAccent
3. Status hue on the borderGovernedCanvas.tsx:77 STATUS_BORDER
4. Status hue again in the corner badgeGovernedCanvas.tsx:214
5. Proposal diff hue in a top-centre badgeGovernedCanvas.tsx:335

Items 1 and 2 encode the identical fact, and 3 and 4 encode the identical fact. The proposal is one carrier per fact:

Two more corrections fall out of reading the card as type rather than as colour:

• Name first. Today an uppercase mono band ("NOTIFY", 11.5px, letter-spaced) sits above the name you came to read. n8n leads with the name. Move the kind into the secondary line — Notify · #ops-room — losing no information and no vocabulary.
• One left edge. The head starts at 12px and the title at 44px (GovernedCanvas.tsx:270), so the card has two left edges. Putting the chip beside a single text column gives one.
• Selection ring should be --ring, not --primary. In dark, --primary is #e7eaf2 — a near-white 2px halo at 14.5:1 against the card, louder than the running state it competes with. --ring (#5b9dff) reads at 6.4:1, which is ample.
• Status borders drop their /40 alpha in dark. border-success/40 over the new card measures 2.45:1 — under the 3:1 the edge contract requires. Full strength measures 8.6:1.

7 · Before / after, both themes

Same content, same 240px width, same kind hue. What changed: the floor stepped away from the card, the edge got a contract, the accent bar went, the name came first, and the two left edges became one.

Measurements

8 · States, both themes

The parked gate keeps its amber wash — the one card allowed a tinted surface, because a run parked on a human is the thing a run view exists to surface.

9 · Branded connectors: presentation over machinery already shipped

This is much smaller than it looks, because the mechanism exists and already wins against the kind glyph. NodeKindChip takes an optional tool and, when resolveToolGlyph matches it, renders a service glyph instead of the kind icon (NodeKindChip.tsx:89-118). It is confined to one node kind by a single line in nep-view.ts:192:

Widen that expression to also yield a resolved channel platform for notify and channel-event triggers, and a branded connector node needs no new node kind, no new chip component and no new render path.

The one real gap: the platform is not on the wire

Neither node config names a service. Both carry an opaque id:

The platform is recoverable server-side — the channels row's channel_key is external:<platform>:<peer>:<identity>, built in channels/linked.ts:211 — but both client projections strip it to { id, name, kind }, where kind is the structural kind (room | person | external | agent-dm), not the provider. So this needs a projection change in exactly two places, no new query:

1. Add platform to the palette's channel rowsapps/api/src/workflows/palette/index.ts:163
2. Add it to resolved graph names too, for read-only canvases with no paletteapps/api/src/workflows/names/graph-names.ts:55
3. Widen NameBook / PaletteResponse, and stop dropping the fieldnames/name-book.ts:35 nameBookFromPalette
4. Resolve platform → glyph, and widen the one line abovenep-view.ts:192

What a branded node may honestly claim

A correction the brief's framing invites, and it changes the wording on the card. A notify node does not send anything to Slack. It resolves its target to a Neutron thread and appends a message (worker-steps.ts:320-328 → db.appendMessage). There is no transport fan-out in the notify step at all; the only outbound-to-transport path in the product is the inbox reply, which is WhatsApp-only today (inbox/reply-core.ts:184).

So the brand mark names where this lands — the origin transport of the destination thread — not the wire the message leaves on. That keeps the verb neutral:

The channel-event trigger is the stronger case of the two: an event genuinely does arrive from that transport, so branding a trigger claims nothing extra. If the owner wants the most conservative version, brand triggers only and leave notify on its kind glyph — but the accurate-verb version above is the recommendation, because "which service is this about" is the question the icon is being asked.

That last point is the design rule worth stating outright: the brand mark replaces the glyph, never the hue. n8n can hand a whole node over to a brand because its node type is the service. Ours cannot — the kind is real, governed vocabulary that validation, wiring rules and the run view all depend on — so the kind keeps the chip's background and the service gets the foreground.

Which services can be branded, honestly

A gap worth closing in the same pass: externalTransportKind (components/channels/channels.ts:34) maps wa/whatsapp/tg/telegram/email/voice but not slack or discord, so a Slack channel row in the channels list already falls through to a generic hash icon today. Same table, same fix.

10 · Icon sourcing

The recommendation is to source nothing new. Every brand mark this design needs is already in the repo, as inlined single-path simple-icons geometry keyed by the exact platform slugs the transports use:

Those four ids are byte-identical to LinkedTransport.platform, and MessagingPlatforms.tsx:243 already renders mark + name + tint per provider in settings — so the connector node inherits a shipped, reviewed precedent rather than inventing one.

One structural change to ToolGlyph is worth making while there: it currently reaches brands through ChannelLogo, whose ChannelKind is web | email | wa | tg | voice — so Slack and Discord are unreachable from a node glyph today even though their paths exist elsewhere. Point ToolGlyph's brand branch at the messaging/icons.tsx registry (the one keyed by platform slug) and both the node glyph and the channels list can share one map.

11 · Palette and information architecture

The palette today is a kind rail: twelve rows, one per node kind, each with a short tag (start, tool, llm, gate, post, if…) from WorkflowEditor.tsx:73. Services are chosen afterwards, inside the floating config panel, from a seat-scoped palette response.

n8n inverts this: its palette is service-first, because in n8n the node type is the service. Copying that shape wholesale is what would explode the list — n8n's 400+ integrations × ~10 actions each is a search problem, and it is the reason n8n needs a search box before it needs a palette. We should not import that problem to gain an icon.

Recommendation: keep the kind rail canonical and add one bounded group below it. A "Connectors" group listing the channels this seat is actually connected to — each row a prefilled node, not a new kind:

The bound is the argument. n is not "every service we might support" — it is "channels this seat can reach", which the palette endpoint already returns and already scopes by seat. A connector row creates a trigger or a notify with channel_id prefilled; picking one is a shortcut through the config panel, never a different node.

Canvas controls belong in one cluster

The owner went looking for a tidy-up control and could not find one. It exists — but the canvas's controls are scattered across three different places, at three different sizes, with one of them conditionally absent:

Proposal: one bottom-left cluster on the canvas itself, in the same 28px button vocabulary, present on every surface that can use it. The conditional-absence bug becomes a disabled state with a reason in the tooltip — a greyed control teaches that the capability exists, an absent one teaches nothing. Tidy also stops being editor-only: a read-only canvas can re-derive the layered layout for viewing without writing positions. #485 carries the surfacing work; this is the shape it should land in.

The readout shows the live zoom, which also makes ZOOM_FLOOR legible: a user who has hit 86% can see that the canvas has stopped shrinking and started panning, rather than assuming zoom is broken.

12 · A graph, end to end

Cards narrowed to 176px here only to fit a four-step chain on this page. The real card stays 240px — see the invariant below.

13 · Reconciling with PD009 (split & merge)

PD009 is in flight on the same surface. The two designs agree, and in one place PD009's proposal is the better form of an invariant this page needs — worth recording so neither gets implemented against the other:

The connector pipeline, end to end

What has to exist, in order, for a Slack notify to render as a Slack notify:

Only three boxes are new, none of them in the engine, the schema, or the node-kind vocabulary. The first and last already exist — which is why this reads as a presentation change rather than a feature.

14 · Invariants this must not break

The just-shipped legibility work makes the canvas's sizes load-bearing, and the most tempting version of "neater, tighter cards" would silently undo it. Three constraints, with the arithmetic:

Two of the three are already covered by tests (zoom-floor.test.ts, port-geometry band tests). The gate-height floor is arithmetic that no test currently asserts as a minimum — P1 should add it, so the redesign cannot regress the floor silently.

Phases

1. The edge contract, on top of !737 — !737 merges first and keeps its --shadow-* tokens and its delineation test untouched. This phase adds what that test is missing: the stated threshold (≥3:1 dark / ≥2:1 light) asserted over all 8 palettes, a dedicated --card-edge so the card stops borrowing --border-strong, --canvas-ground so the floor is no longer bg-card, the port-ring token following the surface, and status borders losing /40 in dark. No repaint is redone. ~1 session.
2. Round the read-only port — one class on the !live branch, plus the kind hue, so all four read-only surfaces stop drawing squares. Smallest visible win on the list and genuinely independent of everything else. ~0.3 sessions.
3. Card layout and the colour rule — drop KindAccent, single text column, name-first ordering with the two-line clamp, 10px radius, ring-ring for selection. Touches GovernedCanvas.tsx and card-metrics.ts only. Land after #485 so wire straightness is verifiable in the same session. ~1 session.
4. Switch arm rows — fill the grown card with one labelled 28px row per port band, retire the floating arm pills. Coordinate with PD009, which wants the same rows for split. ~1 session.
5. Canvas control cluster — fit + tidy + zoom in one bottom-left group on the canvas, Tidy always present (disabled with a reason instead of absent), live zoom readout. Overlaps #485's surfacing work — coordinate rather than duplicate. ~0.5 sessions.
6. Platform on the wire — add platform to the palette and graph-names projections, widen NameBook/PaletteResponse, stop dropping it in nameBookFromPalette. Pure API + types, no visual change yet. ~1 session.
7. Branded connector nodes — widen nep-view.ts:192, point ToolGlyph's brand branch at the platform-slug registry, add slack/discord to externalTransportKind, meta line reads Kind · Service · Target. ~1 session.
8. Connectors group in the palette — one bounded group of the seat's connected channels, each a prefilled trigger/notify. ~1 session.

P1 and P2 are independently shippable and worth shipping first. P6 is a prerequisite for P7 and invisible on its own. P5 (arm rows) and P8 (palette connectors group) are the two the owner could drop without losing the brief's intent; P2 is the cheapest visible improvement on the whole list.

Acceptance

• The same graph, screenshotted light AND dark, with every card box clearly delineated in both. One workflow, one browser session, both themes — the two images attached to neutron#482. This is the primary gate; nothing else substitutes for it.
• Wires into and out of every card in that screenshot are horizontal where the graph is a chain, including into and out of the approval and across cards of different heights — the #485 baseline still holding after the card layout changed. A slanted wire on a linear chain is a regression, not a cosmetic nit.
• No read-only surface draws a square port. Checked on all four: the workflow list card, the published-graph view, the approval preview, and the run view.
• A 4-arm switch shows four labelled rows, each row's centre on its own port, no arm label rendered loose on the canvas, and the card's height unchanged from max(112, ports × 28).
• Fit, tidy and zoom are reachable from the canvas without prior interaction. Specifically: Tidy is visible on a freshly-opened workflow that has never been dragged (disabled with a reason is a pass; absent is a fail).
• Measured, not eyeballed: --card-edge against --card-raised is ≥3:1 in dark and ≥2:1 in light, and --card-raised against --canvas-ground is ≥1.10:1 in both. Asserted for every theme template (default, catppuccin, tokyo-night, nord) × light/dark — a unit test over the parsed token values, not a screenshot.
• No status border, badge, or selection ring measures under 3:1 against the new card surface in either theme.
• ZOOM_FLOOR is still 0.86 after the redesign, and a test asserts GATE_CARD_HEIGHT ≥ 112 with the reason named. Port hit area is still 32px and the gate's four bands still tile with no gap and no overlap.
• Nothing rendered on a card falls below the shipped floors: card 190px, port hit 24px, port dot 8px, head 9px, label 10px, sublabel 9px at ZOOM_FLOOR.
• A notify to a Slack-origin channel and a channel-event trigger on a WhatsApp channel each render their brand mark, their kind hue, and a meta line naming the service — verified live, both themes.
• A notify to an internal room renders the kind glyph and no service name. A channel whose platform is unknown does the same. Neither shows a placeholder or a broken glyph.
• No card claims to send via a service. The verb stays Notify; the service appears only as provenance of the target.
• No new node kind. NepNode["kind"] still has exactly its twelve members and graph.ts's schema is unchanged, so published v1 graphs replay untouched.
• No network request for an icon. Grep the built bundle for external image or font hosts and find none; the page renders with the network disabled.

Out of scope