Extend the token contract past colour, invert the button base (v2.10.0)

A design audit read all three repos and found the same thing everywhere: the
guards check colour values and token names, and nothing else. Not numbers, not
fonts, not shadows, not transitions, not breakpoints — and that is exactly
where the three repositories had come apart. Drift here has never been a
discipline problem; the annotated breakpoints and careful fallback comments are
evidence of real care. It is a coverage problem.

So publish more, and assert what is published.

tokens.json gains two keys. `values.light` / `values.dark` resolve EVERY
non-colour token to a literal CSS value — type steps, spacing, radii, control
sizes, font stacks, transitions, and shadows collapsed through their oklab
mixes to rgba(). `breakpoints` publishes the media-query widths, which media
queries cannot read as custom properties and so must restate as literals. Both
modules now compare against them; between them they found ~290 drifted
fallbacks that no guard could previously see.

check-token-usage.js also fails on a font-size set to an absolute literal. The
theme was reaching around its own scale twice (_buttons.scss, _language-tag)
while the modules did it ninety times — when the source of truth does it, the
consumers will do it more. --text-2xs (11px) is the new floor and extends the
UI tier into a 11/13/15/17/19 progression; there is deliberately no 14px step.

Scale collapse, since a system that avoids elevation published nine elevation
tokens and four non-pill radii: --shadow-xl and --radius-xl are removed (both
were referenced by nothing in any of the three repos), each remaining shadow
and radius is documented with the one job it has, and the glow ramp is labelled
as what it is — the three states of one button, not a scale.

Focus was one decision with four tokens, two idioms and no rule for choosing.
There is now --focus-outline for the composed default outline (its absence is
why one declaration got hand-copied 44 times downstream), --ring-focus for when
an outline would be clipped, and the tint is renamed --focus-ring-color so no
two focus tokens are one transposition apart.

Finally, the button base is inverted. A bare <button> is now quiet — outlined,
flat, ink on transparent — and the filled-primary treatment opts in via
.btn--primary or by being a submit control, which is the one button in a form
that IS the loud action. It was backwards: sixteen component files reset
border-radius / box-shadow / transform purely to escape a default that a system
whose stated register is restraint should never have had. Those resets are now
redundant rather than load-bearing, and the gotcha runs the other way: a
control that needs to shout must say so.

Also fixes a real bug in the published vocabulary — the declaration regex was
matching BEM modifiers in selectors, so `.cell--type::before` published `--type`
and `--date` as theme tokens. Fictional entries in `names` are precisely what
the name check exists to catch.

Author: fmadore

CLAUDE.md

@@ -37,17 +37,43 @@ that renders it — and "fixing" it by lowercasing `theme.ini` just moves the fa
 
 ### Design tokens are machine-checked — never hand-maintain a list
 
-`scripts/build-tokens.js` resolves every OKLCH token in `_colors.scss` to sRGB and writes
-`tokens.json` — the light/dark values **plus** `names`, the full token vocabulary — then
+`scripts/build-tokens.js` reads the four variable files and writes `tokens.json`, then
 syncs it into IwacSearch and IwacVisualizations, whose `check-theme-tokens` guards fail
-their builds on a drifted fallback or an unknown token name.
+their builds on anything that disagrees with it. It publishes four things:
+
+| Key | What |
+|---|---|
+| `light` / `dark` | every OKLCH colour token resolved to sRGB hex |
+| `values.light` / `values.dark` | every **other** token resolved to a literal CSS value — type steps, spacing, radii, control sizes, font stacks, shadows (collapsed to `rgba()`), transitions |
+| `names` | the full custom-property vocabulary |
+| `breakpoints` | the six media-query widths |
 
 - A wrong or invented token name is caught by `npm run check:tokens`. Run it; don't
   reason about it from memory.
-- **Adding a token is a cross-repo change**: `npm run build:tokens`, then rebuild both modules.
+- **Adding a token is a cross-repo change**: `npm run sync:tokens`, then rebuild both modules.
 - Never hand-edit `tokens.json` or the `<!-- BEGIN GENERATED -->` tables in
   [docs/DESIGN-SYSTEM.md](docs/DESIGN-SYSTEM.md).
 
