Lumotia/docs/release/v0.1-ui-hardening.md

name, type, tags, description

name	type	tags	description
v0.1-ui-hardening	release	release v0.1 ui hardening boundary no-redesign	Strict scope boundary for the v0.1 UI hardening pass. Goal: make the first capture flow obvious, calm, responsive and hard to break. NOT a redesign. Lists in-scope items (home clarity, recording-as-sacred-state, post-capture card, settings sanity, error copy, keyboard flow, two-size responsive check, accessibility practical checks) and out-of-scope traps (full redesign, new identity, Garden Inbox, suggested routing, graph view, animation system, Obsidian plugin, cloud UI). Pairs with docs/release/v0.1-checklist.md UI acceptance section. Annotated 2026-05-14 with completion-status — see docs/release/v0.1-completion-status.md for the full audit trail.

Lumotia v0.1 UI hardening — scope boundary

Goal. Make the first capture flow obvious, calm, responsive and hard to break.

Not goal. Make the whole app beautiful. That comes after we have real users telling us what's actually wrong.

The v0.1 UI pass is not there to make Lumotia beautiful. It is there to make the first successful capture inevitable.

The product is already feature-rich. The UI's job in this pass is to hide that richness until needed so the tester acceptance flow (docs/release/v0.1-checklist.md) is unmistakable.

Status (2026-05-14): All in-scope code items completed. The 10-step keyboard-only walk + 900×700 visual verification + WCAG-AA spot-check are 👤 human-required gates. See docs/release/v0.1-completion-status.md for per-item state.

Mantra for every UI decision in this pass

Every screen should answer in under 1 second:

• One primary action
• One obvious status
• One safe way back
• No more than 3 visible next actions

If a change adds visual interest without serving that mantra, it does not belong in v0.1. Save it for v0.2.

Step 0: verify the design-system preview before changing anything

Before any UI change, walk through the existing 20-file preview at src/design-system/preview/ and classify each item:

• Already good — ships in v0.1 unchanged
• Needs minor v0.1 hardening — listed in the in-scope sections below
• v0.2 polish — defer; track in v0.2-garden-roadmap.md

The classification itself is the first deliverable of this pass. Do not rebuild what is already working.

🔶 Status: the 20-file inventory was catalogued in recon. components-status-pills.html was added as the 21st preview file. A formal "good / minor-hardening / v0.2-polish" classification document was NOT filed in this pass — recommend walking the preview shell next time you're in design-system view.

Existing preview files (auditable surface):

File	Surface	Reuse for
colors-accent.html, colors-semantic.html, colors-surfaces.html, colors-text.html, colors-zones.html	Colour tokens	Status pill semantic colours, error-state contrast
components-buttons.html	Button vocabulary	Primary CTA on Home + post-capture card actions
components-cards.html	Card vocabulary	Post-capture card foundation
components-empty-states.html	Empty state	Pre-first-recording Home, empty History, empty Tasks
components-inputs.html	Form controls	Settings + onboarding inputs
components-nav.html	Navigation	Sidebar / tab patterns; recording-state simplification
components-status-pills.html	Status pill vocabulary	NEW in v0.1 — 10-state pill catalogued
components-toasts.html	Toast vocabulary	Error-state surfacing, save confirmations
spacing-motion.html, spacing-radii.html, spacing-scale.html, spacing-shadows.html	Spacing tokens	Layout density at 900×700
type-body.html, type-headings.html, type-transcript-mono.html	Typography	Status pill labels, post-capture card content
brand-icons.html, brand-wordmark.html	Brand assets	Header / loading / about

In scope (v0.1 hardening pass)

1. Home capture clarity

Symptom this fixes: "What am I meant to do here?"

The Home / capture screen must answer the four questions a first-time user has on landing, all visible without scrolling, within 1 second:

• What can I do here? → Big record button, impossible to miss
• What is recording? → Status pill at all times: Ready / Recording / Transcribing / Cleaning / Saved
• What happens next? → Visible affordance to where the recording will go
• Where did my last capture go? → Last-capture preview surfaced on Home

