docs/UX.md sets the visual and interaction rules every change must meet. ROADMAP.md gains a goal and done-when criteria for each phase.
- commit
- 4626856f1a364dee3432ee909ef030a7fa316ce9
- parent
- 37ada28630b125f132343927477190ec537d2ab8
- author
- Dami <dami.etoile@gmail.com>
| M | ROADMAP.md | 13 | ++++++- |
| A | docs/ | 63 | ++++++++++++++++++++++++++++++ |
@@ -2,7 +2,18 @@
22 33 Principles: keyboard first, 1-2-3 muscle memory stays the default, the main44 binary stays pure Go (`CGO_ENABLED=0`), and every feature ships with unit5-tests plus a libghostty e2e test.5+tests, a libghostty e2e test and reviewed golden screens. Visual and UX6+quality keep pace with features: see [docs/UX.md](docs/UX.md).7+8+## Goals9+10+| Phase | Goal | Done when |11+|---|---|---|12+| 1 | The engine can do everything 1-2-3 R2 users reach for daily, and every change can be undone | Undo/redo covers every mutation; /Copy, /Move, /Worksheet Insert and Delete adjust relative and absolute references; /Range Format and range names work and persist; date and finance functions match excelize on a differential test suite |13+| 2 | Finding and using features is faster than in any terminal spreadsheet | Ctrl+P palette reaches every command with its key shown; formulas autocomplete with signature hints; the status line shows live stats of the pointed range; precedents and dependents are visible and jumpable; titles freeze; search and filter work; fill down and series work; a vim keymap is available |14+| 3 | one23 uses the terminal it's running in to the fullest, and degrades gracefully | Copy and paste ranges through the system clipboard; charts render as images in Ghostty/kitty and as text elsewhere; URLs are clickable; error cells are marked beyond color; cursor shape reflects the mode; the theme follows light and dark |15+| 4 | Data moves in and out of one23 without friction or cgo | CSV/TSV, XLSX, SQLite, Parquet and Lotus .wk1 import, with export where it makes sense; large imports show progress; the binary still builds with `CGO_ENABLED=0` |16+| 5 | one23 goes where 1-2-3 couldn't | Multiple sheets with cross-sheet references; derived frequency and pivot sheets; recorded and Starlark macros; an SSH server mode; opt-in decimal arithmetic; VHS demo tapes in CI |617 718 ## Phase 1: engine foundations (unblocks everything else)819 @@ -0,0 +1,63 @@
1+# UX and visual bar2+3+Features don't merge unless they meet this bar. Visual quality is not a4+follow-up task.5+6+## Principles7+8+1. **1-2-3 muscle memory is the default.** `/` menus with first-letter9+ selection, POINT mode, F2/F5, label prefixes. New power is added10+ alongside, never by breaking these.11+2. **Everything is discoverable.** Every action is a registered command12+ (`internal/ui/commands.go`) with a title and one-line description. It is13+ reachable from the slash menu where 1-2-3 would put it, from key bindings14+ in `keymap`, and from help (generated from the registry). When the15+ command palette lands, it lists every registered command with its keys.16+3. **The screen always says what's going on.** The mode indicator is always17+ correct. The third panel line tells the user what keys do in any18+ non-READY state. Prompts live on the second panel line.19+4. **Never lose work.** Destructive actions warn when there are unsaved20+ changes and are undoable once undo exists. Errors are specific21+ ("expected , or )" with the cursor on the spot), never generic.22+5. **Esc backs out one level; Enter confirms.** Everywhere, no exceptions.23+24+## Visual rules25+26+- Style only through `theme` roles (`internal/ui/theme.go`). No inline27+ `lipgloss.NewStyle()` in views. Need a new role? Add it to `theme` with a28+ comment saying what it's for, in both the dark and light variants.29+- Use the 16 ANSI colors so the user's terminal palette applies. No30+ hard-coded RGB.31+- Text on a colored background needs about 4.5:1 contrast against both32+ reference palettes (`e2e/palette_test.go`). Check it in the gallery.33+- Never rely on color alone: state also shows as text (mode indicator,34+ `[modified]`, `ERR`, `CIRC`).35+- Numbers right-aligned, labels left unless prefixed, headers centered.36+ Menu items separated by two spaces. Keys shown as `F2`, `Ctrl+Z`, `Del`37+ (see `keyLabel`).38+- Layout works from 60x16 up to very wide terminals. Nothing jumps39+ position between frames; overlays don't shift the grid.40+- Render only what's visible. A keystroke on a 10,000-cell sheet must feel41+ instant.42+43+## Required with every user-facing change44+45+- [ ] Registered command(s) with title and description; key binding in46+ `keymap` if it has one; menu entry where 1-2-3 would have it.47+- [ ] Unit tests in `internal/ui` driving `Update`, plus engine tests.48+- [ ] An e2e test in `e2e/` for the main flow.49+- [ ] Golden screen(s) in `e2e/screens_test.go` for every new visual state,50+ with a `-light` variant if it introduces new colors.51+- [ ] `make screens`, then look at `e2e/testdata/screens/gallery.html`52+ (serve it over HTTP and screenshot it, or open it in a browser).53+ Fix anything misaligned, low-contrast, cramped or clipped before54+ committing.55+- [ ] README keys table updated if keys changed.56+57+## Review checklist for screenshots58+59+- Is the mode indicator right? Does line 3 explain the keys?60+- Is anything clipped at 60 columns?61+- Can every piece of text be read in both palettes?62+- Does the new element look like it belongs: same spacing, same roles,63+ same capitalization as the rest?