+`values` and `breakpoints` exist because the guards used to check colour and nothing
+else: the fallback assertion was a regex matching a hex literal in the fallback slot, so
+every non-colour fallback in three repos was unchecked, and roughly 290 of them had
+drifted — line-heights, control sizes, type steps, font stacks (one still naming the
+removed *Noto Serif*), shadows, transitions. **Drift here has never been a discipline
+problem; it is a coverage problem.** Every value the generator publishes and a guard
+compares has stayed correct across a major redesign. Every value left to prose moved.
+So: when you add a design decision, publish it and assert it — a comment saying
+`/* sm */` beside a `640px` media query is what "documented" looked like right up until
+it was wrong.
+
+### Type sizes and media widths are asserted too
+
+`npm run check:tokens` also fails on a `font-size` set to an absolute literal (px/rem/pt)
+anywhere in `asset/sass` — use a `--text-*` token; `--text-2xs` (11px) is the floor, and
+there is deliberately no 14px step. Relative units (`em`, `%`) stay legal. Both modules'
+guards enforce the same rule plus the breakpoint contract: `min-width` sits **on** a
+published breakpoint, `max-width` at **breakpoint − 1**, so the halves of a pair never
+both match.
+
 ### `asset/css/` is generated
 
 Edit `asset/sass/`. Anything written to `asset/css/` is overwritten by the next build.
@@ -68,12 +94,21 @@ keep the mixing perceptual.
 Use `> dl > .property > dd`. Value-annotation tooltips nest their own `<dl>` inside a
 `<dd>`, and a descendant selector leaks the 168px label-column layout into them.
 
-### Every `<button>` inherits the global base style
-
-`_buttons.scss` gives all buttons a radius, `box-shadow: var(--glow-sm)`, and a hover
-lift + glow. A component that overrides only `background`/`color` keeps the rounded
-floating shape and the halo — reset `border-radius`, `box-shadow` and `transform`
-explicitly.
+### The `<button>` default is QUIET — the loud one opts in
+
+Inverted in 2.10. A bare `<button>` is now an outlined flat control (ink text, hairline
+border, no shadow, no lift). The filled-primary treatment — brand fill, `--glow-sm`
+halo, hover lift — comes from `.btn--primary` or from being a **submit** control
+(`input[type=submit]` / `button[type=submit]`), which Omeka core and module forms render
+without any theme class to hook.
+
+Before this, the base selector painted *every* button filled-and-glowing, so sixteen
+component files reset `border-radius` / `box-shadow` / `transform` purely to escape the
+default, and a component overriding only `background`/`color` silently kept a rounded
+floating halo. Those resets are now redundant rather than load-bearing — harmless where
+they remain, and safe to drop when you're already editing the file. The thing to watch
+now is the reverse: **a control that needs to shout must say so**, or it will render
+quiet.
 
 ### Read a module's rendered HTML before styling it
 

asset/css/style.css

@@ -52,30 +52,37 @@
         box-shadow var(--transition-fast);
 }
 