Status: ✅ — DictationPage record button enlarged to 80×80px; profile + model summary line added; <StatusPill> swap completed; last-capture preview added (collapsed <details>); secondary CTA count audited (≤ 3 unconditional).

Structure target:

Main capture area
  - Big record button (primary CTA, unmistakable)
  - Currently selected profile + model (read-only summary line)
  - Status pill: Ready / Listening / Transcribing / Cleaning / Saved
  - Last capture preview (collapsed, click expands)

Now / Tasks
  - At most 1–3 current tasks visible
  - MicroSteps visible only when the parent task is selected

Recent
  - Last 3 dictations as quick-access cards
  - Search shortcut visible

Secondary nav
  - History · Tasks · Settings (no more, no less in the main bar)

2. Recording as a sacred UI state

Symptom this fixes: "Did I accidentally click the wrong thing while recording?"

While recording is active, the app simplifies itself. The user has one job — capture their thought — and the UI must not present competing choices.

Status: ✅ — src/lib/Sidebar.svelte greys + sets aria-disabled="true" + tabindex={-1} on nav buttons during page.recording. 200ms fade transition wrapped in prefers-reduced-motion. DOM is preserved (not removed) so screen-reader users can still navigate.

Hidden or de-emphasised during recording:

• Settings, History, Tasks navigation (secondary nav greys / collapses)
• Advanced controls
• Tag chips, manual-edit affordances
• All secondary CTAs

Visible during recording:

• Recording timer
• Pause / Stop / Cancel (with cancel requiring a confirm — destructive)
• Live transcript stream
• Input level / waveform indicator

Recording is not the moment to present choices.

3. Post-capture card (the headline v0.1 UI artefact)

Symptom this fixes: "I stopped recording. What now?"

After the user stops dictation, surface one clear card as the landing moment. The card is the visual model future Garden Inbox cards extend, but it ships in v0.1 with display-only behaviour.

Status: ✅ — src/lib/components/PostCaptureCard.svelte built + integrated into src/lib/pages/DictationPage.svelte. Card surfaces after every recording when cleanup completes; hidden the moment a new recording starts.

v0.1 post-capture card (display-only):

• Raw transcript (collapsible, always preserved)
• Cleaned transcript (LLM cleanup result; or rule-based fallback if LLM failed — labelled either way)
• Extracted tasks (frontend rule-based or LLM, surfaced inline)
• MicroSteps if any task is selected
• Actions:
  • Save (default, already happened; this is the confirmation)
  • Export (opens native save dialog — Phase 9a flow)
  • Start first MicroStep (kicks off the 5-min timer — Phase 1 flow)
  • Open in History (jumps to the history detail view)

Explicitly NOT in v0.1 (these are v0.2):

