@juwel-development/design-system 1.1.0 → 2.1.0

package/src/Interaction/TextArea/TextArea.tsx

@@ -0,0 +1,110 @@
+import { cva } from 'class-variance-authority';
+import { type FunctionComponent, useEffect, useId, useRef } from 'react';
+import type { Subject } from 'rxjs';
+
+// One recipe, deliberately not shared with Input (issue #5): each control owns its whole recipe so
+// one-recipe-per-component holds without a base module. Colours are semantic tokens re-pointed by
+// `.dark`, so no `dark:` class is needed. 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). Height is the
+// recipe's, not a `rows` prop.
+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',
+);
+
+interface ITextAreaProps {
+  /** Always rendered and associated with the control; never replaced by the placeholder. */
+  label: string;
+  /** How the surrounding form reads the value on submit. */
+  name: string;
+  required?: boolean;
+  invalid?: boolean;
+  disabled?: boolean;
+  defaultValue?: string;
+  placeholder?: string;
+  autocomplete?: 'name' | 'email' | 'url' | 'organization' | 'tel' | 'off';
+  hint?: string;
+  errorMessage?: string;
+  onInput$?: Subject<string>;
+  /** Emit to empty the control in place, keeping the same node so focus and IME composition survive. */
+  reset$?: Subject<void>;
+  testId?: string;
+}
+
+/**
+ * A labelled multi-line text control. Its value is uncontrolled - the form reads it by `name` on
+ * submit - so it works with JavaScript disabled. Ids are minted internally, so the prop surface
+ * stays closed and the label/hint/error associations survive with no hydration.
+ */
+export const TextArea: FunctionComponent<ITextAreaProps> = ({
+  label,
+  name,
+  required,
+  invalid,
+  disabled,
+  defaultValue,
+  placeholder,
+  autocomplete,
+  hint,
+  errorMessage,
+  onInput$,
+  reset$,
+  testId,
+}) => {
+  const id = useId();
+  const controlId = `${id}-control`;
+  const hintId = `${id}-hint`;
+  const errorId = `${id}-error`;
+  const describedBy =
+    [hint ? hintId : undefined, invalid ? errorId : undefined]
+      .filter(Boolean)
+      .join(' ') || undefined;
+
+  // reset$ is an inbound command, so the component subscribes here (coding.md#asynchrony), unlike
+  // onInput$ which it emits on. Emptying the live node keeps focus and any in-flight IME composition,
+  // which a `key` remount would discard (issue #64).
+  const controlRef = useRef<HTMLTextAreaElement>(null);
+  useEffect(() => {
+    const subscription = reset$?.subscribe(() => {
+      if (controlRef.current) {
+        controlRef.current.value = '';
+      }
+    });
+    return () => subscription?.unsubscribe();
+  }, [reset$]);
+
+  return (
+    <div className={'flex flex-col gap-[var(--space-stack)]'}>
+      <label htmlFor={controlId} className={'font-medium text-foreground'}>
+        {label}
+      </label>
+      <textarea
+        ref={controlRef}
+        id={controlId}
+        name={name}
+        className={textArea()}
+        required={required}
+        disabled={disabled}
+        defaultValue={defaultValue}
+        placeholder={placeholder}
+        autoComplete={autocomplete}
+        aria-invalid={invalid || undefined}
+        aria-describedby={describedBy}
+        data-testid={testId}
+        onInput={(event) => onInput$?.next(event.currentTarget.value)}
+      />
+      {!required && <span className={'text-muted text-sm'}>optional</span>}
+      {hint && (
+        <p id={hintId} className={'text-muted text-sm'}>
+          {hint}
+        </p>
+      )}
+      {invalid && (
+        <p id={errorId} className={'text-error text-sm'}>
+          {errorMessage}
+        </p>
+      )}
+    </div>
+  );
+};

package/src/Layout/Footer/Footer.tsx

