| 1 | # Status-bar color grammar |
| 2 | |
| 3 | Status-bar ink goes through `crates/palette/src/grammar.rs` (`SemanticFamily` |
| 4 | and `ChromeInk`). Widgets use existing theme slots; they do not invent RGB. |
| 5 | The 0.10.0 direction uses five visual families per theme, with shades for |
| 6 | contrast rather than an unrelated hue for every mode and state. |
| 7 | |
| 8 | | Family | Role | Existing theme slots | |
| 9 | | --- | --- | --- | |
| 10 | | Surface | Field, plate, selection and depth | Background and selection shades | |
| 11 | | Neutral | Body, values, labels and secondary context | Body/soft/muted/hint/dim text | |
| 12 | | Action | Identity, navigation, mode, effort and context | `accent_primary` | |
| 13 | | Live | Active work and settled outcomes | `status_working` | |
| 14 | | Attention | Human decisions, permissions, warnings and failure | Existing permission, warning and danger shades | |
| 15 | |
| 16 | Five families are not five literal RGB values. In particular, warnings and |
| 17 | failures keep their existing distinct safety inks, words and symbols. Ask, |
| 18 | Auto-Review and Full Access preserve their permission ramp. A mode selection |
| 19 | never borrows failure red. Completed work shares the live hue but changes its |
| 20 | glyph and label; the display never relies on color alone to distinguish them. |
| 21 | Underwater keeps its atmospheric field while its controls follow this grammar. |
| 22 | |
| 23 | `Identity`, `Info` and `PolicyAct/Plan/Operate` resolve to the action slot. |
| 24 | `Active` and `Outcome` resolve to the live slot. Metadata retains four weights: |
| 25 | `MetadataValue`, `Metadata`, `MetadataHint` and `MetadataDim`. `Failure` always |
| 26 | resolves to the exact theme error slot; the visual grouping with Attention does |
| 27 | not turn a failure into a warning or change any permission authority. |
| 28 | |
| 29 | All selectable themes are covered by grammar and rendered selection checks. |
| 30 | Terminal-owned colors remain host-defined: an unknown contrast pair is not |
| 31 | reported as passing. ASCII symbols and reduced/still motion retain explicit |
| 32 | state labels independently of these color choices. |
| 33 | |
| 34 | ## Repo / worktree honesty |
| 35 | |
| 36 | Repository chrome is derived from Git's common directory and the cached |
| 37 | `GitStatusSnapshot` (`crates/tui/src/tui/git_status.rs`). The render path |
| 38 | never probes. The label is: |
| 39 | |
| 40 | - main checkout: `repo · branch*` |
| 41 | - linked worktree: `repo/worktree · branch*` |
| 42 | - unknown branch, known location: `repo` or `repo/worktree` (no invented |
| 43 | ref) |
| 44 | - not a git repository: omit the segment |
| 45 | |
| 46 | `*` is dirtiness. Ahead / behind stay on the same metadata string. Narrow |
| 47 | widths truncate the label by `ShellTier` and drop the segment rather than |
| 48 | wrap. |
| 49 | |
| 50 | ## Adding chrome |
| 51 | |
| 52 | 1. Use one of these families. If a fact needs a new distinction, prefer a word |
| 53 | or glyph rather than another unrelated hue. |
| 54 | 2. Reuse an existing `ChromeInk` and active-theme slot where possible. |
| 55 | 3. Check the actual foreground/background pair on the rendered surface, |
| 56 | including selection, light themes and terminal-owned backgrounds. |
| 57 | |
| 58 | Shoreline pairs glacial action blue (`#67B8D6`) with warm charcoal; its light |
| 59 | variant uses deep ocean blue (`#006684`) on warm paper. Selection surfaces |
| 60 | use the same blue family. These replace the earlier periwinkle/cobalt pair; |
| 61 | Underwater retains its existing ocean ramp and accent palette. |
| 62 |