core/ROADMAP-UI.md

Armature — v0.6.x UI Hardening Roadmap

Goal: Fix all viewport scaling, banner integration, and styling inconsistencies so Claude Code can run a meaningful automated usability survey against a stable, uniform UI.

---

Problem Inventory

P1 — Viewport & Scaling (blocks everything)

#	Issue	Where	Impact
1	Dual layout systems — base.html template has its own banner→surface→footer column; app-shell.js Preact shell has a separate sw-shell → sw-shell__body → sw-shell__surface column. They never coordinate.	server/pages/templates/base.html ↔ src/js/sw/shell/app-shell.js	Every surface inherits an ambiguous viewport ancestor.
2	Transform-based scaling is broken — transform: scale() on #surfaceInner doesn't reflow layout. Breaks getBoundingClientRect (menu.js already carries a scale-correction hack at line 20), scroll containment, pointer events, and the inverse-width/height hack (100/s%) doesn't account for banners consuming viewport space.	base.html:56-67, appearance.js:41-53, menu.js:20-33	Menus, tooltips, dropdowns all mis-positioned at any non-100% scale. Click targets wrong.
3	Banner height desync — base.html hardcodes --banner-h: 28px and renders banners in-flow. app-shell.js ShellBanner measures offsetHeight into --banner-top-height / --banner-bottom-height and uses position: fixed + body padding. Two independent banner systems.	base.html:31,72-75,103-107 ↔ app-shell.js:25-42, sw-shell.css:22-37,63-69	With banners enabled, content overflows by the banner height or gets double-inset depending on which code path is active.
4	100vh on mobile — .sw-shell, .chat-app, .chat-loading, .login-shell use 100vh which doesn't subtract mobile browser chrome (address bar, toolbar).	sw-shell.css:9, chat/css/main.css:15,25, sw-login.css:7	Content overflows on iOS Safari, Android Chrome.
5	Chat uses 100vh not 100% — .chat-app { height: 100vh } ignores parent container (which already excludes banners/footer). Notes correctly uses height: 100%. Every extension surface that copies chat's pattern will inherit the bug.	packages/chat/css/main.css:15	Chat surface overflows behind banners.

P2 — CSS Architecture

#	Issue	Where	Impact
6	Class name collisions — .settings-section defined in both modals.css:41-43 and surfaces.css:75-83 with different padding, margin, and border-bottom rules. .sw-dropdown in primitives.css:443 (styled <select>) vs sw-primitives.css:262 (custom dropdown component). .sw-tabs in primitives.css:459 vs sw-primitives.css:234.	Kernel CSS	Styles randomly win depending on load order. Bug reports differ by surface.
7	Old/new primitive duplication — Two button systems (.btn-primary/.btn-small in primitives.css vs .sw-btn--primary/.sw-btn--sm in sw-primitives.css). Two toast systems (.toast vs .sw-toast). Two dropdown, two tabs implementations.	primitives.css ↔ sw-primitives.css	No single source of truth for any component. Extension authors can't know which to use.
8	Extension CSS bleeds globally — Extension main.css loaded via <link> at document level, no scoping. Any class name can override kernel or sibling extension styles.	base.html:26-28, extension-surface.css	Package CSS fights with kernel. Two packages with .sidebar both lose.
9	No intermediate breakpoint — Only 768px mobile breakpoint. No tablet (768–1024px). Secondary workspace pane hardcoded 480px. Admin nav hardcoded 200px.	layout.css:263, surfaces.css:305	Cramped layout on iPad/small laptops.

P3 — Visual Consistency

