Modal peek stack and a CSS-layer package

What this covers

I raised the peek flow — entering a document from a gallery card — from side → center → recursive push → editable peek, and split the one big lumped-together editor.css into a @layer + design token structure so consumers can override the theme. I organize this task by task — for each, the situation, the goal, how it was solved, and what I learned.

Day summary

1. Nested modal document navigation

Background (concepts)

• Peek / nested modal navigation: a UX that keeps only one overlay window (dialog) and digs into documents by swapping the documentId inside it. It doesn't open a new window each time.

What the situation was

When gallery → peek → related page continues, opening a new modal/route at each depth stacks focus traps, scroll locks, and animations. If (newId, oldDoc content) paints for one frame during async document resolve, the user feels they "went back." If a peek reopen right after refresh is cache-first, the previous revision may show again.

Core work

Keeping one overlay and swapping only the internal activeDocumentId preserves spatial context. On readOnly → editable promotion I persist via onPeekContentChange, and RELATED links are handled as in-modal push (not a new tab). On id change, a render-time reset blocks the stale intermediate frame, and the reopen path splits the cache policy with skip or force network. router.back()/popstate is incompatible with view transitions, so explicit stack pop + URL push is safe. As a result I kept spatial context all the way from side/center → recursive push → editable peek.

Lesson

• peek is a document-stack UX — it's boundary design, not appearance.
• An async resolve hook must block stale immediately on id change — a "brief old document" is a UX bug.
• refresh + cache-first splits into skip or force network on the reopen path.
• On an E2E drag failure, separate the baseline first and distinguish product vs. simulation limits.

→ Nested modal document navigation

2. Layered CSS package

Background (concepts)

• Cascade layer (@layer): a feature that ranks priority tiers on CSS rules. A rule put inside @layer always loses to a consumer rule that isn't in a layer (unlayered) — regardless of the usual selector specificity.
• specificity: the reckoning that decides which CSS rule wins for the same property. Without layers, only this specificity fight remains.
• design token: values like color and spacing named as CSS variables like --sdui-doc-*. Consumers make a theme by changing only the values.

What the situation was

A single editor.css makes fork, theming, and viewer-only bundles all hard, and if the consumer's custom CSS is outside a layer, only a specificity war remains. If the CSS export is missing from the npm publish manifest, consumers get an unstyled viewer.

Core work

I mechanically split the lumped-together single CSS into @layer sdui-doc.* and promoted tokens like --sdui-doc-surface. After verifying that the result of splitting by section and re-joining is byte-identical to the original — proving "no visual change" — I wrote the consumer override recipe in the README. Key rule: all package CSS goes inside a layer, the consumer theme overrides it with one unlayered line. The problem where a rule was wholly invalidated because --sdui-doc-surface wasn't defined, I caught with a default-value alias. I added the CSS export to the manifest and left a changeset minor (visual change) note to prevent an unstyled-viewer publish incident.

Lesson

• A CSS split is a cascade-priority UX — it's boundary design, not appearance.
• Layer splitting isn't "changing values," it's structural work that opens up consumer override possibility.

→ CSS cascade layers theming

Derived knowledge

• Nested modal document navigation
• CSS cascade layers theming