@@ -0,0 +1,60 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe on the <footer>. The type is set here, not borrowed from Header's label role: this slot is
+// opaque and legitimately holds a sentence, and --tracking-label across one is damage, not a device (ADR
+// 0004). `edge` is a variant, not a conditional: a footer is always last, exactly once, so there is no
+// "first footer" for a data-section-style selector to suppress, and its predecessor is unpredictable - a
+// conditional would silently drop the hairline. It draws in `rule`, the page's single hairline weight
+// Section joins and Header's bottom edge share. Colours are semantic tokens re-pointed by `.dark`.
+const footer = cva(
+  'font-secondary text-small text-muted py-[var(--space-region)] px-[var(--gutter)]',
+  {
+    variants: {
+      edge: {
+        none: '',
+        rule: 'border-t border-solid border-rule',
+      },
+    },
+    defaultVariants: { edge: 'rule' },
+  },
+);
+
+export interface IFooterProps extends VariantProps<typeof footer> {
+  children?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The shell's bottom edge: a `<footer>` that owns the `contentinfo` landmark, the small type, the shell's
+ * vertical air and the gutter, and its own top rule - and nothing about what is inside it. It is a frame,
+ * not an arrangement: `children` are placed directly in the footer with no wrapper and no `<nav>`.
+ *
+ * @Guarantees — enforced on every render
+ * - The footer is set at the `small` role and carries no size of its own.
+ * - Children are placed unmodified, directly inside the `<footer>`, with no wrapping element.
+ * - The top edge is the caller's choice - `edge="rule"` (the default) or `edge="none"` - and when drawn is
+ *   always the page's single hairline weight, in the `rule` colour Section's join uses.
+ * - It is never sticky or fixed and needs no JavaScript.
+ *
+ * @CallerMustEnsure
+ * - The footer is a direct child of the page, not nested inside `main`, `article`, `aside`, `nav` or a
+ *   `Section`. Nesting silently demotes it out of the `contentinfo` landmark, and the component cannot
+ *   detect this.
+ *
+ * @UXGuidelines
+ * - Supply your own `<nav aria-label="…">` inside the slot if the footer navigates - a footer's contents
+ *   are frequently not navigation, so this component declares no nav landmark over them. Where the footer
+ *   does navigate, name `Header`'s nav with `navName` too: two unnamed navigation landmarks are
+ *   indistinguishable to a screen-reader user.
+ */
+export const Footer: FunctionComponent<IFooterProps> = ({
+  edge,
+  children,
+  testId,
+}) => (
+  <footer className={footer({ edge })} data-testid={testId}>
+    {children}
+  </footer>
+);

package/src/Layout/Form/Form.tsx

@@ -0,0 +1,102 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+/** Which of the four states the page has put the form in. Owned by the page, never by Form: the
+ *  component renders the state it is given and never decides which one it is in. */
+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', {
+  variants: {
+    state: {
+      idle: 'text-muted',
+      sending: 'text-muted',
+      sent: 'text-success',
+      failed: 'text-error',
+    },
+  },
+  defaultVariants: { state: 'idle' },
+});
+
+// The note's ARIA role: a settled outcome is a status region, a failure an alert; while the form
+// still stands the note is plain prose and carries none.
+const NOTE_ROLE: Partial<Record<FormState, 'status' | 'alert'>> = {
+  sent: 'status',
+  failed: 'alert',
+};
+
+interface IFormProps {
+  /** Where the submission goes. Passed straight to the form element; Form makes no decision about it. */
+  action: string;
+  method?: 'get' | 'post';
+  state?: FormState;
+  /** The fields. */
+  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;
+  testId?: string;
+}
+
+/**
+ * The container around a set of fields: fields, an actions row, a note. It renders a real `<form>`
+ * carrying `action` and `method`, so a native submission works with no JavaScript, and it renders
+ * the `state` it is given without ever owning a submission, a transport or validation timing - both
+ * a server-rendered driver and a hydrated island express every state through the same props.
+ *
+ * `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.
+ */
+export const Form: FunctionComponent<IFormProps> = ({
+  action,
+  method = 'post',
+  state = 'idle',
+  children,
+  actions,
+  note,
+  testId,
+}) => {
+  if (state === 'sent' && !note) {
+    throw new Error(
+      'Form in the `sent` state must be given a `note` - it is the outcome message.',
+    );
+  }
+
+  const showFields = state !== 'sent';
+  const noteRole = NOTE_ROLE[state];
+
+  return (
+    <form
+      action={action}
+      method={method}
+      aria-busy={state === 'sending' || undefined}
+      data-testid={testId}
+      className={
+        'flex max-w-[var(--measure)] flex-col gap-[var(--space-region)]'
+      }
+    >
+      {showFields && (
+        <div className={'flex flex-col gap-[var(--space-stack)]'}>
+          {children}
+        </div>
+      )}
+      {showFields && actions && (
+        <div className={'flex flex-row gap-[var(--space-stack)]'}>
+          {actions}
+        </div>
+      )}
+      {note && (
+        <p role={noteRole} className={form({ state })}>
+          {note}
+        </p>
+      )}
+    </form>
+  );
+};

package/src/Layout/Header/Header.tsx

@@ -0,0 +1,84 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe on the <header>. It sets the label type role - the "small grotesk, letter-spaced, muted"
+// the issue described, whose "never grows past 1rem" was a role wearing a number, so no size literal
+// appears here (#14). The shell's air is one value in every direction: --space-region above, below and
+// (on the nav) between, --gutter across, so the bar aligns with every inset Section. The current-page
+// treatment keys on the attribute, not on a component: [&_[aria-current=page]] compiles to specificity
+// 0,2,0 and beats Link's quiet text-muted (0,1,0) with no !important and no import, so the current item
+// sits at foreground - the colour every other item reaches only on hover. `edge` draws the bottom
+// hairline in `rule`, the one weight a page's boundaries share with a Section join, and defaults to
+// `rule` - the conventional header - so a ruleless shell opts out. Colours are semantic tokens re-pointed
+// by `.dark`, so no `dark:` class.
+const header = cva(
+  [
+    'flex items-baseline justify-between',
+    'font-secondary text-label tracking-label text-muted',
+    'py-[var(--space-region)] px-[var(--gutter)]',
+    '[&_[aria-current=page]]:text-foreground',
+  ].join(' '),
+  {
+    variants: {
+      edge: {
+        none: '',
+        rule: 'border-b border-solid border-rule',
+      },
+    },
+    defaultVariants: { edge: 'rule' },
+  },
+);
+
+export interface IHeaderProps extends VariantProps<typeof header> {
+  /** The standing link: a place name, a mark, or a home link. The consumer supplies the whole anchor -
+   *  Header renders no link of its own. A place name uses `<Link treatment="quiet" href="/">…</Link>`; a
+   *  mark uses `<Link treatment="graphic" href="/"><Brandmark …/></Link>`, whose `graphic` treatment
+   *  paints nothing over a `currentColor` mark. */
+  standing?: ReactNode;
+  /** Names the nav for assistive technology. Omit unless the page has more than one nav. */
+  navName?: string;
+  /** The nav links. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The shell's top edge: a standing link and a nav, at the label type role. It renders the banner
+ * landmark and a single `<nav>`, arranging nothing beyond the two slots, so it works with no hydration.
+ *
+ * @Guarantees — enforced on every render
+ * - The header is set at the label role and carries no size of its own: `font-secondary text-label
+ *   tracking-label text-muted`, so it never grows past that role whatever the page font size.
+ * - A nav item marked `aria-current="page"` renders at `foreground` whatever supplied it - the treatment
+ *   keys on the attribute, not on `Link`, so it holds against a bare anchor or any component.
+ * - The shell's air is one value above, below and between: `--space-region` vertically and between nav
+ *   items, `--gutter` across, so the bar aligns with every inset `Section`.
+ * - It is never sticky and needs no JavaScript: there is no `sticky` variant and nothing to hydrate.
+ * - Omitting `navName` emits no `aria-label` at all, not an empty one.
+ *
+ * @UXGuidelines
+ * - Name the nav with `navName` once the page has more than one navigation landmark - a footer nav will
+ *   be the second, and two unnamed navs are indistinguishable to a screen-reader user.
+ * - Nav links use `Link`'s `quiet` treatment. The current-page treatment is applied here from
+ *   `aria-current`, so set `current` on the `Link` and style nothing yourself.
+ * - The nav does not collapse into a menu: a disclosure needs JavaScript, so on a narrow viewport the
+ *   items wrap. A mobile menu is out of scope, not a follow-up.
+ */
+export const Header: FunctionComponent<IHeaderProps> = ({
+  edge,
+  standing,
+  navName,
+  children,
+  testId,
+}) => (
+  <header className={header({ edge })} data-testid={testId}>
+    <div>{standing}</div>
+    <nav
+      aria-label={navName}
+      className={'flex flex-wrap items-baseline gap-[var(--space-region)]'}
+    >
+      {children}
+    </nav>
+  </header>
+);

package/src/Layout/Hero/Hero.tsx

@@ -0,0 +1,73 @@
+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>. It holds the fold - a minimum height taller than its content, so leftover
+// space is guaranteed and how the slot sits in it is a decision, not a default (#17). With no className
+// escape hatch, whatever place picks is final, so it is a variant: center is the conventional hero and the
+// default; between drops a poster's foot on the fold's bottom edge; start asks for the minimum height
+// without the centring. `end` is deliberately absent - content pinned to the bottom over empty space is
+// not a hero. It reads --fold-height for the floor and --space-stack for the gap Prose and PageHead use.
+const hero = cva(
+  'flex flex-col min-h-[var(--fold-height)] gap-[var(--space-stack)]',
+  {
+    variants: {
+      place: {
+        start: 'justify-start',
+        center: 'justify-center',
+        between: 'justify-between',
+      },
+    },
+    defaultVariants: { place: 'center' },
+  },
+);
+
+export interface IHeroProps extends VariantProps<typeof hero> {
+  /** The fold's one opaque slot. Rendered unmodified: a poster composes a mark, an `H1` lead and a foot
+   *  here; another brand composes something else. `Hero` imposes no anatomy. */
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The first screen's frame: a plain container that holds at least the fold height and places one opaque
+ * slot within it. It renders no heading and no landmark - a hero's lead is an `<H1>` the consumer places
+ * in the slot, and the `Section` around it owns the region, the bleed, the band and the gutter. A hero
+ * varies in its structure where a footer varies only in its contents, so there is no shared anatomy to
+ * model and the opaque slot is the honest answer.
+ *
+ * @Guarantees — enforced on every render
+ * - It is at least `--fold-height` tall and never taller by construction: a `min-height` floor, not a
+ *   fixed height, so content longer than the fold grows the frame rather than overflowing it.
+ * - `children` render unmodified; the component adds nothing to and strips nothing from them, and sets no
+ *   margin, max-width, colour or heading of its own.
+ * - It owns no bleed, band or gutter and emits no `<section>` and no landmark role - the enclosing
+ *   `Section` carries those.
+ * - `place` positions the slot in the leftover space: `center` (the default), `start` or `between`; the
+ *   parts are gapped with `--space-stack`.
+ * - It is never sticky or fixed and needs no JavaScript, so it renders identically server-side.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - The hero sits inside a `Section` - `<Section bleed="full"><Hero>…</Hero></Section>` - which owns the
+ *   bleed, the band, the gutter and the region. `Hero` imports no component and adds none of these.
+ *
+ * @UXGuidelines
+ * - Cap the lead at `--measure-display`, not at a caption's width, and apply it to your own lead - not
+ *   here, since capping the slot would cap the mark too. Measured on the lockup that prompted this: at
+ *   24ch a one-sentence lead set five lines and became a second block competing with the mark; at 36ch it
+ *   sets three and reads as the mark's caption. This is the one place where copy length is a layout
+ *   parameter - a hero whose lead sentence can vary in length needs its measure chosen against the real
+ *   sentence, not a rule of thumb.
+ * - A hero built on a wide lockup is a desktop bet by construction. A 15-character lockup can only be as
+ *   wide as the phone, so at 390px the scale contrast between mark and lead is capped by the viewport
+ *   rather than chosen - roughly 2:1, against roughly 6:1 at 1440.
+ */
+export const Hero: FunctionComponent<IHeroProps> = ({
+  place,
+  children,
+  testId,
+}) => (
+  <div className={hero({ place })} data-testid={testId}>
+    {children}
+  </div>
+);

package/src/Layout/PageHead/PageHead.tsx

@@ -0,0 +1,79 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe on the <header>, one on each element it paints. The head is full-bleed: it carries the
+// band and the gutter every page unit shares but takes no max-width and joins no grid, so it opts out
+// of the index column a default Section sits in (#9) by spanning the full content width - the text, not
+// the head, owns every measure. The title is the title role, one rung below the hero's display: the cap
+// on out-scaling the homepage hero is the display > title token relationship renderTokens pins (ADR
+// 0004/0005), never a local clamp, so tracking-optical is the head's only optical touch and no size
+// literal appears. That tracking is the title role's, not this component's (#57): H2 binds to the same
+// role and carries the same correction, so the role reads one way wherever it is rendered. The stack gap is --space-stack, the sibling gap Prose uses. Colours are semantic
+// tokens re-pointed by `.dark`, so no `dark:` class.
+const pageHead = cva(
+  'flex flex-col gap-[var(--space-stack)] py-[var(--space-band)] px-[var(--gutter)]',
+);
+
+// The scale event: the title role, led and tracked as a large heading, foreground. No measure - the
+// head is full-bleed and the consumer keeps titles short.
+const pageHeadTitle = cva(
+  'font-primary text-title leading-title tracking-optical text-foreground',
+);
+
+// The standfirst: the lede role, foreground, run one measure wider than the reading column (#18).
+const pageHeadLede = cva(
+  'font-primary text-lede leading-lede text-foreground max-w-[var(--measure-wide)]',
+);
+
+// The small print: the small role, muted, held to the reading measure like Prose's tail.
+const pageHeadIntro = cva(
+  'font-primary text-small text-muted max-w-[var(--measure)]',
+);
+
+export interface IPageHeadProps {
+  /** The page title - the head's one scale event, rendered as the page's `h1` at the title role. */
+  title: ReactNode;
+  /** The standfirst under the title: a lede-role paragraph at a measure slightly wider than the
+   *  reading column. Omit for a bare title. */
+  lede?: ReactNode;
+  /** The muted small-print paragraph under the lede, held to the reading measure. Omit where the head
+   *  is title and lede only. */
+  intro?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * A subpage's opening: one scale event, then small print. It renders a `<header>` carrying the page's
+ * `h1`, an optional lede standfirst and an optional muted intro, full-bleed over the vertical band and
+ * the gutter. It arranges the three slots and owns their type roles; the consumer supplies the copy.
+ *
+ * @Guarantees — enforced on every render
+ * - The title is an `h1` at the `title` role - one rung below the hero's `display` - so it can never
+ *   out-scale the homepage hero: the cap is the `display > title` token relationship (ADR 0004/0005),
+ *   not two `clamp()`s ordered by luck, and no size literal is set here.
+ * - The head is full-bleed: it carries `--space-band` and `--gutter` but takes no `max-width` and joins
+ *   no grid, so it opts out of the index column and spans the full content width.
+ * - The lede is the `lede` role at `--measure-wide`, one measure wider than the reading column; the
+ *   intro is the `small` role, muted, at `--measure`. Each measure is on the text, never on the head.
+ * - Omitting `lede` or `intro` renders that paragraph not at all.
+ * - It is never sticky or fixed and needs no JavaScript.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - The head sits inside the page's main content (a `main`, `article` or `section`), not as a top-level
+ *   child of `body`, so its `<header>` is the page head and not a second `banner` beside the shell's
+ *   `Header` (#14).
+ * - This head opens a subpage. The homepage hero is `PosterFold` (#17), which renders at the `display`
+ *   role; reach for that where the page is the poster, not for this.
+ */
+export const PageHead: FunctionComponent<IPageHeadProps> = ({
+  title,
+  lede,
+  intro,
+  testId,
+}) => (
+  <header className={pageHead()} data-testid={testId}>
+    <h1 className={pageHeadTitle()}>{title}</h1>
+    {lede !== undefined && <p className={pageHeadLede()}>{lede}</p>}
+    {intro !== undefined && <p className={pageHeadIntro()}>{intro}</p>}
+  </header>
+);

package/src/Layout/Section/Section.tsx

@@ -0,0 +1,79 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe on the <section>. The join is the load-bearing part: a top rule is drawn only when the
+// immediately preceding sibling also carries data-section, so it appears between two sections and never
+// above the first - and never beneath a header, whose own rule is a direction-level choice (#14), not a
+// default here. The [[data-section]+&] selector says exactly "every section after the first", which
+// :not(:first-child) does not - that would rule beneath anything at all. It reads `rule`, not `border`:
+// a section join carries the whole load a gap would, and at page scale a 1.23:1 line may not read as a
+// separation. The rule spans the full element width in both bleed variants, since a border sits outside
+// padding - the join is the page's structure, so it does not inset with the content. `bleed` is the only
+// axis: inset holds content off the viewport edge by the gutter, full runs edge to edge for a hero or
+// page head; both keep the vertical band. No margin and no max-width anywhere - sections abut, the band
+// is air inside the unit, and Prose owns the reading measure. Colours are semantic tokens re-pointed by
+// `.dark`, so no `dark:` class.
+const section = cva(
+  [
+    'py-[var(--space-band)]',
+    '[[data-section]+&]:border-t [[data-section]+&]:border-solid [[data-section]+&]:border-rule',
+  ].join(' '),
+  {
+    variants: {
+      bleed: {
+        inset: 'px-[var(--gutter)]',
+        full: '',
+      },
+    },
+    defaultVariants: { bleed: 'inset' },
+  },
+);
+
+export interface ISectionProps extends VariantProps<typeof section> {
+  /** Names the section as a region a screen-reader user can jump to. Omit for an ordinary section: an
+   *  unnamed section is inert to assistive technology, which is the right default. Two or three named
+   *  regions on a page is navigation; six is landmark noise, which is why this is opt-in. */
+  name?: string;
+  children?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The page's structural unit: a band carrying its own vertical air and, unless it bleeds, the gutter.
+ * It arranges nothing inside itself - what it owns is the join to the section before it, which is why
+ * it is a composable of the page rather than a container of its contents.
+ *
+ * @Guarantees — enforced on every render
+ * - Sections abut and never gap: the component sets no margin, and the join is the separation. A rule
+ *   appears only between two sections - drawn when the preceding sibling also carries data-section, so
+ *   never above the first section nor beneath a header before it.
+ * - A `bleed="full"` section drops the gutter and runs edge to edge; the vertical band is kept on both
+ *   bleed variants, and the join spans the full width of either.
+ * - An unnamed section is not a landmark: it emits no `aria-label` and is inert to assistive technology.
+ *
+ * @CallerMustEnsure
+ * - Where `name` is given it matches the section's visible heading. The component labels the region with
+ *   that string because it cannot reach the heading's id to reference it with `aria-labelledby` instead.
+ *
+ * @UXGuidelines
+ * - On a page with no borrowed proof - no logos, no testimonials, no credits - a gap between blocks reads
+ *   as missing content, while air inside the type reads as care. So the levers on a page's rhythm are the
+ *   measure, the leading and the band, never a space between sections. This is why Section offers no gap
+ *   and no margin.
+ */
+export const Section: FunctionComponent<ISectionProps> = ({
+  bleed,
+  name,
+  children,
+  testId,
+}) => (
+  <section
+    data-section={''}
+    className={section({ bleed })}
+    aria-label={name}
+    data-testid={testId}
+  >
+    {children}
+  </section>
+);