pastilhasandClaude Opus 5
f977d26fef
The three previous attempts at this job died of endlessness, not difficulty. Nothing stopped the next component arriving with its own `text-emerald-400` while an old one was being fixed, so the number never fell for long. `bun run check:theme` counts palette classes per directory against a committed baseline. It does not care what the number is, only which way it moves. 942 across 21 directories today. Every directory can be paid down independently and none can quietly regrow — which turns an infinite job into a finite one. A baseline rather than a ban, deliberately: a rule forbidding palette classes outright fails on its first run, and a check nobody can make pass is a check everybody turns off. Proven by adding one `text-emerald-400` and watching it fail with the directory, the delta, and what to use instead. ── Documentation, which is part of the work rather than after it ── `src/workspaces/theme/README.md` is new and is the contract: how to write a theme, all 84 declarations by family, why colours are unwrapped HSL triplets while surfaces are complete CSS values, why assets are quoted paths, and the rules for components. Start from Plain, not from Duck — every value you change is then one you decided about. `plugins/EXTRACTING-A-PLUGIN.md` gains a rule beside the others: a plugin never hardcodes a colour, and pays its debt down DURING the extraction. The counts are named there — Soulseek 313, Invoices 95, Wallet 68 — because "some colours" does not convey that it is two thirds of the platform's total. The kickoff prompt says the same thing in the form a fresh agent will meet it. That is what makes the plugin exemption safe rather than a way of losing the work: the ratchet stops covering a directory the moment it leaves, so the rule has to travel with it. `THEMES-NOTES.md` rewritten to match reality — it still listed done things as open. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.9 KiB
Themes — where this got to
Merged to master. The reference implementation is src/workspaces/theme/README.md; this file is the state
of the work — what was done, what was decided and why, and what is still open.
Done
The visual layer is out of the application. It imports one stylesheet and mounts one provider, and
contains no colours of its own. A theme is one CSS file scoped to [data-theme='<id>'] plus one line in
src/workspaces/theme/src/themes.ts.
Three themes ship: Duck Light, Duck Dark, Plain. Switch from the avatar menu. Light and dark are separate themes, not modes — the owner's call, and it removes a concept from the app.
Themed and no longer component-owned: the page wallpaper, the graph-paper grid, the header, the logo, the panel surface (background, border, radius, blur, the fullscreen and header-less variants), the dock, cards, glass, scrollbars.
Zero raw palette classes in the five core apps — FileBrowser, FileViewer, SystemMonitor, Chat, Plugins
— for state colour. text-white/bg-black remain where they sit over media, which is correct in every
theme.
A sixth tone, busy. The 38 ambers meant running, not warning — Chat's own comment said so. The
vocabulary had no word for it. --busy-ink came with it and generalises: a fill bright enough to carry
black text is too light to BE text.
The account stores a theme id, so the choice follows the account rather than one browser's
localStorage. Accounts predating themes migrate from appearance.colorMode on the server, which is the
only place that can tell "never chose" from "chose the default".
A ratchet: bun run check:theme. Per-directory counts of palette classes that may fall and never
rise. 942 across 21 directories today. This is what makes the job finite — the previous attempts died of
endlessness, not difficulty.
Build failures name their cause. Bun.build throws an AggregateError whose message is the string
"Bundle failed" with the real diagnostics in .errors, so the result.success branch was unreachable and
the catch reported the wrapper. throw: false fixed years of Bundle failed.
The landing app is deleted — built elsewhere now, and it carried a third copy of the palette.
Decisions worth not relitigating
duck-* utility names are kept, pointed at neutral variables. ~1,470 occurrences. Renaming them in the
same change as the extraction would have made a visual difference impossible to attribute. --duck-teal
and friends survive as aliases because prose.css reads them directly, eleven times, for chat markdown.
duck-dark is --ink. It was never a brand colour: #14532d in light, near-white in dark, used ~950
times to mean "text". That misnaming is why it is the most-used token in the app.
Surfaces are complete CSS values, not HSL triplets. --panel-bg must be able to be a gradient or
rgba(); a flat colour would rule out the glass Duck already has.
Assets are quoted paths, not url(). Bun's CSS bundler resolves url() at build time while these
files are served from public/ at runtime. useThemeAsset reads the path and wraps it.
.dark survives as a per-theme flag. 396 dark: utilities in 33 components resolve against it.
Removing them retires the flag.
Fidelity stopped being the constraint partway through. Duck's exact colours were preserved while the extraction needed to be provably invisible. The owner then said the palette is not precious — the wallpaper, the grid and the mark are what matter — so shades collapse rather than being approximated.
Open
1. vimazing, the reference implementation, has not been read. The switching mechanism (data-theme
on <html>) and the packaging format are deliberately the dumbest thing that works, because that repo
will dictate them.
2. The plugin candidates carry ~600 palette classes — Soulseek 313, Invoices 95, Wallet 68, Jellyfin
48, Photos 47, Transmission 41. Deliberately untouched: they are leaving this repository, and their colour
belongs to their extraction, when the imports are being rewritten anyway. The rule is now written into
plugins/EXTRACTING-A-PLUGIN.md and the kickoff prompt so each extraction pays down its own.
3. src/apps/officer-web/Screens holds 144, and src/workspaces/components 47 — the latter is the
higher-leverage one, being shared. MetricCard.tsx is the single worst shared component.
4. Theme asset packaging for third parties is not designed. A theme references its wallpaper and logo
by path, which works for themes we ship. Where a stranger's assets live — the intent is a convention under
public/ — is not settled.
5. The marketplace app has its own palette copy. A skeleton awaiting a rewrite, so not worth folding in yet.
6. An appearance settings screen does not exist. The theme picker is a list in the avatar menu, deliberately the crudest control that proves the point.
Verifying theme work
scripts/theme-vardiff.ts— computed variables of two running builds. The instrument that matters. It found the one real regression of the whole refactor: six--duck-*variables resolving to EMPTY, because the utilities were remapped whileprose.cssread the variables directly.scripts/theme-snapshot.ts— screenshots, 8 routes × 2 modes, or a pinned theme.scripts/theme-preview-server.ts— this checkout's frontend against a running platform's API.
Screenshots are noisier than they look. The wallpaper rotates per page load, so a control capture of one build against itself differs on 4 of 16 screens — and a different 4 each time. Two rounds were spent chasing that noise. Use them to find which screens changed, then look; use the variable diff to decide whether anything actually did.
Render under Plain to find what is not themed. Anything still coloured is a component painting itself. That is how the wallpaper, the header and the logo were found.