Should I distinguish different levels of dashed areas

[michael]

Maybe use different colors, or different sizes.

[michael]

The issue is that users of my test group couldn't easily find the "main insertion" points, like where you have the full range of node types available.

@keybits suggested that we somehow visualize different levels of dashed areas (now lines) so there's the primary level (node insertion points at body level) and lower-level ones. His idea was different colors for top-level vs. lower-level gaps.

@johannesmutter wtdy?

[johannesmutter]

The root of this issue comes down to a fundamental design choice: the philosophy of structure versus the philosophy of flexibility. Or, the classic "Notion (atomic blocks)" versus "Sanity/Structured CMS (strict schema)" dilemma.

In a world of structured nodes with multiple properties (like a StoryNode), we run into spatial and semantic constraints. A Hero node inside a Button node makes no visual or semantic sense. This necessitates strict rules about where certain types of nodes are allowed. But these rules inevitably confuse the user: why can't I paste this node here? or why does this node type not appear as an option?

In a purely flexible system with single-property nodes, this issue does not exist because the nodes are atomic and compose without rules. But we know that approach brings its own set of huge problems…

So how do we fix the user's confusion about where nodes are allowed?

Definitely not by using colors for differently styled gap markers. Color belongs to the user's content. Introducing a variety of shades will just create readability issues, add distraction, and fail the 4 to 8% of users who are color blind. The editor UI must be made of subtle shades of gray, reserving pops of color strictly for where focus is needed, like selections or a blinking cursor.

Also, we should not encode this knowledge into different line patterns. Icons are already hard to decode, and abstract patterns are on another level of difficulty. Gap markers are supposed to recede into the background, not act as the figure. If you encode information in them, you are forcing them to be readable, which contradicts their purpose as a subtle background element. Lastly, gap markers sometimes span an area of just 1 by 20 pixels. That is simply not enough space to communicate which node types are allowed.

See e.g. Figma: they have already exhausted the visual options with two colors and line vs. hazard stripe pattern

Here are a few ideas that could actually work:

Smart Insert Menus
Consider adding a slash / command menu or a + insert button. When opened, do not hide the nodes that are restricted in the current context. Instead, show them but render them as disabled or grayed out. If a user clicks or hovers over a disabled "Story" option while inside a "List Item", show a tooltip or automatically move their selection to the closest ancestor where that node type is allowed. The user's intention is clear: they want that node. They just need a gentle push to find the right spot. Don't block them.

Visual Scope Indicators (Breadcrumbs)
When a user is deeply nested (for example, inside Story > DescriptionArray > Button > Label), they lose track of their context because the UI just looks like text. You could add a super slim bottom toolbar that renders a flattened branch of the selection hierarchy. It could optionally indicate what node types are available. Similar to the iA Writer bottom bar or the macOS Finder path bar, breadcrumbs educate the user about how deep into a hierarchy they are. Depth is a great intuitive indicator for how limited the choice of node types gets. Users will learn this pattern in the first 3 minutes of using your app. Top level: all nodes allowed. Level 2: a few. Level 3: only text.

...

I'm sure there are more options, but leaving it here

…

iA Writer bottom toolbar:

macOS Finder path bar:

[michael]

Yeah i'm also not a fan of adding colors.

You mean we could have some sort of status bar, as you select node gaps, they'll highlight available node types?

I'm not sure for editable website specifically that I'd want the classic "list of available content types", not only it takes screen space but it's also hard to describe the types in words. you really need to see them, hence that's why i went with that type/layout cycling. once you clicked ENTER on a node gap, we'd need to show some UI to cycle through the types and layouts (if available). maybe we can collect ideas for that, and experiment within the svedit repo (for a future release - not now)

---

however the main issue that Tom pointed out remains. Take this situation for instance:

it's hard to tell apart the gaps at the root level and the nested ones. It's clear how i will add content after "Build with blocks", but it's almost impossible to see that this full-width-dashed line is where you can insert entirely new "main blocks". a slight visual difference would already help (like 3 +++ instead of 1, bad idea just as an example). so before the user "investigates" what's behind this particular dashed line we need to "promote" it better than the nested gaps.