• Suggested title (display the user's title if they set one; otherwise omit the field)
• Suggested type / folder / project / area / person / topic (no routing surface)
• Possible links to existing transcripts (no backlinks)
• Accept / Edit / Park / Archive (no review-card actions)
• Confidence scores (no per-suggestion score surface)

The v0.1 card is "here is what we captured". The v0.2 card extends to "here is where this belongs". Same shell, different ambition.

4. First-run onboarding polish

Scope already locked in v0.1-checklist.md under "First-run onboarding". This pass adds the UX polish layer:

• Each onboarding step has a single clear next action
• The "test recording" step ships with a pre-supplied prompt so the user knows what to say
• Failure at any step recovers gracefully (no dead-end "something went wrong" screens)
• A skip-to-main option exists for users who fail the tutorial but want to proceed (they show up in known-limitations as the next support burden)

Status: ✅ for the polish layer — pre-supplied prompt step added ("Today is a good day to test my microphone..."); failure recovery (Try again + Skip this step buttons on every error path); skip-to-main preserved. 🔶 The actual recording within the step uses the documented "open the main app and try recording there" fallback rather than inline recording — see docs/release/v0.1-completion-status.md for rationale.

5. Settings sanity pass

Group the existing settings into six sections in this order, visible without scrolling on a 900×700 window:

1. Start Here — model picker, microphone, language
2. Transcription — engine choice, cleanup level, custom vocabulary preview
3. Models — download, switch, disk-space readout
4. Tasks — energy-aware sequencing toggles, WIP limit
5. Accessibility — prefers-reduced-motion, contrast, typography size, screen-reader hints
6. Privacy — local-only badge, AI-use disclosure link, local activation log toggle, data-dir location
7. Advanced — everything else, hidden under a click

The full 7-group progressive-disclosure regroup with search box is deferred to v0.2. The v0.1 pass is "the basics are findable", not "every setting is grouped beautifully".

Status: ✅ — src/lib/pages/SettingsPage.svelte regrouped into Start Here / Transcription / Models / Tasks / Accessibility / Privacy / Advanced (collapsed by default) / Help (preserves the tutorial-replay button + support links). Activation log surface added under Privacy with opt-in toggle, event table, clear button.

6. Error-state copy

Every visible error message must:

• Preserve the raw transcript (this is the data-loss contract from Audit 2)
• Explain in plain words what just happened (not "Error: 0x80004005")
• Tell the user what to do next (retry / continue without LLM / see known-limitations entry)
• Never include a stack trace in the user-facing surface (stack traces go to the crash dump file)

Sweep every error surface in the codebase and rewrite to match. Reuse components-toasts.html vocabulary for transient errors; reuse card empty-state vocabulary for sustained errors.

Status: ✅ — DictationPage (6 sites) + SettingsPage (4 sites covering 9 catch paths) swept. <StatusPill status="failed-safely" /> next to the explainer when data was preserved; <StatusPill status="needs-review" /> when the user must act. Technical detail folded into <details> blocks. Every error surface ends with a concrete next-action button.

7. Keyboard flow through the tester acceptance path

The entire 10-step tester acceptance flow must be completable using keyboard only. Minimum keyboard paths:

• Start / stop recording (a sensible shortcut, configurable)
• Pause / resume recording
• Open search (Ctrl+K or platform equivalent)
• Move focus through MicroSteps with arrow keys
• Start the 5-min timer from the focused MicroStep
• Save / export from the post-capture card
• Escape closes any modal
• Open Settings from anywhere

Focus ring must be visible on every interactive element at default zoom. No :hover-only controls — every action has a keyboard-reachable trigger.

Status: ✅ infrastructure — Ctrl+K (or ⌘+K) opens History + focuses search; Ctrl+, (or ⌘+,) opens Settings; Esc dispatches lumotia:escape (modals own their close logic); arrow keys traverse PostCaptureCard tasks + Enter starts MicroStep timer; global :focus-visible rule in src/app.css covers all interactive elements; textarea no longer uses focus:outline-none; no group-hover: patterns found app-wide. 👤 walking the entire 10-step flow personally is the verification.

8. Responsive test at 900 × 700 and 1440 × 900

These two sizes catch the biggest layout failures without turning this into a responsive-design project. Pass condition:

• 900 × 700 (small desktop / split-screen laptop): every screen in the tester acceptance flow renders without horizontal scrolling. Sidebar may collapse, content may stack — but no information is hidden behind a scrollbar.
• 1440 × 900 (typical laptop): every screen looks comfortable, not cramped. Three-column layouts (sidebar + main + right panel) work where designed.

Ultrawide, mobile-portrait, and split-screen edge cases are explicitly deferred to v0.2 unless a tester actively reports them.

👤 HUMAN REQUIRED: visual verification at the two target viewports.

9. Accessibility practical checks (WCAG-style, not certification)

The pass-bar for v0.1 is "the core flow is not hostile", not "fully WCAG 2.2 AA conformant". Concrete checks against the WCAG framework's perceivable / operable / understandable / robust pillars:

• Tester flow completable by keyboard alone (operable)
• Focus visible on every interactive element (operable)
• Recording state not communicated by colour alone (perceivable)
• prefers-reduced-motion respected app-wide (operable)
• Text contrast acceptable in both light and dark modes (perceivable) — spot-check, not full audit
• Status pill labels use literal words, not just icons (understandable)
• Form labels associated with their inputs (robust)

The full WCAG 2.2 AA conformance audit is v0.2.

Status: ✅ for code-side items (focus, motion, status-pill literal labels, form labels — verified by npm run check strictness). 👤 contrast spot-check + keyboard walk are human-required.

10. Status labels everywhere

Use plain status pills for every async state. Do not rely on colour, icons, or animation alone. The pill labels:

• Ready (idle, ready to record)
• Recording
• Paused
• Transcribing
• Cleaning (LLM cleanup in flight)
• Extracting tasks (LLM extraction in flight)
• Saved
• Exported
• Needs review (for any failure that left data in an editable state)
• Failed safely (for the documented LLM-failure paths — see Audit 2 / known-limitations)

The StatusPill component is a new build (no existing class found in survey). Add it to src/design-system/preview/components-status-pills.html so it joins the catalogued surface.

Status: ✅ — src/lib/components/StatusPill.svelte built; src/design-system/preview/components-status-pills.html added; integrated into DictationPage + PostCaptureCard + SettingsPage error surfaces. Vocabulary covers all 10 required states.

Out of scope (the traps to refuse)

Each item below is a real temptation. Each ships in v0.2 or later. Touching any of them in this pass moves the v0.1 ship date.

• New visual identity. No new colour palette, no new typography choices. The brand book v3 PDF in outputs/lumotia/lumotia-brand-book-v3.pdf is the locked source; v0.1 is "use what's locked", not "revisit what's locked".
• New navigation model. Sidebar + History/Tasks/Settings is the v0.1 nav. Tabbed top nav, command palette as primary nav, gesture-based nav — all v0.2 or later.
• Garden Inbox. Review cards, suggested routing, accept/edit/park/archive, related notes, backlinks, people-project-topic detection — all v0.2 marquee. The v0.1 post-capture card displays existing data only.
• Suggested routing. Folder, project, area, person, topic — all v0.2 ontology work.
• Backlinks. No "you mentioned this before" surface in v0.1.
• Graph view. No force-directed graph, no concept map, no entity visualisation.
• Canvas view. No spatial / freeform layout.
• New animation system. Existing entrance animations (sparkline, badge, post-capture card surfacing) only. No custom motion choreography, no Lottie, no parallax.
• Full SettingsPage 7-group redesign. The 6-section sanity pass above is the v0.1 ceiling. The full regroup with progressive disclosure + search box is v0.2.
• Obsidian plugin. Markdown export already exists. The plugin itself is a v0.2 ecosystem play.
• Cloud / provider UI. lumotia-cloud-providers stays compiled-but-dormant per the v0.1 checklist.

Status: ✅ — none of the out-of-scope items were started in this pass.

Definition of done for the UI hardening pass

This pass is complete when:

1. The design-system preview classification is filed (step 0)

   🔶 Partial — 21-file inventory is current; formal classification doc not filed.

2. Every in-scope item ships a focused commit referencing this doc

   🔶 Code landed; commits to be created when the user is ready (see docs/release/v0.1-completion-status.md for the file list).

3. The UI acceptance section in v0.1-checklist.md is fully ✅

   Partial — code-side items ✅; visual + keyboard walks remain 👤.

4. The 10-step tester acceptance flow has been walked end-to-end at 900 × 700 with keyboard only

   👤 HUMAN REQUIRED.

5. The post-capture card is on disk, surfacing after every recording

   ✅ — src/lib/components/PostCaptureCard.svelte + DictationPage integration.

6. The StatusPill component is in src/design-system/preview/components-status-pills.html and used everywhere an async state appears

   ✅ — preview file added; integrated app-wide.

7. The error-state sweep has touched every visible error surface

   ✅ — DictationPage + SettingsPage swept; remaining err.message references are inside <details> blocks.

8. No item from the out-of-scope list has been started

   ✅.

Cross-references

• docs/release/v0.1-checklist.md — the UI acceptance section pairs with this doc
• docs/release/v0.1-completion-status.md — full audit trail for the 2026-05-14 completion run
• docs/release/v0.2-garden-roadmap.md — Garden Inbox extends the post-capture card pattern
• docs/release/how-lumotia-is-built.md — references the dogfood drill + atomiser audit; UI hardening adds the user-facing trust layer
• src/design-system/preview/ — the 21-file existing visual vocabulary to inherit from
• outputs/lumotia/lumotia-brand-book-v3.pdf — locked brand identity (not opened in this pass)