feat(ui): theme-driven redesign of all three panels

[stanlyzoolo]

Implements docs/plans/design_handoff_keepkit_redesign, plus the theming pre-work that handoff asks for first, and a second pass over the result read on a real terminal.

Theming

internal/ui/theme.go — Theme, ten semantic color roles plus the gauge's dim track. styles.go — every package-level var XxxStyle becomes a field of Styles, built by the single NewStyles(Theme). The model holds one and reads it through m.sty().

Result: no hex literal below internal/ui, grep 'ui\.[A-Z][A-Za-z]*Style\b' empty, and switching every color in the app is switching one value. glamour's readme theme and ui.PlaceOverlay take the theme too, so nothing is left behind on the old palette. TestStylesBuildFromTheme fails if any field is built from something other than its Theme.

The roles retire ColorCategory/ColorKey/ColorMuted — what they marked is carried by weight, Emphasis and the new Surface background.

One palette is deliberately not a set of roles: ui.LanguageColor (lang.go) holds linguist's per-language brand colors, and a theme switch must not repaint them. Theme is keepkit's vocabulary of meanings; these are somebody else's marks, and the whole value of a cyan dot beside go is that it is the cyan the reader has already seen on every repo page.

Panels

[1] tools — right-aligned version column (signal + ↑ when behind, ok + • on keepkit's own row), section headers lead with their label, the grouped view opens with an updates section that cuts across the tags, the title carries the tracked and outdated counts.

[2] brief — the six label: value lines become a metrics strip (installed / latest / maintenance / stars as captioned columns on Surface, each cell centered in its column, re-flowing to fewer columns on a narrow panel), then the language stack as the card's one picture — a named list with a colored dot per language and a full-width proportional band under it — then a one-line meta row where an empty note or tag offers the key that fills it. The changelog gains a heading with the version transition and the release link.

[3] readme — the preprocessor drops the leading H1, and the slogan under it when it repeats the repo description the card already prints. glamour headings lose their reprinted ## markers; body text takes the same Text role the card's changelog notes render in, and both code blocks and inline code get the Surface plate.

Status bar — one global key list in every focus instead of three per-focus ones; what is panel-local moved into that panel's footer. Key hints lost their brackets. The right corner names the running build.

Keymap

Per the handoff: # edits tags, R renames, t/u/R are global, and enter is each panel's primary action — run in [1], update in [2]. That is what freed t/u/r from their per-focus meanings and let the status bar go global.

u on the card is gone; enter does it. r is unbound in [1] rather than gaining a third meaning.

Defects found reviewing the diff (dde55b3)

1. changelogHeading compared installed and latest as raw strings while printing both through DisplayVersion, so a tool reporting 1.10.2 against a v1.10.2 tag — up to date — got a v1.10.2 → v1.10.2 arrow. Gated on hasUpdate now.
2. metricsStrip sized its columns from the widest caption alone, so ✕ not installed rendered as ✕ not insta at the 80x24 baseline. Sized by the widest value too; the two version-less installed states become one word each.
3. The meta line's language bar wrapped internally on a multi-language repo, which breaks the line's arithmetic — lipgloss.Width measures a multi-line cell by its widest line, not by the footprint it occupies. Cut to one line with a …. (Superseded by the second pass: the languages are their own block now and are emitted outside the cell-wrapping loop, so there is no cell to break.)

Second pass (adbf9e1)

Six refinements from reading the redesign on a real terminal, and two defects that reading turned up.

A gutter in [2] and [3]. One blank column at both ends of everything the two panels draw. Content that touches the border it lives in reads as having overflowed it, and on the right that column is also what keeps text off the scrollbar thumb. Two single definitions own the budgets — the new cardWidth() and the amended helpWrapWidth() — and indentLines applies the indent last, to whole finished lines: plain spaces outside the styling can never split an escape sequence, they land in front of the metrics plate's background segments rather than inside them, and an indent cannot shift a line index, so buildCard's clickable-link map stays correct for free.

Centered metrics. Each cell is centered in its column, odd slack to the right. A caption and the value under it are one measurement; flush-left hung them off a rule that was nowhere near either.

The language stack becomes a picture. languages heads its own list, separated from the first language by the same middot that separates two of them; only the dot carries color, in GitHub's own hue, and a full-width band under the list holds the same shares, closed by a blank row so the band reads as an edge rather than an underline. The band normalizes over the languages actually listed — summed over the repo's total it would leave a gap standing for languages the card never named — hands out one cell per language before distributing the remainder by largest fractional part, and uses ▬ (U+25AC) rather than a full block, which measures two cells under RUNEWIDTH_EASTASIAN=1.

The running build in the bar's corner. That corner held a third copy of the pending-updates count — the [1] title carries it beside the tracked count and every outdated row carries its own ↑ — while the version had no surface outside an overlay. When a newer release is known and still uninstalled the version takes the signal role and the same ↑ an outdated tool row carries, so the app announces its own update in the vocabulary it announces everyone else's. selfCompactCell drops the name it was repeating and keeps only the action (U update / U restart); the two are governed by the same gate, so the action can never appear without its subject beside it.

Readme body and inline code speak the card's language. Body text moves to the Text role — the very one the card's changelog notes use — and inline code reads exactly like a code span there: Emphasis on the Surface plate. Danger was wrong twice: red is the card's one alarm color and a README spends it a dozen times a screen, and the dark red was the least legible thing in the panel rather than the most.

Painted footer separators. Dim, like the card's — an unpainted middot renders at the terminal's default brightness, louder than the labels it is separating.

Two defects the visual pass found, both older than this branch and invisible to the suite:

1. metricsStrip solved its column count by dividing inner by the column width, ignoring the blank cell at each end and the rules between pairs. A 40-cell panel was told it had three columns, handed each of them ten, and printed MAINTENANC — the caption metricMinCol exists to protect. The count is now solved against the row the strip actually draws, and the stand-down threshold (metricStripMinWidth) includes the row's two blank edge cells, which it was short by.
2. A language share rounded to whole percents printed makefile 0% beside a band segment that plainly was not zero. Shares now read as GitHub writes them — one decimal, a whole number left whole, <0.1% below a tenth.

Every assertion added or changed in this pass was killed by a mutation before being kept — the gutter in each panel, the centering, the band, the blank row under it, the painted separator, the version cell's ↑, and the readme's code role.

Not implemented, on purpose

• Theme picker overlay, built-in themes, persisting the choice — THEMING-PREWORK.md defers them to a separate feature after this refactor. The infrastructure is in place.
• U update all / T themes from the mockup's key sheet — the handoff says its key lists are approximate and to reconcile with the real keymap. There is no bulk update, and U is the existing self-update.
• A rule under readme section headings — glamour.StyleConfig cannot express it; the only way to fake it is injecting a --- the author never wrote.
• Font sizes (the mockup's 19px name, smaller metric values) — a terminal has one font size, set by the emulator for the whole grid. The three sizes the design draws are three steps of weight and brightness here.
• Lightening the near-black language colors — linguist picks them against a white page, so lua, powershell and json are very dark dots on a dark terminal. Lightening them would make the dot no longer the color it is claiming to be.

Known follow-up

demo/hero.gif and demo/update.gif still show the old UI.

Checks

go build / go vet / go test -race ./... / golangci-lint run — all green, plus the cross-compile step (GOOS=windows build+vet, GOOS=darwin build). Coverage: internal/model 94.0%, internal/ui 98.2%. Docs (CLAUDE.md, ARCHITECTURE.md, README.md) updated in the same branch and re-verified against the code.

🤖 Generated with Claude Code