[johannesmutter]

… Depth is a great intuitive indicator for how limited the choice of node types gets …

I think we could visualise how many levels deep a node gap is, directly on the dashed line. Like an outliner tree, but in 2D only

---

Also instead of just rendering a + plus, one could render a tiny icon for the types of nodes that can be inserted. I already prepared NodeGapMarkers for this, so developers can pass a different symbol. The icon could either indicate the actual node type e.g. a T for Text, or it could indicate a size group e.g. (full slice/ large: hero, story — medium: heading, image — small: text, buttons)

Inside Svedits NodeGapMarkers.svelte:

/* Centered insertion symbol (default mask renders a plus). */
&::after {
	content: '';
	position: absolute;
	width: var(--node-caret-symbol-size, 6px);
	height: var(--node-caret-symbol-size, 6px);
	top: 50%;
	left: 50%;
	transform: translate(-50%, -50%);
	background: var(--node-caret-symbol-bg, var(--node-caret-gap-color, var(--svedit-canvas-stroke)));
	mask: var(--node-caret-symbol-mask,
		linear-gradient(black, black) center / 100% var(--node-caret-symbol-stroke, 1px) no-repeat,
		linear-gradient(black, black) center / var(--node-caret-symbol-stroke, 1px) 100% no-repeat
	);
}

[johannesmutter]

it's hard to tell apart the gaps at the root level and the nested ones.

Just this issue could be also solved with different stroke width, different levels of indentation, …

I think we need to experiment here and explore a number of directions, considering various scenarios, contexts, the presence or absence of spacing, background colors, etc.

Also need to untangle the issues here: binary question about wether its a root node vs nested; and the issue of available node types (not necessarily linked with the hierarchy issue)

[johannesmutter]

You mean we could have some sort of status bar, as you select node gaps, they'll highlight available node types?

I meant primarily a status bar to visualise the selection depth, either semantic with node types and their labels, or purely visual (flattened tree).

[michael]

I like the basic idea of visualizing "depth" - that's a useful indicator to users, but it shouldn't get technical like writing out "Level 3" or something. As you say - needs experimentation.

Wouldn't like to use symbols as it doesn't scale (should be possible to have like a large number of node types). And editable website in particular i want developers to add new node types without having to think of a lot of things (e.g. adding an icon). I think it's generally a nice design constraint to design without icons, maybe we should even consider removing them in the Svedit demo.

That said, for certain apps it makes perfect sense to have icons if you have a fixed set of node types and the icons are your visual language. Just not for editable website (and possibly svedit?).

[michael]

Also need to untangle the issues here: binary question about wether its a root node vs nested; and the issue of available node types (not necessarily linked with the hierarchy issue)

root node vs nested as a backup if we don't succeeed visualize depth generically.

issue of available node types is a separate issue yes.

discoverability of "next type" and "next layout" again a separate issue

[johannesmutter]

Wouldn't like to use symbols as it doesn't scale (should be possible to have like a large number of node types). And editable website in particular i want developers to add new node types without having to think of a lot of things (e.g. adding an icon)

Very good point. We don't want to put Stoplersteine in sb.'s way.

A thought I had was that icons could map to stable svedit primitives: NodeArray, AnnotatedText, and maybe root vs. not root (though I think that's not a good candidate to be visualised via an icon)

[michael]

There might be a sweet spot. I suppose bold/italic/link toggles are good candidates for icons in a bottom floating toolbar (like we have it). But maybe we can do the whole node type / layout dance in a scalable way. Perhaps inline up/down/left/right buttons - with the challenge of interferring with selection, i already had problems with the link preview / editor overlays.

Anyways would be cool to experiment with that in Svedit one or another PR, and see what works.

[keybits]

Thanks for looking into this - fascinating to read the thoughts of both of you who have been deep in this for some time!

For new users of EW specifically, I still feel that just distinguishing the root node as different would help people get started. Agree about not using colours, so perhaps just a heavier dash of some kind would be helpful.

I realise that's not a full solution and trying out options like you've discussed would be valuable, but for the current EW distinguishing the root node could a quick UX improvement.