Skip to content

Themes: write the contract down and check it in CI - #321

Merged
rdrake merged 3 commits into
developfrom
theme-contract
Nov 21, 2026
Merged

rdrake merged 3 commits into
developfrom
theme-contract

Conversation

@rdrake

@rdrake rdrake commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Item 2 of the theme-structure review: what a theme can rely on, written down and checked in CI.

What changes

  • The contract is written down. A new section, docs/resources/themes.md § The theme contract, covers:
    • the tokens a theme sets;
    • the attributes on <html> it may key on, in a table with each attribute's values and source;
    • the selectors it may restyle.
  • test/tests/themeContract.ts checks it (40 tests, run in CI with no browser):
    • Unused tokens. Every custom property a theme declares must be read somewhere in client/. The only exception is ps's switched-off animal slots.
    • Static contrast. For each theme, light and dark, the test resolves the tokens through style.css and the theme's @import chain, then checks the pairs the app paints:
      • text, muted text and links at 4.5:1 on the window and the chat;
      • text on a highlighted row;
      • the rail's text on both ends of the rail's gradient;
      • the join line at 3:1.
    • How it measures.
      • Colours are lowered to sRGB with Lightning CSS and read back, named colours included. A value that resolves to no colour fails.
      • A translucent surface is measured over what it is painted on.
      • Besides :root, every block that re-maps either side of a pair is checked as its own surface, with the blocks it sits inside, that qualify it, or that match wherever it does. Blocks on <html> cascade with :root; the blocks below start from their computed values.
    • Missing tokens fail. A theme on coffee's rules that lacks a pair's token is an error; only day and morning, which use TheLounge's own variables, are exempt.
    • One known exception: day's link green, which is TheLounge's own, held at its measured 3.03:1.
  • zelenzy's dialog links: the new check caught them at 4.31:1, though the file's comment claimed 4.6:1. They now use the selection blue a step darker, 4.9:1; buttons keep the blue itself.
  • Dead CSS removed: about 20 unused rules in style.css (old sync, push-state and session-row styles) and panasync's unused --ansi-cyan-dim.

Verification

  • pnpm test passes (lint, typecheck, mocha).
  • Mutation checks: deleting --rail-fg from coffee.css, darkening ps's night muted ink, a low-contrast link, and a light window under ps's light words each fail the test.
  • Two review rounds; their findings are fixed here.

Not done

  • Muted text and links on a highlighted row are not checked yet. Several themes miss 4.5:1 there today: day, princess, morning, creama and frost. That is a palette change for each theme, so it is left out of this PR.
  • The unused-token check pools every file under client/, so it does not yet tell a token read only by another theme.

@rdrake
rdrake marked this pull request as ready for review November 21, 2026 01:48
themes.md § The theme contract: the tokens a theme sets, the attributes
the app puts on <html> for every theme (data-motion-rest was in none of
the docs), and what a restated selector costs.

test/tests/themeContract.ts reads the files, so it runs in CI where the
browser scenarios cannot: every custom property a theme declares is read
by client/ (panasync's --ansi-cyan-dim was not, and is gone), and each
theme's :root tokens, resolved through its imports in light and dark and
lowered to sRGB by Lightning CSS, hold 4.5:1 for text, muted text and
links on the window and chat, on a highlighted row and on the rail, and
3:1 for the join line. Day's link blue is the one recorded exception.

Also drops twenty rules in style.css that no component uses (the old
settings sync panel, the push state dots, the session rows).
A :root under a width query is a surface of its own; a block that re-maps
either side of a pair is measured with what it inherits, including the
blocks that qualify it from above (zelenzy's dialogs under Increase
Contrast); ps's light words and the chat's surfaces outside #chat are the
named exceptions. Known exceptions carry today's ratio as their floor, a
token that resolves to no colour fails instead of yielding NaN, and the
rail is checked at both ends of its gradient. The docs say what the
browser scenarios cover.
…blocks a broader one also matches

A block on <html> (a width query's :root, ps by night) cascades with :root
and resolves there; the blocks below start from those computed values. A
block whose selector narrows another's (ps's light words under the outline,
rim and glow settings) now inherits it. The picture and chat-only exceptions
apply only where the block leaves the surface alone or every branch is
outside the chat. Day's link floor is its measured 3.03.
@rdrake
rdrake merged commit cfc1d8a into develop Nov 21, 2026
13 checks passed
@rdrake
rdrake deleted the theme-contract branch November 21, 2026 03:19

This branch was previously deployed

1 inactive deployment
github-pages — f64ddf3e Deployed Nov 21, 2026 by rdrake via deploy #1384
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant