From 985ff0755d90e812cb9f2b027b0f0c77e84c8d04 Mon Sep 17 00:00:00 2001 From: archvillainette Date: Mon, 20 Jul 2026 11:05:46 +0000 Subject: [PATCH] fix: light emphasis colour so plain Bootstrap tables are readable (#36) (#37) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #36. ## What was wrong `/wiki/manage` showed its table in near-black text on the near-black page: the header row, the `tid`, `Posts` and `Created` columns were effectively invisible. ## Root cause The theme repaints Bootstrap's **light** colour mode dark (`$body-color`, `$body-bg`, `$card-bg`, …) but never overrode `$body-emphasis-color`, which Bootstrap defaults to `$black` (`#09080b` here). Everything that chains to `--bs-emphasis-color` inherited that ink: - `--bs-table-color` / `-striped-` / `-hover-` / `-active-` on any plain `.table` - `--bs-tooltip-bg` (dark text on a dark tooltip) - `--bs-nav-tabs-link-active-color`, `--bs-nav-underline-link-active-color` - `--bs-list-group-action-hover-color` / `-active-color` - the `.text-emphasis` / `.link-body-emphasis` utilities `_controls.scss` had already patched this by hand for the two tables anyone had noticed (`notification/table`, `flags/list`) and for post-content tables. Every other table in the forum was still broken. Fixing the variable once is a smaller diff than a third per-table patch, and it covers tables that do not exist yet. ## The change One variable in `scss/overrides.scss` — the file whose stated job is exactly this — plus a contract test so the next dark-repaint variable that goes missing fails a check instead of shipping. ## Verification Booted the `sow-nodebb` dev stack with this working tree mounted (`PLUGIN_PATH=../sow-nodebb-theme`), seeded a wiki namespace with topics, and compared `/wiki/manage` before and after: unreadable → fully legible, gold rules and buttons unchanged. Also eyeballed `/categories`, `/notifications`, `/user/admin`, a topic, `/wiki` and `/flags` for regressions — none. The ACP is unaffected: it builds from `admin/overrides`, not this file. All `tests/*.test.js` pass; the new test fails when the variable is reverted. Co-authored-by: vickydotbat Reviewed-on: https://git.westgate.pw/ShadowsOverWestgate/sow-nodebb-theme/pulls/37 --- AGENTS.md | 47 +++++++++++++---------- scss/overrides.scss | 6 +++ tests/dark-mode-variable-contract.test.js | 23 +++++++++++ 3 files changed, 55 insertions(+), 21 deletions(-) create mode 100644 tests/dark-mode-variable-contract.test.js diff --git a/AGENTS.md b/AGENTS.md index c693a32..7714131 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,27 +30,32 @@ Fast checks, no forum needed: tables). There is no `npm test` script; run each file directly. - `node scripts/check-emails.js` — when working on email templates. -Live visual check against a real forum, using the sibling checkout at -`../sow-nodebb`: +Live visual check against a real forum — **always possible, never skip it**. +Every change in this repo can be seen in a browser before it ships; there is no +theme change that can only be checked in production. A unit test cannot tell +you that a colour is unreadable, so look at the page. -1. `cd ../sow-nodebb && cp .env.example .env` (if not done already), then set - `PLUGIN_PATH=../sow-nodebb-theme` and `PLUGIN_ID=nodebb-theme-westgate` so - the compose file mounts this working tree. -2. `docker compose -f docker-compose.dev.yml up` -3. Open `http://localhost:4567` (or `HTTP_PORT` from `.env`). Dev admin login: - `admin` / `Admin12345!` (defaults; dev-only). -4. If Westgate is not the active theme yet, switch to it once in - ACP → Appearance → Themes; the choice persists in the redis volume. -5. NodeBB compiles this theme's SCSS and templates at build time, so a browser - reload alone is not enough after editing them. Rebuild, then reload: - `docker compose -f docker-compose.dev.yml exec nodebb ./nodebb build --config=/opt/config/config.json` - (restart the `nodebb` service if changes still don't show). -6. Full reset (also required after changing `PLUGIN_*` in `.env`): - `docker compose -f docker-compose.dev.yml down -v` +Use the sibling checkout at `../sow-nodebb`: -Agents with browser tooling (e.g. Playwright) should point it at -`http://localhost:4567` to load pages, take screenshots, and verify theme -changes on the live forum. +1. `cd ../sow-nodebb && cp .env.example .env`, then uncomment the "Theme + development" block so this working tree is the mounted package: + `PLUGIN_PATH=../sow-nodebb-theme`, `PLUGIN_ID=nodebb-theme-westgate`, + `EXTRA_PLUGINS=nodebb-plugin-westgate-wiki nodebb-plugin-westgate-pages`. +2. `nix develop --command make dev` — the forum comes up at + `http://localhost:4567` (or `HTTP_PORT`) with this theme already active. + Dev admin login: `admin` / `Admin12345!` (defaults; dev-only). +3. NodeBB compiles this theme's SCSS and templates at build time, so a browser + reload alone is not enough after editing them: `make dev-build`, then + reload. `make dev-restart` if changes still don't show. +4. `make dev-reset` wipes everything; required after changing `PLUGIN_*` or + `EXTRA_PLUGINS` in `.env`. + +A fresh database is empty, so pages that render content (wiki, categories, +topics) need seeding first. `../sow-nodebb/AGENTS.md` has the recipes for +seeding over the REST API, for writing plugin settings straight to Redis, and +for driving a headless browser on this NixOS box (the Playwright MCP server +does not work here). Point any browser tooling at `http://localhost:4567` to +load pages, take screenshots, and compare before/after. ## Design Context @@ -70,8 +75,8 @@ changes on the live forum. - `templates/`: Harmony template overrides (same relative paths as Harmony). - `custom_pages/`: source content and mockups for custom-pages surfaces. - `lib/`, `public/client.js`: server hooks and client behavior. -- `tests/`: contract tests for topbar, footer, icons, and wiki table - rendering. Plain assert scripts: run each with +- `tests/`: contract tests for topbar, footer, icons, wiki table rendering, + and the Bootstrap dark-repaint variables. Plain assert scripts: run each with `node tests/.test.js`; there is no `npm test` script. ## Theme Direction diff --git a/scss/overrides.scss b/scss/overrides.scss index 7c57860..8db2593 100644 --- a/scss/overrides.scss +++ b/scss/overrides.scss @@ -48,6 +48,12 @@ $dark: $wg-ink !default; $body-color: $wg-text-soft !default; $body-bg: $wg-ink !default; +// We repaint Bootstrap's LIGHT colour mode dark, so emphasis must be light too. +// Bootstrap defaults it to $black; leaving it there paints near-black text on our +// dark surfaces wherever a component chains to --bs-emphasis-color: plain .table +// (e.g. /wiki/manage), tooltips, nav-tabs/nav-underline active links, list-group +// hover states, and the .text-emphasis / .link-body-emphasis utilities. +$body-emphasis-color: $wg-text !default; $body-tertiary-bg: $wg-panel !default; $text-muted: $wg-text-muted !default; $border-color: rgba($wg-gold, 0.14) !default; diff --git a/tests/dark-mode-variable-contract.test.js b/tests/dark-mode-variable-contract.test.js new file mode 100644 index 0000000..ef0dec1 --- /dev/null +++ b/tests/dark-mode-variable-contract.test.js @@ -0,0 +1,23 @@ +// Westgate repaints Bootstrap's LIGHT colour mode dark, so every Bootstrap +// variable that defaults to a near-black ink must be re-pointed at a light +// token. Missing one is invisible until some component chains to it — that is +// how /wiki/manage ended up with near-black table text on a near-black page. +const assert = require("assert"); +const fs = require("fs"); +const path = require("path"); + +const overrides = fs.readFileSync( + path.join(__dirname, "..", "scss", "overrides.scss"), + "utf8" +); + +// Bootstrap's defaults for these are $black / $body-color-ish inks. +["$body-color", "$body-bg", "$body-emphasis-color"].forEach(variable => { + const declaration = new RegExp(`\\${variable}:\\s*([^;]+);`).exec(overrides); + assert(declaration, `${variable} must be overridden for the dark repaint`); + assert.match( + declaration[1], + /\$wg-/, + `${variable} must resolve to a Westgate palette token, got: ${declaration[1].trim()}` + ); +});