@juwel-development/design-system 1.1.0 → 2.0.0

package/src/Display/DefinitionList/DefinitionList.tsx

@@ -0,0 +1,90 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Rules are the layout. Each Item owns its two-track grid and its hairlines. The term track is a fixed
+// width, so per-item grids line up without a subgrid. At `lg` (64rem) a second `dt` is pinned to the
+// term column so it cannot auto-place into the description column and break the row silently. Colours
+// are semantic tokens re-pointed by `.dark`, so no class carries a `dark:` prefix.
+const item = cva(
+  [
+    'grid gap-[var(--space-stack)] py-6',
+    'border-b border-solid border-border first:border-t',
+    'lg:grid-cols-[16rem_minmax(0,1fr)] lg:items-baseline lg:gap-x-12',
+    'lg:[&>dt]:col-start-1 lg:[&>dd]:col-start-2 lg:[&>dd]:row-start-1',
+  ].join(' '),
+);
+
+// The term at the subtitle role - a step below title (docs/adr/0005 fixes the role, no size prop), so
+// terms never tie with the heading introducing the list. Foreground, and no measure cap.
+const term = cva('font-primary text-subtitle leading-subtitle text-foreground');
+
+// The description at the body role, muted, capped at the reading measure in both layout modes.
+const description = cva(
+  'font-primary text-body leading-body text-muted max-w-[var(--measure)]',
+);
+
+interface IDefinitionListRootProps {
+  children?: ReactNode;
+  testId?: string;
+}
+
+interface IDefinitionListItemProps {
+  children?: ReactNode;
+  testId?: string;
+}
+
+interface IDefinitionListTermProps {
+  children?: ReactNode;
+}
+
+interface IDefinitionListDescriptionProps {
+  children?: ReactNode;
+}
+
+const DefinitionListRoot: FunctionComponent<IDefinitionListRootProps> = ({
+  children,
+  testId,
+}) => <dl data-testid={testId}>{children}</dl>;
+
+const DefinitionListItem: FunctionComponent<IDefinitionListItemProps> = ({
+  children,
+  testId,
+}) => (
+  <div className={item()} data-testid={testId}>
+    {children}
+  </div>
+);
+
+const DefinitionListTerm: FunctionComponent<IDefinitionListTermProps> = ({
+  children,
+}) => <dt className={term()}>{children}</dt>;
+
+const DefinitionListDescription: FunctionComponent<
+  IDefinitionListDescriptionProps
+> = ({ children }) => <dd className={description()}>{children}</dd>;
+
+/**
+ * A typeset list of terms and their descriptions, where the rules are the layout. The consumer
+ * composes the list from the four members; no member takes a data array. `Root` renders `<dl>`,
+ * `Item` the grouping `<div>` (valid inside `<dl>` for exactly this purpose), `Term` a `<dt>`,
+ * `Description` a `<dd>`.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders semantic `dl`/`div`/`dt`/`dd`, and works with JavaScript off.
+ * - The term is fixed to the subtitle type role and exposes no size prop or variant (docs/adr/0005).
+ * - The description is body, muted, and capped at `--measure`; the term carries no measure cap.
+ * - A hairline sits above the first item and below every item, in `border`, and the block closes at
+ *   the foot. No card, box, fill, icon or bullet - it reads from the rules alone.
+ * - Single column below 64rem with the term above its description; two columns at and above it with a
+ *   fixed term track and baseline-aligned rows. The switch is a media query, not a prop.
+ *
+ * @UXGuidelines
+ * - Several `Term`s may share one `Description`; keep them inside one `Item` so the term column
+ *   stays intact.
+ */
+export const DefinitionList = {
+  Root: DefinitionListRoot,
+  Item: DefinitionListItem,
+  Term: DefinitionListTerm,
+  Description: DefinitionListDescription,
+} as const;

package/src/Display/Figure/Figure.tsx

@@ -0,0 +1,116 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent } 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
+// here to compose). `ratio` has no default, so an omitted ratio emits no aspect-* class and the image
+// keeps its intrinsic shape; `focus` defaults to center and is inert without a ratio, since object-*
+// has nothing to crop in the base. Colours are semantic tokens re-pointed by `.dark`, so no `dark:`.
+const figure = cva('block w-full object-cover bg-backing', {
+  variants: {
+    ratio: {
+      portrait: 'aspect-portrait',
+      square: 'aspect-square',
+      landscape: 'aspect-landscape',
+      wide: 'aspect-wide',
+    },
+    focus: {
+      center: 'object-center',
+      top: 'object-top',
+      bottom: 'object-bottom',
+      left: 'object-left',
+      right: 'object-right',
+    },
+  },
+  defaultVariants: { focus: 'center' },
+});
+
+export interface IFigureProps extends VariantProps<typeof figure> {
+  /** The image source. Produce it through the consuming build's image pipeline - see @UXGuidelines. */
+  src: string;
+  /** The image's text alternative. Empty string when the image is decorative, or when `caption`
+   *  already names it - a non-empty alt beside a caption reads the same content to a screen reader
+   *  twice. */
+  alt: string;
+  /** The source's intrinsic pixel width. */
+  width: number;
+  /** The source's intrinsic pixel height. */
+  height: number;
+  /** Responsive delivery. One decision with two parts, so they are one prop: a `srcSet` with `w`
+   *  descriptors and no `sizes` makes the browser assume 100vw and download the largest candidate. */
+  responsive?: { srcSet: string; sizes: string };
+  /** Names the image. Its presence is what makes this a `figure`. */
+  caption?: string;
+  /** Whether this image is visible when the page first paints. Set it on a hero. */
+  priority?: boolean;
+  testId?: string;
+}
+
+/**
+ * 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.
+ *
+ * @Guarantees — enforced on every render
+ * - Every image reserves its box before it loads: an intrinsic `width`/`height`, and a locked
+ *   `aspect-ratio` once a `ratio` is given.
+ * - `decoding="async"` always; `loading` follows `priority` (`eager`+`fetchpriority="high"` when set,
+ *   `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.
+ *
+ * @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.
+ */
+export const Figure: FunctionComponent<IFigureProps> = ({
+  src,
+  alt,
+  width,
+  height,
+  ratio,
+  focus,
+  responsive,
+  caption,
+  priority,
+  testId,
+}) => {
+  const image = (
+    <img
+      src={src}
+      alt={alt}
+      width={width}
+      height={height}
+      className={figure({ ratio, focus })}
+      srcSet={responsive?.srcSet}
+      sizes={responsive?.sizes}
+      loading={priority ? 'eager' : 'lazy'}
+      fetchPriority={priority ? 'high' : undefined}
+      decoding={'async'}
+      data-testid={caption === undefined ? testId : undefined}
+    />
+  );
+
+  if (caption === undefined) {
+    return image;
+  }
+
+  return (
+    <figure
+      className={'flex flex-col gap-[var(--space-stack)]'}
+      data-testid={testId}
+    >
+      {image}
+      <figcaption
+        className={'font-secondary text-label tracking-label text-muted'}
+      >
+        {caption}
+      </figcaption>
+    </figure>
+  );
+};

package/src/Display/Rail/Rail.tsx

@@ -0,0 +1,108 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Root owns both tracks so the sticky index has this grid as its containing block - the whole guarantee
+// rests on Index being a direct child. One column below 64rem, index above content; at `lg` a fixed
+// 10rem index track and `minmax(0,1fr)` beside it, with `items-start` giving the index cell the full row
+// height to stick within. The three numbers are literals stated in prose (docs/adr/0003), not tokens.
+const railRoot = cva(
+  [
+    'grid gap-[var(--space-stack)]',
+    'lg:grid-cols-[10rem_minmax(0,1fr)] lg:items-start lg:gap-x-12',
+  ].join(' '),
+);
+
+// The index track: sticky with a 1.5rem offset only at and above 64rem; below it the index lies down
+// and stays static, so it needs no opaque fill, edge or stacking decision. It is aria-hidden - it
+// repeats the section's heading, which lives in the content track. The label role sits on each part.
+const railIndex = cva('lg:sticky lg:top-6');
+
+// Both parts at the label role (docs/adr/0005 binds it to no heading), told apart by colour alone. The
+// numeral is muted with a hairline under it in `border`, not `rule` - the page-structure weight Section
+// joins carry, which a device this small should not draw. The name is foreground. Colours are semantic
+// tokens re-pointed by `.dark`, so no class carries a `dark:` prefix.
+const railNumeral = cva(
+  'block border-b border-solid border-border pb-1 font-secondary text-label tracking-label text-muted',
+);
+
+const railName = cva(
+  'block pt-1 font-secondary text-label tracking-label text-foreground',
+);
+
+interface IRailRootProps {
+  children?: ReactNode;
+  testId?: string;
+}
+
+interface IRailIndexProps {
+  /** The filing numeral as a string - `02`, not `2`. Zero-padding is a brand decision, so the caller
+   *  writes the exact glyphs. Omitted, the index renders its name alone with no empty numeral element. */
+  number?: string;
+  children?: ReactNode;
+  testId?: string;
+}
+
+interface IRailContentProps {
+  children?: ReactNode;
+  testId?: string;
+}
+
+const RailRoot: FunctionComponent<IRailRootProps> = ({ children, testId }) => (
+  <div className={railRoot()} data-testid={testId}>
+    {children}
+  </div>
+);
+
+const RailIndex: FunctionComponent<IRailIndexProps> = ({
+  number,
+  children,
+  testId,
+}) => (
+  <div className={railIndex()} data-testid={testId} aria-hidden="true">
+    {number !== undefined && <span className={railNumeral()}>{number}</span>}
+    <span className={railName()}>{children}</span>
+  </div>
+);
+
+const RailContent: FunctionComponent<IRailContentProps> = ({
+  children,
+  testId,
+}) => <div data-testid={testId}>{children}</div>;
+
+/**
+ * A section filed beside a sticky index: the section's matter in the wide track and, at and above 64rem,
+ * a persistent index in the narrow one. Composed from three members - `Root` renders the two-track grid,
+ * `Index` the sticky filing device, `Content` the opaque slot for the matter. `Root` is a `div` with no
+ * landmark; the section's heading lives in `Content`, and `Index` repeats it only as a visual marker.
+ *
+ * @Guarantees — enforced on every render
+ * - `Index` persists beside its section at and above 64rem and reads as a filed heading above the text
+ *   below it. The switch is a media query, not a prop.
+ * - `Index` is decorative to assistive technology (`aria-hidden`): it repeats the heading the content
+ *   track carries and does not replace it.
+ * - The index numeral is muted with a hairline under it in `border`; the name is foreground; both sit at
+ *   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.
+ * - No margin, max-width, fill, box or vertical rule; no `tabular-nums` or `font-variant-numeric`.
+ * - It needs no JavaScript: `position: sticky` is CSS.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - `Rail.Index` is a direct child of `Rail.Root`: `position: sticky` positions against the grid
+ *   container, so the index sticks for the height of its row only when Root is its parent.
+ * - The section's heading lives in `Rail.Content`. `Index` is aria-hidden and carries no heading, so a
+ *   consumer that files a section only in the index leaves it without an accessible name.
+ *
+ * @UXGuidelines
+ * - 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
+ *   answer is a column; whether that column should also be an index is a separate decision.
+ * - Do not place a rail on a hero or a full-bleed section. A bleeding section drops the gutter, so there
+ *   is no inset for an index track to stand in, and a poster is not a filed section.
+ */
+export const Rail = {
+  Root: RailRoot,
+  Index: RailIndex,
+  Content: RailContent,
+} as const;

package/src/Display/Table/Table.tsx

@@ -0,0 +1,191 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Rules are the layout. One recipe styles the whole table from its wrapper, so the block reads as a
+// table from two rule weights and nothing else: no cell borders, no fill, no zebra, no hover. Colours
+// are semantic tokens re-pointed by `.dark`, so no selector carries a `dark:` class. The responsive
+// behaviour is keyed on the wrapper's `data-notes`, so a server renders the right markup with no
+// hydration and the mode is one attribute a stylesheet and a test can both read.
+const table = cva(
+  [
+    // With no note column the wrapper becomes a horizontally scrollable region (see Root); the scroll
+    // sits here so the table keeps its table formatting context and the figures stay column-aligned.
+    '[&:not([data-notes])]:overflow-x-auto',
+    // The table: full width, collapsed borders so adjacent row rules meet as one line, text flush left.
+    '[&>table]:w-full [&>table]:border-collapse [&>table]:text-left',
+    // The required caption, rendered first, as the table's label in the tracked grotesk device.
+    '[&_caption]:pb-3 [&_caption]:text-left [&_caption]:font-secondary [&_caption]:text-label [&_caption]:tracking-label [&_caption]:text-muted',
+    // Every row carries a hairline top (Row); the first row - the first row group after the caption -
+    // is promoted to the heavier `rule` colour, and that heavier line is what reads as a table not a list.
+    '[&>table>*:nth-child(2)>tr:first-child]:border-rule',
+    // notes="supplementary": the note column leaves the page for everyone, sighted or not, below 48rem.
+    '[&[data-notes=supplementary]_[data-variant=note]]:max-md:hidden',
+    // notes="content": the note is the content, so each row stacks into a single column below 48rem.
+    '[&[data-notes=content]>table]:max-md:block',
+    '[&[data-notes=content]_thead]:max-md:block [&[data-notes=content]_tbody]:max-md:block [&[data-notes=content]_tfoot]:max-md:block',
+    '[&[data-notes=content]_tr]:max-md:block [&[data-notes=content]_td]:max-md:block [&[data-notes=content]_th]:max-md:block',
+  ].join(' '),
+);
+
+// One hairline above every row, in `border`. Root promotes the first row's colour to `rule`; the last
+// row takes no bottom rule, so the block stays open at the foot - the difference from a closed list.
+const tableRow = cva('border-t border-solid border-border');
+
+// A value is serif with real tabular figures; a note is the muted grotesk. Both sit at the small role,
+// which carries the enforced 15px floor below which figures stop comparing column to column.
+const tableCell = cva('px-4 py-2 text-small first:pl-0 last:pr-0', {
+  variants: {
+    variant: {
+      value: 'font-primary text-foreground tabular-nums',
+      note: 'font-secondary text-muted',
+    },
+    align: { left: 'text-left', right: 'text-right', center: 'text-center' },
+  },
+  defaultVariants: { variant: 'value', align: 'left' },
+});
+
+// The label: the tracked muted grotesk, at the label role. Carried by both scopes (column and row).
+const tableHeaderCell = cva(
+  'px-4 py-2 font-secondary font-medium text-label text-muted tracking-label first:pl-0 last:pr-0',
+  {
+    variants: {
+      align: { left: 'text-left', right: 'text-right', center: 'text-center' },
+    },
+    defaultVariants: { align: 'left' },
+  },
+);
+
+interface ITableRootProps {
+  /** The table's accessible name. Rendered as the first child; always present. */
+  caption: string;
+  /** What the note column is. Governs narrow-viewport behaviour; omit when there is none. */
+  notes?: 'supplementary' | 'content';
+  children?: ReactNode;
+  testId?: string;
+}
+
+interface ITableSectionProps {
+  children?: ReactNode;
+}
+
+interface ITableRowProps {
+  children?: ReactNode;
+  testId?: string;
+}
+
+interface ITableCellProps extends VariantProps<typeof tableCell> {
+  children?: ReactNode;
+}
+
+interface ITableHeaderCellProps extends VariantProps<typeof tableHeaderCell> {
+  /** Explicit, never inferred from Head/Body position - inference would need render-time context. */
+  scope: 'row' | 'col';
+  children?: ReactNode;
+}
+
+const TableRoot: FunctionComponent<ITableRootProps> = ({
+  caption,
+  notes,
+  children,
+  testId,
+}) => {
+  const content = (
+    <table>
+      <caption>{caption}</caption>
+      {children}
+    </table>
+  );
+  // No note column: the wrapper is a labelled region (a named `section`) so the horizontally
+  // scrolled table is keyboard-operable - WCAG 2.1.1 needs the scroll container itself focusable,
+  // there being no focusable cell content to carry it. With a note column there is nothing to
+  // scroll to, so the wrapper stays a plain grouping element.
+  if (notes === undefined) {
+    return (
+      <section
+        className={table()}
+        data-testid={testId}
+        aria-label={caption}
+        // biome-ignore lint/a11y/noNoninteractiveTabindex: a scroll container must be keyboard-operable (WCAG 2.1.1)
+        tabIndex={0}
+      >
+        {content}
+      </section>
+    );
+  }
+  return (
+    <div className={table()} data-notes={notes} data-testid={testId}>
+      {content}
+    </div>
+  );
+};
+
+const TableHead: FunctionComponent<ITableSectionProps> = ({ children }) => (
+  <thead>{children}</thead>
+);
+
+const TableBody: FunctionComponent<ITableSectionProps> = ({ children }) => (
+  <tbody>{children}</tbody>
+);
+
+const TableFooter: FunctionComponent<ITableSectionProps> = ({ children }) => (
+  <tfoot>{children}</tfoot>
+);
+
+const TableRow: FunctionComponent<ITableRowProps> = ({ children, testId }) => (
+  <tr className={tableRow()} data-testid={testId}>
+    {children}
+  </tr>
+);
+
+const TableHeaderCell: FunctionComponent<ITableHeaderCellProps> = ({
+  scope,
+  align,
+  children,
+}) => (
+  <th scope={scope} className={tableHeaderCell({ align })}>
+    {children}
+  </th>
+);
+
+const TableCell: FunctionComponent<ITableCellProps> = ({
+  variant,
+  align,
+  children,
+}) => (
+  <td
+    className={tableCell({ variant, align })}
+    data-variant={variant ?? 'value'}
+  >
+    {children}
+  </td>
+);
+
+/**
+ * A composable data table where the rules are the layout. The consumer composes the table from the
+ * seven members; no member takes a data array. A specification / details table is the shape it is
+ * built for - a row label, a value in tabular figures, and a note.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders semantic `table`/`thead`/`tbody`/`tfoot`/`tr`/`th`/`td`, and works with JavaScript off.
+ * - `Root` renders its required `caption` as the table's first child, so every table is named.
+ * - The block reads as a table from two rule weights alone: the heavier `rule` above the first row,
+ *   `border` hairlines between rows, and no bottom rule on the last. No cell borders, fill, zebra or hover.
+ * - `Cell variant="value"` sets tabular figures; `variant="note"` does not. Both at the 15px small role.
+ * - `HeaderCell` emits the `scope` it is given; none is inferred.
+ *
+ * @UXGuidelines
+ * - `align` is a cell property but reads as a column one: set the same `align` on a `HeaderCell` and
+ *   every `Cell` beneath it, and keep them in sync - the component cannot align a column for you.
+ * - Choose `notes` by what the note column *is*: `"supplementary"` drops it below 48rem for everyone
+ *   (out of the accessibility tree too); `"content"` stacks each row; omit it when there is no note.
+ */
+export const Table = {
+  Root: TableRoot,
+  Head: TableHead,
+  Body: TableBody,
+  Footer: TableFooter,
+  Row: TableRow,
+  HeaderCell: TableHeaderCell,
+  Cell: TableCell,
+} as const;

