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
| Task | What I wanted | What I did | Result |
|---|---|---|---|
| Peek UX | Single shell + in-place push + breadcrumb stack | Keep one overlay and swap only activeDocumentId, RELATED is in-modal push, persist via onPeekContentChange on editable promotion | side/center → recursive push → editable peek, spatial context kept |
| State | Block stale intermediate frames, split cache policy on refresh | render-time reset on id change, reopen path skips or forces network | Blocks the "seemed to go back" (newId, oldContent) frame and the previous revision |
| CSS | tokens/base/blocks/chrome/print @layer split | Mechanically split the single CSS into @layer sdui-doc.*, verify byte-identical | Per-layer file split with no visual change, index/viewer entry split |
| Token | --sdui-doc-* tokens — same values, structure only into layers | Promote tokens like --sdui-doc-surface + default-value alias | Consumers can override the theme with one unlayered line |
| Publish | Include CSS entry in exports/files, verify byte-identical | Add CSS export to the manifest, note changeset minor (visual change) | Prevents an unstyled-viewer publish incident |
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
documentIdinside 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@layeralways 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.