-@mixin primary-button {
-    @include button;
+// ==========================================================================
+// The LOUD button — filled primary, glow, hover lift.
+//
+// Appearance only (no padding / case / layout), so it can be laid over the
+// quiet base in _buttons.scss without re-deciding geometry. This is the
+// opt-in half of the base-style inversion: until v2.10 every <button> in the
+// document got this treatment by default and any quiet control had to reset
+// three properties to escape it. Restraint is the register; the shout opts in.
+// ==========================================================================
+@mixin button-filled {
     background: var(--primary);
-    border: none;
+    border: 1px solid transparent;
     color: var(--white);
     box-shadow: var(--glow-sm);
 
-    &:hover:not(.disabled) {
+    &:hover:not(:disabled):not(.disabled) {
         background: var(--primary-hover);
+        border-color: transparent;
         color: var(--white);
         transform: translateY(var(--lift-xxs));
         box-shadow: var(--glow-md);
     }
 
-    &:active:not(.disabled) {
+    &:active:not(:disabled):not(.disabled) {
         background: var(--primary-active);
         transform: translateY(0);
         box-shadow: var(--glow-xs);
     }
 
     &:focus-visible {
         color: var(--white);
-        outline: 2px solid var(--primary);
-        outline-offset: 2px;
     }
 
     &:disabled,
@@ -92,6 +99,16 @@
     }
 }
 
+@mixin primary-button {
+    @include button;
+    @include button-filled;
+
+    &:focus-visible {
+        outline: 2px solid var(--primary);
+        outline-offset: 2px;
+    }
+}
+
 // ==========================================================================
 // Card hover effect
 // Consistent shadow + quiet border emphasis. Calmer than v1's brand-tinted
@@ -112,9 +129,11 @@
 // Focus ring
 // Consistent focus-visible outline for interactive elements
 // ==========================================================================
+// The default focus idiom. Use --ring-focus instead when an outline would be
+// clipped (inside overflow:hidden or a scroll container) — see _tokens.scss.
 @mixin focus-ring {
     &:focus-visible {
-        outline: 2px solid var(--focus-color);
+        outline: var(--focus-outline);
         outline-offset: 2px;
     }
 }

asset/sass/abstracts/mixins/_mixins.scss

@@ -1,3 +1,14 @@
+// The responsive contract. Published into tokens.json by build-tokens.js and
+// asserted by both modules' check-theme-tokens.js, because media queries
+// cannot read custom properties: the modules necessarily restate these as
+// literals, and until 2026-08 the only thing keeping them honest was a
+// `/* sm */` comment beside each one. That failed twice — IwacVisualizations'
+// laicite block reflowed at 640px labelled "sm" while every other block on
+// the same page reflowed at 600px.
+//
+// Six steps. Use `max-width: #{$x - 1px}` (or `- 0.02px`) for the "below"
+// half of a pair so the two never overlap.
+$xs: 400px;   // narrow phones — hero headline step only
 $sm: 600px;
 $md: 768px;
 $lg: 1024px;

asset/sass/abstracts/variables/_breakpoints.scss

@@ -63,7 +63,7 @@
 
   // Semantic / state
   --focus-color: var(--primary);
-  --focus-ring:  color-mix(in oklab, var(--primary) 30%, transparent);
+  --focus-ring-color:  color-mix(in oklab, var(--primary) 30%, transparent);
   --selection-bg: color-mix(in oklab, var(--primary) 14%, transparent);
 
   // Status colors — OKLCH, calibrated for AA on light surfaces
@@ -157,7 +157,7 @@
   --border-strong: oklch(42% 0.016 70);
 
   --focus-color: var(--primary);
-  --focus-ring:  color-mix(in oklab, var(--primary) 35%, transparent);
+  --focus-ring-color:  color-mix(in oklab, var(--primary) 35%, transparent);
   --selection-bg: color-mix(in oklab, var(--primary) 22%, transparent);
 
   --success:    oklch(72% 0.14 152);

asset/sass/abstracts/variables/_colors.scss

@@ -20,11 +20,17 @@
   --shadow-color-strong: color-mix(in oklab, oklch(15% 0.01 264) 18%, transparent);
   --shadow-color-subtle: color-mix(in oklab, oklch(20% 0.01 264) 6%,  transparent);
 
+  // Four steps, deliberately not five: shadows are reserved for true panels
+  // and overlays here — rows and tags are divided by rules instead — so an
+  // elevation scale long enough for a card-based grammar is a scale that
+  // gets used like one. --shadow-xl (the fifth) was removed in 2.10: it was
+  // referenced by nothing in any of the three repos.
+  //   xs — hairline lift on quiet chrome    sm — panels (--panel-shadow)
+  //   md — hover / raised panels            lg — overlays: drawer, modal
   --shadow-xs: 0 1px 2px 0  var(--shadow-color-subtle);
   --shadow-sm: 0 1px 3px 0  var(--shadow-color), 0 1px 2px -1px var(--shadow-color-subtle);
   --shadow-md: 0 4px 6px -1px var(--shadow-color), 0 2px 4px -2px var(--shadow-color-subtle);
   --shadow-lg: 0 10px 15px -3px var(--shadow-color), 0 4px 6px -4px var(--shadow-color-subtle);
-  --shadow-xl: 0 20px 25px -5px var(--shadow-color), 0 10px 10px -5px var(--shadow-color-subtle);
 
   --panel-bg: var(--surface);
   // See the note in :root — re-declare so the inner var() resolves against
@@ -62,12 +68,20 @@
   // ========================================================================
   // Border Radius Scale
   // ========================================================================
-  --radius-sm: 0.375rem; // 6px
-  --radius-md: 0.5rem;   // 8px — tightened from 12px to feel more
-                         // institutional/instrument-like, less consumer
-  --radius-lg: 0.75rem;  // 12px
-  --radius-xl: 1rem;     // 16px
-  --radius-full: 9999px;
+  // Three non-pill steps, each with ONE job. A rules-not-boxes system that
+  // publishes four interchangeable radii invites four different answers to
+  // the same question — which is how maps ended up at 6px, cards at 8px and
+  // the compact search panel at 12px on the same page.
+  --radius-sm: 0.375rem; // 6px  — inline marks: chips, tags, map controls
+  --radius-md: 0.5rem;   // 8px  — DEFAULT for panels, controls, inputs.
+                         // Tightened from 12px to feel more
+                         // institutional/instrument-like, less consumer.
+  --radius-lg: 0.75rem;  // 12px — media only: figures, thumbnails, carousel
+                         // plates. A photograph reads as matted, not as a
+                         // card; nothing that is chrome may use this.
+  --radius-full: 9999px; // pills
+  // (--radius-xl, 16px, removed in 2.10 — declared, referenced by nothing in
+  //  any of the three repos, and one more way to disagree about a corner.)
 
   // ========================================================================
   // Accent Lines & Lift
@@ -103,9 +117,29 @@
   --measure-wide:   72.5rem;   // ~1160px — search results, wide lists
 
   // ========================================================================
-  // Focus Rings
-  // ========================================================================
-  --ring-focus:    0 0 0 3px var(--focus-ring);
+  // Focus — ONE decision, two idioms, and a rule for picking between them.
+  //
+  //   --focus-outline   DEFAULT. `outline` + `outline-offset: 2px`. Use it
+  //                     unless the element is clipped.
+  //   --ring-focus      The box-shadow ring, for when an outline would be
+  //                     clipped: inside `overflow: hidden`, inside a scroll
+  //                     container, or on an element flush against a panel
+  //                     edge. --ring-focus-sm is the tighter 2px version for
+  //                     dense controls.
+  //   --focus-color     the colour. --focus-ring-color is the translucent
+  //                     tint --ring-focus is built from; consuming it
+  //                     directly is almost always a mistake.
+  //
+  // The four names used to be --focus-color / --focus-ring / --ring-focus /
+  // --ring-focus-sm with nothing saying which applied when, and --focus-ring
+  // vs --ring-focus one transposition apart. The result downstream was
+  // `outline: 2px solid var(--focus-color, var(--primary, #ce4115))`
+  // hand-copied 44 times across IwacVisualizations' block stylesheets —
+  // because there was no token for the composed outline, only for its
+  // colour. --focus-outline is that token.
+  // ========================================================================
+  --focus-outline: 2px solid var(--focus-color);
+  --ring-focus:    0 0 0 3px var(--focus-ring-color);
   --ring-focus-sm: 0 0 0 2px color-mix(in oklab, var(--primary) 22%, transparent);
 
   // ========================================================================
@@ -123,7 +157,11 @@
   --tracking-wider:  0.08em;
 
   // ========================================================================
-  // Glow Effects (primary-tinted shadows for buttons/accents)
+  // Glow (primary-tinted shadow) — ONE effect, three states.
+  //
+  // Not an elevation scale: xs/sm/md are the active / rest / hover states of
+  // the single filled button (see base/elements/_buttons.scss, which is the
+  // only sanctioned consumer). Nothing else in the system glows.
   // Derived from --primary so admin color overrides cascade through.
   // ========================================================================
   --glow-xs: 0 1px 3px 0  color-mix(in oklab, var(--primary) 20%, transparent);
@@ -184,7 +222,6 @@
   --shadow-sm: 0 2px 6px -1px var(--shadow-color), 0 2px 4px -2px var(--shadow-color-subtle);
   --shadow-md: 0 6px 16px -4px var(--shadow-color-strong), 0 4px 8px -4px var(--shadow-color-strong);
   --shadow-lg: 0 12px 28px -8px color-mix(in oklab, black 35%, transparent), 0 8px 16px -8px color-mix(in oklab, black 20%, transparent);
-  --shadow-xl: 0 20px 40px -12px color-mix(in oklab, black 45%, transparent), 0 12px 24px -8px var(--shadow-color-strong);
 
   --panel-bg: var(--surface-raised);
   // See comment in :root block — re-declare for dark cascade.

asset/sass/abstracts/variables/_tokens.scss

@@ -37,6 +37,21 @@ $font__pre: $font__code;
   // where the visual gain at large viewports is real and the drift on
   // mid-sizes isn't distracting. Body & UI sizes hold steady so a 14px
   // facet label doesn't quietly become 14.6px between breakpoints.
+  // The UI tier is a 2px arithmetic progression: 11 · 13 · 15 · 17 · 19.
+  // --text-2xs is the FLOOR — nothing in the stack may set type smaller,
+  // and there is deliberately no 14px step. Both halves of that sentence
+  // are load-bearing:
+  //
+  //   * Before the floor existed, the scale stopped at 13px while dense
+  //     axis / chip / legend labels genuinely need less, so ~12 of them
+  //     were written as bare 0.6875rem literals here and in
+  //     IwacVisualizations, plus a 9px one. A step nothing can reach is
+  //     a step everyone reaches around.
+  //   * A 14px step would put three sizes inside 2px, which is a puddle,
+  //     not a scale. IwacVisualizations' 12/14/18px literals came from a
+  //     generic utility framework, not from a gap here: they migrate to
+  //     13 / 15 / 19 rather than the theme growing a step to match them.
+  --text-2xs:   0.6875rem;   // 11px — FLOOR: dense axis/legend/chip labels
   --text-xs:    0.8125rem;   // 13px — eyebrow labels, metadata dt
   --text-sm:    0.9375rem;   // 15px — secondary UI, captions
   --text-base:  1.0625rem;   // 17px — body copy