@juwel-development/design-system 3.0.0 → 3.1.0

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,75 @@
+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>, its variants declared in the order the prop table reads. Six existing
+// components hand-write this same set of utilities and the spec pins each against it - they cannot
+// import this one (architecture standard, the import test) - but that pinning compares the utilities
+// as a set, so nothing here is ordered to satisfy a test. The roster is the evidence and not the
+// token family: `band` is vertical padding and never a gap, and only `--measure` has ever bounded a
+// container, so the bound is on-or-off rather than a set of named measures (docs/adr/0008).
+// `split` turns at `lg`, the threshold Rail and DefinitionList already use.
+const stack = cva('flex', {
+  variants: {
+    gap: {
+      stack: 'gap-[var(--space-stack)]',
+      region: 'gap-[var(--space-region)]',
+    },
+    measure: { true: 'max-w-[var(--measure)]', false: '' },
+    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. 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.
+ * - `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,

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/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>