@juwel-development/design-system 3.0.0 → 3.2.0

package/dist/types/Theme/Palette.d.ts

@@ -38,14 +38,35 @@ export type PaletteTokens = {
      *  because a failed image renders its alt text on this plate and that text must stay legible. That
      *  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
      *  the fill is transparent. */
@@ -68,11 +89,39 @@ export type PaletteTokens = {
     error: string;
     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 declare 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 declare const dark: PaletteTokens;

package/dist/types/index.d.ts

@@ -1,4 +1,6 @@
 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';
@@ -12,12 +14,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';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juwel-development/design-system",
-	"version": "3.0.0",
+	"version": "3.2.0",
 	"type": "module",
 	"description": "Shared design system: tokens and components.",
 	"license": "MIT",

package/src/Arrangement/Cluster/Cluster.tsx

@@ -0,0 +1,80 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe on a plain <div>. The two axes are two positions and take different roles, so the base
+// sets `gap-y` and the variant sets `gap-x` - a shorthand would hand the caller both. `gap` holds the
+// two roles attested along a line and defaults to `region`, the wider one every clustered site uses;
+// the wrapped-line gap and the baseline alignment have one answer each in the evidence, so the recipe
+// fixes them and no prop reaches them (docs/adr/0008). Header hand-writes a near-identical row and
+// cannot import this one (architecture standard, the import test); it deliberately differs on gap-y.
+const cluster = cva(
+  'flex flex-wrap items-baseline gap-y-[var(--space-stack)]',
+  {
+    variants: {
+      gap: {
+        stack: 'gap-x-[var(--space-stack)]',
+        region: 'gap-x-[var(--space-region)]',
+      },
+      justify: {
+        start: '',
+        between: 'justify-between',
+      },
+    },
+    defaultVariants: { gap: 'region', justify: 'start' },
+  },
+);
+
+export interface IClusterProps extends VariantProps<typeof cluster> {
+  /** The clustered matter. Rendered unmodified: `Cluster` imposes no anatomy and wraps nothing in an
+   *  item element. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * A horizontal arrangement that wraps: children in a row, aligned on their baselines, with a wider
+ * gap along a line than between wrapped lines. It owns one arrangement and nothing else - no
+ * landmark, no band, no join, no gutter, no fill - and takes no outer space, so whatever holds it
+ * owns the rhythm around it.
+ *
+ * @Guarantees — enforced on every render
+ * - It renders a `div` with no landmark role, no `nav` of its own and no margin.
+ * - Children wrap onto further lines rather than overflowing or shrinking, at every prop combination.
+ * - Children are always aligned on their baselines. These rows mix type at different roles — a nav
+ *   link at the label role beside a credit line at the small role — and centring them makes the type
+ *   look mis-set, so this is the arrangement rather than a default to override (docs/adr/0008).
+ * - `gap` selects which space role separates items **along a line**: `region` (the default), the gap
+ *   between one group and the next, or `stack`, the sibling gap between items that belong together.
+ *   Nothing else — neither the band role, which is vertical padding and never a gap, nor the gutter,
+ *   which is measured against the screen where these roles are measured against the type.
+ * - The gap between **wrapped lines** is always `--space-stack` and no prop can change it: a wrapped
+ *   line sitting as far from its neighbour as its items sit from each other stops reading as one group.
+ * - `justify="start"` (the default) runs the row from the start edge; `justify="between"` distributes
+ *   it end to end, which is the row with a group at each end.
+ * - No literal length and no numbered spacing rung appears in the recipe: every value it emits is a
+ *   role the token layer already names, so a second brand re-points all of them.
+ * - `children` render unmodified, and it needs no JavaScript.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - A cluster that navigates is wrapped in — or wraps — the caller's own `<nav aria-label="…">`.
+ *   This component declares no landmark, exactly as `Footer`'s guidance already directs.
+ * - The gutter and the vertical band belong to whatever holds it — a `Section`, a `Footer` — and not
+ *   to a prop here, or two components own one job.
+ *
+ * @UXGuidelines
+ * - `gap="stack"` is the row whose items belong together, as a form's actions do. `gap="region"`
+ *   separates one group from the next; reach for it when the row's items are not a single set.
+ * - `justify="between"` needs two groups to distribute. A row of loose items pushed end to end reads
+ *   as a gap in the middle rather than as a distribution.
+ */
+export const Cluster: FunctionComponent<IClusterProps> = ({
+  gap,
+  justify,
+  children,
+  testId,
+}) => (
+  <div className={cluster({ gap, justify })} data-testid={testId}>
+    {children}
+  </div>
+);

package/src/Arrangement/Stack/Stack.tsx

@@ -0,0 +1,81 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe on a plain <div>. Six components hand-write this same utility set and their specs pin
+// it as a set, not an order (architecture standard, the import test). `band` is vertical padding,
+// never a gap; the bound holds exactly the two container roles docs/adr/0008's Amendments attest
+// (#97), which argue the `w-full` pairing. `split` turns at `lg`, the Rail/DefinitionList threshold.
+const stack = cva('flex', {
+  variants: {
+    gap: {
+      stack: 'gap-[var(--space-stack)]',
+      region: 'gap-[var(--space-region)]',
+    },
+    measure: {
+      true: 'max-w-[var(--measure)]',
+      false: '',
+      action: 'w-full max-w-[var(--measure-action)]',
+    },
+    direction: {
+      column: 'flex-col',
+      split: 'flex-col lg:flex-row lg:items-start',
+    },
+  },
+  defaultVariants: { gap: 'stack', measure: false, direction: 'column' },
+});
+
+export interface IStackProps extends VariantProps<typeof stack> {
+  /** The stacked matter. Rendered unmodified: `Stack` imposes no anatomy. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * A vertical arrangement: children in a column, separated by one named space role and optionally
+ * bounded by the reading measure or the action column. It owns one axis and one gap and nothing
+ * else - no landmark, no heading, no band, no join, no gutter, no fill - and takes no outer space,
+ * so whatever holds it owns the rhythm around it.
+ *
+ * @Guarantees — enforced on every render
+ * - It renders a `div` with no landmark role, no heading and no margin of its own.
+ * - `gap` selects which space role separates the children: `stack` (the default), the gap between
+ *   siblings within one block, or `region`, the gap between groups of blocks. Nothing else — a
+ *   spacing neither role expresses is a request for a measurement (docs/adr/0003, docs/adr/0004).
+ * - `measure` bounds the element to `--measure`, the reading column; omitted, the column is
+ *   unbounded, which is right wherever the children are not running text. It sets no font-size, so
+ *   a `ch`-counted measure keeps resolving against inherited body type.
+ * - `measure="action"` bounds the element to `--measure-action`, the action column - the width a
+ *   stack of full-width controls fills, so they read as one unit and their labels align - and fills
+ *   its slot up to that bound, so a centering frame cannot shrink it to its widest label. The two
+ *   options answer different questions about what the column holds - text or controls - never how
+ *   wide it should be (docs/adr/0008, Amendments).
+ * - `direction="column"` (the default) never changes axis. `direction="split"` is the same column
+ *   turning into a row at and above 64rem, its children aligned to their start edge rather than
+ *   stretched. It is the only viewport-dependent behaviour here, and it is named for the job: the
+ *   breakpoint is an implementation detail and is not part of the vocabulary.
+ * - No literal length and no numbered spacing rung appears in the recipe: every value it emits is a
+ *   role the token layer already names, so a second brand re-points all of them.
+ * - `children` render unmodified, and it needs no JavaScript.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - The gutter and the vertical band belong to the `Section` around it —
+ *   `<Section><Stack>…</Stack></Section>` — and not to a prop here, or two components own one job.
+ * - A stack holding running text is a reading block: reach for `Prose` instead, which is this
+ *   arrangement plus the contract that says the content is prose.
+ *
+ * @UXGuidelines
+ * - `gap="region"` separates groups of blocks, not blocks. A region-sized gap between two paragraphs
+ *   reads as missing content — the argument `Section` makes for joining rather than gapping.
+ */
+export const Stack: FunctionComponent<IStackProps> = ({
+  gap,
+  measure,
+  direction,
+  children,
+  testId,
+}) => (
+  <div className={stack({ gap, measure, direction })} data-testid={testId}>
+    {children}
+  </div>
+);

package/src/Display/Figure/Figure.tsx

@@ -1,6 +1,6 @@
 import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
-import type { FunctionComponent } from 'react';
+import type { FunctionComponent, ReactNode } from 'react';
 
 // One recipe, on the `img` - the only element that varies. The wrapper `figure` and the `figcaption`
 // carry literal class strings in JSX (the Input pattern, not the compound namespace: there is nothing
@@ -42,6 +42,10 @@ export interface IFigureProps extends VariantProps<typeof figure> {
   responsive?: { srcSet: string; sizes: string };
   /** Names the image. Its presence is what makes this a `figure`. */
   caption?: string;
+  /** A slot over the image frame - the consumer's own decoration, rendered unmodified as a sibling of
+   *  the image inside a positioning context. Having something to render is what makes that context
+   *  exist; where inside it the overlay sits is expressed on the consumer's own element. */
+  overlay?: ReactNode;
   /** Whether this image is visible when the page first paints. Set it on a hero. */
   priority?: boolean;
   testId?: string;
@@ -50,7 +54,9 @@ export interface IFigureProps extends VariantProps<typeof figure> {
 /**
  * An aspect-locked image frame with a focal point and an optional caption. The caption decides the
  * element: with one, the image is wrapped in a `figure` with a `figcaption`; without one, the image
- * renders alone, making no self-contained claim a thumbnail or logo should not make.
+ * renders alone, making no self-contained claim a thumbnail or logo should not make. An `overlay`
+ * decides a second element the same way: with one, the image sits in a positioning context the
+ * overlay can be placed against; without one, there is no wrapper at all.
  *
  * @Guarantees — enforced on every render
  * - Every image reserves its box before it loads: an intrinsic `width`/`height`, and a locked
@@ -59,14 +65,25 @@ export interface IFigureProps extends VariantProps<typeof figure> {
  *   `lazy` otherwise), so an above-the-fold hero is never deferred.
  * - A `figure` element appears only where there is a caption.
  * - `srcset` never ships without `sizes`: `responsive` bundles the two so one cannot go without the other.
+ * - An `overlay` renders unmodified: the component adds no class and no ARIA attribute to it, strips
+ *   nothing from it, and paints nothing on the frame - the wrapper it renders carries the positioning
+ *   context and no other property, so the image fills its container exactly as it does without one.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - A decorative overlay carries the consumer's own `aria-hidden="true"`. The library will not add it:
+ *   a slot it modifies is no longer a slot.
  *
  * @UXGuidelines
  * - Pass a `src` your build's image pipeline produced. One raw source measured 2 MB against 31.6 KB
  *   for the same crop, taking `load` from 0.95 s to 10.3 s. The component cannot check this.
  * - Check a photograph's hue range before putting a brand colour beside it. One frame sat entirely
  *   between hue 14° and 40°, so an amber call-to-action muddied against a terracotta wall - the accent
- *   lives where the photo isn't. `Figure` renders no overlay, so this is about what a page puts next
- *   to a figure, not on it.
+ *   lives where the photo isn't. The component paints nothing over the frame itself, so this is about
+ *   what a page puts next to a figure - and about what it puts in `overlay`, which is the consumer's
+ *   own decoration and answers to the same hue range.
+ * - `overlay` is a place, not a treatment. The library provides somewhere legal for a rim, a ring or a
+ *   plate to go, and provides none of them; positioning it inside the frame is the consumer's, expressed
+ *   on their own absolutely-positioned element.
  */
 export const Figure: FunctionComponent<IFigureProps> = ({
   src,
@@ -77,9 +94,18 @@ export const Figure: FunctionComponent<IFigureProps> = ({
   focus,
   responsive,
   caption,
+  overlay,
   priority,
   testId,
 }) => {
+  // Absence, not falsiness, and not `undefined` alone: `overlay={showRing && <Ring />}` hands over
+  // `false` when the decoration is off, and that consumer asked for no overlay - wrapping anyway
+  // would put a `div` where their flex or grid item used to be, which is the one thing this slot
+  // promises never to do. Absence is React's own set of nothing-to-render nodes, so a bare
+  // truthiness test is wrong in the other direction: `0` renders as `"0"`.
+  const hasOverlay =
+    overlay !== undefined && overlay !== null && typeof overlay !== 'boolean';
+
   const image = (
     <img
       src={src}
@@ -92,12 +118,27 @@ export const Figure: FunctionComponent<IFigureProps> = ({
       loading={priority ? 'eager' : 'lazy'}
       fetchPriority={priority ? 'high' : undefined}
       decoding={'async'}
-      data-testid={caption === undefined ? testId : undefined}
+      data-testid={caption === undefined && !hasOverlay ? testId : undefined}
     />
   );
 
+  // The positioning context exists only where there is something to position, so an overlay-less
+  // `Figure` renders exactly what it rendered before this slot existed - which matters most in the
+  // caption-less shape, where the image itself is the flex or grid item its container sees.
+  const frame = !hasOverlay ? (
+    image
+  ) : (
+    <div
+      className={'relative'}
+      data-testid={caption === undefined ? testId : undefined}
+    >
+      {image}
+      {overlay}
+    </div>
+  );
+
   if (caption === undefined) {
-    return image;
+    return frame;
   }
 
   return (
@@ -105,7 +146,7 @@ export const Figure: FunctionComponent<IFigureProps> = ({
       className={'flex flex-col gap-[var(--space-stack)]'}
       data-testid={testId}
     >
-      {image}
+      {frame}
       <figcaption
         className={'font-secondary text-label tracking-label text-muted'}
       >

package/src/Display/Rail/Rail.tsx

@@ -84,6 +84,8 @@ const RailContent: FunctionComponent<IRailContentProps> = ({
  *   the label role. Colours are semantic tokens re-pointed by `.dark`, so no class carries a `dark:` prefix.
  * - `number` is optional: omitted, the index renders the name alone and no empty numeral element.
  * - `Content` renders its children unmodified and sets no measure cap - `Prose` owns the reading measure.
+ * - `Content` sets no spacing between those children either - a composed `Stack` owns the gap. The slot
+ *   is opaque, so it cannot see the pieces whose rhythm it would set: the same reason it sets no measure.
  * - No margin, max-width, fill, box or vertical rule; no `tabular-nums` or `font-variant-numeric`.
  * - It needs no JavaScript: `position: sticky` is CSS.
  *
@@ -94,6 +96,10 @@ const RailContent: FunctionComponent<IRailContentProps> = ({
  *   consumer that files a section only in the index leaves it without an accessible name.
  *
  * @UXGuidelines
+ * - The heading `Content` is required to carry and the section's matter beneath it are two pieces in one
+ *   opaque slot, and the slot separates nothing. Compose the column inside it -
+ *   `<Rail.Content><Stack gap="…"><H2>Work</H2>{matter}</Stack></Rail.Content>` - and take the space role
+ *   from `Stack`'s own guidance: `Rail` holds no opinion on which of the two roles this position wants.
  * - An index is an information layer, not a layout remedy. Measured on the page that prompted it, the
  *   filing numeral bought 0px of width across three fallback rungs, and the column it sits in closed only
  *   +224px of a 933px deficit - it widens a composition's span, not its content. If a page sags, the

package/src/Display/Typography/H1/H1.tsx

@@ -6,13 +6,17 @@ import type { FunctionComponent, ReactNode } from 'react';
 // (docs/adr/0005). Weight inherits - Tailwind's preflight resets h1-h6 to font-weight: inherit, so
 // the sized levels carry no weight class. --tracking-optical is the large-type correction, carried by
 // the title role and above (#57), so the biggest type on the page is the first to take it. Colour is a
-// semantic token re-pointed by `.dark`, so no variant carries a `dark:` class.
-const h1 = cva('font-primary text-display leading-display tracking-optical', {
-  variants: {
-    color: { foreground: 'text-foreground', muted: 'text-muted' },
+// semantic token re-pointed by `.dark`, so no variant carries a `dark:` class. The measure is base and
+// not a variant because the role fixes it and a caller picks nothing (docs/adr/0008, #87).
+const h1 = cva(
+  'font-primary text-display leading-display tracking-optical max-w-[var(--measure-display)]',
+  {
+    variants: {
+      color: { foreground: 'text-foreground', muted: 'text-muted' },
+    },
+    defaultVariants: { color: 'foreground' },
   },
-  defaultVariants: { color: 'foreground' },
-});
+);
 
 interface IH1Props extends VariantProps<typeof h1> {
   children: ReactNode;
@@ -26,11 +30,17 @@ interface IH1Props extends VariantProps<typeof h1> {
  * - Renders an `h1`; its outline level and the display role are one choice, not two (docs/adr/0005).
  * - Reads `--font-primary`, sized by `--text-display`, led by `--leading-display` and optically
  *   corrected by `--tracking-optical`, the large-type correction every role from title up carries.
+ * - Bounded at `--measure-display`, the display role's own measure — narrower than the reading column
+ *   because bigger type wants fewer characters per line (docs/adr/0004). The bound is the recipe's,
+ *   not a caller's: the level fixes the role and the role fixes the measure, so there is no `measure`
+ *   prop to select between roles (docs/adr/0008). It holds under every `color`.
  * - `color` selects the `foreground` or `muted` role; nothing else paints text.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - This is an ordinary page title, and it is also a hero's lead - `display` is the hero role, so a
- *   poster hero's `h1` is this one, placed inside a `Hero` (#17), which renders no heading of its own.
+ *   poster hero's `h1` is this one, placed inside a `Hero` (#17), which renders no heading of its own
+ *   and leaves its slot uncapped — the display measure arrives with this heading rather than with the
+ *   slot, which would cap the mark beside it too (#87).
  * - A subpage head is the exception: `PageHead` renders its own `h1` at the `title` role, the one
  *   sanctioned escape valve from level-fixes-role (docs/adr/0005). Reach for it where it fits.
  * - Heading levels descend without skipping — an `h1` is followed by an `h2`, never an `h3`.

package/src/Display/Typography/Note/Note.tsx

@@ -0,0 +1,56 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// The annotation device: the secondary family at the small role, because docs/adr/0004 fixes
+// --font-secondary as the face labels are set in and an annotation labels rather than reads. It
+// defaults to `foreground` where Eyebrow defaults to `muted`: Eyebrow inverts the ordinary default
+// because its device is defined as muted, and an annotation is not - it is foreground *or* muted -
+// so Note follows `P` and keeps the ordinary default. No tracking and no weight: those two
+// are what make an Eyebrow. No measure and no margin: the annotation sits in no reading column, and
+// the page owns the rhythm around it. Colour is re-pointed by `.dark`, so no variant carries `dark:`.
+const note = cva('font-secondary text-small', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+export interface INoteProps extends VariantProps<typeof note> {
+  /** The annotation. A `ReactNode` rather than a string, because these lines carry inline links. */
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * A short annotation at the small type role in the secondary family — a routing line above a submit
+ * button, a privacy line at the point of submission, a line beside a control. Not reading matter:
+ * it takes no measure and sits in no reading column, which is what separates it from `Prose.Tail`
+ * at the same size, and it carries neither the tracking nor the weight that make an `Eyebrow`.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders a `p`, reading `--font-secondary` and sized by `--text-small`.
+ * - `color` selects the `foreground` (default) or `muted` role; nothing else paints text.
+ * - Emits no tracking, no font-weight, no measure and no margin under any prop.
+ * - Carries no ARIA role and no live region under any prop.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - The device has three carriers and this primitive is only one: use it for an annotation no other
+ *   component owns. A form's own message belongs to `Form`'s `note` and a table's to its note cell,
+ *   each painted by the component that owns it.
+ * - Do **not** put a `Note` in `Form`'s `note` slot: that nests a `p` in a `p` and paints the text
+ *   twice. The slot takes a node, so pass the wording straight to `Form` and let the links ride
+ *   inside it — inline content only, never a block. `Form` cannot delegate here either — the
+ *   architecture standard's one-way dependency rule is why `Prose` restates `P`'s utilities.
+ * - Where the annotation is a form's status message, `Form` owns `role="status"`/`role="alert"` by
+ *   state; a `Note` announces nothing.
+ */
+export const Note: FunctionComponent<INoteProps> = ({
+  children,
+  color,
+  testId,
+}) => (
+  <p className={note({ color })} data-testid={testId}>
+    {children}
+  </p>
+);

package/src/Interaction/Button/Button.tsx

@@ -10,8 +10,11 @@ import type { Subject } from 'rxjs';
 // base too: identical across variants, drawn with outline, colour at rest so it never fades in -
 // see docs/adr/0002-focus-ring-token-contract.md. The corner is in the base as well, one radius
 // token every variant shares, so none can disagree - see docs/adr/0003-radius-token-contract.md.
+// The face is in the base for the same reason - see docs/adr/0004-typography-token-contract.md (#90).
+// The size is in the base for the same reason, and here it is load-bearing: the recipe fixes
+// vertical padding and sets no height, so the font-size is what drives it (docs/adr/0004, #92).
 const button = cva(
-  'transition-colors duration-[var(--motion-duration-color)] rounded-[var(--radius-control)] py-2 sm:py-2 disabled:bg-disabled disabled:hover:bg-disabled-hover cursor-pointer disabled:cursor-not-allowed select-none text-nowrap inline-flex flex-row items-center justify-center gap-2 outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  'font-primary text-body transition-colors duration-[var(--motion-duration-color)] rounded-[var(--radius-control)] py-2 sm:py-2 disabled:bg-disabled disabled:hover:bg-disabled-hover cursor-pointer disabled:cursor-not-allowed select-none text-nowrap inline-flex flex-row items-center justify-center gap-2 outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
   {
     variants: {
       variant: {

package/src/Interaction/Input/Input.tsx

@@ -8,9 +8,11 @@ import type { Subject } from 'rxjs';
 // `.dark`, so no variant carries a `dark:` class. The border is the only boundary of a transparent
 // control, 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).
+// Focus adds only the shared ring - the border never changes on focus (docs/adr/0002). 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 input = cva(
-  'block 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 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',
   {
     variants: {
       // text/email/url are visually identical; the axis only selects the control's `type`
@@ -91,7 +93,14 @@ export const Input: FunctionComponent<IInputProps> = ({
 
   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>
       <input
@@ -111,15 +120,17 @@ export const Input: FunctionComponent<IInputProps> = ({
         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/Interaction/Link/Link.tsx

@@ -8,6 +8,10 @@ import type { FunctionComponent, ReactNode } from 'react';
 // semantic tokens re-pointed by `.dark`, so no treatment carries a `dark:` class. Underlines read the
 // library's --underline-* tokens and arrive instantly, off the transition allowlist (docs/adr/0001):
 // prose thickens its on hover, quiet and label-link raise one at rest thickness, graphic has none.
+// Only `quiet` declares a face; the other three decline one deliberately (docs/adr/0004, #90).
+// No treatment declares a type role either, `quiet` included, and that silence is a decision, not
+// the omission #92 closed elsewhere: a face is constant across placements, a size is not
+// (docs/adr/0004, #92; docs/adr/0006 for label-link).
 const link = cva(
   'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
   {
@@ -16,7 +20,7 @@ const link = cva(
         prose:
           'text-link underline decoration-[length:var(--underline-thickness)] underline-offset-[var(--underline-offset)] hover:decoration-[length:var(--underline-thickness-hover)]',
         quiet:
-          'text-muted no-underline decoration-[length:var(--underline-thickness)] underline-offset-[var(--underline-offset)] transition-colors duration-[var(--motion-duration-color)] hover:text-foreground hover:underline',
+          'font-secondary text-muted no-underline decoration-[length:var(--underline-thickness)] underline-offset-[var(--underline-offset)] transition-colors duration-[var(--motion-duration-color)] hover:text-foreground hover:underline',
         'label-link':
           'text-inherit no-underline decoration-[length:var(--underline-thickness)] underline-offset-[var(--underline-offset)] hover:underline',
         graphic: 'text-inherit no-underline',
@@ -42,10 +46,10 @@ interface ILinkProps extends VariantProps<typeof link> {
 
 /**
  * A link in one of four treatments. `prose` for running text (told apart by its underline, never by
- * hue), `quiet` for standing navigation (muted, and foreground with an underline on hover),
- * `label-link` for a link acting as a label (inherits its colour, underlines on hover, sets no type
- * of its own), and `graphic` for an anchor whose child is not text (paints nothing, so a mark keeps
- * its own colour). It renders a plain `<a>`, so it works with no hydration.
+ * hue), `quiet` for standing navigation (muted, set in the labelling face, and foreground with an
+ * underline on hover), `label-link` for a link acting as a label (inherits its colour, underlines
+ * on hover, sets no type of its own), and `graphic` for an anchor whose child is not text (paints
+ * nothing, so a mark keeps its own colour). It renders a plain `<a>`, so it works with no hydration.
  */
 export const Link: FunctionComponent<ILinkProps> = ({
   href,