Feature: Theming shapes, roles, & accesibility checks

[jhweir]

Theming: the shape vocabulary, roles that actually paint the app, and contrast the system checks for you

Summary

One problem, worked through in eleven rounds. The first closed gaps in the theme vocabulary — avatars
that ignored the shape presets, media no theme could round, two density slots wired at the component
end and dead at the other, one font family for a scale that ships three. The second made roles
actually paint things. The third fixed what the second under-shot and replaced the picker that made
role editing opt out of the theme system by default. The fourth renamed the roles that were named
wrongly, and gave themes a schema version so it could. The fifth made the system check its own work:
contrast is now a test, and a foreground the author did not pin is derived rather than guessed. The
sixth is what the first real session of using the editor turned up — a whole class of surfaces
migrated to the wrong role, and, underneath it, three shipped dark themes whose elevation had been
inverted since the day they were written. The seventh replaced the fix for that with a rule, so the
stack is derived rather than stated. The eighth moved the ramp itself to OKLCH, which is what makes
one step mean one lightness at every hue. The ninth was a full architectural audit of the control
surface, which turned up four gaps and three bad conventions — and, once contrast was measured with
something that works in the dark, two shipped bugs. The tenth stopped reasoning about the colours and
measured them against the build this replaces, which found that the measure-and-correct layer the
fifth round introduced had never once run. The eleventh came from asking why a feature that had been
built was never seen, and found the answer was enforcement: the vocabulary had been right since round
two, and 197 nodes had quietly drifted back to scale positions anyway, almost all of them from four
shared defaults — one of which was a line of guidance that every template written from it had duly
copied. Pulling on the same thread found the chroma taper had been two models all along, and that the
browser had only ever run one of them.

Where it started: templates used scale positions over roles 88 to 2, and the ~50 role references
that existed were inside picker and modal internals. Changing "Surface" in the editor moved a date
picker's popup and left the page it sat on alone.

Where it ends: zero scale positions remain in templates, chrome, modules, primitives or
components except where a colour is genuinely a palette — and a test now says so on every commit,
by importing each schema and walking the real composed tree rather than grepping source, which is the
difference between finding 42 and finding all 197. Every built-in theme now renders within
2.2 lightness points of what it rendered before this branch, measured step by step in a browser
on both builds. On the default template, pinning every
role repaints 85–92% of painting backgrounds and 84–93% of text route by route — the remainder
being Cesium's globe attribution, CodeMirror's syntax tokens, and data-driven colours that should not
follow a theme. Every built-in theme clears WCAG AA on the nine pairs the vocabulary declares, and a
test says so on every commit.

Part one — the shape vocabulary

avatarRadius is its own group. Avatars are the only components guaranteed square, and that is
what makes a percentage radius safe: 50% resolves per-axis, so it is a circle on a square box and
an ellipse on a 16:9 video. Circle is offered on that row and nowhere else, for the same reason.
Three hardcoded radii would have defeated it — avatar's [part='img'] pinned a second 50% (winning
for exactly the avatars that have a picture, the reported symptom), we-video painted over
[part='base'], and we-iframe had no base at all, so every visual prop it accepted was discarded.

Media joins surfaceRadius rather than taking a fifth group. r: 'avatar' / r: 'media' resolve
to the group variables for layer-4 components, where there is no cascade entry to inherit from.

Two dead density slots. inputSpacing had five components declaring it and no theme key able to
set it. Tabs got the we-button treatment — own vertical, control-group horizontal — because
controlPaddingX means "breathing room either side of a label" and buttons apply it with a hard 0
vertical precisely because they have a fixed height to sit in.

A heading font and a mono font, separate from body, resolved at the use site so a scoped theme
changing its body face brings its headings with it.

Part two — roles

Seven roles were missing, each found by asking why something reached past the vocabulary.
accentStrong (the accent at text contrast — 28 sites wrote primary-600/700 because accent is
sized for a fill), dangerText/successText/warningText (status as a foreground; the status roles
covered a tinted panel only, and danger text appeared as danger-400, -500 and -600 in neighbouring
files), accentHover/accentActive, and surfaceInverse.

The migration covers templates, kit, app-shell and editor chrome, the modules, all primitives,
layer-4 components and the block renderer. Three parts needed judgement: a background inside
hoverProps is a state, not an elevation; a graph's node colours are a categorical palette (a node
painted warning-100 because it is a note is not a warning); and neutral-50 means the page at a
root, a floating panel where a shadow says it floats, and a recessed well where a radius says it is a
box — classified by enclosing object, not by line.

The inherited text colour was the single biggest lever, and index.scss already knew it: the
line carried a comment saying the role "belongs to the role migration proper".

Part three — what round two got wrong, and the picker

The value-identical rule was the wrong rule. Migrating primitives only where the role's default
matched the value exactly protected appearance and systematically missed foregrounds, because the
text roles sit at neutral-900/500/400 while primitives use 600/700/800/1000. Nav labels are bare
we-text inside a ghost button, so they inherited the button's unmigrated colour and pinning text
moved 25 of 52 text elements. It also left components half-migrated — alert.neutral read
{ bg: 'page', color: 'neutral-800' }, a pair that is no longer a pair. The semantic pass takes the
shade shifts deliberately and documents the two non-migrations: status fills (the danger button)
and palettes.

The secondary button needed a three-rung ladder the vocabulary has one rung of. Rather than
invent roles nobody would pin, its hover and pressed states mix the rest state toward text — which
reproduces the old neutral-300/400 to within a point and inverts correctly in a dark theme because
text does. isRawCSSValue learned about color-mix() to allow it.

roles now merges with a preset's instead of replacing it. Pinning one role on channels
discarded the twelve measured pins that make it that theme; it came apart from a single click.

The picker. The roles editor offered a Google-Docs swatch list of raw hexes, so every pick opted
a role out of the parametric system — the thing the conventions file tells theme authors not to do.
we-color-picker now has a token grid (emits var(--we-color-…), which still follows hue,
saturation and polarity), a saturation/value area with hue and alpha sliders, and a text field
with hex/rgb/hsl/oklch. Both new props default off, so existing callers keep what they had. The
colour maths lives in @we/design-utils because the contrast checking in part five needs the same
conversions.

The picker's own first outing found five of its bugs, two sharing a root: part="swatch token"
does not match [part='swatch'], so the token grid had no styling and fell back to the user agent's
button; and background: <colour>, <image> is invalid CSS, so the trigger swatch painted nothing.
A test now guards the selector class, since it fails invisibly by construction. The popover closes
on an outside click and on Escape, the format control is a segmented button group rather than a
native <select> (whose popup takes the platform's colours, not the theme's), and there is an
eyedropper on the platforms that have EyeDropper.

Part four — the names, and a version that lets them change

Three roles were named against the grain of the rest of the table, and one pair was actively
misleading: accentText meant the foreground you put on an accent fill, while accentStrong meant
the accent used as text. Somebody reading the table would pick exactly the wrong one. They are now
onAccent and accentText, with textInverse becoming onInverse to match — a bare noun is a fill
or a foreground in its own right, on<Fill> is a foreground that exists to contrast with a specific
fill. controlSurface was added for the filled neutral of a control (a switch track, a progress
trough, a count chip), which is neither a surface nor a state and was reaching for neutral-200.

A rename is only safe because themes are portable user data — published to a marketplace, stored
in a space, sent as a link. An unknown role key is silently ignored, so without migration a theme
published last week keeps looking almost right while one relationship quietly stops being honoured;
nobody reports that, they conclude the theme was never very good. schemaVersion and
parseOverrides() now sit on every read path. The rename map is applied in one pass because it
is a permutation — applying it sequentially would move accentText's value into its own new slot and
lose one of the two.

Three preferences the OS was already expressing are now honoured: prefers-color-scheme (a
"System" entry in the theme picker that re-resolves when the OS flips, rather than a light theme
somebody has to notice and change), prefers-reduced-motion (the transition tokens collapse to
0ms, so every component that animates through a token stops at once), and forced-colors.

Part five — contrast, and the pins that survive a change

Contrast is now a test. Nothing checked it before, so a theme could ship with body text a shade
off its own page and the only signal was somebody squinting. It is checkable at all because the
roles name their pairings — onAccent is defined as the thing that sits on accent — so both sides
of each pair are known rather than inferred by crawling a rendered page. And a theme is four numbers
and a lightness ramp, so the same arithmetic the CSS does gives the colour without a browser: it runs
as a unit test on every commit rather than as a screenshot somebody remembers to take.

It found eleven failures across the shipped built-in themes on its first run — muted text at 4.2:1,
success text at 3.6:1, warning text at 2.9:1 — all now fixed by moving the role defaults, not by
loosening the check.

A foreground the author never pinned is derived rather than guessed. applyAutoContrast picks
between the light and dark candidates by measuring, and it measures against every fill the
foreground will sit on — a label chosen against a button's rest state alone can go unreadable halfway
through a click, when the fill darkens under the pointer. So the weakest pairing decides.

A relative pin — color-mix(in srgb, var(--we-role-surface) 88%, var(--we-role-text)) — is the
one form that expresses a relationship rather than a value. It survives a change to the role it
references, and because it mixes toward something that inverts with the theme, "a step darker" in a
light theme becomes "a step lighter" in a dark one without being told which it is. This was possible
before and undocumented; the editor now recognises the form and names it, so it takes its place on
the ladder between a lightness pin and a literal.

oklch() is accepted and offered as a fourth format. Worth having even while the ramps are still
HSL, and not because it is newer: OKLCH lightness is perceptual, so equal L reads as equal brightness
across hues where HSL's 50% is far brighter for yellow than for blue. A front door, not a new
internal representation — everything downstream still speaks sRGB.

