@terpjs/react-core 0.13.0 → 0.14.0

package/src/styles.ts

@@ -181,6 +181,20 @@ export const TERP_STYLES_CSS = `
   --density-cell-pad-y: var(--density-compact-cell-pad-y);
   --density-cell-pad-x: var(--density-compact-cell-pad-x);
 }
+/* The content column's gutter, tightened for a phone. One remap, and it replaces the two
+   base-plus-variant pairs the header and main each used to carry: everything that has to
+   start on the same vertical line now reads --shell-gutter and the variant moves the value
+   once. The band the page header renders also reads it as a NEGATIVE margin to bleed to the
+   column's edge, so a fourth and fifth copy of the same measure would have arrived with it —
+   which is what turned this from a nice-to-have into the mechanism.
+
+   UNLAYERED, beside the density remap, for the reason recorded there and not by analogy:
+   tokens.css declares --shell-gutter on :root and ships as an extracted <link> that PRECEDES
+   the injected sheet, so a layered copy of this rule would lose to it in a production build
+   while winning in dev. (0,2,0) against :root's (0,1,0) settles it here in either. */
+[data-terp="appshell"][data-variant="mobile"] {
+  --shell-gutter: var(--space-4);
+}
 
 @layer terp.reset {
 /* Document reset: the app shell owns the full canvas. Without this the
@@ -391,9 +405,12 @@ html {
   border: 1px solid;
   border-radius: var(--radius-md);
 }
+/* The neutral tone's wash is --color-neutral-100, the value Badge and a neutral-toned
+   row already spell for the same tone. It was --color-neutral-50, which is the canvas: on
+   a card with no fill the alert kept its border and lost its wash entirely. */
 [data-terp="alert"][data-tone="neutral"] {
   color: var(--color-neutral-600);
-  background: var(--color-neutral-50);
+  background: var(--color-neutral-100);
 }
 [data-terp="alert"][data-tone="info"] {
   color: var(--color-status-info);
@@ -546,6 +563,56 @@ textarea[data-terp="input"] {
   [data-terp="splitpage-panes"][data-list-width="lg"] {
     grid-template-columns: minmax(0, 32rem) minmax(0, 1fr);
   }
+  /* DetailList's multi-column half. Mobile-first, like SplitPage's panes above: the narrow
+     shape is one column with the term as a block above its value, which is the BASE rule and
+     therefore needs no query at all — this block is only the widths at which a shared label
+     column, or two pairs per row, fit.
+
+     They ran at every width before, and 430px is where that showed: four tracks in ~370px, and
+     detail-list-value's overflow-wrap: anywhere then broke words mid-token rather than letting
+     a value have its own line. The anywhere is right — it is what stops an unbreakable digest
+     overflowing its column — so the fix is to stop asking a phone to hold four tracks.
+
+     Why a viewport query and not a container query, which would be the more nearly right
+     instrument: container queries appear nowhere in this sheet, so introducing one for a single
+     component is a mechanism change that wants its own record rather than a line in a defect
+     fix, and the cutover the framework already has covers the width the failure was measured
+     at. It is also why DetailList reflows itself while Grid deliberately refuses to for a fixed
+     column count — Grid publishes columns="auto" as its responsive answer, and DetailList's
+     closed one-or-two has no such escape, so the reflow has to be the component's own.
+
+     PLACEMENT: the detail-list base rules are declared ~100 lines BELOW this block, so source
+     order cannot settle these. Specificity does, and deliberately: every selector here carries
+     the marker plus at least one attribute (0,2,0) against the base rule's (0,1,0). That is
+     exactly how splitpage-panes above already wins over its own base rule further down, and
+     styles.test.ts pins the property, because a reader cannot see it from the rule. The one
+     thing this block must NOT declare is row-gap: that belongs to the gap prop, whose roll-call
+     weighs the same (0,2,0) and is therefore declared later on purpose. */
+  [data-terp="detail-list"][data-columns="2"] {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    column-gap: var(--space-4);
+  }
+  /* minmax(0, max-content) rather than a bare auto for the label track. An auto track floors
+     at min-content, which makes it the one track in this component that was never floored at
+     zero — so a label with nothing to break on widened the column and pushed the list past its
+     container, the same failure the value track's minmax(0, 1fr) was written to stop. Capping at
+     max-content also stops the label column claiming width no label is using: measured in a
+     565px card, two independently-sized auto label tracks left a value track of ~400px holding
+     ~60px of text. */
+  [data-terp="detail-list"][data-layout="aligned"] {
+    grid-template-columns: minmax(0, max-content) minmax(0, 1fr);
+    column-gap: var(--space-3);
+  }
+  [data-terp="detail-list"][data-layout="aligned"][data-columns="2"] {
+    grid-template-columns: repeat(2, minmax(0, max-content) minmax(0, 1fr));
+  }
+  /* display: contents is what makes the dt and dd grid items of the dl itself, so labels align
+     ACROSS rows without a DOM change — and it belongs in here rather than in the base rules
+     because it is the mechanism of the shared column, which exists only above the cutover.
+     Narrow, the row wrapper stays a block and each pair reads as two lines. */
+  [data-terp="detail-list"][data-layout="aligned"] [data-terp="detail-list-row"] {
+    display: contents;
+  }
 }
 
 /* Grids -------------------------------------------------------------------- */
@@ -645,26 +712,22 @@ textarea[data-terp="input"] {
      the mechanism anywhere in the suite. */
   overflow-wrap: anywhere;
 }
-/* Two pairs per row. minmax(0, 1fr) rather than 1fr for the reason Grid's fixed counts need
-   it: a bare 1fr floors at min-content, and a 64-character digest with nothing to break on
-   then widens its column and pushes the list past its container — which is the defect the
-   diagnosis was describing, rather than the missing alignment it named. */
-[data-terp="detail-list"][data-columns="2"] {
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  column-gap: var(--space-4);
-}
-/* Aligned: every label in a shared column. The row wrapper becomes display: contents so the
-   dt and dd are grid items of the dl itself — the only way to align across rows without
-   changing the DOM, and the reason the wrapper needed a marker at all. */
-[data-terp="detail-list"][data-layout="aligned"] {
-  grid-template-columns: auto minmax(0, 1fr);
-  column-gap: var(--space-3);
-}
-[data-terp="detail-list"][data-layout="aligned"][data-columns="2"] {
-  grid-template-columns: repeat(2, auto minmax(0, 1fr));
-}
-[data-terp="detail-list"][data-layout="aligned"] [data-terp="detail-list-row"] {
-  display: contents;
+/* The tracks for two pairs per row, and for aligned, live in the wide-viewport block above
+   rather than here: one column is the narrow shape and therefore the base. What stays here is
+   everything that holds at every width.
+
+   Both non-inline layouts open their rows to --space-3. At the base --space-1 the distance
+   WITHIN a pair and the distance BETWEEN pairs were the same 4px, so a card of five labelled
+   values had nothing grouping it — five pairs read as ten equally-spaced lines. inline keeps
+   --space-1, because there a pair IS one line of a paragraph and 4px is the leading between
+   lines of one block; opening it would space out a run of sentences.
+
+   row-gap rather than gap, and the distinction is load-bearing: the column gap in aligned is
+   the label-to-value distance, and at two pairs per row it is the space between pair groups —
+   both owned by the rules in the wide block. A shorthand here would silently reset them. */
+[data-terp="detail-list"][data-layout="aligned"],
+[data-terp="detail-list"][data-layout="stacked"] {
+  row-gap: var(--space-3);
 }
 [data-terp="detail-list"][data-layout="aligned"] [data-terp="detail-list-term"],
 [data-terp="detail-list"][data-layout="aligned"] [data-terp="detail-list-value"],
@@ -672,12 +735,37 @@ textarea[data-terp="input"] {
 [data-terp="detail-list"][data-layout="stacked"] [data-terp="detail-list-value"] {
   display: block;
 }
-/* Stacked: label above value. The label takes the muted step so the pair reads as one unit
-   rather than two lines of equal weight. */
+/* The label takes the muted, smaller, regular step so a pair reads as one unit rather than two
+   lines of equal weight — and aligned shares the rule rather than getting a second treatment
+   of its own. It did not, and that was the defect: an aligned term measured 16px / weight 500 /
+   near-black, which is the value's own typography, so a card of five labelled values rendered
+   as a wall of bold text with nothing telling a reader which half to read first.
+
+   inline is deliberately NOT here. There the term is half a sentence — the colon comes from
+   the ::after above — and muting half a sentence is a different defect from the one this fixes.
+   Two layouts diverging was the bug; three converging would be another. */
+[data-terp="detail-list"][data-layout="aligned"] [data-terp="detail-list-term"],
 [data-terp="detail-list"][data-layout="stacked"] [data-terp="detail-list-term"] {
   font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-normal);
   color: var(--color-fg-muted);
 }
+/* The gap prop, and this block must stay AFTER the layout rules above. Both
+   [data-terp="detail-list"][data-gap="3"] and [data-terp="detail-list"][data-layout="aligned"]
+   weigh (0,2,0), so nothing but source order decides which row-gap a list carrying both
+   attributes renders — backwards, the prop silently does nothing, which looks like the prop not
+   working rather than like a cascade mistake. The same tie the responsive Stack rules turn on,
+   pinned the same way in styles.test.ts.
+
+   row-gap only, for the reason the layout rules above give. The prop is documented as the
+   distance BETWEEN pairs, and the column gap stays the layout's. */
+[data-terp="detail-list"][data-gap="0"] { row-gap: var(--space-0); }
+[data-terp="detail-list"][data-gap="1"] { row-gap: var(--space-1); }
+[data-terp="detail-list"][data-gap="2"] { row-gap: var(--space-2); }
+[data-terp="detail-list"][data-gap="3"] { row-gap: var(--space-3); }
+[data-terp="detail-list"][data-gap="4"] { row-gap: var(--space-4); }
+[data-terp="detail-list"][data-gap="6"] { row-gap: var(--space-6); }
+[data-terp="detail-list"][data-gap="8"] { row-gap: var(--space-8); }
 
 /* Checkboxes / radios / switches ------------------------------------------- */
 /* One label shape for all three, so the marker is shared: the control differs,
@@ -727,11 +815,42 @@ textarea[data-terp="input"] {
 }
 
 /* Cards -------------------------------------------------------------------- */
+/* The surface model, and this is the rule that states it: an in-flow block declares a
+   FRAME and no fill. Border, radius and padding are the whole of a card's chrome, and
+   what shows through it is the canvas the page already paints.
+
+   It used to paint --color-neutral-0 over a --color-neutral-50 canvas — a second colour
+   saying what the border already says, and it cost twice. A card dropped onto anything
+   that is itself a surface repainted it rather than sitting on it, which is the
+   frame-inside-a-frame the plain variant exists to escape; and an app that themed the
+   canvas found that its cards did not follow, because the fill named the OTHER end of
+   the ramp. Both go away with the declaration: the plain variant is now the base rule
+   minus a border and a padding, and a themed canvas reaches every block on the page.
+
+   Six rules follow the same line, and they are the framework's other in-flow blocks:
+   hubcard-body, profile-card, resource-list-row, empty-state, dataview-card and the full
+   DataView's table frame — whose header cells carried the same fill, invisibly, since a
+   filled frame sat directly behind them. Three kinds of element deliberately do NOT. An
+   overlay has to be opaque over whatever it covers (dialog, popover-panel, toast, the
+   combobox list, and appshell-header, which the page scrolls under); a control needs a
+   surface of its own to read as a control against the page (input, select, the secondary
+   button); and login-card is the one object on an otherwise empty canvas, where the fill
+   IS the object.
+
+   The washes moved with it, because a wash that painted --color-neutral-50 was painting
+   the canvas and on a card with no fill it painted nothing: the table's hover and
+   selection, the expanded row's panel, a code block, a neutral alert and a disabled
+   control each step one place along the ramp to --color-neutral-100 — which is already
+   this sheet's hover wash for every control — or to the --color-interactive-* token that
+   names the state. One step along the ramp rather than a value per rule, because the dark
+   themes invert it: the same step is darker than the canvas in light and lighter in dark,
+   midnight and twilight, which is the direction a recess and a wash want in each.
+   --color-bg-inset cannot do that job — in those three themes it is declared AS the
+   canvas value, so an inset named from it would be the one thing that disappears. */
 [data-terp="card"] {
   display: flex;
   flex-direction: column;
   gap: var(--space-3);
-  background: var(--color-neutral-0);
   border: 1px solid var(--color-neutral-200);
   border-radius: var(--radius-lg);
   padding: var(--space-4);
@@ -751,19 +870,48 @@ textarea[data-terp="input"] {
   flex-wrap: wrap;
   gap: var(--space-3);
 }
+/* start rather than center once there is a description, and the condition is the whole point.
+   With a title alone, center is right: the actions slot is a control, so its box is
+   --density-control-min-height tall against a single line box, and start would leave the title
+   riding above it. With two or three lines of description the same declaration floats the
+   control in the middle of the block instead of beside the title it belongs to.
+
+   :has() rather than an attribute Card could stamp, for the reason control-label's disabled
+   states use it (see the note there): the header has no idea what its heading holds, and the
+   alternative is a prop describing the DOM back to the sheet. Specificity (0,2,0) beats the
+   base rule above, so this does not depend on its position. */
+[data-terp="card-header"]:has([data-terp="card-description"]) {
+  align-items: start;
+}
+/* flex: 1 1 0, and the base size is the load-bearing half. Left at the initial 0 1 auto, the
+   heading's hypothetical main size is the max-content width of a block holding a title AND a
+   sentence of description — and flex breaks lines on hypothetical main sizes BEFORE it shrinks
+   anything, so with flex-wrap above the heading claimed the whole line and the actions slot
+   wrapped underneath it. Measured: a 103px header with the button below the description, where
+   the same component with no description rendered inline at 48px. Same prop, two results,
+   depending on whether a sibling prop was set.
+
+   A base size of 0 means both items fit on one line by construction, and the heading then grows
+   into whatever the actions slot does not use. min-width: 0 stays for the other half of that
+   story: a flex item's automatic minimum size is its content's, so a long unbreakable word in a
+   title would otherwise refuse to shrink past it. */
 [data-terp="card-heading"] {
+  flex: 1 1 0;
   min-width: 0;
 }
-/* Chrome off, heading kept. Three declarations removed rather than a second component
+/* Chrome off, heading kept. Two declarations removed rather than a second component
    with six markers of its own describing the same DOM: a titled region inside something
    that is already a surface wants no second border, and the commonest instance is a
    section whose body is a DataView — boxed, the table gets a border inside a border and
    loses the full width its own scroll container gives it.
 
+   Two, and it was three: background: none went with the base rule's fill. Un-declaring
+   what nothing declares is the shape ADR 0094 exists to avoid, and here it would also
+   have been the only line in the sheet still implying a card has a colour of its own.
+
    padding: 0 rather than dropping the declaration, because the base rule sets it and an
    absent value inherits nothing useful. */
 [data-terp="card"][data-variant="plain"] {
-  background: none;
   border-color: transparent;
   padding: 0;
 }
@@ -837,12 +985,16 @@ textarea[data-terp="input"] {
   background: var(--color-neutral-100);
   color: var(--color-fg-default);
 }
+/* The same wash as inline code, and that is new: the block was --color-neutral-50 while
+   the chip above it was --color-neutral-100, so two renderings of one thing disagreed —
+   and the block's half was the canvas, which a card with no fill would have shown
+   through. One value now, for both. */
 [data-terp="code-block"] {
   margin: 0;
   padding: var(--space-3);
   border: 1px solid var(--color-neutral-200);
   border-radius: var(--radius-md);
-  background: var(--color-neutral-50);
+  background: var(--color-neutral-100);
   overflow-x: auto;
   font-size: var(--font-size-sm);
   line-height: var(--font-line-height-base);
@@ -892,9 +1044,15 @@ textarea[data-terp="input"] {
 [data-terp="card-actions"] {
   flex-shrink: 0;
 }
+/* lg, and it is no longer "the step below the page title" — page-title moved DOWN to sm in
+   0.14.0 when the header became a band, so a section heading is now two steps above the view's
+   own h1. That inversion is deliberate and belongs to the band: a page title there is chrome
+   naming where you are, not the largest thing on the page, while a card title is the heading
+   of content you are reading. The original reasoning for lg is unchanged: at base a section
+   heading was typographically indistinguishable from the prose underneath it. */
 [data-terp="card-title"] {
   margin: 0;
-  font-size: var(--font-size-base);
+  font-size: var(--font-size-lg);
   font-weight: var(--font-weight-semibold);
   line-height: 1.3;
 }
@@ -1296,6 +1454,30 @@ textarea[data-terp="input"] {
   flex-grow: 1;
   min-width: 0;
 }
+/* The header's INLINE padding is the content column's gutter, and it is a shared measure
+   rather than a value this rule is free to pick. Four boxes have to start on the same
+   vertical line — this header, appshell-main, appshell-footer, and the band the page header
+   renders, which reaches the column's edge by reading the same value as a negative margin.
+
+   It was var(--space-4) here against var(--space-6) on main and on the footer, which put
+   the breadcrumb trail 0.5rem right of the header's own toggle on every desktop shell and
+   lined it up with nothing: two of the three boxes already agreed and the header was the
+   outlier. Not a clean indent either, which is why it read as broken rather than deliberate
+   — the toggle is a 2.25rem box centring a 1em glyph at font-size-sm, so its BOX sat 8px
+   left of the trail while its GLYPH sat 3px right of it. On mobile it happened to be
+   correct, because main stepped down to var(--space-4) and met the header's fixed value by
+   accident.
+
+   Every reader now names --shell-gutter and the variant moves the value once, at the remap
+   above. That is a published contract token rather than a private property because
+   tokens.guard.test.ts refuses a fallback-less var() against anything tokens.css does not
+   declare — and a shell measure an app may want to move is what ADR 0097 §1 says a contract
+   token is for. The block padding is untouched and stays var(--space-2) under the
+   min-height floor.
+
+   No backticks anywhere above, and that is not a style preference: one here terminates
+   TERP_STYLES_CSS and the parse then fails somewhere else entirely with "try inserting a
+   semicolon". This comment cost that mistake once too, which is twice in one sheet. */
 [data-terp="appshell-header"] {
   position: sticky;
   top: 0;
@@ -1305,7 +1487,7 @@ textarea[data-terp="input"] {
   align-items: center;
   justify-content: space-between;
   gap: var(--space-3);
-  padding: var(--space-2) var(--space-4);
+  padding: var(--space-2) var(--shell-gutter);
   min-height: var(--shell-header-height);
   box-sizing: border-box;
   background: var(--color-neutral-0);
@@ -1358,16 +1540,26 @@ textarea[data-terp="input"] {
 [data-terp="appshell-brand-row"] > [data-terp="iconbutton"] {
   color: var(--color-sidebar-muted);
 }
+/* Main, the footer and the page band all read the same gutter as the header — see that rule
+   for why they are one measure. The mobile override this pair used to carry is gone into the
+   remap: --shell-gutter is 1.5rem on desktop and 1rem on a phone, which is exactly what main's
+   two rules computed, so main does not move and it has one owner instead of two.
+
+   THE FOOTER DOES MOVE, and it is the one thing here that is a change rather than a
+   refactor. It carried var(--space-6) with no mobile override, so its inline padding stayed
+   1.5rem at every width while main stepped down to 1rem beside it; reading the gutter now
+   tightens it to 1rem on a phone, 8px left of where it was. That is the point of the measure
+   rather than a casualty of it — a footer indented past the content above it was the same
+   disagreement this token exists to end — but no baseline covers it, because the 420x900
+   phone specimens put the footer below the fold. Stated here because it is invisible to the
+   lanes and would otherwise read as an accident to whoever finds it. */
 [data-terp="appshell-main"] {
   flex-grow: 1;
-  padding: var(--space-6);
+  padding: var(--shell-gutter);
   min-width: 0;
 }
-[data-terp="appshell"][data-variant="mobile"] [data-terp="appshell-main"] {
-  padding: var(--space-4);
-}
 [data-terp="appshell-footer"] {
-  padding: var(--space-3) var(--space-6);
+  padding: var(--space-3) var(--shell-gutter);
   border-block-start: 1px solid var(--color-neutral-200);
   color: var(--color-fg-subtle);
   font-size: var(--font-size-xs);
@@ -1479,38 +1671,140 @@ textarea[data-terp="input"] {
 [data-terp="page"][data-measure="narrow"] {
   max-width: 32rem;
 }
+/* The page band (ADR 0097 §2, amended by building it).
+
+   ONE row, and the row IS the title. The frame used to spend two: a crumb row with a 2rem
+   floor, then an h1 row at font-size-xl. Those two rows said the same thing twice, and the
+   duplication was in the component rather than in the eye of a reviewer — Page built its
+   trail as [...breadcrumbs, { label: title }] and then rendered <h1>{title}</h1>, so every
+   DetailPage in every app printed its own name as the leaf crumb and again 24px below it.
+   Removing one of the two was therefore the whole design question, and the answer is that
+   the TRAIL survives: it carries the path back up, which an h1 cannot, and its leaf is a
+   heading, which a crumb need not be. So the leaf is the h1 (see page-title below) and the
+   band is the trail with the page's badges, its lead line and its actions on the same line.
+
+   xl retires from page-title with it, and that is a reversal of 4b's type-scale decision
+   rather than a side effect. That decision was right for the shape it was made in: when the
+   title is the page's masthead, 24 / 18 / 16 / 14 is a scale and 18 / 16 / 16 / 14 is a
+   list. In a band the title is CHROME — it names where you are, above content that starts
+   immediately under a border — and a 24px leaf on a trail of 14px ancestors reads as
+   small-small-BIG rather than as one trail. It also does not fit: the band is
+   shell-header-height with space-2 of block padding, which leaves 2rem, and xl at
+   line-height 1.3 is 1.95rem of it before a badge or a lead line asks for room.
+   --font-size-xl keeps two readers (heading[data-size="xl"], login-title), so the top of the
+   scale is still wired; an app that wants the masthead back redefines the marker from its own
+   unlayered theme.css, exactly as the retired comment here said.
+
+   align-items: center rather than baseline, because the row mixes a heading, pill badges and
+   a button cluster: baseline alignment lines up the text and leaves the pills sitting low.
+   Wrapping is kept from the old heading row for the same reason it was there — a long title
+   meeting a wide action cluster takes a second line instead of overflowing — and the band
+   grows past its floor when it does. */
 [data-terp="page-header"] {
-  display: grid;
-  gap: var(--space-2);
-}
-/* The crumb row keeps a 2rem floor, and it is doing work rather than reserving
-   space for its own sake: the trail is shorter than 2rem at font-size-sm, so
-   dropping the floor closes the gap under the trail on every page that has one.
-   Measured — removing it moves all six baselines with a trail and nothing else. */
-[data-terp="page-breadcrumbs"] {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
-  min-height: 2rem;
+  justify-content: space-between;
+  gap: var(--space-2) var(--space-4);
+  min-width: 0;
 }
-/* Title left, the actions slot right, wrapping rather than overflowing when a long
-   title meets a wide action cluster. */
+/* The band's left group: the trail (whose leaf is the h1), then badges, then the lead line.
+   flex: 1 1 auto with min-width: 0 is what lets the lead line truncate instead of pushing
+   the action cluster off the row. */
 [data-terp="page-heading"] {
   display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--space-3);
   flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-2) var(--space-3);
+  flex: 1 1 auto;
+  min-width: 0;
 }
-/* The single h1 of the view. margin: 0 is load-bearing — the browser default h1
-   margin would otherwise fight the header's own gap. */
+/* The single h1 of the view, and now also the trail's current crumb: one node instead of two
+   copies of one string. margin: 0 is load-bearing twice over — the browser default h1 margin
+   would fight the band's own gap, and an h1 inside the trail's <li> would otherwise break the
+   row. font-size is declared rather than inherited because the UA sheet sets h1 { font-size:
+   2em } ON the element, and a declaration on the element beats an inherited value however
+   specific the ancestor rule is: without this the leaf renders at twice the trail.
+
+   Semibold at the trail's own size, which is the whole "the trail is the title" idea in one
+   declaration — heavier than its ancestors, not larger. */
 [data-terp="page-title"] {
   margin: 0;
-  font-size: var(--font-size-lg);
+  font-size: var(--font-size-sm);
   font-weight: var(--font-weight-semibold);
   letter-spacing: 0;
   color: var(--color-neutral-900);
   line-height: 1.3;
 }
+/* Status pills next to the title. A row of its own so a page passing several keeps them
+   together when the band wraps, rather than letting one pill orphan onto the second line. */
+[data-terp="page-badges"] {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-1);
+  min-width: 0;
+}
+/* The lead line: one short sentence about the page, truncated rather than wrapped, because
+   the band has a height and prose that wraps would set it. A page whose explanation does not
+   fit on one line is describing its body, and that belongs in the body. */
+[data-terp="page-description"] {
+  margin: 0;
+  flex: 1 1 auto;
+  min-width: 0;
+  color: var(--color-fg-subtle);
+  font-size: var(--font-size-sm);
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+/* The band's CHROME, which needs no shell above it and so is not gated on one. Its height
+   and its border are what make the row a band rather than a title line, and they are correct
+   wherever Page renders — the workbench's specimen cards and the unit tests included. That
+   split is the repair of a real contradiction: these declarations used to sit inside the
+   shell-gated rule below while the comment claimed "standalone, the band is still a bordered
+   row at the header's height", which the rule made false and a test fifteen lines away in
+   styles.test.ts pinned as false. The three page-header specimens were pictures of a plain
+   flex row that the comment described as chrome.
+
+   box-sizing: border-box so the floor counts the padding, matching appshell-header, whose
+   height this is reading. Without it the two are a padding apart and the "same height as the
+   header above it" claim is off by 1rem.
+
+   :not([data-measure="narrow"]) because a form is capped WITH its header (ADR 0098 §3) — a
+   Save button a screen-width from its field is worse than one over it — so a form gets the
+   one-row band with no chrome at all: a title row, which is what it wants.
+
+   padding-BLOCK only. The inline gutter belongs to the bleed below, because standalone there
+   is nothing to bleed into and an inline pad with no negative margin would inset the band's
+   content from the body beneath it for no reason. */
+[data-terp="page"]:not([data-measure="narrow"]) > [data-terp="page-header"] {
+  padding-block: var(--space-2);
+  min-height: var(--shell-header-height);
+  box-sizing: border-box;
+  border-block-end: 1px solid var(--color-neutral-200);
+}
+/* The BLEED, which does need a shell, because the negative-margin idiom is only correct when
+   the box being escaped is appshell-main and that box pads by exactly --shell-gutter. ADR
+   0097 §2 kept "it works with no shell above it at all" as a property of the mechanism, and
+   keying this half on the shell is what keeps it: standalone the band is the same bordered
+   row at the same height, it simply does not reach past its container.
+
+   The surface comes with the bleed rather than with the chrome, and that is deliberate under
+   0.14.0's surface model: a block paints no fill of its own, and this one is only chrome —
+   the app header's companion — once there is an app header above it to pair with.
+
+   ONE rule for both variants, which is the payoff of the token rather than a tidy-up. As two
+   literals this needed a mobile twin, and a negative margin whose sign has to agree with a
+   padding declared three rules away is exactly the drift that put the trail 8px off the
+   header in the first place. */
+[data-terp="appshell-main"]
+  > [data-terp="page"]:not([data-measure="narrow"])
+  > [data-terp="page-header"] {
+  margin: calc(-1 * var(--shell-gutter)) calc(-1 * var(--shell-gutter)) 0;
+  padding-inline: var(--shell-gutter);
+  background: var(--color-neutral-0);
+}
 /* The content measure, and the subheader band, which are ONE declaration rather than two
    features (ADR 0097 §2). A full-width band only means anything once the column beside it is
    constrained, and constraining the column is what leaves the header spanning the full track.
@@ -1702,7 +1996,6 @@ textarea[data-terp="input"] {
   gap: var(--space-4);
   padding: var(--space-4);
   max-width: 32rem;
-  background: var(--color-neutral-0);
   border: 1px solid var(--color-neutral-200);
   border-radius: var(--radius-lg);
 }
@@ -1848,7 +2141,6 @@ textarea[data-terp="input"] {
   padding: var(--space-4);
   border: 1px solid var(--color-neutral-200);
   border-radius: var(--radius-lg);
-  background: var(--color-neutral-0);
   color: var(--color-neutral-900);
   box-sizing: border-box;
   transition: border-color var(--motion-duration-fast) var(--motion-easing-standard);
@@ -1958,6 +2250,11 @@ textarea[data-terp="input"] {
    leaves the toolbar inside a surface, and leaves two nested frames whenever the view
    is empty (the empty state's dashed frame inside the card's solid one).
 
+   What the slot carries is now a FRAME rather than a fill — border and radius, with the
+   page showing through, per the card rule's note on the surface model. That changes the
+   sentence above by one word and not the ownership it settles: the frame is the table's,
+   not the view's.
+
    Keyed on [data-variant="full"] rather than the bare marker for the reason the
    previous rule gave and which still holds: [data-variant="embedded"] must declare
    nothing, and un-declaring a surface with background: transparent / border: 0 is the
@@ -1965,7 +2262,6 @@ textarea[data-terp="input"] {
 [data-terp="dataview"][data-variant="full"] > [data-terp="dataview-scroll"],
 [data-terp="dataview"][data-variant="full"] > [data-terp="dataview-error"],
 [data-terp="dataview"][data-variant="full"] > [data-terp="dataview-skeleton"] {
-  background: var(--color-neutral-0);
   border: 1px solid var(--color-neutral-200);
   border-radius: var(--radius-lg);
 }
@@ -2072,10 +2368,15 @@ textarea[data-terp="input"] {
 [data-terp="dataview-toolbar"][data-variant="selection"] {
   /* Still a filled surface, because it marks a MODE and losing that would make
      selection invisible — but now it is a surface of its own rather than a band of the
-     card, so it takes the padding and radius that make it read as one. */
+     card, so it takes the padding and radius that make it read as one.
+
+     And the fill is the SELECTION token now, not --color-neutral-50: that value is the
+     canvas, so the strip that floats on the canvas was painting a rectangle nobody could
+     see. --color-interactive-selected is what the selected rows below it carry, which is
+     the pairing this band wanted anyway — one mode, one colour, top to bottom. */
   padding-inline: var(--density-cell-pad-x);
   border-radius: var(--radius-md);
-  background: var(--color-neutral-50);
+  background: var(--color-interactive-selected);
 }
 [data-terp="dataview-toolbar-count"] {
   font-weight: var(--font-weight-medium);
@@ -2253,7 +2554,6 @@ input[data-terp="input"][type="password"]::-ms-reveal {
   letter-spacing: 0.04em;
   border-bottom: 1px solid var(--color-neutral-200);
   white-space: nowrap;
-  background: var(--color-neutral-0);
 }
 /* A column's declared track. A MINIMUM rather than a width, because a specified width is only a
    preference under table-layout: auto and the algorithm shrinks it to fit — which is why the pixel
@@ -2311,9 +2611,16 @@ input[data-terp="input"][type="password"]::-ms-reveal {
    A row's own state outranks the selection tint, and the :not() is what says so
    without depending on source order — both selectors weigh (0,2,0) otherwise,
    which is precisely the trap the layer comment at the top of this file
-   describes. Selection stays legible through the checkbox and data-selected. */
+   describes. Selection stays legible through the checkbox and data-selected.
+
+   The tint is --color-interactive-selected, the token's first reader. It was
+   --color-neutral-50 — the canvas — which read as a tint only while the table sat on a
+   filled card, and equalled the hover wash exactly, so a selected row and a pointed-at
+   row looked the same. A brand-tinted row now says selected in every theme, and holds
+   muted ink at AA there (5.19 at its narrowest, in midnight; declared as
+   muted-on-selection so the gate measures it). */
 [data-terp="dataview-row"][data-selected="true"]:not([data-tone]) {
-  background: var(--color-neutral-50);
+  background: var(--color-interactive-selected);
 }
 [data-terp="dataview-row"][data-tone="neutral"] {
   background: var(--color-neutral-100);
@@ -2427,7 +2734,6 @@ th[data-terp="dataview-actions-cell"] > span {
   display: grid;
   gap: var(--space-2);
   padding: var(--density-cell-pad-y) var(--density-cell-pad-x);
-  background: var(--color-neutral-0);
   border: 1px solid var(--color-neutral-200);
   border-radius: var(--radius-lg);
   box-shadow: var(--shadow-sm);
@@ -2559,7 +2865,7 @@ th[data-terp="dataview-actions-cell"] > span {
    "this belongs to the row above" rather than as another row. */
 [data-terp="dataview-expanded-cell"] {
   padding: var(--density-cell-pad-y) var(--space-4);
-  background: var(--color-neutral-50);
+  background: var(--color-neutral-100);
   border-block-end: 1px solid var(--color-neutral-200);
 }
 
@@ -2743,13 +3049,13 @@ th[data-terp="dataview-actions-cell"] > span {
   padding: var(--space-3);
   border: 1px solid var(--color-neutral-200);
   border-radius: var(--radius-md);
-  background: var(--color-neutral-0);
 }
 
 /* Empty / error / loading states ------------------------------------------- */
 /* Same centred block, opposite messages: empty is a dashed outline on the page
    surface because nothing is wrong, error is a filled danger wash because
-   something is. */
+   something is. Which is now literal — the outline is all of it, and the surface
+   underneath is whatever the block was dropped on. */
 [data-terp="empty-state"] {
   display: grid;
   justify-items: center;
@@ -2759,7 +3065,6 @@ th[data-terp="dataview-actions-cell"] > span {
   color: var(--color-neutral-600);
   border: 1px dashed var(--color-neutral-300);
   border-radius: var(--radius-lg);
-  background: var(--color-neutral-0);
 }
 /* Compact: a section's emptiness rather than the page's. Same frame and same words,
    laid out as a row — the glyph beside the text instead of above it — so two of
@@ -3751,8 +4056,12 @@ button[data-terp="input"][data-placeholder="true"] {
 }
 [data-terp="input"]:disabled {
   /* background-color (not the background shorthand) so the Select's chevron,
-     drawn as a background-image, survives the disabled state. */
-  background-color: var(--color-neutral-50);
+     drawn as a background-image, survives the disabled state.
+
+     --color-neutral-100 rather than the canvas value it used to carry: a disabled field
+     on a card with no fill would have been a hole in the page rather than a control with
+     a wash, and the enabled field beside it paints the other end of the ramp. */
+  background-color: var(--color-neutral-100);
   color: var(--color-fg-subtle);
   cursor: not-allowed;
 }
@@ -4050,8 +4359,29 @@ button[data-terp="input"][data-placeholder="true"] {
 [data-terp="dataview-table"] tbody tr {
   transition: background-color var(--motion-duration-fast) var(--motion-easing-standard);
 }
-[data-terp="dataview-table"] tbody tr:hover td {
-  background: var(--color-neutral-50);
+/* --color-interactive-hover, which is the semantic name for the value every control's
+   hover in this sheet already spells, and the token's first reader. The row was one step
+   lighter, on the canvas value, so once the table frame stopped painting a fill there was
+   nothing for a hover to differ from.
+
+   THE ROW'S OWN COLOUR WINS, and the two :not() clauses are the whole of that rather than
+   defensive noise. A row's tone and its selection tint are painted on the tr; this wash is
+   painted on the td, and a cell background paints ABOVE its row's. So without the guards,
+   pointing at a selected row repaints it #f1f5f9 over #eff6ff and it reads as unselected,
+   and pointing at a danger-toned row erases the tone entirely. Both are data; the wash is
+   an affordance, and an affordance may not overwrite what the row is telling you.
+
+   The selection half only became visible when --color-interactive-selected split away from
+   --color-neutral-50: while both spelled the same value the collision painted identically
+   and no baseline could have shown it. The tone half was live before that and equally
+   unpicturable, because no specimen renders a hovered row at all.
+
+   A guarded row therefore shows no wash change and the cursor is what says it is hoverable
+   there — which is exactly what this comment already claimed for the neutral tone, whose
+   --color-neutral-100 happens to equal this token in every theme. That was true by
+   coincidence for one tone; it is true by construction for all of them now. */
+[data-terp="dataview-table"] tbody tr:not([data-tone]):not([data-selected="true"]):hover td {
+  background: var(--color-interactive-hover);
 }
 /* The row containing keyboard focus, highlighted because it is the one Enter would
    open. Guarded on data-clickable, and the guard is not decoration: the row marker