Skip to content

docs(design): selection bubble, quick insert and slash menu design - #124

Merged
6 commits merged into
mainfrom
docs/bubble-quick-insert-design
Nov 17, 2026
Merged

6 commits merged into
mainfrom
docs/bubble-quick-insert-design

Conversation

@HMarzban

Copy link
Copy Markdown
Contributor

Summary

This is a design for the owner's review: the selection bubble, quick insert and the "/" menu. It has an audit of today's UI, research, a spec with owner decisions, and a clickable prototype. It is documentation only; no app, server or test code changes.

References:

  • The owner's first reference is not TinyDocy. Its UI strings ("Make page wide", "Page is wide") match Claude's Docs viewer.
  • The second reference is Notion's panel and "/" menu.
  • Both are used only as interaction references.

Decisions to approve (spec §2), highest leverage first

  1. O11: one row, not a vertical panel (recommended). Notion's panel covers 6–9 lines of the text being formatted, and it is how AI "skills" lists grow. One row borrows the panel's best parts: Tx top level, a Turn-into face word, Comment in its own group, Recent colours first.
  2. O1: one "Turn into" Style ▾ in the bubble. Its face shows the current type (Text / H2 / List / Mixed / Title 🔒). It includes headings, lists, quote and code, instead of separate H ▾ and List ▾ menus.
  3. O2: named colour rows on every desktop surface (bubble and row), in two columns with Recent first. Phones keep the 44 px grid, with a pill that names each colour applied.
  4. O12 and BQ9: "/" menu amendments.
    • A Suggested section from recent insert kinds, local only.
    • An inline "Type to search" ghost; focus never leaves the editor.
    • A footer with a Markdown tip and Close · esc.
    • "New" badges that expire by date or on first use, with no storage.
  5. BQ2 (phase 0): the bubble stops calling registerPlugin from its lazy chunk. Today's React <BubbleMenu> breaks the AGENTS rule and rebuilds every plugin view after the chunk lands.
  6. O4: no reactions in v1.
    • O3: 💬 trails the bubble, only where canComment() is true.
    • BQ7: no AI slot.
    • O9: page width goes in ⋯ › View, not quick access.
    • O5: a + on the empty line instead of a desktop bottom pill.
    • O6: a phone Insert sheet.
    • O7: the bubble on keyboard selections only after Shift is released.
    • O8: touch-tablet stand-ins get words.
    • O10: one motion token.

What the reviews corrected

Three independent reviews (UX, UI and accessibility, staff engineering) ran on the first draft. All their findings are folded in. Three of my own claims were wrong or overstated:

  • The registerPlugin cost is real but modest. Measured: 0 of 29 plugin views were reused, and updateState took 0.5 ms. But EditorContent already rebuilds the views on every tab switch. The bubble adds one late rebuild; it is not a performance problem.
  • The claim that a darker bubble edge meets 1.4.11's 3:1 was withdrawn. oklch(0.80) on white is 1.87:1. 1.4.11 now rests on the focus ring (7.8:1) and the pressed bar, and the dark bubble gets its own surface.
  • The link popover's side is fixed by the @docs.plus Hyperlink package. In v1 it opens below the selection, never over it. Changing the side is a request to the package.

Screenshots

Today Proposed
Today's bubble Proposed bubble
Today's colour popover Named colour rows with hover preview
Today's slash menu Slash with ghost, Suggested, footer
Today's phone Insert dropdown Phone Insert sheet
Turn into O11 b panel (not recommended) Dark colour RTL "/"
Turn into menu Vertical panel option Dark colour menu RTL slash menu

Not in this PR

  • No product code. Implementation waits for approval, then a superpowers:writing-plans plan (spec §15, phases P0–P5).
  • Toggle and Date blocks are out of scope (BQ5); they need a schema addition.
  • Reactions are not in v1 (O4).

Test plan

  • Current-state screenshots from next dev: Chromium; desktop 1280 px, phone 390 and 320 px, tablet 820 px; light and dark.
  • The registerPlugin claim was measured with a temporary Playwright probe, which is not committed.
  • The prototype was driven headless through 25 states with no console errors, and every screenshot was checked.
  • UX, UI/accessibility and staff-engineering reviews; all findings folded in.
  • Owner review of the decisions in spec §2.
  • UI/UX review gate: for the docs, this PR; for each visible implementation phase, its own PR.

🤖 Generated with Claude Code

Audit of today's bubble, Insert, "/" and phone surfaces with screenshots,
research across eight editors and the platform guidance, and a design
for owner review: owner decisions O1-O12, the bubble without
registerPlugin, the "/" menu amendments and a phased plan.
A clickable throwaway prototype with a switch for each owner decision,
theme, RTL, reduced motion and device, plus its screenshots.
@HMarzban HMarzban closed this pull request by merging all changes into main in 29f6faf Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant