@juwel-development/design-system 3.0.0 → 3.2.0

package/src/Interaction/TextArea/TextArea.tsx

@@ -8,9 +8,11 @@ import type { Subject } from 'rxjs';
 // drawn in `controlBorder` (>=3:1 against surface) and turned `error` on both `:user-invalid` and
 // `aria-invalid` so a server-rendered and a browser-validated invalid state paint identically. Focus
 // adds only the shared ring - the border never changes on focus (docs/adr/0002). Height is the
-// recipe's, not a `rows` prop.
+// recipe's, not a `rows` prop. The control's face, and the placeholder that follows it, are
+// docs/adr/0004's (#90); so is its size (#92) - `body` is the role clearing the 16px below which
+// iOS Safari zooms a focused control.
 const textArea = cva(
-  'block min-h-24 w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
+  'block min-h-24 w-full rounded-[var(--radius-control)] border border-solid border-control-border bg-transparent px-3 py-2 font-primary text-body text-foreground transition-colors duration-[var(--motion-duration-color)] outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)] [&:user-invalid]:border-error aria-[invalid=true]:border-error disabled:cursor-not-allowed disabled:border-disabled disabled:text-muted',
 );
 
 interface ITextAreaProps {
@@ -82,7 +84,14 @@ export const TextArea: FunctionComponent<ITextAreaProps> = ({
 
   return (
     <div className={'flex flex-col gap-[var(--space-stack)]'}>
-      <label htmlFor={controlId} className={'font-medium text-foreground'}>
+      {/* Each of these declares `font-secondary` on itself, never on the wrapper above - the
+          wrapper would hand the labelling face to the control too (docs/adr/0004, #90). The
+          label's size is declared here for the same reason, and it is `body`, the control's own
+          role, rather than `label` (docs/adr/0004, #92). */}
+      <label
+        htmlFor={controlId}
+        className={'font-secondary font-medium text-body text-foreground'}
+      >
         {label}
       </label>
       <textarea
@@ -101,15 +110,17 @@ export const TextArea: FunctionComponent<ITextAreaProps> = ({
         onInput={(event) => onInput$?.next(event.currentTarget.value)}
       />
       {!required && optionalLabel && (
-        <span className={'text-muted text-sm'}>{optionalLabel}</span>
+        <span className={'font-secondary text-muted text-small'}>
+          {optionalLabel}
+        </span>
       )}
       {hint && (
-        <p id={hintId} className={'text-muted text-sm'}>
+        <p id={hintId} className={'font-secondary text-muted text-small'}>
           {hint}
         </p>
       )}
       {invalid && (
-        <p id={errorId} className={'text-error text-sm'}>
+        <p id={errorId} className={'font-secondary text-error text-small'}>
           {errorMessage}
         </p>
       )}

package/src/Layout/Cover/Cover.tsx

@@ -0,0 +1,85 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe, no variants: both-axes centring is the component's whole job (#96), so there is nothing
+// to choose - a distribution axis waits for evidence under ADR 0008's test. items-center centres the
+// inline axis, the slot's auto margins (below) the block axis; alone among the composables it carries
+// its own inset - the deliberate exception to "Section owns the gutter" (CONTEXT.md: Cover).
+const cover = cva(
+  [
+    'flex flex-col items-center',
+    'min-h-[var(--cover-height)]',
+    'px-[var(--gutter)] py-[var(--space-region)]',
+  ].join(' '),
+);
+
+// Not a second recipe - the slot has nothing to vary, and the standard allows one cva()
+// (design-system-components.md §4), the frame's own above. Block-axis auto margins split the leftover
+// space equally, so a foot after the slot still lands on the bottom edge - justify-center on the
+// frame would centre slot and foot as one group and lift the foot off that edge.
+const slot = 'my-auto';
+
+export interface ICoverProps {
+  /** The screen's one opaque slot, centred on both axes. Rendered unmodified: a menu composes a title,
+   *  a tagline and a stack of actions here; a sign-in composes a form. `Cover` imposes no anatomy. */
+  children: ReactNode;
+  /** The line on the screen's bottom edge - a version line, a legal line - centred on the inline axis.
+   *  Omitted - or given nothing: `null`, a flag's `false` - nothing renders: no empty container
+   *  holds its place. */
+  foot?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * A whole screen's frame: a plain container at least the cover height tall that centres one column in
+ * the leftover space, on both axes, with an optional foot pinned to the bottom edge. It is the fold's
+ * counterpart (CONTEXT.md): a menu, a sign-in, a splash is the entire app for a moment, and nothing
+ * follows it - so where `Hero` deliberately stops short of the viewport to say the page continues, a
+ * cover reaches it, because stopping short would signal a continuation that does not exist. It renders
+ * no heading and no landmark: whatever the screen says is composed in the slot.
+ *
+ * @Guarantees — enforced on every render
+ * - It is at least `--cover-height` tall: a `min-height` floor, not a fixed height, so content longer
+ *   than the viewport grows the frame rather than overflowing it.
+ * - `children` sit in the middle of the leftover space, centred on both axes; the centring is fixed,
+ *   with no distribution to choose.
+ * - `foot` renders on the frame's bottom edge, centred on the inline axis, and renders nothing - not
+ *   even an empty container - when not given or given nothing to render (`null`, a flag's `false`).
+ * - `children` and `foot` render unmodified; the component adds nothing to and strips nothing from
+ *   them, and sets no colour, no heading and no landmark of its own.
+ * - It owns its own inset - `--gutter` on the inline axis, `--space-region` on the block axis - the
+ *   deliberate exception to "`Section` owns the gutter": the frame equals the viewport, so it cannot
+ *   sit inside a `Section` band without overflowing it, and there is no band around it to carry one.
+ * - It is never sticky or fixed and needs no JavaScript, so it renders identically server-side.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - The cover stands on its own, never inside a `Section`: the band's vertical air would push the
+ *   frame past the viewport it exists to equal. A page that continues past its first screen wants
+ *   `Section` and `Hero` instead - the fold, not the screen.
+ * - Anything the page must announce - a landmark, a heading - is composed in the slot; the frame
+ *   declares nothing over it.
+ *
+ * @UXGuidelines
+ * - A cover is for a page that is the whole app for a moment - a menu, a sign-in, a splash. The
+ *   moment content follows on the same page, the screen has become a fold and stopping short of the
+ *   viewport is the honest signal: reach for `Hero` inside a `Section` instead.
+ * - The foot is a quiet line, not a footer: a version, a legal notice. Content a viewer must reach
+ *   belongs in the slot, where it sits in the column the screen is actually about.
+ */
+export const Cover: FunctionComponent<ICoverProps> = ({
+  children,
+  foot,
+  testId,
+}) => {
+  // Absence, not falsiness, after Form's note guard: `foot={showLegal && <p/>}` hands over `false`,
+  // and an empty <div> would still be a flex item sitting on the bottom edge.
+  const hasFoot =
+    foot !== undefined && foot !== null && typeof foot !== 'boolean';
+
+  return (
+    <div className={cover()} data-testid={testId}>
+      <div className={slot}>{children}</div>
+      {hasFoot && <div>{foot}</div>}
+    </div>
+  );
+};

package/src/Layout/Form/Form.tsx

@@ -8,8 +8,9 @@ export type FormState = 'idle' | 'sending' | 'sent' | 'failed';
 // The one recipe, and it paints the note only (issue #6): `state` selects the note's tone - muted
 // while the form stands, success on the outcome, error on the failure. Region selection is the
 // NOTE_ROLE map below, not classes, so this axis never grows a layout job. Colours are semantic
-// tokens re-pointed by `.dark`, so no variant carries a `dark:` class.
-const form = cva('text-sm', {
+// tokens re-pointed by `.dark`, so no variant carries a `dark:` class. The face joins the size in
+// the base, so no state can disagree with it (docs/adr/0004, #90).
+const form = cva('font-secondary text-small', {
   variants: {
     state: {
       idle: 'text-muted',
@@ -37,8 +38,12 @@ interface IFormProps {
   children?: ReactNode;
   /** The actions row - the consumer supplies its own submit Button. */
   actions?: ReactNode;
-  /** Standing note in `idle`/`sending`; the outcome message in `sent`/`failed`. */
-  note?: string;
+  /** Standing note in `idle`/`sending`; the outcome message in `sent`/`failed`. Inline content: a
+   *  sentence, with a Link or emphasis inside it. Form renders the paragraph the note sits in and
+   *  owns its ARIA role, so a node that brings its own block element - a second `<p>` - is unnested
+   *  by the parser and the text leaves the region carrying that role. A node that renders nothing
+   *  (`null`, `false`, an omitted prop) is no note: the paragraph is not rendered at all. */
+  note?: ReactNode;
   testId?: string;
 }
 
@@ -51,8 +56,8 @@ interface IFormProps {
  * `sent` drops the fields and actions so a completed submission cannot be resubmitted, while the
  * `<form>` itself is retained in every state so the DOM shape is stable across a runtime change.
  *
- * The note's text is always the consumer's; Form chooses only its element and ARIA role. `sent` is
- * the outcome message, so a `sent` with no `note` is a programmer error and throws.
+ * The note's content is always the consumer's; Form chooses only its element and ARIA role. `sent`
+ * is the outcome message, so a `sent` with no `note` is a programmer error and throws.
  */
 export const Form: FunctionComponent<IFormProps> = ({
   action,
@@ -63,7 +68,16 @@ export const Form: FunctionComponent<IFormProps> = ({
   note,
   testId,
 }) => {
-  if (state === 'sent' && !note) {
+  // Absence, not falsiness: a ReactNode may be falsy and still render (`0` renders as `"0"`), so a
+  // truthiness test would both refuse a legitimate note in `sent` and drop a paragraph React had
+  // written a value into. Absence is React's own set of nothing-to-render nodes rather than
+  // `undefined` alone, because `note={showPrivacy && <>...</>}` hands over `false` when the line is
+  // off - and an empty `<p>` is still a flex item, so it would cost a region gap and, in `sent`, a
+  // status region announcing nothing.
+  const hasNote =
+    note !== undefined && note !== null && typeof note !== 'boolean';
+
+  if (state === 'sent' && !hasNote) {
     throw new Error(
       'Form in the `sent` state must be given a `note` - it is the outcome message.',
     );
@@ -87,12 +101,14 @@ export const Form: FunctionComponent<IFormProps> = ({
           {children}
         </div>
       )}
+      {/* Not pinned against Stack (#75) as the two columns above are: the actions row runs along the
+          other axis, which is Cluster's arrangement (#76) and not a stack with a different gap. */}
       {showFields && actions && (
         <div className={'flex flex-row gap-[var(--space-stack)]'}>
           {actions}
         </div>
       )}
-      {note && (
+      {hasNote && (
         <p role={noteRole} className={form({ state })}>
           {note}
         </p>

package/src/Layout/Header/Header.tsx

@@ -2,7 +2,7 @@ import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 
-// One recipe on the <header>. It sets the label type role - the "small grotesk, letter-spaced, muted"
+// The recipe on the <header>. It sets the label type role - the "small grotesk, letter-spaced, muted"
 // the issue described, whose "never grows past 1rem" was a role wearing a number, so no size literal
 // appears here (#14). The shell's air is one value in every direction: --space-region above, below and
 // (on the nav) between, --gutter across, so the bar aligns with every inset Section. The current-page
@@ -15,7 +15,7 @@ import type { FunctionComponent, ReactNode } from 'react';
 const header = cva(
   [
     'flex items-baseline justify-between',
-    'font-secondary text-label tracking-label text-muted',
+    'font-secondary text-label leading-label tracking-label text-muted',
     'py-[var(--space-region)] px-[var(--gutter)]',
     '[&_[aria-current=page]]:text-foreground',
   ].join(' '),
@@ -30,6 +30,20 @@ const header = cva(
   },
 );
 
+// Not a second recipe - the standing slot has nothing to vary, and the standard allows a component
+// one cva() (design-system-components.md §4), which is the bar's own above. A named constant beside
+// the nav's inline class string, so the comment has something to sit on.
+//
+// The height floor is the nav's own line box, written from the two tokens the recipe above sets the
+// header from, so the declared floor and the rendered line cannot drift (#81). `shrink-0` because an
+// explicit min-width replaces a flex item's automatic minimum - without it the bar squeezes the slot
+// below its content and wraps the place name the floor exists to keep on one line.
+const standingSlot = [
+  'inline-flex shrink-0 items-center',
+  'min-h-[calc(var(--text-label)*var(--leading-label))]',
+  'min-w-[var(--standing-min-width)]',
+].join(' ');
+
 export interface IHeaderProps extends VariantProps<typeof header> {
   /** The standing link: a place name, a mark, or a home link. The consumer supplies the whole anchor -
    *  Header renders no link of its own. A place name uses `<Link treatment="quiet" href="/">…</Link>`; a
@@ -49,7 +63,14 @@ export interface IHeaderProps extends VariantProps<typeof header> {
  *
  * @Guarantees — enforced on every render
  * - The header is set at the label role and carries no size of its own: `font-secondary text-label
- *   tracking-label text-muted`, so it never grows past that role whatever the page font size.
+ *   leading-label tracking-label text-muted`, so it never grows past that role whatever the page font size.
+ * - The nav's line box is the library's own rather than the consuming document's: the header leads
+ *   itself at the label role, so the height it declares for its slot is the height it renders.
+ * - The standing slot is floored, never fixed: its minimum height is that same line box - the label
+ *   role's size times its leading - its minimum width is `--standing-min-width`, and its contents are
+ *   centred. Standing content inside both floors leaves the bar the same height from route to route,
+ *   so a place name on one page and a mark on another do not move the shell; content past either floor
+ *   grows the slot, on one line, and is never clamped or wrapped.
  * - A nav item marked `aria-current="page"` renders at `foreground` whatever supplied it - the treatment
  *   keys on the attribute, not on `Link`, so it holds against a bare anchor or any component.
  * - The shell's air is one value above, below and between: `--space-region` vertically and between nav
@@ -57,6 +78,18 @@ export interface IHeaderProps extends VariantProps<typeof header> {
  * - It is never sticky and needs no JavaScript: there is no `sticky` variant and nothing to hydrate.
  * - Omitting `navName` emits no `aria-label` at all, not an empty one.
  *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - A mark that should *fill* the standing slot is given a **definite width** by whoever placed it -
+ *   `width: var(--standing-min-width)` on the element wrapping it, so the mark and the floor move
+ *   together when a theme re-points the token. Measured against a `viewBox`-only SVG, the common
+ *   shape: it has no intrinsic width to fill from, and `width: 100%` cannot resolve against the slot's
+ *   indefinite basis - so a mark told to fill that way renders at its intrinsic width instead (300px in
+ *   a slot floored at 120px, against 120px on the place-name route) and the floor stops governing,
+ *   which is the jump between routes the floor exists to remove. A definite width holds at any bar
+ *   width; `flex: 1 1 0; min-width: 0` only collapses the mark when the bar is already out of room, so
+ *   it is not the rule to reach for. The library cannot apply either rule for you: the same width on a
+ *   place name would clamp the name and wrap it.
+ *
  * @UXGuidelines
  * - Name the nav with `navName` once the page has more than one navigation landmark - a footer nav will
  *   be the second, and two unnamed navs are indistinguishable to a screen-reader user.
@@ -73,7 +106,7 @@ export const Header: FunctionComponent<IHeaderProps> = ({
   testId,
 }) => (
   <header className={header({ edge })} data-testid={testId}>
-    <div>{standing}</div>
+    <div className={standingSlot}>{standing}</div>
     <nav
       aria-label={navName}
       className={'flex flex-wrap items-baseline gap-[var(--space-region)]'}

package/src/Layout/Hero/Hero.tsx

@@ -2,6 +2,8 @@ import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 
+// Not pinned against Stack (#75): the fold height is this component's own, so the base legitimately
+// differs and an equality spec would only forbid a difference that is the point of the component.
 // One recipe on a plain <div>. It holds the fold - a minimum height taller than its content, so leftover
 // space is guaranteed and how the slot sits in it is a decision, not a default (#17). With no className
 // escape hatch, whatever place picks is final, so it is a variant: center is the conventional hero and the
@@ -52,12 +54,14 @@ export interface IHeroProps extends VariantProps<typeof hero> {
  *   bleed, the band, the gutter and the region. `Hero` imports no component and adds none of these.
  *
  * @UXGuidelines
- * - Cap the lead at `--measure-display`, not at a caption's width, and apply it to your own lead - not
- *   here, since capping the slot would cap the mark too. Measured on the lockup that prompted this: at
- *   24ch a one-sentence lead set five lines and became a second block competing with the mark; at 36ch it
- *   sets three and reads as the mark's caption. This is the one place where copy length is a layout
- *   parameter - a hero whose lead sentence can vary in length needs its measure chosen against the real
- *   sentence, not a rule of thumb.
+ * - The lead is capped at `--measure-display`, and `H1` is what carries the cap - place one in the slot
+ *   and the bound comes with it (#87). The slot itself stays uncapped, because capping it would cap the
+ *   mark too. Measured on the lockup that prompted this: at 24ch a one-sentence lead set five lines and
+ *   became a second block competing with the mark; at 36ch, where the token sits, it sets three and reads
+ *   as the mark's caption. This is the one place where copy length is a layout parameter, and the token
+ *   is one value for the whole product - so a hero whose lead runs longer than that measurement assumed
+ *   is a reason to re-measure `--measure-display` against the real sentence, which moves every `H1` with
+ *   it, and never a reason to cap that one hero by hand.
  * - A hero built on a wide lockup is a desktop bet by construction. A 15-character lockup can only be as
  *   wide as the phone, so at 390px the scale contrast between mark and lead is capped by the viewport
  *   rather than chosen - roughly 2:1, against roughly 6:1 at 1440.

package/src/Layout/PageHead/PageHead.tsx

@@ -10,6 +10,8 @@ import type { FunctionComponent, ReactNode } from 'react';
 // literal appears. That tracking is the title role's, not this component's (#57): H2 binds to the same
 // role and carries the same correction, so the role reads one way wherever it is rendered. The stack gap is --space-stack, the sibling gap Prose uses. Colours are semantic
 // tokens re-pointed by `.dark`, so no `dark:` class.
+// Not pinned against Stack (#75): the band and the gutter are the head's own page job, so the base
+// legitimately differs and there is no equality to hold - a Stack carries neither.
 const pageHead = cva(
   'flex flex-col gap-[var(--space-stack)] py-[var(--space-band)] px-[var(--gutter)]',
 );

package/src/Layout/Section/Section.tsx

@@ -16,6 +16,10 @@ import type { FunctionComponent, ReactNode } from 'react';
 // `.dark`, so no `dark:` class.
 const section = cva(
   [
+    // Anchor, not placement: a consumer hangs its own decoration off the join, and cannot get an anchor
+    // by wrapping the section without costing two joins. No offset and no z-index, so the layout is
+    // unchanged and no stacking context forms - decoration at z-index:-1 must still escape to an outer one.
+    'relative',
     'py-[var(--space-band)]',
     '[[data-section]+&]:border-t [[data-section]+&]:border-solid [[data-section]+&]:border-rule',
   ].join(' '),
@@ -51,10 +55,17 @@ export interface ISectionProps extends VariantProps<typeof section> {
  * - A `bleed="full"` section drops the gutter and runs edge to edge; the vertical band is kept on both
  *   bleed variants, and the join spans the full width of either.
  * - An unnamed section is not a landmark: it emits no `aria-label` and is inert to assistive technology.
+ * - The section is a positioning context, under either bleed, so a consumer may place absolutely-positioned
+ *   decoration against its edges - including the join above it, the one edge only a section knows. It sets
+ *   no offset and no `z-index`, so it is not a stacking context and decoration at a negative `z-index`
+ *   still resolves against an outer one.
  *
  * @CallerMustEnsure
  * - Where `name` is given it matches the section's visible heading. The component labels the region with
  *   that string because it cannot reach the heading's id to reference it with `aria-labelledby` instead.
+ * - A descendant meant to position against an ancestor *outside* the section is given its own positioned
+ *   wrapper, since the section is now the nearer positioned ancestor and takes the anchor. The
+ *   re-anchoring is silent - no error and no warning, only a descendant that lands somewhere else.
  *
  * @UXGuidelines
  * - On a page with no borrowed proof - no logos, no testimonials, no credits - a gap between blocks reads

package/src/Theme/Palette.ts

@@ -39,15 +39,36 @@ export type PaletteTokens = {
    *  keeps it near `surface` rather than a mid grey. */
   backing: string;
 
-  /** The main call-to-action fill. */
+  /** The main call-to-action fill. A filled control draws no border, so the fill is the only thing
+   *  separating the control from the surface - what `controlBorder` is for an unfilled one.
+   *  Constraint (WCAG 2.2 SC 1.4.11): at least 3:1 against `surface` in the same theme,
+   *  `primaryHover` included, since a hovered control has to stay identifiable too. A second
+   *  constraint governs this value and `primaryHover` from the other side, stated on
+   *  `primaryForeground` - the ink they carry - rather than restated here. */
   primary: string;
   primaryHover: string;
-  /** Text and icons drawn on top of `primary`. */
+  /** Text and icons drawn on top of `primary`. Constraint (WCAG 2.2 SC 1.4.3): at least 4.5:1
+   *  against both `primary` and `primaryHover` in the same theme, hover included, since a hovered
+   *  control has to stay readable too. Button text is normal-weight at the `body` role, so it takes
+   *  the text threshold rather than the 3:1 large-text allowance. This is what makes the ink follow
+   *  the theme where the fills' own roles do not: a fill light enough to clear 3:1 against a dark
+   *  surface is too light to carry near-white text, so the ink sits at the *surface's* end of the
+   *  neutral range in each theme. Not required against `disabled` or `disabledHover` - a disabled
+   *  control is an inactive user interface component, which SC 1.4.3 exempts. */
   primaryForeground: string;
 
-  /** The alternative action fill, for choices that sit beside a primary one. */
+  /** The alternative action fill, for choices that sit beside a primary one. Filled like `primary`
+   *  and so identified the same way. Constraint (WCAG 2.2 SC 1.4.11): at least 3:1 against
+   *  `surface` in the same theme, `secondaryHover` included. A second constraint governs this value
+   *  and `secondaryHover` from the other side, stated on `secondaryForeground`. */
   secondary: string;
   secondaryHover: string;
+  /** Text and icons drawn on top of `secondary`. Constraint (WCAG 2.2 SC 1.4.3): at least 4.5:1
+   *  against both `secondary` and `secondaryHover` in the same theme, hover included, since a
+   *  hovered control has to stay readable too. Not required against `disabled` or `disabledHover` -
+   *  a disabled control is an inactive user interface component, which SC 1.4.3 exempts. Why the
+   *  threshold is 4.5 and not 3, and why this makes the ink follow the theme: see
+   *  `primaryForeground`, which carries the same rule for the other ramp. */
   secondaryForeground: string;
 
   /** The tone a control takes when it cannot be interacted with - its fill, or its border when
@@ -75,6 +96,25 @@ export type PaletteTokens = {
   info: string;
 };
 
+/**
+ * The ink follows the theme, and that is what set the eight fill and ink values across both sets
+ * (issue #93). Solve the window a fill has to sit in - at least 3:1 against its surface (#78) and
+ * at least 4.5:1 against the ink drawn on it - and it comes out lopsided: a near-white ink is
+ * unbounded above in light and leaves a window just 1.26x wide in dark, and a near-black ink is the
+ * exact inverse. The reason is structural - in a dark theme a fill has to be light enough to
+ * separate from a near-black surface, and a light fill wants dark text - so pinning the ink
+ * near-white in both themes asks a dark fill to be both at once. That 1.26x has to hold two values,
+ * rest and hover, where what shipped before it stepped 1.35x and 1.23x here and 1.35x and 1.48x in
+ * dark. Letting the ink invert instead puts every value on a stock ramp step, with hover steps of
+ * 1.25x and 1.27x here and 1.56x and 1.48x in dark.
+ *
+ * Two routes were rejected, and they are what a reader arriving here is most likely to re-propose:
+ * - Keep one near-white ink in both themes and move the fills. It clears 4.5:1, but caps the dark
+ *   hover at that same 1.26x - gutting the state #78 constrained hover in order to keep.
+ * - Give each ramp its own ink, the same in both themes. It clears 4.5:1 only against pure black:
+ *   against `#0f172a`, the dark set's own `surface`, sky-600 lands at 4.36 and fails. It also buys
+ *   a light theme with white text on one button and black on the one beside it.
+ */
 export const light: PaletteTokens = {
   surface: '#ffffff',
   foreground: '#0f172a',
@@ -84,12 +124,12 @@ export const light: PaletteTokens = {
   rule: '#808fa3',
   backing: '#f1f5f9',
 
-  primary: '#8b5cf6',
-  primaryHover: '#7c3aed',
+  primary: '#7c3aed',
+  primaryHover: '#6d28d9',
   primaryForeground: '#f8fafc',
 
-  secondary: '#0ea5e9',
-  secondaryHover: '#0284c7',
+  secondary: '#0369a1',
+  secondaryHover: '#075985',
   secondaryForeground: '#f8fafc',
 
   disabled: '#94a3b8',
@@ -106,10 +146,19 @@ export const light: PaletteTokens = {
 };
 
 /**
- * Dark reverses the ramp the fills are drawn from: `primary` takes the step that light uses for
- * its hover, and hovering steps *up* into light. That is what the components' old
+ * Dark reverses the direction the fills step: it sits higher up the ramp than light does and hovers
+ * *up* into lighter still, where light sits lower and hovers down. That is what the components' old
  * `dark:bg-primary-600 dark:hover:bg-primary-500` pair encoded, moved here so it is stated once
- * for the whole system instead of repeated per component.
+ * for the whole system instead of repeated per component. The two sets no longer share a step, since
+ * each theme's pair has to clear its own ink as well as its own surface (issue #93).
+ *
+ * The ink inverts with the ramp: slate-950 under these lighter fills, where light takes slate-50
+ * under its darker ones. The pair is the two ends of the one neutral ramp the rest of the palette is
+ * already built from - `#f8fafc` is slate-50, `surface` slate-900, `muted` slate-500 - rather than a
+ * new colour arriving for a single job. `#020617` is also the lightest slate step that still admits
+ * violet-500 and sky-600, which is what leaves this set's `secondary` pair unmoved: slate-900 draws
+ * 4.22 and 4.36 against them and fails. Why the ink follows the theme at all, and the two routes
+ * rejected in getting here: see the light set.
  */
 export const dark: PaletteTokens = {
   surface: '#0f172a',
@@ -120,13 +169,13 @@ export const dark: PaletteTokens = {
   rule: '#5b6a80',
   backing: '#1e293b',
 
-  primary: '#7c3aed',
-  primaryHover: '#8b5cf6',
-  primaryForeground: '#f8fafc',
+  primary: '#8b5cf6',
+  primaryHover: '#a78bfa',
+  primaryForeground: '#020617',
 
   secondary: '#0284c7',
   secondaryHover: '#0ea5e9',
-  secondaryForeground: '#f8fafc',
+  secondaryForeground: '#020617',
 
   disabled: '#475569',
   disabledHover: '#334155',

package/src/Theme/renderTokens.ts

@@ -61,6 +61,14 @@ const CONTROL_MIN_WIDTH = `:root {
   --control-min-width: 10.5rem;
 }`;
 
+/* The shell's standing slot claims a width, and that is what this names: how much of the bar the
+   slot takes, never how wide any drawing is - a slot role, so Brandmark keeps setting no dimension of
+   its own (.out-of-scope/brandmark-size-vocabulary.md). Not a colour and no Tailwind namespace, so it
+   sits in :root beside the control minimum width. 7.5rem is the one attested value, measured in #81. */
+const STANDING_MIN_WIDTH = `:root {
+  --standing-min-width: 7.5rem;
+}`;
+
 /* The library's underline is not a colour: like the focus-ring dimensions it lives in :root only,
    never @theme inline. Not prose's alone - every Link treatment that draws a line draws it from these.
    Constraint: --underline-thickness-hover > --underline-thickness (the thicken on hover is the only
@@ -102,11 +110,17 @@ const TYPOGRAPHY = `@theme {
      subtitle was rejected in ADR 0004 - it welds the lede's size to H3's and its leading to a head's. */
   --text-lede: 1.25rem;  /* 20px */
   --leading-lede: 1.4;
-  --text-body: 1.0625rem;  /* 17px */
+  --text-body: 1.0625rem;  /* 17px, floored at 16px: below it iOS Safari zooms the viewport when a control set at this role takes focus (#92) */
   --leading-body: 1.6;
   --text-small: 0.9375rem;  /* 15px floor: below it tabular figures stop comparing column to column */
   --text-label: 0.8125rem;  /* 13px floor: below it the tracking reads as damage, not a device */
 
+  /* The label role's leading, declared standalone and deliberately not paired into text-label's
+     utility: pairing would move every existing label site's line box at once, silently. A component
+     whose own height is measured against its labels reads leading-label explicitly (Header #81). 1.5
+     is the line height SC 1.4.12 expects text to survive, so a user stylesheet applying it moves nothing. */
+  --leading-label: 1.5;
+
   /* Two quantities on one property that must not collapse: --tracking-label is a fixed letter-spaced
      style, --tracking-optical a correction that varies with size. The names say which is which, so the
      distinction survives without the ADR in hand. Scope: the title role and above - H1, H2 and the page
@@ -115,15 +129,15 @@ const TYPOGRAPHY = `@theme {
   --tracking-optical: -0.02em;
 }`;
 
-/* The reading measure is in ch, not rem, so the character count stays held when the body size moves
-   under it; --measure-display is narrower because bigger type wants fewer characters per line, and
-   --measure-wide slightly wider - the standfirst of a page head (PageHead #18) is an opening statement,
-   not a reading column, so it runs a little past the reading measure by design. All three in ch and,
-   having no Tailwind namespace, in :root beside radius, read as max-w-[var(--measure)]. */
+/* The reading measures are in ch so the character count holds when the body size moves under them:
+   --measure-display narrower because bigger type wants fewer characters per line, --measure-wide a
+   little past the reading column for the page-head standfirst (PageHead #18). --measure-action is
+   the action column, in rem (docs/adr/0008, Amendments, #97); 20rem clears --control-min-width. */
 const MEASURE = `:root {
   --measure: 66ch;
   --measure-display: 36ch;
   --measure-wide: 72ch;
+  --measure-action: 20rem;
 }`;
 
 /* Three spacing roles, not a ladder: --space-stack is the sibling gap in a stack, --space-region the air
@@ -159,6 +173,14 @@ const FOLD = `:root {
   --fold-height: min(70vh, 40rem);
 }`;
 
+/* The least height a whole screen takes (CONTEXT.md: Cover) - measured against the screen like the
+   fold, in :root beside it with no Tailwind namespace, read as min-h-[var(--cover-height)]. In svh so
+   a mobile browser's collapsing chrome never hides a foot pinned to the bottom edge. A floor and
+   never a ceiling, so overflowing content grows the frame; enforced per ADR 0004. */
+const COVER = `:root {
+  --cover-height: 100svh;
+}`;
+
 /* Four aspect roles in a @theme block like typography: --aspect-* is a Tailwind 4 namespace, so it
    generates the aspect-portrait utilities Figure reaches rather than a :root value. Named shapes, not
    a ladder - ADR 0003/0004 rejected a radius and spacing scale (see SPACING) because a scale lets a
@@ -225,6 +247,9 @@ ${RADIUS}
 /* The control minimum width is not a colour either, and sits in :root beside radius. */
 ${CONTROL_MIN_WIDTH}
 
+/* The standing slot's minimum width is not a colour either, and sits in :root beside the control one. */
+${STANDING_MIN_WIDTH}
+
 /* The library's underline dimensions are not colours either, and sit in :root beside radius. They are
    not prose's alone: every Link treatment that draws a line draws it from these (docs/adr/0006). */
 ${UNDERLINE}
@@ -237,7 +262,9 @@ ${TYPOGRAPHY}
    after it and are not carried in @theme inline with the palette. */
 ${ASPECT}
 
-/* The reading measure has no Tailwind namespace, so it sits in :root beside radius. */
+/* The measures have no Tailwind namespace, so they sit in :root beside radius. The reading measures
+   are in ch against the type; the action column is in rem against the root, since it bounds a stack
+   of controls rather than a reading line (docs/adr/0008, Amendments). */
 ${MEASURE}
 
 /* Spacing has no Tailwind namespace either - --spacing is a single base multiplier ADR 0004 forbids
@@ -250,6 +277,9 @@ ${GUTTER}
 /* The fold height has no Tailwind namespace either, so it sits in :root beside the gutter. */
 ${FOLD}
 
+/* The cover height has no Tailwind namespace either, so it sits in :root beside the fold. */
+${COVER}
+
 /* The checklist tick's dimensions are not colours either, and sit in :root beside the underline block. */
 ${TICK}
 `;

package/src/index.ts

@@ -1,5 +1,7 @@
 import './styles.css';
 
+export { Cluster } from 'Arrangement/Cluster/Cluster';
+export { Stack } from 'Arrangement/Stack/Stack';
 export { Brandmark } from 'Display/Brandmark/Brandmark';
 export { Checklist } from 'Display/Checklist/Checklist';
 export { DefinitionList } from 'Display/DefinitionList/DefinitionList';
@@ -13,12 +15,14 @@ export { H3 } from 'Display/Typography/H3/H3';
 export { H4 } from 'Display/Typography/H4/H4';
 export { H5 } from 'Display/Typography/H5/H5';
 export { H6 } from 'Display/Typography/H6/H6';
+export { Note } from 'Display/Typography/Note/Note';
 export { P } from 'Display/Typography/P/P';
 export { Prose } from 'Display/Typography/Prose/Prose';
 export { Button } from 'Interaction/Button/Button';
 export { Input } from 'Interaction/Input/Input';
 export { Link } from 'Interaction/Link/Link';
 export { TextArea } from 'Interaction/TextArea/TextArea';
+export { Cover } from 'Layout/Cover/Cover';
 export { Footer } from 'Layout/Footer/Footer';
 export type { FormState } from 'Layout/Form/Form';
 export { Form } from 'Layout/Form/Form';