SPEC-STV-10-Mobile-UX

📜

SPEC-STV-10 · Spec header. Spec ID: SPEC-STV-10 · Title: Mobile & Desktop UX · Version: 1.0.0 · Status: Planned · Authority: Specification · Priority: P0 · Owner role: Frontend lead · Reviewers: Product architect, Backend architect · Last reviewed: 2026-05-11 · Sync targets: resources/views/**, resources/js/ui/**, docs/MOBILE_UX.md · Depends on: SPEC-STV-HUB, SPEC-STV-04 · Consumed by: SPEC-STV-03, SPEC-STV-08, SPEC-STV-11 · Conflict rule: Hub wins. · Change policy: Frontend lead + Product architect; Registry bump.

👆

Mobile editing UX → see SPEC-STV-13. This spec (SPEC-STV-10) is canonical for breakpoints, layout, performance budgets, theming, and i18n. The detailed mobile gesture system, text-selection toolbar, AI select-to-edit mobile flow, AI preview bottom sheet, mobile slash menu, page-tree drawer, public mobile reading, haptics, gesture conflict rules, and mobile a11y alternatives live in SPEC-STV-13 · Mobile Gestures & Text Selection Editor → SPEC-STV-13. On mobile-only concerns, SPEC-STV-13 wins; SPEC-STV-HUB remains constitutional above both.

1 · Breakpoints

Name	Min width	Layout
`mobile`	0	Single column, drawer sidebar, bottom action bar.
`tablet`	768 px	Two-pane: collapsible sidebar + editor.
`desktop`	1280 px	Three-pane: sidebar + editor + context panel.
`wide`	1680 px	Three-pane with wider editor max-width (960 px reading width).

2 · Desktop layout

Left sidebar (260 px) — workspace switcher, search trigger, page tree (lazy-expand children), favorites, recent, settings link.

Editor (center, max 960 px reading width) — page cover, icon, title, breadcrumb, blocks. Floating toolbar on selection. Drag handle on hover.

Right context panel (320 px) — page outline (TOC), comments, share/permissions, versions, properties when the page hosts a database.

Keyboard shortcuts — see SPEC-STV-04 §10 plus Cmd/Ctrl + \ to toggle sidebar, Cmd/Ctrl + . to toggle context.

3 · Tablet layout

Two-pane. Sidebar collapses to icon rail; expand on hover or tap. Context panel becomes a sheet that slides from the right.

Drag handle and floating toolbar still active; slash menu opens.

Soft-keyboard awareness: editor scrolls so the caret stays visible.

4 · Mobile layout

Top bar: workspace icon, page title, … menu.

Drawer (left) — page tree, opened via the workspace icon or swipe-from-edge.

Bottom action bar — search, new page, AI, share, more.

Editor — single column. Inline + button to insert a new block. Long-press a block for the drag handle and the actions sheet.

Floating toolbar — minimized to icons; opens an action sheet when more space is needed.

No columns block — columns collapse to stacked blocks on mobile.

Table block — horizontally scrollable with a sticky first column.

Database views — board, gallery, calendar each pick a touch-friendly variant; timeline becomes a horizontally scrollable list.

5 · Touch targets & accessibility

Minimum tap target 44×44 CSS px.

Focus rings visible on keyboard nav; prefers-reduced-motion respected by all transitions.

Color contrast ≥ 4.5:1 for body text, ≥ 3:1 for UI; both light and dark themes ship.

All interactive blocks expose ARIA roles; the editor uses contenteditable with announced selection changes.

6 · Mobile editor adaptations

Slash menu — replaced by a bottom sheet shown by the + button.

Drag — long-press 250 ms; haptic feedback (web Vibration API where available).

Selection — native selection handles; floating mini-toolbar above; AI button at far right.

Autosave indicator — small dot in the top bar; tap reveals last-saved time.

Offline — last successful state cached in IndexedDB; edits queued and flushed when online; conflict resolution = last-write-wins with a non-destructive merge prompt for the user when divergent.

7 · Performance budget (mobile)

Metric	Budget
First contentful paint	< 1.8 s on 4G mid-tier
Time to interactive	< 3.5 s
JS bundle (editor route)	< 220 KiB gzip initial, lazy chunks after
Image upload preview	Local preview before commit
Block render	List-virtualization above 200 blocks

8 · Theming

Light + Dark default. System preference detection; per-user override. CSS variables for surface / text / accent. No business logic in CSS.

9 · i18n

default_language per workspace.

All UI strings via lang/*.php and Vite-bundled JSON. RTL support flagged for v1.1.

10 · Empty states & onboarding

Empty workspace shows the template gallery with the 13 starter categories.

Empty page shows three suggestions (Type / Slash / Templates).

First AI use shows the preview-gate explanation.

First share shows the permissions matrix.