Summary
We recently improved edge visuals by making connections heavier and adding circular endpoint caps at each node border anchor. The remaining unresolved product/design question is how those endpoint caps should behave when node stacking conflicts with edge readability.
Problem
Right now, endpoint caps are rendered in the same layer as the edge path. That means if another node visually sits above the connection point, the cap is occluded.
There are two competing truths here:
- Spatial truth: node stacking should win, so a node on top hides anything underneath.
- Graph readability: connection endpoints should remain visible, especially for active/selected relationships.
If we force all caps above all nodes, the graph becomes more legible, but we break depth honesty. Caps from buried connections can float above unrelated nodes, which will look wrong as the canvas becomes denser.
Proposed direction
Use a hybrid layering model:
- Default state: edge paths and caps respect node stacking and remain below nodes.
- Interaction state: promote caps (and optionally connected edge stroke) only for contextually important edges, such as:
- edges connected to the selected node
- edges connected to a hovered node
- edges connected to a node currently being dragged
This keeps the canvas spatially honest by default while still surfacing important graph relationships when the user actually needs them.
Why this is the right trade-off
- Preserves clean depth semantics in normal browsing.
- Avoids noisy floating caps from unrelated hidden edges.
- Improves usability during interaction, which is when endpoint visibility actually matters.
- Scales better visually as the canvas gets denser.
Suggested implementation shape
- Split the current edge rendering into separate concepts if needed:
- base edge path layer
- base cap layer
- promoted/active cap layer for selected or hovered relationships
- Introduce an explicit notion of “active edge” derived from UI state.
- Keep styling token-driven so promoted edges still respect light/dark theme.
Acceptance criteria
- Base edge caps remain below normal node content.
- Caps for active/selected/hovered/drag-relevant edges are visually promoted above competing nodes.
- Promoted edges are clearly legible in both light and dark themes.
- The layering rule is documented so future graph styling stays consistent.
Summary
We recently improved edge visuals by making connections heavier and adding circular endpoint caps at each node border anchor. The remaining unresolved product/design question is how those endpoint caps should behave when node stacking conflicts with edge readability.
Problem
Right now, endpoint caps are rendered in the same layer as the edge path. That means if another node visually sits above the connection point, the cap is occluded.
There are two competing truths here:
If we force all caps above all nodes, the graph becomes more legible, but we break depth honesty. Caps from buried connections can float above unrelated nodes, which will look wrong as the canvas becomes denser.
Proposed direction
Use a hybrid layering model:
This keeps the canvas spatially honest by default while still surfacing important graph relationships when the user actually needs them.
Why this is the right trade-off
Suggested implementation shape
Acceptance criteria