Files

11 KiB
Raw Permalink Blame History

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 respects should_use_colors() (terminal detection), and paint() is the same with the decision passed in
  • color_text() is for the CLI's own printing only. Anything reachable from content_trim takes the decision as an argument and calls paint(), 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_decision scans this file and fails on a new caller; the allowlist is ambiguous, which builds a failed-search message for stderr
  • A function that takes an enabled flag must use it all the way down. The inline pass honoured its flag on the early return and then asked should_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_cells and metadata_value_cells return 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 now content_trim(.., false) has no escape and content_trim(.., true) still colours, which pins the flag as the only thing that decides
  • The palette is the Color enum, not a string. Color::ansi() gives the CLI its SGR sequence and From<Color> for ratatui::style::Color gives 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 how magenta came to be undefined
  • Reset color with \x1b[0m after 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 in main, restoring the default SIGPIPE disposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of making println! panic. Do not wrap prints to handle write errors and do not reinstate SIG_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, and every_status_has_a_mark pins it against status_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 own RESET
  • The strike is under the colour flag, like every other escape. A piped show carries 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, and every_status_has_a_mark is 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 to mark 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, because show prints 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 From on 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 an owner or tags label 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_cells the Tags field does, a campaign codename takes tag_color bare the way Codename does, 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, opencode and 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 because tag_color is 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. Codename in 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_COLORS slot 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 in TAG_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, because Bug and bug are 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_pinned fails 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, bug and BUG among 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;8m is byte for byte what crossterm emits for ratatui's Color::DarkGray, the grey frig and pantop use for dimmed rows