package/src/Display/Typography/Eyebrow/Eyebrow.tsx

@@ -0,0 +1,46 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// The letter-spaced eyebrow device: the secondary family, the label size and the label tracking, at
+// weight 500 (docs/adr/0004). First consumer of --font-secondary. The tracking is a fixed style, read
+// from --tracking-label so a site-wide optical curve cannot collapse it. It defaults to `muted`
+// because the device is defined as muted - the one primitive to invert that default. Never sets
+// font-variant-caps or -numeric: both fail silently on a face without the feature. Colour is a
+// semantic token re-pointed by `.dark`, so no variant carries a `dark:` class.
+const eyebrow = cva('font-secondary text-label tracking-label font-medium', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'muted' },
+});
+
+interface IEyebrowProps extends VariantProps<typeof eyebrow> {
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The eyebrow / caption device, a `p` at the label type role: the secondary family, the label size
+ * and a fixed +0.14em tracking, muted. The single primitive for the one *unowned* use of the device
+ * — a short tracked line standing above a section heading.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders a `p`, reading `--font-secondary`, sized by `--text-label` and tracked by
+ *   `--tracking-label`, at weight 500.
+ * - `color` selects the `muted` (default) or `foreground` role; nothing else paints text.
+ * - Sets neither `font-variant-caps` nor `font-variant-numeric` under any prop.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - This is **not a form label**: it renders no `htmlFor` and labels no control. A labelled control
+ *   uses `Input`/`TextArea`, which label themselves.
+ */
+export const Eyebrow: FunctionComponent<IEyebrowProps> = ({
+  children,
+  color,
+  testId,
+}) => (
+  <p className={eyebrow({ color })} data-testid={testId}>
+    {children}
+  </p>
+);

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

@@ -0,0 +1,46 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Level fixes role: an h1 is always the display role, with no size prop to invert the ladder
+// (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' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+interface IH1Props extends VariantProps<typeof h1> {
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The page-title heading, an `h1` at the display type role.
+ *
+ * @Guarantees — enforced on every render
+ * - 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.
+ * - `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.
+ * - 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`.
+ */
+export const H1: FunctionComponent<IH1Props> = ({
+  children,
+  color,
+  testId,
+}) => (
+  <h1 className={h1({ color })} data-testid={testId}>
+    {children}
+  </h1>
+);

package/src/Display/Typography/H2/H2.tsx

@@ -0,0 +1,43 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Level fixes role: an h2 is always the title role, with no size prop (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 and the title role is where it starts
+// (#57), so an h2 and the page head's h1 - the same role - are tracked alike, and h3 down is not.
+// Colour is a semantic token re-pointed by `.dark`, so no variant carries a `dark:` class.
+const h2 = cva('font-primary text-title leading-title tracking-optical', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+interface IH2Props extends VariantProps<typeof h2> {
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The section heading, an `h2` at the title type role.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders an `h2`; its outline level and the title role are one choice, not two (docs/adr/0005).
+ * - Reads `--font-primary`, sized by `--text-title`, led by `--leading-title` and optically corrected
+ *   by `--tracking-optical` — the title role is the smallest role that carries it, so `H3` and below
+ *   take none.
+ * - `color` selects the `foreground` or `muted` role; nothing else paints text.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Heading levels descend without skipping — an `h2` sits under an `h1`, not under an `h3`.
+ */
+export const H2: FunctionComponent<IH2Props> = ({
+  children,
+  color,
+  testId,
+}) => (
+  <h2 className={h2({ color })} data-testid={testId}>
+    {children}
+  </h2>
+);