diff --git a/docs/README.md b/docs/README.md index 069ecddf..7a2ba300 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,6 +35,7 @@ This directory contains SeedPass project documentation. - `tui_v2_parity_checklist.md` - `tui_v2_parity_backlog.md` - `tui_v2_legacy_parity_matrix.md` +- `tui_v2_ui_refresh_plan.md` - `tui_v2_cutover_decision.md` - `tui_v2_large_vault_validation.md` - `security.md` diff --git a/docs/dev_control_center.md b/docs/dev_control_center.md index f3a0fd23..27dd399c 100644 --- a/docs/dev_control_center.md +++ b/docs/dev_control_center.md @@ -29,6 +29,7 @@ Use these docs as inputs, but treat this file as the decision layer: - TUI parity backlog: `docs/tui_v2_parity_backlog.md` - TUI parity checklist: `docs/tui_v2_parity_checklist.md` - TUI legacy parity matrix: `docs/tui_v2_legacy_parity_matrix.md` +- TUI v2 UI refresh plan (mockup-aligned): `docs/tui_v2_ui_refresh_plan.md` - Cutover memo: `docs/tui_v2_cutover_decision.md` - Security readiness: `docs/security_readiness_checklist.md` - Supply-chain integrity: `docs/supply_chain_release_integrity.md` diff --git a/docs/tui_v2_parity_backlog.md b/docs/tui_v2_parity_backlog.md index 01a886d1..22754bc0 100644 --- a/docs/tui_v2_parity_backlog.md +++ b/docs/tui_v2_parity_backlog.md @@ -9,6 +9,7 @@ Linked plans: - `docs/tui_v2_plan.md` - `docs/tui_v2_parity_checklist.md` - `docs/tui_v2_cutover_decision.md` +- `docs/tui_v2_ui_refresh_plan.md` ## What We Learned diff --git a/docs/tui_v2_ui_refresh_plan.md b/docs/tui_v2_ui_refresh_plan.md new file mode 100644 index 00000000..bc10e050 --- /dev/null +++ b/docs/tui_v2_ui_refresh_plan.md @@ -0,0 +1,332 @@ +# TUI v2 UI Refresh Plan (Mockup-Aligned) + +Status: Active (2026-03-02) +Branch target: `beta` +Primary references: `UI_mockups/PNG/*.png`, `UI_mockups/SeedPass_UI-Board.pdf` + +## 1) Purpose + +Translate the mockup direction into an implementation-ready, multi-session plan for Textual TUI v2 while preserving SeedPass's green visual identity. + +This plan is intentionally detailed so future sessions can continue implementation without re-discovery. + +## 2) Design Direction We Are Targeting + +From the mockups, the desired direction is: + +1. Table-first operations with high information density. +2. Persistent left "seed/account tree" navigation column. +3. Large, contextual lower "inspector board" that changes by selected entry kind. +4. Persistent bottom action strip for discoverability. +5. Strong framed layout (hard borders, segmented panels, explicit labels). +6. Black/neutral structure language, but with SeedPass green theme colors. + +## 3) Visual System Contract (Keep Green Theme) + +Use the existing TUI v2 palette as baseline (already present in `src/seedpass/tui_v2/app.py`): + +- Base background: `#080a0c` +- Panel background: `#0d1114` +- Header/footer background: `#0b0f13` +- Primary text: `#daf2e5` +- Secondary text: `#97b8a6` +- Border default: `#1a3024` +- Border emphasis: `#274533` +- Accent/action: `#2abf75` +- Focus highlight: `#58f29d` + +Rules: + +1. Keep semantic role colors stable (focus, warning, success, muted). +2. Use contrast through brightness and border weight, not unrelated hues. +3. Keep monochrome mockup geometry and spacing, but render in green palette. + +## 4) Information Architecture (Target Layout) + +Target screen structure: + +1. Top status ribbon: +- fingerprint +- managed users count +- entries count +- active kind/filter +- last sync timestamp + +2. Main split: +- Left: seed/account tree + context summary. +- Right: + - Top: search + filter controls + dense entry table/grid. + - Bottom: contextual inspector board for selected entry. + +3. Bottom action strip: +- Global shortcuts always visible. +- Context shortcuts appended for selected kind and mode. + +## 5) Interaction Model Contract + +Primary modes: + +1. Browse Mode: +- Grid-focused. +- Fast navigation/search/filter/sort. + +2. Inspect Mode: +- Inspector board-focused. +- Entry-specific actions (reveal/copy/export/edit/link). + +3. Edit Mode: +- Existing document editor/entry mutation mode. + +Behavior rules: + +1. Selected row always drives inspector board content. +2. Locked vault state must be visible in status ribbon and action strip. +3. Sensitive actions reflect state chips: +- `HIDDEN`, `REVEALED`, `COPIED`, `LOCKED` +4. If no selection exists, inspector shows onboarding or "select entry" guidance. + +## 6) Component-Level Spec + +### 6.1 Left Navigation Tree + +Goal: match mockup's persistent profile/seed hierarchy. + +Requirements: + +1. Always visible. +2. Shows active profile + managed-account context. +3. Supports keyboard traversal and selection. +4. Selection changes filter context for center grid. + +Initial fallback (if full tree data unavailable): + +1. Render static grouped sections from currently available services. +2. Keep widget contract stable so backing data can be enriched later. + +### 6.2 Top Entry Grid + +Goal: table-like view similar to mockups. + +Columns (target): + +1. Index num +2. Entry num +3. Title +4. Kind +5. Tags (truncated) +6. Date modified +7. Archive/blacklist status + +Rules: + +1. Compact row density by default. +2. Overflow truncation with consistent ellipsis behavior. +3. Sort indicators shown in header (even if only one active sort initially). +4. Keyboard row selection must stay smooth on large datasets. + +### 6.3 Inspector Board (Lower Panel) + +Goal: board-style details by entry kind, matching mockup families. + +Common board header: + +1. Entry label + kind. +2. Modified timestamp. +3. Archive/blacklist status. +4. Index/entry IDs. +5. Right-side primary action button area (`Edit`, etc). + +Common board body: + +1. Field blocks with labels. +2. Copy/export/reveal controls as command hints/buttons. +3. Notes area. +4. Tags panel (right rail when space permits). + +### 6.4 Bottom Action Strip + +Goal: persistent discoverability. + +Global segment examples: + +1. `[S]ettings` +2. `[A]dd Entry` +3. `[C]reate Seed` +4. `[R]emove Seed` +5. `[H]ide/Reveal Sensitive` +6. `[E]xport` +7. `[I]mport` +8. `[B]ackup` + +Context segment examples: + +1. Password: copy password, copy username, reveal, qr. +2. 2FA: copy code, refresh code, show qr. +3. SSH/PGP: copy public/private, export key. +4. Nostr: copy npub/nsec, show public/private qr. + +## 7) Entry-Type Board Templates (Implementation Contract) + +Each entry kind gets a formatter/template function returning a structured board text payload. + +Template priority order: + +1. `password` / `stored_password` +2. `note` / `document` +3. `seed` / `managed_account` +4. `totp` +5. `ssh` +6. `pgp` +7. `nostr` +8. `key_value` +9. fallback generic JSON board + +Per-kind minimum fields: + +1. Password/stored password: +- password (masked by default), username, url, tags, notes + +2. Note/document: +- content preview, tags, notes, file type (document) + +3. Seed/managed account: +- seed phrase hidden/reveal state, derivation/index metadata where available, tags, notes + +4. TOTP: +- current code, period, digits, secret hidden/reveal, qr support + +5. SSH: +- public key, private key hidden/reveal, export hints + +6. PGP: +- fingerprint, public key, private key hidden/reveal, export hints + +7. Nostr: +- npub, nsec hidden/reveal, public/private qr modes + +## 8) Keyboard and Command Mapping Plan + +Keep existing keybinds; add stronger discoverability and zone consistency. + +Add/confirm mappings: + +1. Zone focus: +- `1` left tree +- `2` top grid +- `3` inspector board + +2. Mode emphasis: +- `Tab` optional focus advance +- `Shift+Tab` reverse focus (if Textual behavior allows cleanly) + +3. Inspector actions: +- keep `v` reveal and `g` qr globally +- add board-level shortcuts to status/action strip text + +4. Palette aliases: +- add board/action aliases where needed to mirror strip labels. + +## 9) Delivery Plan (Phased Slices) + +## Phase 1: Shell Restructure (Layout only) + +Deliver: + +1. Split right pane into top grid + lower inspector board. +2. Add top status ribbon and bottom action strip scaffolding. +3. Keep existing data behavior unchanged. + +Exit criteria: + +1. Layout visually resembles mockup structure. +2. Existing interaction tests still pass. +3. No regression in reveal/qr/session behavior. + +## Phase 2: Grid Modernization + +Deliver: + +1. Table-style header row and compact rows. +2. Column alignment/truncation rules. +3. Sort indicator placeholders and active filter badges. + +Exit criteria: + +1. Large-list navigation remains performant. +2. Paging/search/filter actions remain deterministic. + +## Phase 3: Inspector Board Templates (Core Kinds) + +Deliver: + +1. Board templates for password, note/document, seed, totp. +2. Sensitive-state chips + action hints. +3. Context-aware action strip additions. + +Exit criteria: + +1. Selected entry shows board instead of raw JSON for covered kinds. +2. Reveal/qr flows are explicit and test-covered. + +## Phase 4: Inspector Board Templates (Advanced Kinds) + +Deliver: + +1. SSH/PGP/Nostr/key_value boards. +2. Copy/export affordance text and command parity hints. +3. Managed-account board treatment. + +Exit criteria: + +1. All major kinds render purpose-built boards. +2. No loss of existing palette command capability. + +## Phase 5: Tree Navigation and Polish + +Deliver: + +1. Left tree visual and keyboard behavior. +2. Compact vs expanded density mode. +3. Final visual polish against mockups (in green theme). + +Exit criteria: + +1. Tree + grid + board flow is coherent end-to-end. +2. User walkthrough of top daily workflows feels parity+ with legacy. + +## 10) Testing and Quality Gates Per Slice + +Mandatory per slice: + +1. Update/extend Textual interaction tests in: +- `src/tests/test_tui_v2_textual_interactions.py` +- `src/tests/test_tui_v2_action_matrix.py` + +2. Run: +- `poetry run pytest -q src/tests/test_tui_v2_textual_interactions.py src/tests/test_tui_v2_action_matrix.py` + +3. If app logic paths changed meaningfully, run: +- `scripts/tui2_coverage_gate.sh` + +4. Update docs: +- this file +- `docs/tui_v2_legacy_parity_matrix.md` +- `docs/dev_control_center.md` (if priorities shift) + +## 11) Non-Goals (for this refresh) + +1. Replacing Textual runtime stack. +2. Reworking core service/data model APIs for cosmetic UI concerns. +3. Introducing non-deterministic behavior in entry rendering. +4. Removing legacy TUI fallback before explicit cutover decision. + +## 12) Session Handoff Checklist + +Before ending any session touching this refresh: + +1. Mark phase/slice progress in this document. +2. Record what was implemented and what remains. +3. Add test evidence and known regressions. +4. Append summary to `memory-update.md`. + +Current next slice (recommended): **Phase 1 - Shell Restructure**. diff --git a/memory-update.md b/memory-update.md index b1fb60a3..47254d79 100644 --- a/memory-update.md +++ b/memory-update.md @@ -884,3 +884,20 @@ - Planning docs updated: - `docs/tui_v2_legacy_parity_matrix.md` now marks onboarding parity as implemented and clears active medium/high parity gaps. - `docs/dev_control_center.md` now reflects that the tracked onboarding/stats/session UX gaps are landed. + +## 2026-03-02 UI direction capture slice: mockup-aligned TUI v2 refresh plan +- Added a detailed multi-session implementation spec: + - `docs/tui_v2_ui_refresh_plan.md` +- Plan captures: + - visual contract preserving existing green palette + - target information architecture (left tree, top grid, bottom inspector board, bottom action strip) + - component requirements and per-entry-kind board template contracts + - keyboard/command discoverability expectations + - phased delivery plan with explicit exit criteria + - required test gates and handoff checklist for session continuity +- Linked the plan from control/index docs: + - `docs/dev_control_center.md` + - `docs/README.md` + - `docs/tui_v2_parity_backlog.md` +- Recommended next implementation slice documented as: + - Phase 1: shell restructure (layout scaffolding only, no behavior regressions).