11 KiB
11 KiB
Colour
The palette, what each colour means, and the rule that keeps one layout for two renderers.
Color and Output
- Use
color_text()for coloured output — it respectsshould_use_colors()(terminal detection), andpaint()is the same with the decision passed in color_text()is for the CLI's own printing only. Anything reachable fromcontent_trimtakes the decision as an argument and callspaint(), because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes.nothing_the_body_renders_asks_the_terminal_for_the_colour_decisionscans this file and fails on a new caller; the allowlist isambiguous, which builds a failed-search message for stderr- A function that takes an
enabledflag must use it all the way down. The inline pass honoured its flag on the early return and then askedshould_use_colors()for the bold run, which made the flag a lie in half the function. The better answer, where it fits, is to take no flag:ordered_cellsandmetadata_value_cellsreturn the colour rather than a decision about it - A test that asserts an absence has to be paired with one that asserts the presence. The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so
should_use_colors()was false and the leaking branch was never taken. The pair is nowcontent_trim(.., false)has no escape andcontent_trim(.., true)still colours, which pins the flag as the only thing that decides - The palette is the
Colorenum, not a string.Color::ansi()gives the CLI its SGR sequence andFrom<Color> for ratatui::style::Colorgives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is howmagentacame to be undefined - Reset color with
\x1b[0mafter colored text - Bold uses
\x1b[1;35m(magenta bold) - Always test color output works correctly in both terminal and pipe modes
quiet_broken_pipe()runs first inmain, restoring the defaultSIGPIPEdisposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of makingprintln!panic. Do not wrap prints to handle write errors and do not reinstateSIG_IGN; the exit codes are documented in the README
Color Guideline
- UUID → red (31)
- Status → orange (33)
- Timestamp → cyan (36)
- Title → green (32)
- Unknown values (
_None_,_Not set_) → grey (38;5;8) - Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
- Relation kind mark → brightred
×blocked by and blocks, cyan→relates to, orange←regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking - Relation status mark → grey
○backlog, orange◐committed, cyan◐reviewing, green●done, grey●discarded, grey?for a target the board does not hold. Discarded takes the full circle of done in the grey of the untouched pile: nothing is left to do, and it is not an achievement. The pair is what has to be unique, which is the same bargain the two half circles already take, andevery_status_has_a_markpins it againststatus_dirs. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. Green is here and deliberately absent from the priority ramp, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show - Relation row to a discarded target → struck through, the whole row. The one thing in the palette that is not a colour, and it is here because the status mark cannot carry it: that mark is one cell in a column of five states, so a row pointing at abandoned work reads as a live dependency, which is exactly what it is not. The strike says the relation no longer stands for anything while the row stays on the ticket, for completeness and for the case the target is moved back out of discarded. Only discarded: a done target still stands for the fact that it was a blocker, and a
_missing_one says something different again, that the row cannot be resolved at all. Gutter and padding included, so the line runs unbroken from the label to the end of the title, and every cell opens its own SGR 9 since each is closed by its ownRESET - The strike is under the colour flag, like every other escape. A piped
showcarries none of it, the same bargain committed and reviewing already take for being told apart by colour alone, and the board draws it as a style instead. Do not answer the pipe by changing the glyph in the mark column: the pair there has to stay unique, andevery_status_has_a_markis what says so - Markdown link → cyan, markers and url kept. Not a new meaning for the colour: the plan numbers, the criterion numbers and the
relates tomark are already cyan inside a rendered body, and a link is the same kind of thing, a pointer the reader may follow rather than a value. The url is not hidden behind the text the way a renderer would hide it, becauseshowprints to a terminal worklane cannot assume will make it clickable, and a link whose target cannot be read is worse than a long line - Chrome → grey. A rendered
[ ], the overlay's page indicator and the frame's. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level - A key name → cyan, and bold; what pressing it does → the default foreground. The one place the palette spends a colour on something that is not a value: a key is what a reader is hunting for on a row they otherwise skip, and with the key merged into its description the colour is the only thing saying which letter to press. Not a second meaning for the timestamp's cyan in any place the two could be confused — nothing on the footer, the prompt or a border hint holds a value at all — and it is the accent frig draws the same row in, which is the point. Grey stays on the chrome around it: the page indicator, and the row's gaps
- Chrome → grey, in the history block too: the kind label at the head of a mechanical row, and the
Fromon a comment's author line. Both name their row rather than holding a value, which is what grey already says. The label was orange, which means Status everywhere else, so anownerortagslabel claimed a meaning belonging to the value beside it - A value in the history block takes the colour it has in the metadata table three lines above. A status is orange, a tags entry goes through the same
tag_cellsthe Tags field does, a campaign codename takestag_colorbare the wayCodenamedoes, and_Not set_,_None_and_missing_are grey. An owner stays plain: a person's name is the one value the palette has no meaning for, and spending a colour on the field that needs it least is how a colour stops meaning anything. The block's job is to be scanned, and it is not worth scanning if it has a palette of its own to learn first - History actor → its name through
tag_color, the way a campaign codename is. Not a new meaning for a reserved colour but the existing use of the tag slots, a name that groups rows: one writer is one colour in every entry it wrote, so a reader sees who has been working a ticket without reading the same name four times.claude,opencodeand a person each get their own - History timestamp → cyan, and its own span. It shared one with the actor while the two were formatted as
name (time), which spent the timestamp's colour on a name. The parentheses are plain: they are punctuation, not chrome with something to say - Campaign label → its codename through
tag_color, bold, marked~. The colour is what groups a campaign across the cards that carry it, which is exactly what a tag's colour is for, and one word is one colour in every view becausetag_coloris a pure function of it. The mark and the bold are what tell it from a tag on a row that holds both: the mark is not#, or the row would read as a list of tags with a stranger in it, and not@, which reads as a person on every board anyone has used.Codenamein a metadata table takes the colour without the mark, since the field name has already said what it is - Campaign label with no codename → grey. The label is then the short id, and grey keeps a reserved meaning off a
TAG_COLORSslot in the one case where it would land on one: red is the uuid's everywhere else, and grey already means what a reader skips, which is what a campaign with no codename has to say for itself - The palette splits in two: seven colours that each mean one thing, and
TAG_COLORS, the eight a tag may be drawn in. A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour inTAG_COLORS, and do not draw a tag in one outside it tag_color()is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, becauseBugandbugare two different tags to the field and to every search- The hash is FNV-1a written out here, not
DefaultHasher. std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for.the_tag_mapping_is_pinnedfails on any change to it, so a repaint is a decision rather than a surprise - The index is multiply-shift, not
% TAG_COLORS.len(). The length is a power of two, so a modulus keeps only the low three bits of the hash, and FNV-1a's low bits carry only the low bits of the input bytes: multiplication cannot move information downwards. Under a modulus every pair of tags differing above bit 2,bugandBUGamong them, landed in one slot regardless of the rest of the string. It looked like a good palette on this board, two colliding cards out of sixty-four, because the vocabulary had been folded into a handful of slots. Taking the top bits of a 128-bit product uses the whole hash - Eight tag colours means roughly one card in five shows two tags alike. That is arithmetic and is accepted: the colour groups a tag across cards, it does not tell two tags apart within one, and the tag text is beside it either way. Do not widen the list to chase the number on one board
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground.
\x1b[38;5;8mis byte for byte what crossterm emits for ratatui'sColor::DarkGray, the grey frig and pantop use for dimmed rows