The roles editor names the rung each role is on (auto → a token by name → a theme tint → relative
to another role → a literal), warns when a pinned pair falls below AA, and renders a preview strip
— a small gallery painted under the theme being edited, so the roles that only appear in a state or
on one screen are visible while they are being chosen. The visual inspector now offers roles first
and the scale second, labelled for what each is ("follow the theme" vs "a fixed colour, for a
palette"), with a menu item that jumps from a role in the inspector to that role in the theme editor.

Part six — what the first real session with it found

Three things, from using the editor rather than reasoning about it.

Cards and page headers followed "Sunken". They should follow "Surface", and the cause was the
value-faithful migration again in a new guise: the pre-role templates painted a card and a well with
the same neutral-100, because against a neutral-50 page that grey looked right either way. So
the migration preserved every appearance and got a good share of the meanings wrong, and nothing
showed it until somebody dragged a slider and watched the page header move.

The discriminator is what a thing sits on, which the source cannot answer — cardShell and
sectionCard are contributed from another package. So pnpm --filter @we/schema-shared surface-audit
imports each schema, walks the real composed tree, and reports the nearest painting ancestor of
every sunken node: a node whose parent is page is an object on the page, and therefore a surface.
It found 389, fixed at the fragments and named containers rather than one node at a time. The Tasks
column deliberately stays sunken — a trough holding surfaces is exactly what a kanban column is, and
its comment complaining that the colour was "nearly invisible against the page" was only true while
the cards in it were the same colour.

Which exposed that the dark themes had been upside down all along. page is neutral-50 and
surface is neutral-0, so the inversion flips their order: in dark a card lands below the page
and a sunken well lands above both. It never showed because the cards were painted with the well,
which inverts to lighter and looked right by accident. The ordering is now an invariant in
contrast.test.ts — sunken ≤ surface ≤ raised, and a card never below its page — which failed on
dark, black and cyberpunk; all three now pin their stacks, and the editor's Light/Dark buttons
do the same so a hand-flipped theme does not inherit the bug the presets just escaped. Equal is
allowed: channels shares one colour between page and card and separates with borders, which is a
design.

The preview moved to the top of the panel, sticky and collapsible, instead of living inside the
Roles section. A hue slider, a radius slider and a shadow toggle all land in that same small gallery,
and a preview you have scrolled past is not a preview.

The inspector now says which roles paint the selected node — in the header, including inherited
ones. That was the missing half of the bridge: the swatch pickers could only answer for a node that
names a colour in its own props, which is the minority, since text almost never sets color. It
walks the schema up, marks what was inherited and from where, and jumps to that role in the theme
editor.

And @we/editor's tests were not running. Its vitest config included tests/** only, so
ThemePanel.test.ts — beside the module it covers, this repo's usual placement — had never once
executed, while reporting as a passing suite. Fixing the glob revealed the panels are not importable
under vitest at all (a .tsx pulling in @we/components/solid runs a client-only API at module
scope), so the pure logic moved into themeRoles.ts and paintedRoles.ts. 41 editor tests now run
where 16 did.

Part seven — the stack stops being a table and becomes a rule

Three dark themes were each stating four literal lightnesses to keep their cards above their pages.
Two of those stacks were written by hand in part six, and the numbers came out within a point of
each other every time — which is the tell that it wanted to be a rule.

surface: oklch(from var(--we-role-page) calc(l + 0.045) c h);
surfaceraised: oklch(from var(--we-role-page) calc(l + 0.1) c h);
surfacesunken: oklch(from var(--we-role-page) calc(l - 0.035) c h);

Checked against every shipped theme before it was adopted: light 100/100/90.4 against 100/100/90
pinned, dark 14.1/19.5/6.9 against 14/19/8, cyberpunk 15.2/20.6/7.9 against 15/21/8. So
dark and cyberpunk drop their stacks, and a theme built from scratch is correct with no pins
at all — the bug class is retired rather than wired around.

Why OKLCH here and not in the ramp. HSL lightness is a coordinate, not a brightness: the same
five points is 3.6 L* near black and 6.3 L* in the mid-dark, so no constant serves themes sitting
at different places on the curve. color-mix cannot do this job either — it interpolates between
two colours, so a fixed percentage moves by a share of the distance remaining, which is less even
than the HSL it would replace. calc(l + n) in OKLCH moves by a fixed perceptual amount. It also
carries c and h through, so a tinted theme gets a tinted stack for free — verified in Chrome:
page rgb(38,20,46) → surface rgb(49,31,58), still purple, which the scale positions never did.

Two themes still pin, both with a reason. black sits at the sRGB floor, where a +0.045 step
and the page round to the same 8-bit value — no formula survives that. channels wants its page and
cards identical, separated by borders. The invariant permits equality precisely so it can say so.

An @supports block returns the scale positions where relative colour syntax is missing, and
applyThemeVars repeats the feature test because an inline custom property outranks the stylesheet
that would otherwise supply it.

Part eight — the ramp itself

The last quirk in the foundation, and the one most likely to bite a theme author. HSL lightness is a
coordinate, not a brightness: the same nominal 500 measured L* 46 for blue and L* 69 for green,
and the hue slider spanned 39 L* points end to end. Changing a hue silently changed how heavy
the accent read, with no way to know but to look.

The evidence was already in the file. dangerText, warningText and successText sat at -600,
-700 and -800 — three steps for one concept, because green and amber are lighter than red at the
same number. They share -700 now. That is what the change buys, and it is the same shape as every
other fix on this branch: a hand-tuned constant replaced by a property that holds.

The scale is anchored, not invented. Each step is the OKLCH lightness of the sRGB colour the old
HSL step produced, so greys, text and surfaces land exactly where they were and only the chromatic
families move. chromaTaper reproduces what HSL's saturation × min(l, 1−l) did implicitly, since
OKLCH chroma is absolute and pale steps would otherwise sit outside sRGB. The
CHROMA_PER_SATURATION constant is calibrated: at saturation 50 it puts step 500 at chroma 0.140
where the old ramp measured 0.141.

Two role resteps fell out of it. accent moves 500 → 600, because on a perceptual scale the step
that carries a near-white label is a specific lightness and 500 is not it (a primary button measured
3.34:1). And the three status foregrounds collapse to one step.

Two stored values changed meaning and are converted rather than renamed: a hue is an angle in a
particular space and the two disagree by up to 45° in the warm end (220 → 263, 45 → 90), and
saturation stopped being a percentage string because calc() cannot divide a percentage into the
unitless number a chroma has to be. migrate.ts v3 handles both.

Four silent bugs surfaced on the way, each worth recording:

• A chroma ceiling was needed. channels carries saturation: 85 — ordinary under HSL, where
  saturation is relative. Multiplied out it asked for chroma 0.30, and a blue at 0.30 gamut-maps to
  the magenta edge. The entire accent turned pink.
• The presets never declared their schema version, so parseOverrides read them as v1 and ran
  every migration over them — converting an already-converted hue a second time, 266 → 299.
• themeToStyle re-declares the palette formulas for scoped themes and was still emitting HSL,
  quietly overriding the generated OKLCH at runtime.
• Hand-measured lightness pins in channels, timeline and the fixed roles were HSL percentages
  being read as OKLCH ones, and far darker as a result. All 27 converted numerically.

Part nine — the audit, and what it found

A zoom-out over the whole system rather than the colour layer alone. Seven findings, all of them
ThemeOverrides changes and therefore cheapest before anyone has authored a theme.

The parametric model was the weakest part. multiplier was 1 or -1 in every preset — a
boolean typed as a number — and subtractor: '112%' meant "reflect the ramp and offset it", which
is not a thing anybody can picture. It is a floor at 12%, and the only way to find that out was to
drag it and look, which is exactly what part six did. A theme now states polarity,
lightnessFloor and lightnessCeiling. Same arithmetic, exact conversion, and the two bounds turn
out to be the contrast control the system had by accident and could not reach.

Status colours had no fill. accent had six slots; danger had two. A theme could completely
restyle the primary button and could say nothing about the destructive one, which was hardcoded to
danger-500. There are danger/success/warning fills now, with one derived onStatus between
them rather than three on* roles.

Which found a live bug: the danger button was a near-white label on a scale step, and a scale
step inverts — so in a dark theme that fill lands light and the label sat on it at about 2:1.
Nothing caught it because no contrast pair named the button.

And a second one. Modelling the derivation in the test rather than the declared default — which
is what actually renders — put black and channels at 3.83:1 and 4.10:1 on the primary button.
Their accent sat near 50% lightness, where no label reads at either end.

Four smaller gaps closed: stroke weight is themeable (radius had four groups, stroke none);
spacing scales independently of type (fontScale moved both, since the steps are in rem);
disabledOpacity replaces a hardcoded 0.5 — as a control, not the role I first proposed, because
one colour cannot serve a disabled ghost button and a disabled danger one; and ringColor is gone,
having been a second way to say the focus role with no stated precedence.

Saturation now means the same thing at every hue. The flat chroma ceiling from part eight was
the same bug as the HSL ramp, one axis over: sRGB holds 0.259 of chroma for a violet at mid
lightness and 0.103 for a teal, so saturation: 100 gave the violet 70% of its range and stopped
affecting the teal at about 29. applyThemeVars measures the sRGB boundary per hue and publishes a
ceiling the ramp scales against.

Fills are derived too, not only foregrounds. A filled control near the middle of its theme's
ramp has no readable label — both candidates are equidistant from it — and where the middle falls
depends on the range. Two things had to be true for the derivation to work, neither obvious: the
hover and pressed states had to become steps from the fill rather than independent scale
positions (the label is chosen against the worst of the three, and black's pressed state at 78.5%
was dragging the whole choice to Lc 35), and chroma has to be clamped as the fill moves, because
carrying it toward white clips and a clipped colour's luminance barely moves.

A final sweep regularised what was left: every fill family has exactly five roles (danger had
grown a hover and an active that success and warning lacked), the focus ring's width became
themeable now that a border's is, and three controls moved to the heading they belong under.

Modules can theme their own components. COMPONENT_CASCADE was a closed literal, so a feature
module could read theme variables and not contribute one — it could borrow a core group whose
meaning did not fit, or hardcode. That cut against the premise that modules raise the ceiling on
what templates can express. registerComponentCascade opens it.

Contrast is measured twice, and the second measure changed the design. WCAG 2 adds a flat 0.05
to both sides of its ratio, which dominates the denominator against a near-black background — so
dark themes score far better than they read. This branch had already worked around that three times
without noticing. Checked with APCA, 24 pairs failed, every one in a dark theme; light themes
passed both. The fix was not more hand-picked steps but derivation: six foregrounds keep their hue
and walk their lightness away from the background until they clear, which also retired the pins
black and channels had accumulated.

Part ten — measuring against the build this replaces

The dark theme was reported as looking wrong, and the useful decision was to stop trading hints and
build a harness: capture the rendered palette and roles on both branches through the real theme
picker, and diff them. Templates are removed from the question that way — it asks whether the theme
changed, not whether something asks for a different role.

That harness misled me twice before it was trustworthy, and both are worth recording because a
harness you believe is worse than none. It selected the theme before the template, and a template
re-applies its own recommended theme — so two branches were photographed wearing the wrong theme,
agreeing perfectly, which is indistinguishable from success. And it clicked a row's label rather than
its button, which reaches the handler for most rows and silently does nothing for others. It now
verifies what it measured before recording it.

The chroma taper read the wrong end of the ramp. It was computed from a step's base lightness
rather than its rendered one, so in a dark theme the colour was inverted end for end: neutral-0
came out at 0% chroma where it should carry ~40%, and the light end at 209%. This is what made the
whole theme read as "washed out and slightly wrong" without any single element looking broken.

neutral-0 means the dark end in a dark theme. A scale position inverts, so it is the lightest
colour a light theme has and the darkest a dark theme has. Templates never had to disambiguate —
against dev's page the same grey read correctly either way — so migrating by name preserved the
light-theme reading and inverted every dark one. 55 sites, found by pairing removed and added lines
in the migration diff rather than by grepping.

The derivations had never run. This is the important one. Every one of them read a role with
getComputedStyle(root).getPropertyValue(…), which returns a custom property's token stream — for
a parametric role, a literal string beginning oklch(calc(…. parseColor returns null for it, and
each derivation hit its continue. So applyLegibleFills, applyAutoContrast,
applyLegibleForegrounds and the state direction did nothing at all, except where a role happened to
be a literal pin — which is exactly the case anybody spot-checking would have looked at.

Measured in the browser: muted text was Lc 20 on black, 27 on channels, 33 on cyberpunk,
45 on dark, against a threshold of 60. All four read 60–61 now. The contrast suite resolves those
expressions arithmetically itself, so it modelled derivations that were not running and stayed green
over every one of them. The fix is a probe element: assign the role to a real background-color and
read it back, because only a browser evaluates a var()/calc() chain and only for a typed property.

Fills were on the wrong axis. The surface stack is defined relative to the page and must invert
with the theme; a fill must not — a red is red in both. Fills defaulted to step 700, which lands at
L 42 light and L 78.6 dark, so every dark theme's accent was a pale lavender and its destructive
button pale pink, and three presets had pinned their way out of it. Step 500 is the ramp's polarity
fixed point (L 60.0 against 60.4), but one lightness for every hue is what OKLCH will not let you
fake: violet at L 0.60 is a colour and gold at L 0.60 is a stone. Each fill now states its own
lightness — where the pre-OKLCH palette already had them — with an untapered ceiling measured there.
The ramp's taper exists to converge the neutral scale on white and black, which is the one thing a
warning fill must not do.

A label was chosen by one metric and marked by two. pickReadableForeground scored with WCAG 2
while the suite grades with WCAG 2 and APCA. On a mid-tone fill they disagree outright — a red at
L 0.62 is Lc 72 under white and Lc 38 under near-black, while WCAG hands the win to near-black — so
the derivation picked the label that failed the other standard and reported a failure it had caused.
Each measurement is now normalised by its own threshold and the worse governs. Two things fell out:
onStatus split into onDanger/onSuccess/onWarning, because one label across fills at L 0.62,
0.75 and 0.76 is a compromise rather than a choice; and AUTO_CONTRAST dropped the hover and pressed
variants, which are redundant now that a state moves away from its label.

The state direction stopped being a proxy. A hover must move a fill away from the text on it.
Under scale positions that held by accident; restated as signed deltas it became "dark themes
lighten", wrong for a dark theme with a white label, then "everything deepens", wrong in the mirror.
It is now derived per fill family from the label that actually landed — which was documented as
needing a fixed point and does not: the fill settles, the label is chosen, the direction follows.

themeToStyle is now themeParametersToStyle. It returns a theme's parameters and role defaults
and nothing measured, and its name read as "turn this theme into a style you can apply". Six places
followed that reading — the document root, the scoped template wrapper, the theme editor's preview
strip, its role swatches, its colour picker, and both of the schema renderer's themed-node wrappers.
Custom properties inherit, so none of them lost the derived half; they took the ambient theme's.
A green theme inside a violet app was drawn with a violet's chroma ceilings, looking plausible and
being wrong, and only ever wrong when the two themes differed — which is precisely what a theme
editor and a scoped space theme arrange.

Three themes were still converted arithmetically. subtractor: 110% became floor 10% / ceiling
110% by arithmetic, which reads an HSL lightness as though it were an OKLCH one. dark was refitted
by hand at the time and the others were not. Mean |ΔL| across the neutral ramp against the old build:

	before	after
Light / Dark / Retro / Timeline	1.3 / 1.1 / 1.0 / 0.2	unchanged
Black	12.7	2.1
Cyberpunk	13.7	2.2
Channels	14.2	1.8

Fitted by least squares over the neutral steps, weighted by how much of a screen each paints, and
rejecting any ramp that clips a step to white. The script reproduces dark's hand-fitted 20% / 121%
from its measurements, which is what says the method is sound rather than merely fitting something.

black lost four pins in the process, with a convincing note attached: "its page is pure black, and
a +0.045 OKLCH step from there rounds to the same 8-bit sRGB value." True, and only true because the
floor had been mistranslated to 0%. Dev pinned nothing there. A pin written to work around a defect
is indistinguishable from a pin written to express a design — and a unit test had grown around this
one, asserting that black pins a lightness, which was asserting the defect.

Performance, which the working derivations exposed

A write to root.style invalidates the document, so the next getComputedStyle forces a synchronous
recalculation of it. The four derivations each read a role, computed, wrote it, and read the next.

19 interleaved recalcs (as first shipped)	45.2 ms
4 recalcs, batched within each derivation	10.9 ms
1 read phase, then all writes	0.6 ms
the entire colour derivation, in JS	0.24 ms

Four fill searches, six foreground searches and nine gamut bisections cost a quarter of a millisecond
between them; everything else was the browser recomputing a 583-node document between steps. The
browser is asked exactly once now, and deriveRoleVars is pure arithmetic over what it answered.

Separately, the primary button lagged behind the text beside it during a drag —
--we-theme-switch-duration was raised on every application, so each frame re-armed a 250 ms
cross-fade and anything with an animated background spent the drag chasing. A switch and an edit are
now distinguished by the caller, which is the only place that can tell them apart.

The editor, from actually using it

• A dock whose store arrived late could never be found again. A dock names its edge as a string
  key into hostDockStores, a plain object; if the store is not there yet the resolving memo never
  touches the accessor, registers no dependency, and cannot recover. ShellStoreProvider wraps
  EditorStoreProvider, so this was guaranteed rather than racy — the theme panel could not be
  opened at all, and opening any other panel was the only escape. Registration is observable now.
• The colour picker opened hundreds of pixels from its trigger. Its popover is absolutely
  positioned and nothing in the component was positioned, so its containing block escaped to outside
  the scroll area: scrolled 400px, the trigger moved and the popover did not. Reproduced only after
  putting a we-scroll-area in the test, which is what the real panel uses.
• The audit moved the controls it was reporting on. Rendered above the role rows, gaining an issue
  pushed every picker down — so dragging inside a picker's square moved it out from under the pointer,
  changing the colour, changing the list. It is on demand now, in a fixed-height box in the preview
  section, cleared on any change: a result computed against colours since edited is not stale
  information, it is wrong information.
• The editor's panels repainted a surface the dock frame had already given them, so they read as a
  different material from every module panel at the same edge.
• A pinned accent froze its own hue. Three presets stated their accent as a fully literal colour,
  so moving the primary-hue slider repainted the ramp, the focus ring and every accent icon and left
  the primary button exactly where it was.
• The accent had no lightness control at all, because fills sit off the neutral ramp — right for
  polarity, and it silently froze every theme's accent at one lightness. Forking dark and dragging the
  hue to green gave #3a862d with nothing able to brighten it; accentLightness is that third axis.
• "Follow system" stopped being listed as a built-in theme. It was the first entry of
  builtInThemes, so on a fresh account it was the most prominent row in the picker, above every
  actual theme, under a heading calling it a built-in one. It carries no parameters — it is a
  question answered at the point of use, resolving to one of the themes listed under it. Its own
  automaticThemes section now, rendered last in both the picker and the settings list. Kept in the
  picker rather than moved to settings because it is mutually exclusive with choosing a theme:
  whatever sets it has to be somewhere the picker can render as selected.
• Derived roles now say what they follow. The elevation stack is a fixed distance from page, so
  moving the page moves all three — which reads as a limitation when the panel says only "auto". They
  read "follows Page" now, parsed out of the role defaults so it cannot drift.

Part eleven — the enforcement half, found by asking why a feature felt absent

The vocabulary was right from part two and the picker leads with roles from part six, but nothing
made the wrong choice hard: bg="neutral-100" typechecks, validates, renders, and looks correct in
whichever theme it was written in. Discipline was the only thing between the migration and its own
slow reversal.

It had already started reversing. 197 nodes across the composed templates painted with a scale
position where a role was meant — a number the obvious search does not find, because it reports 42.
The difference is that a statChip() contributed by @we/schema-kit is invisible to any grep over
the route that renders it, so the audit imports each schema and walks the real composed tree, the
way surface-audit does.

They were not 197 decisions. Four defaults:

Source	Was	Now	Count
statChip's icon	neutral-600	text-muted	126
attributeRow's icon	primary-600	accent-text	24
the rail's selected row	neutral-100 / primary-600	accent-muted / accent-text	—
guidance for a gate prompt's icon	neutral-300	text-faint	47

The last one is the instructive one: a line in the authoring docs recommended a scale position, and
every gate prompt in the repo had duly copied it. Fixing the templates without fixing the sentence
would have left the defect generating itself.

statChip is the one worth looking at twice — its icon was neutral-600 while the label an inch to
its right was already text-muted, so the two disagreed in every theme, and nobody noticed because
in the theme it was written in they happen to land close together.

The audit runs in ~2s, so unlike surface-audit it is a test rather than a script somebody
remembers to run.

What a scale position actually is, since the editor was saying it wrong

The inspector's role readout told you a scale position "does not follow the theme", and the first
person to read it caught that as false. It follows the theme perfectly well — it is computed from the
neutral hue, the saturation, the floor and ceiling and the polarity, so it moves when any of those
move and it inverts with the ramp.

What it does not follow is what the theme decides. A theme pins roles, not steps. channels sets
its surface equal to its page; timeline sets its to pure white; a node naming a step hears neither:

              neutral-100        role surface       role page
Light        [230,230,234]      [255,255,255]     [241,241,244]
Channels     [  7,  8, 11]      [ 26, 28, 33]     [ 26, 28, 33]
Black        [  1,  1,  3]      [ 12, 11, 22]     [  0,  0,  0]
Timeline     [228,230,233]      [255,255,255]     [255,255,255]

In Channels a card painted neutral-100 is a dark hole punched in a design whose premise is that the
card and the page are one sheet.

The quieter half was not said at all, and it is the half that bites text: the measure-and-correct
pass operates on roles, so a label coloured neutral-600 is never measured against what is behind
it, never walked toward legibility, and never appears in the theme editor's audit either.

The chroma taper was two models, and only one of them rendered

chromaTaper took a step name, read the raw lightness table, and carried a comment saying the taper
"must not follow the theme's inversion". The generated CSS has never agreed — it computes
2 * max(0, min(L, 1 - L)) from --we-color-lightness-<step>, the post-ramp value, so it
follows the ramp exactly.

They agree wherever the ramp is the identity, which is light and retro, and that is why it
survived. On dark's step 200 they are 2.3× apart:

Chrome                          rgb(59, 57, 82)
post-ramp taper (the CSS)       rgb(59, 57, 82)   ← exact
raw-step taper (chromaTaper)    rgb(59, 59, 70)   ← 12 out on blue

So every scale position the contrast suite resolved in a dark theme was measured against a colour
the browser does not paint, for the whole of this branch, with 397 tests green. It never flipped a
verdict — chroma barely moves either metric, both being lightness-dominated — which is exactly why
it lasted, and is no reason for the suite that grades themes to model the wrong colour.

chromaTaper now takes a resolved lightness rather than a step name, which makes the mistake
unspellable: a caller has to have applied the ramp before it can ask. The primary gradient built its
taper in JS too and now writes the same CSS expression as the ramp does — at step 500 the difference
is 0.800 against 0.792, and it is changed anyway, because a number that happens to be nearly right is
how this went unnoticed at 200.

Fifteen recorded browser measurements now pin the resolver — three steps across five themes,
sampled from Chrome. Everything else in that suite grades from resolve(), so nothing internal
disagrees with a resolver that is wrong; these are the only assertions an internal change cannot
satisfy by moving both sides at once. Mutation-checked: a broken taper fails all fifteen.

One process note worth keeping. The first attempt at those measurements used numbers captured earlier
in the branch and reported black, cyberpunk and channels as badly wrong. They were not — those
three were refit since, and the data was stale. Ground truth has to be re-read, not remembered.

A text element that reported no text colour

Selecting the author name on a card showed background: surface and nothing else. The background was
right — it comes from the Card, and it is what the text's contrast is measured against — but the
foreground, the one thing being looked for, was missing.

index.scss sets body { color: var(--we-role-text) }, and most text in the app says nothing about
its own colour, so it is painted by the document. The readout walks the schema and only the schema,
found no color in the chain, and reported nothing — indistinguishable from "this element has no
text colour". The timestamp beside it looked correct only because its node happens to set text-muted
explicitly.

Text now always reports, falling back to the document's role and marked as inherited. A background
still reports nothing when nothing above paints one, and that asymmetry is deliberate: there is no
document-level background rule to fall back to, and claiming page would be a guess about a root the
fragment cannot see. The caveat the readout cannot see is recorded on the field — a component between
the node and the document may paint its own colour in its shadow root, as a ghost button does — so
it says where the template leaves it, not the final answer.

The chips also carry which of the three they are. They were a swatch and a role name, so two of them
read as two colours with no way to tell the background from the foreground without hovering each,
which is most of what made a background on a text element look like a mistake rather than context.

And four editor bugs the same investigation turned up

Chasing why the role readout felt absent — it had been built, and never seen — found that it was
fine and its surroundings were not:

• A fresh template was inert to every click. node.id is what the renderer stamps as
  data-we-node-id, and it is the whole handle the visual editor has. Six setters wrote the live
  template and three had forgotten to call ensureNodeIds; saveTemplateAs was the one that
  mattered, being how both "Start fresh" and "Fork" arrive. A tree with no ids renders identically
  and cannot be selected at all, so it did not read as a missing id, it read as the visual editor
  being broken. All six now route through one commitTemplate.
• The inspector painted its own background, surface over the dock frame's surface-sunken, so
  it sat lighter than every neighbouring panel. The code and theme panels had each been corrected
  before, separately — three reports of one drift.
• Three spacing props that did nothing, all in the readout strip itself: gap="150" twice and
  px="150" once resolve to var(--we-space-150), which does not exist, so the chips sat flush with
  no padding. They were the only three in the repo.
• The role chip's jump lost the role. Its tooltip promises "click to edit it for the whole theme"
  and then landed you at the top of a panel holding forty roles across five collapsed groups. It now
  opens the group, scrolls the row to centre and rings it — opening the group being part of the fix,
  since a collapsed section has no row to scroll to.

Each of the first three is invisible by construction, and each is now guarded by a test that fails on
a reintroduction.

---

Verification, the bugs found along the way, and the follow-ups are in the first comment on this
PR — they run to another 20k characters and GitHub caps a description at 65,536.

[netlify]

✅ Deploy Preview for coasys-we ready!

Name	Link
🔨 Latest commit	0dbb774
🔍 Latest deploy log	https://app.netlify.com/projects/coasys-we/deploys/6a8b2f131eecab0008816c7f
😎 Deploy Preview	https://deploy-preview-127--coasys-we.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[jhweir]

Theming — verification, bugs found along the way, and follow-ups

The second half of the description for this PR. Split off because GitHub caps a body at 65,536
characters and the two together are past it; the cap applies per comment as well, so this is room
rather than a summary of what was cut. Nothing is abridged.

Bugs found and fixed along the way

• The whole first migration was silently inert. tokenVar matches roles kebab-cased while
  ThemeRole keys are camelCase; surfaceSunken emits a variable that does not exist, so the
  browser drops the declaration and the element paints nothing. Typecheck, validation and the
  rendered screen all looked fine. The validator now rejects the TypeScript spelling and names the
  right one — only where the two differ, since page and surface read the same either way.

• Tooltips went white in dark mode — my own regression. text/textInverse are scale positions,
  so the pair flipped with the theme. No expression over the scale can be dark in both polarities,
  which is why overlay and shadowColor pin a lightness; surfaceInverse joins them and
  onInverse becomes fixed too. The dark theme's ::part(tooltip) override existed only to undo a
  hardcoded #222 and is gone — which also fixes every other dark theme, since that rule only ever
  fired for the one named dark.

• Switching theme while editing did nothing. The picker persists a pin and lets the recompute
  land in replaceTheme, which drops any change while a theme is being edited — right for walking
  into a space mid-edit, wrong for someone choosing a theme. It is now told which kind of change it
  is.

• A scoped theme's unpinned roles resolved against :root. A custom property containing var()
  is substituted where it is declared, so a scoped theme could redeclare every colour token on its
  wrapper and still paint from the personal theme's scale.

• The measure-and-correct layer never ran, in any theme, since the round that introduced it.
  Every derivation read a role through getPropertyValue, which hands back a custom property's
  unevaluated token stream; parseColor returned null and each one hit its continue. It degraded
  to the declared default — a plausible colour — and it did work for a role pinned to a literal,
  which is exactly what a spot-check would have looked at. Muted text was Lc 20 on black against a
  threshold of 60. The contrast suite models the same pipeline in its own arithmetic, so it reported
  green throughout.

• The chroma taper was computed from the wrong end of the ramp, inverting colour end-for-end in
  every dark theme: 0% chroma at the dark end, 209% at the light one.

• neutral-0 was migrated with light-theme eyes. A scale position inverts, so it is the lightest
  colour a light theme has and the darkest a dark one has; 55 sites had it backwards.

• A label was chosen with WCAG 2 and graded with APCA, which disagree outright on a mid-tone
  fill — so the derivation picked the label that failed the standard it would be judged by.

• A dock whose store registered late could never be resolved again, because the lookup that
  missed it registered no dependency to retry on. Guaranteed by provider nesting, not racy.

• Theme scoping restyled the template it was meant to leave alone, because the scoped wrapper got
  a theme's parameters without the measurements — as did the editor's preview, its swatches, its
  picker, and both of the schema renderer's themed-node wrappers.

Known follow-ups

Open — for after this branch

Three things this branch establishes are worth doing and out of scope here. The first is the only
one I think is a genuine hole in the design rather than a nice-to-have.

• A theme cannot change the shape of the ramp. It can move the hue, the saturation, the floor
  and the ceiling — but the fourteen step lightnesses in colorLightness are global constants. A
  theme wanting more resolution at the dark end, or a flatter middle, has no way to say so.

  Worth being precise about the size of this, because it looks larger than it is. It does not
  invalidate the parametric model — it extends it, adding a shape parameter beside the range
  parameters the ramp already has. And mechanically it is nearly free: the step positions are the
  only literals left in the ramp, since the transform, the chroma taper and the chroma ceiling all
  already resolve in CSS from --we-color-lightness-<step>. Emitting that literal as a variable
  makes the whole ramp reshapeable with no other CSS change.

  The difficulty is what a theme would state. Fourteen free numbers is a table, and tables are
  what the parametric model exists to avoid — it is the "theme as a list of colours" failure mode one
  level down, and it would let a theme put step 200 darker than step 900, silently inverting every
  role expressed over them with no test to catch it. The right shape is one number: a gamma on the
  distribution, 1.0 being today's. It expresses the actual want, it is one slider, and it cannot
  produce a non-monotonic ramp by construction.

  The work is on the JS side, where four things read the step table directly — chromaTaper,
  calculateColor, the contrast suite's lightness, and applyChromaCeilings's
  CHROMA_PEAK_LIGHTNESS = 0.6, which means "where the ramp peaks" and stops being 0.6 the moment
  the shape moves. Plus a theme field, a schemaVersion bump and a migration.

• The enforcement now covers templates and not the design system. role-audit walks the
  composed schemas; a primitive or a layer-4 component painting var(--we-color-neutral-100) in its
  own SCSS is invisible to it, and there are some — Toast, Calendar, CollapsedContent and
  Select each hardcode one. Those are a different search (stylesheets, not schemas) and the same
  defect, and the same argument applies: the vocabulary being right was never the weak part.

• A schema can still say a scale position where a role belongs. The audit catches it after the
  fact, which is a gate rather than a design. The stronger form is to make the wrong thing unsayable
  — scale positions reachable only where a palette is genuinely meant, and a validator error
  otherwise. That is a bigger change than a sweep and it needs a way to declare "this is a palette"
  at the node, which does not exist yet.

A note on why the two-layer split itself is not on this list. Scale positions following the
theme's parameters but not its decisions is the correct design, and the boundary is in the right
place: the two answer different questions, the layering is one-directional (roles are expressed over
the scale, never the reverse), and the derivations need a substrate that is not itself being
corrected or they have no ground truth to resolve against. The rule that a theme may never pin a
scale step is absolute, and this branch established elsewhere that absolutes are where theme systems
break — but that one is principled rather than lazy: a pinned step would silently move every role
expressed over it, breaking the layer beneath the one the author was editing.

Closed — everything this branch recorded

What each turned into, since three of them were not what they looked like:

• The contrast suite now calls deriveRoleVars instead of modelling it. The split is along the
  one line that is inherent — resolving a declared value to a colour is done differently by
  necessity (the runtime asks a browser, the suite does the arithmetic), and everything decided from
  those colours is now the same call. Verified by mutation: disabling the foreground correction
  produces ten failures including the exact Lc 45 that was measured in a browser when the
  derivations genuinely were not running.
• focus is var(--we-role-accent). A theme that pins its accent gets a ring in that colour —
  dark measured rgb(127,114,206) against its own rgb(112,94,201) before.
• The :root aliases have one source. ROLE_ALIASES in @we/tokens is emitted by
  generate-css.ts and re-declared by themeParametersToStyle, so a new alias reaches both by
  existing, and a test asserts the re-statement end. It found two live drifts on the way in: a
  conditional block still re-pinning --we-color-focus to primary-500, which defeated the change
  above for any theme with a primaryHue, and a --we-focus-outline that said 2px at one end and
  var(--we-focus-ring-width) at the other.
• danger, success and warning have the lightness control the accent had. The gap was not
  cosmetic: the only way to brighten a destructive button was to pin the role, which discards the
  derivations that keep its label readable — so brightening a button was also how you got an
  unreadable label on it.
• "Follow system" chooses between the agent's own two themes. It resolved straight to the
  strings light and dark, which happen to be the ids of two built-ins, so an agent with their own
  pair could follow their machine or wear their own themes, never both. AgentSettings gains the two
  ids; empty means the built-in of that polarity, so nothing changes for anyone who has not set them.
  The pair is mirrored to localStorage for the same reason the current theme is — the boot screen
  has to answer before AgentSettings exists.
• channels and timeline were audited: 25 pins down to 18. Seven turned out never to have been
  decisions — channels pinned its page, sunken surface, hover tint and text within half a point of
  what its own floor and ceiling already produce — and none of them changed a rendered colour, which
  Chrome confirmed after they were dropped. Three more were saying the right thing the wrong way and
  are now var(--we-role-page): channels' channel list and page are one sheet, timeline has no
  elevation at all. Timeline's worked by accident besides, since the parametric default is
  page + 10%, which at a white page clamps back to white — so a theme that later darkened its page
  would have kept two pure-white surfaces floating over it. A test now asks of every pin whether
  removing it changes the colour, so this cannot re-accumulate quietly.

One recorded follow-up turned out to be a non-issue, and the reasoning is worth keeping.
accentText, dangerText, successText and warningText were listed as "the same defect class as
the fills, left half-done". They are the opposite case. A fill left the ramp because it must not
invert — a brand's violet is that violet in either polarity. These are foregrounds on surfaces that
do invert, so a value that stayed put would be dark text on a dark background in half the themes.
Step 700 is a long way from 500 precisely because it swings: L 42% light, L 58% dark, which is the
accent reading dark on white and light on black. The rule underneath both is now recorded on the
roles themselves: a role that names a thing is absolute, and a role that names a relationship to
the surface it sits on is a scale position.

Also closed, and not originally recorded: the enforcement gap. Round eleven found 197 nodes that
had drifted back to scale positions, swept them at source, and made the audit a test rather than a
script. That was listed above as the sharpest weakness in the design; it is the templates half of
it, and the design-system half is in the open list.

Not this branch's to fix: packages/graph-system/core has six pre-existing typecheck errors in
its test files, on dev as well as here.

Test plan

• pnpm lint clean; pnpm build clean across the whole workspace; typecheck clean on every
  package but the pre-existing @we/graph-core failures; every suite green.
• pnpm --filter @we/schema-shared validate — 28 schemas, no issues.
• New tests: every built-in theme against the nine declared contrast pairs, and
  pickReadableForeground including the mid-click case (@we/themes); the 1→2 rename as a
  permutation, version stamping, a theme from the future, and a corrupt blob (@we/themes);
  colour parsing, conversion round trips, OKLCH round-trip exactness and its perceptual evenness
  versus HSL, WCAG reference values, translucent compositing (@we/design-utils); the tier ladder
  including the relative rung, and the roles-object update (@we/editor); camelCase-role
  rejection (@we/schema-shared).
• The three-click path to an invisible theme — Dark, then a light base preset — as a test on
  reconcileSurfaces, along with the case it must not touch (re-picking within one polarity,
  which has to leave a tuned stack alone).
• In a browser on a cleared profile, after the ramp move: hue 266, accent rgb(64,104,215),
  and channels' measured grey back at rgb(26,28,33) against rgb(28,27,29) before — the
  theme looks like itself.
• The derived stack measured in Chrome across five parameter sets — light, three dark
  subtractors, and a heavily tinted one — all four roles in order in every case, and the tint
  carried through.
• The elevation ordering as an invariant over every built-in theme — it caught three shipped
  dark themes with their surface stack inverted, which is what a value-faithful migration hides.
• pnpm --filter @we/schema-shared surface-audit — imports every schema, walks the composed
  tree, reports the nearest painting ancestor of each surface-sunken node. 389 → 86, the
  remainder being re-export duplicates and deliberate inset chips.
• The follow-up round, each verified by the thing it was about rather than by the suite passing:
  the contrast suite's call into deriveRoleVars by mutation (disabling the foreground
  correction produces the exact Lc 45 measured in a browser when the derivations were not
  running); the focus change by measuring the ring in Chrome (rgb(112,94,201), the pinned
  accent, where it was rgb(127,114,206)); the ROLE_ALIASES re-statement by a test that
  failed on first run and found two live drifts; the pin audit by measuring every role of
  every built-in theme in Chrome before and after — byte-identical across all seven themes,
  which is what "these pins were saying nothing" has to mean.
• The "Follow system" pair driven through the shell's own picker in Chrome: both selects render
  with the right labels, all seven themes plus "Built-in light or dark" as options, and the
  built-in entry selected while nothing is set.
• Not verified: "Follow system" repainting when the OS setting changes while the app is open.
  The preview harness boots with a pinned theme (data-we-theme=channels), so the document never
  follows system there and the flip cannot be observed — measured identical on the commit
  before this feature, so it is a limitation of the harness rather than a regression, but it is
  the one claim in this area that is asserted in comments and not by a test. Worth a manual pass:
  pick Follow system, set the dark half to a custom theme, and toggle the OS setting.
• pnpm --filter @we/schema-shared role-audit — imports every schema, walks the composed tree,
  reports every bg/color/border naming a scale position. 197 → 0, and now a test (~2s)
  rather than a script. Mutation-checked: restoring one of the four defaults reports all 108 of
  its call sites by name.
• Fifteen browser measurements pin the contrast resolver — three scale positions across five
  themes, sampled from Chrome, tolerance 1 rgb. The only assertions in that suite an internal
  change cannot satisfy by moving both sides at once; everything else grades from resolve().
  Mutation-checked: a broken chroma taper fails all fifteen.
• Guards for the four things round eleven found, each of which fails invisibly by construction —
  a template with no node ids renders identically and cannot be clicked; a panel painting its own
  background is only wrong next to another panel; a spacing prop naming a token that does not
  exist is silently dropped. All three assert on source, because all three are the absence of
  something, and each was mutation-checked by reintroducing the defect.
• Guards for two things that fail invisibly by construction: a multi-value part never matched by
  an exact-match attribute selector, and a built-in theme declaring a role in its CSS its preset
  does not pin.
• In a browser, shape: 16 computed-style assertions — avatar host and picture follow the
  avatar group, image/iframe/inner-iframe follow the surface group, r='avatar'/r='media'
  resolve, heading font separates from body.
• In a browser, padding: tab 8px 12px → 8px 24px under spacious controls; input and
  textarea follow inputSpacing; a pinned surface-hover reaches a hovered input.
• In a browser, role coverage per route on the default template, every role pinned to a
  sentinel: About 85/86%, Cards 88/90%, Tasks 85/84%, Calendar 89/91%, Settings 92/93%
  (backgrounds/text), with the screen unchanged when the pins are removed.
• In a browser, the tooltip is dark-with-light-text in both polarities; switching theme
  mid-edit repaints (and with the fix reverted, provably does not); the picker's token grid emits
  var(--we-color-success-500) and its colour area emits #bf2626; the swatch is square and
  painted, the token grid is styled, both dismissal paths work, and the format control renders
  as buttons.
• In a browser, after the reclassification: the header band, the sticky nav and the section
  cards no longer paint the sunken sentinel, and the dark theme's stack measures in order
  (sunken 0.0057 < page 0.0077 < surface 0.0134 < raised 0.0225 relative luminance).
• In a browser, on both branches: every built-in theme's neutral ramp captured step by step
  through the real picker and diffed. All seven now within 2.2 mean |ΔL| of the old build
  (Black 12.7 → 2.1, Cyberpunk 13.7 → 2.2, Channels 14.2 → 1.8; the other four unchanged).
• In a browser, the derivations proven to run: --we-role-text-muted resolving to a corrected
  literal rather than its declared expression, and muted text at Lc 60–61 on every theme where it
  had been 20 / 27 / 33 / 45.
• In a browser, APCA on five declared pairs across all seven themes — every one clears, with
  the single recorded exception of dark's primary button label at Lc 29, asserted as an equality
  so it cannot drift in either direction.
• In a browser, theme isolation: the same theme applied to two elements while the document
  publishes different chroma ceilings. The declared-only element washes from rgb(19,156,46) to
  rgb(99,142,100); the applied element holds rgb(59,152,67) in both. This is the property the
  preview, the swatches and the picker were each missing.
• In a browser, the accent follows its hue slider on all three themes that pin one, and
  accentLightness reaches a bright green (#008e00 → #60f16e across its range).
• In a browser, performance measured on a 583-node document: 45.2 ms → 0.6 ms per apply, with
  the colour derivation itself at 0.24 ms of that.
• In a browser, the colour picker's popover tracks its trigger inside a we-scroll-area at
  any scroll offset (was 352 px adrift at scrollTop 400).
• New tests this round: dock-registry notification on late registration and removal (4);
  the theme-id resolution facts behind the boot flash (3); the cross-fade suppressed for an edit
  and kept for a switch (2); the split status labels as declared contrast pairs (28 more rows).
• Not verified end to end: the theme editor driven through its own UI in we-preview — the
  pencil only appears for non-built-in themes, so it needs a fork first. Every fix in it is
  unit-tested and measured through the primitives directly, but the assembled panel has been
  reviewed on screen by the author of this branch's user, not by its harness.