| 1 | # TUI redesign — ocean depth / Workbench index |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | Fresh 0.10.0 terminal installs use **Underwater**, the restrained navy ombré. |
| 6 | Shoreline remains the warm charcoal alternative; saved theme choices are |
| 7 | preserved. `/theme` previews either treatment, Enter saves, and Escape restores |
| 8 | the previous choice. The same layout, whale mark and information hierarchy |
| 9 | serve both themes; the ocean is a continuous background, not extra chrome. |
| 10 | |
| 11 | Shoreline is the terminal's warm charcoal, ivory and blue visual system, |
| 12 | introduced on 2026-09-15 to bring the TUI closer to the GPUI product client. |
| 13 | The 2026-09-19 Workbench index pass organizes that system around the next |
| 14 | useful action: start work, resume a session, or inspect connected tools. |
| 15 | The founder delegated the visual direction and explicitly allowed replacing |
| 16 | the previous appearance when it improved the experience. |
| 17 | |
| 18 | The home screen uses a compact codewhale identity, version metadata aligned |
| 19 | opposite it, and one bounded reading lane centered in wide terminals. Actual |
| 20 | workspace and branch context make the screen specific to the current work. |
| 21 | A prominent New session action and a Recent heading for real history organize |
| 22 | the available choices. A compact canonical braille whale accompanies the identity when |
| 23 | space permits, yielding before session titles and actionable rows in short |
| 24 | terminals. The canonical brand asset is unchanged. The full-width |
| 25 | composer, shared session runtime, permission authority and website design |
| 26 | remain their existing systems. The terminal default does not change app defaults. |
| 27 | |
| 28 | This document describes implemented terminal behavior, not the website's |
| 29 | Tidal Folio system. Source owns values and actions; this file records how |
| 30 | they form a coherent interface. |
| 31 | |
| 32 | ## Colors |
| 33 | |
| 34 | Underwater's continuous water column is authored by `OceanRamp::for_theme` in |
| 35 | `crates/tui/src/tui/ocean.rs`: dark navy at the top, deeper near the composer. |
| 36 | Its existing motion policy preserves reduced/still modes and semantic surfaces. |
| 37 | |
| 38 | For the charcoal alternative, the source of truth is `crates/palette/src/tokens.rs` and the |
| 39 | `SHORELINE_UI_THEME` / `SHORELINE_LIGHT_UI_THEME` mappings in |
| 40 | `crates/palette/src/themes.rs`. The dark palette is unchanged by the |
| 41 | Workbench index pass: |
| 42 | |
| 43 | | Role | Value | Use | |
| 44 | | --- | --- | --- | |
| 45 | | Field (`surface_bg`) | `#211F23` | Warm charcoal reading surface | |
| 46 | | Plate (`panel_bg`, `composer_bg`) | `#2B282E` | Composer and raised surfaces | |
| 47 | | Elevated | `#35313A` | Hover and secondary control surfaces | |
| 48 | | Chrome (`header_bg`, `footer_bg`) | `#1A181C` | Recessed shell information | |
| 49 | | Border | `#49424D` | Quiet boundaries and inactive composer | |
| 50 | | Body | `#F2ECE5` | Primary ivory text | |
| 51 | | Soft / muted / hint / dim | `#D9D2DC` / `#B0A7B2` / `#9A919F` / `#7E7583` | Secondary information by role | |
| 52 | | Action / selection background | `#67B8D6` / `#2C4654` | Affordances and focused rows | |
| 53 | | Live | `#7FD6C6` | Live activity | |
| 54 | | Human | `#F6C453` | Human input and decisions | |
| 55 | | Warning / danger / success | `#F0A868` / `#FF8FA8` / `#A3D977` | Semantic state | |
| 56 | | Mode ramp | `#7EB4E8` / `#B9DCEC` / `#AD88FF` / `#FF70A0` | Existing mode distinctions | |
| 57 | |
| 58 | Shoreline Light uses warm paper (`#F5F0E9` field) and blue action |
| 59 | (`#006684`); its full mapping remains in the same source. Neither this pass |
| 60 | nor the Shoreline token family re-inks `web/app/tokens.css`. |
| 61 | |
| 62 | **Focus uses selection ink on selection blue.** Bright action blue is an |
| 63 | accent, not a background for pale text. Selected labels, affordances and |
| 64 | state annotations must remain readable on the selected surface. Failure, |
| 65 | permission and availability also retain words or marks; color never supplies |
| 66 | their only meaning. |
| 67 | |
| 68 | Theme remapping keeps direct palette calls consistent with the active preset. |
| 69 | The mode ramp remains distinct from the action lane so semantic remapping |
| 70 | continues to work in reduced-color terminals. Contrast audits are |
| 71 | role-specific: the existing audit requires 4.5:1 for its primary text pairs |
| 72 | and 3:1 for hint/dim/status/diff pairs. A passing theme audit is not proof |
| 73 | that an arbitrary component foreground/background combination is safe. |
| 74 | |
| 75 | ## Typography |
| 76 | |
| 77 | The terminal host owns the font, size and rasterization. There is no separate |
| 78 | application display face. Hierarchy comes from bold identity and selection, |
| 79 | regular body text, secondary metadata, and spacing between groups. |
| 80 | |
| 81 | Home shows session titles and age; message counts stay in session details. |
| 82 | An empty workspace omits the Recent section. Titles take priority over age. Width calculations |
| 83 | and truncation use terminal display cells, including wide characters; omit |
| 84 | metadata before reducing a useful title to a stub. Longer labels receive an |
| 85 | explicit truncation marker rather than silently running under a border. |
| 86 | |
| 87 | ## Layout |
| 88 | |
| 89 | The home screen is the transcript's launch empty state, implemented by |
| 90 | `underwater::launch_empty_state`. Identity and actions share a lane capped at |
| 91 | 72 text cells, centered when the terminal is wider, with a two-cell action |
| 92 | gutter where width permits. Version metadata aligns to the opposite edge of |
| 93 | the identity row. The workspace caption uses the real workspace and adds its |
| 94 | actual branch only when it fits. Command help follows recent work and MCP; |
| 95 | optional top breathing room consumes spare space only. There is no permanent |
| 96 | mascot column or additional navigation sidebar. The composer remains full width. |
| 97 | |
| 98 | The compact ladder removes spacing first, then migration notice and MCP |
| 99 | detail, then help, workspace context and identity headings, before shortening |
| 100 | the recent list. |
| 101 | Hidden sessions remain reachable through the overflow action while space |
| 102 | allows it. The MCP summary survives longer than its per-server detail. At |
| 103 | extreme dimensions, New session is the final action retained. The painted |
| 104 | row list is also the keyboard and mouse ordering: shrinking the terminal |
| 105 | cannot leave an invisible recent session selected. |
| 106 | |
| 107 | Shared full-screen settings geometry lives in `views::render_underwater_surface`. |
| 108 | At fewer than 24 rows it removes outer vertical margins and top padding; |
| 109 | bottom padding is zero. Horizontal outer margins disappear below 44 columns. |
| 110 | These are shared layout decisions, not separate compact implementations for |
| 111 | each settings page. Config's option editor only expands its header when |
| 112 | three choices plus detail still fit. Model/Thinking panes stack when narrow; |
| 113 | in short stacked layouts the inactive pane becomes one clickable summary |
| 114 | and the focused pane receives the remaining space. |
| 115 | |
| 116 | **Keep the two footer owners until their interactions migrate together.** |
| 117 | The posture/activity row in `phase_strip` carries permissions, mode, work |
| 118 | navigation and transient state. The metrics row in `ui/frame.rs` carries |
| 119 | route, model, context and cost information with its own user configuration |
| 120 | and pointer targets. A one-row merge was an earlier proposal, not the |
| 121 | implemented design. Hiding metrics would remove model/context interactions |
| 122 | unless their measured targets and configuration migrated in the same slice. |
| 123 | The Workbench index deliberately retains both rows and their shedding rules. |
| 124 | |
| 125 | ## Elevation & Depth |
| 126 | |
| 127 | The terminal uses tonal surfaces and cell borders. The composer is a plate |
| 128 | above the field; an inactive outline recedes without making the input vanish. |
| 129 | Full-screen settings use restrained top and bottom rules. Protected-focus |
| 130 | modals retain the existing terminal-cell shadow and border treatment. |
| 131 | There are no new glow, blur, texture or decorative motion effects. |
| 132 | |
| 133 | ## Shapes |
| 134 | |
| 135 | Actions are measured rows and rectangular controls sized in terminal cells. |
| 136 | Their painted area is their pointer target. Home actions share a leading |
| 137 | marker, keyboard selection uses a continuous filled band and bold text, |
| 138 | and hover uses the elevated surface with an underline. New session has a |
| 139 | quiet plate fill before focus; Recent's trailing rule separates the list |
| 140 | without enclosing each session in a box. Pointer hover does |
| 141 | not silently move keyboard selection. Borders and glyphs use the terminal's |
| 142 | existing vocabulary, including its reduced-capability fallbacks. |
| 143 | |
| 144 | ## Components |
| 145 | |
| 146 | ### Home and composer |
| 147 | |
| 148 | Typing begins through the existing composer. Up/Down and Enter navigate and |
| 149 | activate visible home rows; clicking a recent row enters the same resume |
| 150 | flow. The MCP summary opens the existing manager by mouse or keyboard. A |
| 151 | problem row inserts its stated remedy into the composer so the user can see |
| 152 | it before submission. No separate command or session authority is introduced. |
| 153 | |
| 154 | The composer outline uses action blue only while the composer owns focus. |
| 155 | Selecting a home action or opening another surface returns it to the quiet |
| 156 | border tone. Permission and mode retain their own footer status instead of |
| 157 | being repeated in a multicolor composer outline. Model metadata remains |
| 158 | secondary to the message and its controls. |
| 159 | |
| 160 | ### Resume confirmation |
| 161 | |
| 162 | Resuming names the target session and explicitly states that its history |
| 163 | replaces the current context. Warning and button space are reserved before |
| 164 | the title and metadata; long titles truncate to one line and cannot push the |
| 165 | consequence under a button. Both Resume and Cancel are real mouse targets. |
| 166 | Tab, BackTab or Left/Right switches selection; Enter activates the selected |
| 167 | button and its visible hint moves with selection. Escape always cancels. |
| 168 | An outside click dismisses and never confirms. |
| 169 | |
| 170 | Successful restoration announces the sanitized session title through a |
| 171 | localized success toast, using the existing status-toast owner. The string |
| 172 | is supplied in all 15 locale packs. It no longer appends a filesystem path, |
| 173 | session ID and message-count receipt to the restored transcript, so compact |
| 174 | terminals return their space to the conversation. |
| 175 | |
| 176 | ### Settings and pickers |
| 177 | |
| 178 | - **Models:** one provider context row retains catalog freshness without a |
| 179 | duplicate route banner. Only the focused pane receives the filled blue |
| 180 | selection; the inactive pane retains its current-choice marker. Hover |
| 181 | covers the measured row. Compact hints prioritize browsing, searching, |
| 182 | switching, applying and canceling; secondary bindings remain available. |
| 183 | - **Providers:** ordinary management uses the full-screen shell regardless |
| 184 | of configured-provider count. Initial setup, credentials and consent keep |
| 185 | their modal flows. The borderless inspector shares the list's canvas and |
| 186 | keeps provider identity, credential source, route, endpoint, concise warning |
| 187 | lines and consent facts ahead of model choices and prices. The underlined, |
| 188 | clickable Open details action and shared Alt+V shortcut (⌥V on macOS) |
| 189 | open the existing scrollable pager. That projection retains every warning |
| 190 | and the full protocol/capability diagnostics rather than crowding them into |
| 191 | the overview. Escape returns to the provider manager. |
| 192 | - **Provider choice stages:** Kimi plan tier, Stepfun billing route, xAI auth |
| 193 | and ChatGPT auth choices use wrapping, measured selectable rows. A first |
| 194 | click selects through the existing key action; a second click activates |
| 195 | through the existing Enter action. This does not change billing, consent |
| 196 | or credential policy. Key entry, custom-provider text fields and final |
| 197 | credential/consent confirmations retain their existing keyboard behavior. |
| 198 | - **Extensions:** tabs and inventory rows share selection and independent |
| 199 | hover styles. Plugins initially selects the first actual item when one |
| 200 | exists; group headings remain reachable for folding. Inventory rows carry |
| 201 | identity and state, while the selected description/details have a separate |
| 202 | wrapping area of three rows when space permits, one otherwise. Resize |
| 203 | clears stale hitboxes before an invisible panel can retain actions. Trust, |
| 204 | enablement and removal continue through existing guarded flows. |
| 205 | - **Fleet:** the compact roster header has a genuine Workers destination, |
| 206 | reachable by mouse and the existing keyboard action. The decorative Setup |
| 207 | pseudo-tab is gone. Setup/edit belongs to the selected real member; the |
| 208 | display-only Coordinator does not advertise an Enter action it cannot run. |
| 209 | Navigation rows preserve identity, role, shadow and edit markers, adding |
| 210 | route text only for explicit overrides. Repeated inherited-route sentences |
| 211 | and species mosaics no longer tax every row; the selected inspector retains |
| 212 | full member identity, route and detail with quiet inline property labels. |
| 213 | - **Config:** category tabs and Apply use the shared selection treatment. |
| 214 | Selected row annotations inherit readable selection ink instead of keeping |
| 215 | dim or action-colored text over the selection band. |
| 216 | |
| 217 | ### Camera readability and evidence |
| 218 | |
| 219 | The founder's acceptance criterion includes pictures and video: recognizable |
| 220 | identity, clear hierarchy when reduced, stable composition during interaction, |
| 221 | and consistent state colors. The compact wordmark, repeated action gutter |
| 222 | and shared selection treatment serve that criterion. Extra ornament is not |
| 223 | evidence of camera readability. |
| 224 | |
| 225 | The validation set is 40×12, 60×16, 80×24, 100×32 and 140×40: populated home, |
| 226 | MCP failure, selection, resumed conversation, long-title confirmation and |
| 227 | Cancel selected, plus representative settings surfaces and provider details. |
| 228 | Use fresh evidence for the exact source/binary being delivered; earlier |
| 229 | captures do not qualify a later presentation slice. The capture method |
| 230 | reconstructs actual PTY cells and their RGB/SGR state with Menlo and Apple |
| 231 | Color Emoji fallback. These images are not screenshots of the host terminal |
| 232 | and do not prove host font behavior. Static frames do not prove motion, |
| 233 | transition timing or video quality. |
| 234 | |
| 235 | The saved conversation and failing MCP server in this evidence are synthetic |
| 236 | local fixtures, not customer sessions or working-provider claims. Passing |
| 237 | interaction tests demonstrates those tested paths; it does not establish |
| 238 | provider success, installation, hosted CI, publication or whole-release |
| 239 | readiness. Symbol-only goldens cannot validate color. Use color-preserving |
| 240 | PTY evidence and the contrast audit alongside layout/interaction checks; |
| 241 | record exact build and installation receipts separately. |
| 242 | |
| 243 | ## Do's and Don'ts |
| 244 | |
| 245 | - **Do** preserve useful content before spacing, branding and secondary hints. |
| 246 | - **Do** share geometry between painting and input, and clear targets on resize. |
| 247 | - **Do** keep keyboard selection, pointer hover and consequential state distinct. |
| 248 | - **Do** reserve consequence text before decorative or variable-length content. |
| 249 | - **Do** check long titles, wide characters, compact choices and selected text |
| 250 | on the surface where users actually read them. |
| 251 | - **Don't** restore a large launch mark at the expense of session-title width. |
| 252 | - **Don't** hide footer owners or turn decorative labels into apparent controls. |
| 253 | - **Don't** invent new tokens, runtime owners or permissive mutation paths to |
| 254 | implement a visual treatment. |
| 255 | - **Don't** describe reconstructed cells as host screenshots or static captures |
| 256 | as motion proof, and don't imply every settings subview gained mouse parity. |
| 257 | |
| 258 | |
| 259 | ## Working-screen performance readings (2026-09-20) |
| 260 | |
| 261 | TTFT and output rate reuse the existing session accumulator. The compact footer |
| 262 | keeps selected performance readings when they fit, shedding secondary counts |
| 263 | and help first. `/statusline` offers separate Time to first token and Output |
| 264 | rate controls with immediate preview, Enter to save and Esc to restore. Old |
| 265 | `session_metrics` settings continue to enable both and become separate choices |
| 266 | when edited. Full, compact and hidden row settings remain in `/config`. |
| 267 | |
| 268 | The motion focal point remains the shared activity marker: request progress, |
| 269 | verification and completion use one cadence and the existing bounded completion |
| 270 | settle. Numbers stay still between measured receipts, preserving legibility on |
| 271 | video. There is no synthetic live speed counter, new timer or extra footer row. |
| 272 | Reduced and still motion retain the same readings and explicit phase words. |
| 273 | TTFT is a session average; throughput includes first-token wait and stream |
| 274 | pauses, but excludes tool/idle gaps. Missing measurements stay absent. |
| 275 | |
| 276 | |
| 277 | ## Identity, theme and motion refinement (2026-09-20) |
| 278 | |
| 279 | Claude Fable 5.1 reviewed real terminal-cell captures and current motion source. |
| 280 | The founder explicitly chose a brief whale reveal: the canonical braille mark |
| 281 | resolves through nested dot masks over 360 ms, once from its first launch paint. |
| 282 | Text and controls are complete immediately. Typing, paste or resize settles the |
| 283 | mark; reduced/still motion shows the complete asset immediately. This reuses the |
| 284 | existing frame scheduler and requests no reveal frames after the endpoint. |
| 285 | |
| 286 | Completion keeps the word Done stable while its existing glyph settles. Generic |
| 287 | working status uses a direct verb. The send control uses action ink only when the |
| 288 | same predicate used by its click handler permits submission; otherwise it is dim. |
| 289 | Locked model rows retain readable keyboard focus and their availability warning. |
| 290 | New session uses body ink on its filled plate to meet text contrast in light and |
| 291 | warm themes. Uwu now participates in the same remapping as other named presets. |
| 292 | |
| 293 | Themes are being checked against five color families: surface, neutral text, |
| 294 | action, live/outcome, and attention/danger. Shades preserve contrast and severity; |
| 295 | labels and symbols retain meaning without color. Underwater keeps its ambient |
| 296 | identity within the same chrome discipline. Nonempty NO_COLOR selects monochrome |
| 297 | output: terminal-owned foreground, background, and underline colors, preserving |
| 298 | text modifiers and selection symbols. ANSI16 remains a distinct colored fallback |
| 299 | for terminals with a limited palette. |
| 300 |