#	Issue	Where	Impact
10	Mixed unit systems — px, rem, em used interchangeably with no rationale. Some font-sizes in px (primitives), others in rem (sw-primitives), others in em (user-picker).	All CSS files	Zoom/scale behaves differently per element.
11	Google Fonts CDN dependency — @import url(...) in variables.css:5 blocks rendering if CDN is slow; breaks entirely on air-gapped deployments.	variables.css:5	FOUT or blank page on slow networks. No offline support.
12	No spacing scale — Padding/margins are ad-hoc values (10px, 12px, 14px, 16px, 20px, 24px, 28px…). No design-token spacing scale.	All CSS	Inconsistent visual rhythm across surfaces.
13	Hardcoded fallback colors in component CSS — sw-shell.css, sw-primitives.css have inline fallbacks like var(--accent, #b38a4e) — a gold color from a previous theme that doesn't match the current blue #6c9fff.	sw-shell.css, sw-primitives.css	Wrong colors flash briefly if variables load late.

---

Roadmap

v0.6.9 — Session Lifetime Config

Make session duration admin-configurable and expose "keep me logged in" in the login UI. The cookie max-age bug is already fixed (v0.6.8 shipped with 15-min cookie vs 7-day refresh token; now both are 7 days, and the Go SSR middleware accepts expired-but-signed JWTs so JS can refresh client-side).

Step	Description
Admin session settings	Add session.access_token_ttl (default 15m) and session.refresh_token_ttl (default 7d) to the admin settings surface. Stored in the settings table, read by generateTokens(). Both values clamp to a sane range (access: 5m–60m, refresh: 1h–90d).
"Keep me logged in" checkbox	Login form gets an opt-in checkbox. When checked, the refresh token gets the full refresh_token_ttl. When unchecked, refresh token lifetime = 24h (session-length). The cookie max-age tracks whichever lifetime was chosen.
Token generation uses config	handlers/auth.go generateTokens() reads TTLs from config instead of hardcoded 15 * time.Minute / 7 * 24 * time.Hour. The expires_in field in the JSON response reflects the actual access TTL so the client schedules refresh correctly.
Idle timeout (optional)	If the admin enables idle timeout (default: off), the server checks last_activity_at on the refresh-token row. If the gap exceeds session.idle_timeout (e.g. 2h), the refresh is rejected. The client SDK pings /api/v1/auth/activity on user interaction (debounced, max once per minute).
Validation	Test matrix: default config, short access (5m), long refresh (30d), keep-me-logged-in on/off, idle timeout on/off. Background tab for >access TTL then navigate — should not redirect to login.

v0.6.10 — Viewport Foundation

Establish a single, correct layout model. Every surface must render inside one containment chain: body → shell → surface. No dual systems. No transform hacks.

Step	Description
Unify shell layout	Remove the inline <style> block from base.html that creates a parallel column layout. Make base.html render a single <div class="sw-shell"> wrapper. Banners, announcements, footer, and surface all live inside the Preact shell's flex column OR the template column — pick one, kill the other. Recommendation: keep the Go template column (it works without JS) and delete sw-shell.css's parallel layout. The Preact AppShell becomes a component that renders inside #surfaceInner, not a viewport-level container.
Banner single source of truth	One banner rendering path. Template banners (base.html:72-107) set --banner-top-height and --banner-bottom-height via a <script> that measures after DOMContentLoaded. Remove ShellBanner's JS measurement. Surfaces use calc(100vh - var(--banner-top-height) - var(--banner-bottom-height)) or pure flex containment — not both.
Replace transform-scale with CSS zoom	CSS zoom is now supported in all evergreen browsers (including Firefox 126+, June 2024). zoom actually reflows layout — getBoundingClientRect returns correct values, scroll containers work, pointer events are accurate. Remove all transform: scale() code from base.html, appearance.js, menu.js scale-correction hacks. Apply zoom on #surfaceInner. The sw.shell.getScale() API becomes a no-op returning 1 (or reads getComputedStyle().zoom).
Fix 100vh → 100dvh	Replace all height: 100vh with height: 100dvh (fallback: height: 100vh; height: 100dvh;). Affects: sw-shell.css, sw-login.css, chat/css/main.css.
Chat 100vh → 100%	.chat-app and .chat-loading use height: 100% like Notes. They inherit their height from the extension mount container which is already correctly sized.
Validation	Manual test matrix: banner on/off × scale 80%/100%/150% × mobile/desktop × light/dark. Every surface (admin, settings, team-admin, docs, welcome, notes, chat). No overflow, no gaps, menus positioned correctly.

v0.6.11 — CSS Deduplication

Kill the old primitive system. One class per concept.

Step	Description
Audit collision inventory	Script that finds all duplicate class selectors across kernel CSS files. Produce a machine-readable collision report (JSON).
Migrate .settings-section	Remove modals.css:41-43 definition. The surfaces.css definition is authoritative. Modals that used the old styles get explicit overrides scoped to .modal .settings-section.
Retire primitives.css old components	.btn-primary, .btn-small, .btn-danger, .btn-full → migrate all usages to .sw-btn--*. .toast-container / .toast → migrate to .sw-toast-container / .sw-toast. Old .popup-menu → migrate to .sw-menu. Old .sw-dropdown (styled select in primitives.css) → rename to .sw-native-select or delete if unused. Old .sw-tabs / .sw-tab-btn in primitives.css → delete (sw-primitives.css version is authoritative).
Mark deprecated classes	Any remaining old classes get a /* DEPRECATED v0.6.11 — use .sw-btn--* */ comment and a 1-version grace period for package authors.
Package CSS audit	Scan all packages/*/css/main.css for references to deprecated kernel classes. Fix in-tree packages.

v0.6.12 — Extension CSS Isolation

Prevent extension CSS from leaking into the kernel or sibling extensions.

Step	Description
Scoping strategy	Two options: (A) @scope (.extension-mount[data-ext="slug"]) — CSS @scope is supported in Chrome 118+, Firefox 128+, Safari 17.4+. (B) Prefix enforcement — package CSS linter rejects selectors that don't start with .ext-{slug} or [data-ext="{slug}"]. Recommendation: (B) prefix enforcement. @scope support is still patchy; prefix enforcement works everywhere and is trivially lintable.
Linter	scripts/lint-package-css.sh — shell script using grep/awk. Runs in CI. Accepts .ext-{slug} or [data-ext="{slug}"] prefixed selectors only. Exempts :root, @keyframes, @font-face, and @media wrappers.
Kernel CSS contract	Document which kernel classes are stable public API for extensions to reference (.sw-btn--*, .sw-input, .sw-field, .sw-dialog, .sw-toast, .sw-menu, .sw-tabs, CSS variables). Everything else is internal. Publish in docs/EXTENSION-CSS.md.
Migrate in-tree packages	Add data-ext attribute to extension mount container. Prefix all in-tree package CSS. Verify no visual regressions.

v0.6.13 — Responsive & Spacing

Fill the gaps between mobile and desktop.

Step	Description
Tablet breakpoint	Add @media (min-width: 769px) and (max-width: 1024px) rules. Secondary workspace pane: 360px (from 480px). Admin nav collapses to icon-only at this breakpoint. Settings nav: 180px.
Spacing scale	Define spacing tokens in variables.css: --space-1: 4px through --space-8: 64px (4px base, doubling). Migrate hardcoded padding/margin values to tokens. Priority: surfaces that users see on every session (sidebar, topbar, admin content areas).
Font-size scale	Define --text-xs: 0.75rem through --text-xl: 1.25rem (5 stops). Migrate all font-size declarations. Remove em-based sizes (user-picker) and bare px sizes.
Secondary pane responsive	workspace-secondary.open width uses clamp(320px, 35vw, 560px) instead of fixed 480px.

v0.6.14 — Visual Polish

Systematic cleanup of stale values and rendering artifacts.

Step	Description
Purge stale fallback colors	Remove all var(--foo, #hexvalue) fallbacks that reference old gold theme colors (#b38a4e and variants). If a CSS variable is undefined at this point, that's a bug — don't mask it with a wrong fallback.
Self-host fonts	Bundle DM Sans and JetBrains Mono woff2 files in src/fonts/. Replace Google Fonts @import with local @font-face declarations. Zero external font dependencies.
Light theme audit	Walk every surface in light mode. Fix any remaining hardcoded dark-mode colors, contrast issues, or invisible borders. Document any surface-specific light-mode overrides.
Consistent border-radius	Surfaces currently mix 6px, 8px, 10px, var(--radius), var(--radius-lg). Audit and reduce to 3 values: --radius-sm: 4px, --radius: 8px, --radius-lg: 12px.

v0.6.15 — Usability Survey Gate

Make the UI machine-auditable so Claude Code can run an automated survey.

Step	Description
UI inventory manifest	scripts/generate-ui-inventory.sh — walks kernel CSS + package CSS, extracts every rendered class, groups by surface, outputs ui-inventory.json. Fields: {surface, component, classes, file, line, responsive_breakpoints, spacing_tokens_used, font_size_tokens_used}.
Contrast checker	Script that parses variables.css light/dark token pairs and checks WCAG AA contrast ratios for all text-* on bg-* combinations. Outputs pass/fail report.
Component coverage matrix	Markdown table: each kernel primitive (button, input, dropdown, dialog, toast, menu, tabs, avatar, spinner, tooltip, drawer, banner) × each surface that uses it. Identifies surfaces still using deprecated old-style components.
Touch target audit	Script that finds all <button>, [role=button], clickable elements across templates and JS, checks for min-width/min-height ≥ 44px on mobile breakpoint.
Claude Code survey prompt	docs/USABILITY-SURVEY.md — structured prompt template that Claude Code can execute against the codebase. Sections: viewport correctness, banner integration, responsive behavior, styling consistency, accessibility basics (contrast, touch targets, focus indicators), component uniformity. Each section has pass/fail criteria and file paths to inspect.
Survey dry-run	Run the survey. Fix anything it catches. Tag v0.6.15 only after clean survey.

---

Sequencing Rationale

v0.6.9  Session Lifetime Config ← Cookie bug fix already shipped; make TTLs configurable
  ↓
v0.6.10 Viewport Foundation     ← Everything depends on correct containment
  ↓
v0.6.11 CSS Deduplication       ← Can't audit styling until there's one source of truth
  ↓
v0.6.12 Extension CSS Isolation ← Scoping requires the kernel CSS to be stable first
  ↓
v0.6.13 Responsive & Spacing    ← Spacing tokens need stable class names to attach to
  ↓
v0.6.14 Visual Polish           ← Final visual pass after structure is locked
  ↓
v0.6.15 Usability Survey Gate   ← Machine-audit the finished product

Each version is independently shippable and testable. No version depends on anything after it.

---

What "Usability Survey by Code" Means

The v0.6.15 deliverables give Claude Code (or any automated tool) three things:

1. A structured inventory (ui-inventory.json) of every component, on every surface, with its CSS file and line number.

2. Automated checks (contrast, touch targets, token usage) that produce machine-readable pass/fail reports.

3. A survey prompt (USABILITY-SURVEY.md) with explicit criteria and file paths, so Claude Code can cat the relevant files, run the scripts, and produce a scored report without human guidance.

The survey is not a substitute for real user testing — it's a structural quality gate that catches the class of bugs (overflow, contrast, misalignment, inconsistent styling) that have historically slipped through.