officerdev/platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

a ratchet on hardcoded colour, and the docs to match

Browse Source 
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>
This commit is contained in:
pastilhas
2026-08-16 23:42:56 +00:00
co-authored by Claude Opus 5
parent df92a985d2
commit f977d26fef
7 changed files with 375 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
THEMES-NOTES.md
+81 -115
View File
@@ -1,143 +1,109 @@
# Themes decoupling — working notes
# Themes — where this got to
Branch `themes-decoupling`, worktree `platform-themes`. Nothing here is on master.
Read this before the diff. It is the state of the work, the decisions taken and why, and the things
deliberately left alone.
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.
---
## Where it got to
## Done
The visual layer is out of the app and into `src/workspaces/theme`. The application no longer contains any
colour: it imports one stylesheet and mounts one provider.
**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`.
Proven by the two things that matter:
**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.
- **Duck renders identically to before.** Panels, wallpaper, grid fills, glass, logo — checked against
screenshots taken before anything was touched.
- **Plain renders as white with black ink**, with no component edits. Panels turn white, the teal avatar
turns black, grid fills disappear. That is the decoupling working.
**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.
Switch themes from the avatar menu, top right.
**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.
---
## The shape
## Decisions worth not relitigating
```
src/workspaces/theme/
css/base.css structure — Tailwind, the @theme contract, element defaults. NO values.
css/themes/duck-light.css the app's original appearance, moved unchanged
css/themes/duck-dark.css ditto, the old .dark block
css/themes/plain.css white/black — an instrument, not a design
css/chrome.css scrollbars and overlays, now in theme variables
css/index.css the single import an app makes
src/themes.ts the registry: id, name, family, applyDarkClass. Nothing about appearance.
src/ThemeProvider.tsx sets data-theme, toggles .dark, persists the choice
```
**`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.
A theme is a CSS file scoped to `[data-theme='<id>']` plus one line in the registry. Nothing else.
**`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.
---
## Decisions, and why
## Open
**Light and dark are separate themes, not a mode.** The owner's call, and it removes a concept from the
app. `Duck Light` and `Duck Dark` are siblings. Written out in full rather than as a diff — a theme that
only makes sense in the presence of another cannot be authored by a third party or sold to a customer.
**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.
**`.dark` survives as a compatibility flag.** 396 `dark:` utilities are written into 33 components and they
resolve against that class. A theme sets `applyDarkClass` and they keep working. Shim with a known end
date; removing those 396 retires it.
**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.
**`duck-*` utility names are kept, pointed at neutral variables.** ~1,470 occurrences across 108 files.
Renaming them and extracting in the same change would make a visual difference impossible to attribute.
They now resolve through `--brand-primary`, `--ink`, and friends, so a non-Duck theme can define them
sensibly even while the spelling is wrong.
**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.
**`duck-dark` is `--ink`.** It was never a brand colour: `#14532d` in light, near-white in dark. 946
components use it to mean "text". That misnaming is why it is the most-used token in the app.
**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.
**Surfaces are complete CSS values, not HSL triplets.** `--panel-bg` can be `rgba()`, a gradient or an
image. A panel background that could only be a flat colour would rule out the glass the app has now.
**5. The marketplace app has its own palette copy.** A skeleton awaiting a rewrite, so not worth folding
in yet.
**The old provider file is a re-export.** Six call sites keep working untouched, so the extraction is one
variable.
**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.
---
## Blockers and open questions — for the morning
## Verifying theme work
**1. The reference repo (`vimazing`) has not been read yet.** The switching mechanism (`data-theme` on
`<html>`) and the packaging format are deliberately the dumbest thing that works, because that repo will
dictate them. Everything above is independent of that choice.
- `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 while `prose.css` read 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.
**2. Leaks the Plain theme exposed.** These are components painting themselves rather than asking the
theme. The screenshots in `.snapshots/plain/` are the punch list:
**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.
- **The wallpaper.** Still renders under Plain, so it is set by a component, not `--page-bg`. Probably the
dashboard layout. Needs to become a theme-owned surface.
- **Panel radius.** `--panel-radius: 0` had no effect — panels hardcode `rounded-*`. Shape is themeable in
principle and is not yet.
- **The logo.** A fixed image. Fine for Duck, wrong for white-labelling: a customer's build needs its own.
- **~985 raw Tailwind palette usages** (`text-emerald-400`, `bg-black/10`) and **~119 hex literals**. The
worst concentration by far is `officerdev/src/apps/Soulseek/` (~285). `MetricCard.tsx` is the
highest-leverage single fix — a shared component hardcoding its palette.
**3. Server settings still store `appearance.colorMode`, not a theme id.** `useThemeSync` used to stamp the
server's colour mode over the local theme on every load — picking Plain and reloading silently reverted it.
Now the server value is only honoured when the browser has never chosen. The proper fix is storing a theme
id, which needs a settings migration.
**4. A pre-existing bug, unrelated but adjacent.** The server's default is `appearance: { theme: 'light' }`
while the client reads `appearance.colorMode` — so a fresh account's server default has never been read.
Left alone.
**5. `rebuildFrontend()` reports `"Bundle failed"` and discards the bundler's actual errors.** Cost twenty
minutes tonight. Same shape as the agent bugs from earlier — a failure that refuses to say why.
**6. Theme ASSETS have no packaging story yet — deferred deliberately.** A theme publishes an asset as a
quoted path (`--logo-src: '/officer-logo.svg'`) and `useThemeAsset` wraps it, because Bun's CSS bundler
resolves `url()` at build time while these files are served from `public/` at runtime. That works for
themes we ship. It does not answer where a THIRD PARTY's wallpaper and logo live. The owner's intent is a
convention under `public/` — something like `public/themes/<name>/` — so an author drops files in a known
structure and references them by path. Not designed yet; the token shape above already fits it.
**7. Landing and marketplace are untouched.** They have their own copies of the palette; `duck-teal` has
three different definitions across the three apps. Folding them into this layer is a natural follow-up and
was not in tonight's scope.
---
## On verification, and what the screenshots can and cannot tell you
The byte comparison is **dominated by wallpaper noise**. The dashboard background rotates per page load, so
any screen showing it differs from itself between runs — a control capture of the same build against itself
had 4 of 16 differ, and which 4 changes each time. Between 5 and 6 screens come out byte-identical to the
pre-refactor baseline on any given run; the rest are the wallpaper.
So the authoritative instrument is `scripts/theme-vardiff.ts`, which compares the COMPUTED value of every
theme variable between the old and new builds in the same colour mode. It reports **all 53 identical**.
That is a much stronger statement than a screenshot: it says the token layer resolves to exactly the values
the old stylesheet produced.
It also found the one real regression, which no amount of looking would have: six `--duck-*` variables came
out EMPTY in the new build. The utilities were remapped, but `prose.css` reads `var(--duck-teal)` DIRECTLY
in eleven places for chat markdown — links, blockquotes, inline code, checkboxes — and `landing/styles.css`
does the same. Fixed by keeping the legacy names as aliases in every theme, which also protects any plugin
or inline style doing the same thing. They retire with the utility rename.
## Tools built
- `scripts/theme-snapshot.ts` — captures 8 routes × 2 modes, or a pinned theme with `--theme`. Compares two
directories byte-for-byte. Its first version silently photographed light twice; it now warns when a
light/dark pair is identical.
- `scripts/theme-vardiff.ts` — computed theme variables, old build vs new, side by side. The instrument
that actually proved the extraction faithful.
- `scripts/theme-preview-server.ts` — serves this worktree's build against the RUNNING platform's API, so
the new frontend can be seen with real data without starting a second platform beside the live one.
Byte comparison is too strict for before/after across two builds: this worktree has no plugins, so the dock
differs on every page, and live data moves between captures. Use it to find *which* screens changed, then
look at them.
**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.