@juwel-development/design-system 1.0.0 → 2.0.0

package/src/Display/Typography/H3/H3.tsx

@@ -0,0 +1,41 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Level fixes role: an h3 is always the subtitle 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. Colour is a semantic token re-pointed by `.dark`, so no variant carries a `dark:`
+// class.
+const h3 = cva('font-primary text-subtitle leading-subtitle', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+interface IH3Props extends VariantProps<typeof h3> {
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The subsection heading, an `h3` at the subtitle type role. The last of the three sized steps;
+ * levels below it share the body size and separate by weight.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders an `h3`; its outline level and the subtitle role are one choice, not two (docs/adr/0005).
+ * - Reads `--font-primary`, sized by `--text-subtitle` and led by `--leading-subtitle`.
+ * - `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 `h3` sits under an `h2`, not under an `h1`.
+ */
+export const H3: FunctionComponent<IH3Props> = ({
+  children,
+  color,
+  testId,
+}) => (
+  <h3 className={h3({ color })} data-testid={testId}>
+    {children}
+  </h3>
+);

package/src/Display/Typography/H4/H4.tsx

@@ -0,0 +1,40 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Level fixes role: an h4 shares the body size with h5, h6 and p, told apart by weight alone
+// (docs/adr/0005). The `font-bold` is load-bearing - Tailwind's preflight resets h1-h6 to
+// font-weight: inherit, so without it an h4 renders identically to a paragraph. Colour is a semantic
+// token re-pointed by `.dark`, so no variant carries a `dark:` class.
+const h4 = cva('font-primary text-body leading-body font-bold', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+interface IH4Props extends VariantProps<typeof h4> {
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The first of the weight-separated headings, an `h4` at the body size, rendered bold.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders an `h4`; its outline level and the body role are one choice, not two (docs/adr/0005).
+ * - Reads `--font-primary`, sized by `--text-body`, and is bold so it stands apart from a paragraph.
+ * - `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 `h4` sits under an `h3`, not under an `h2`.
+ */
+export const H4: FunctionComponent<IH4Props> = ({
+  children,
+  color,
+  testId,
+}) => (
+  <h4 className={h4({ color })} data-testid={testId}>
+    {children}
+  </h4>
+);

package/src/Display/Typography/H5/H5.tsx

@@ -0,0 +1,41 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Level fixes role: an h5 shares the body size with h4, h6 and p, told apart by weight alone
+// (docs/adr/0005). The `font-semibold` is load-bearing - Tailwind's preflight resets h1-h6 to
+// font-weight: inherit, so without it an h5 renders identically to a paragraph. Colour is a semantic
+// token re-pointed by `.dark`, so no variant carries a `dark:` class.
+const h5 = cva('font-primary text-body leading-body font-semibold', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+interface IH5Props extends VariantProps<typeof h5> {
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * A weight-separated heading, an `h5` at the body size, rendered semibold — one step lighter than
+ * `h4`.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders an `h5`; its outline level and the body role are one choice, not two (docs/adr/0005).
+ * - Reads `--font-primary`, sized by `--text-body`, semibold so it stands apart from a paragraph.
+ * - `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 `h5` sits under an `h4`, not under an `h3`.
+ */
+export const H5: FunctionComponent<IH5Props> = ({
+  children,
+  color,
+  testId,
+}) => (
+  <h5 className={h5({ color })} data-testid={testId}>
+    {children}
+  </h5>
+);

package/src/Display/Typography/H6/H6.tsx

@@ -0,0 +1,41 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// Level fixes role: an h6 shares the body size with h4, h5 and p, told apart by weight alone
+// (docs/adr/0005). The `font-medium` is load-bearing - Tailwind's preflight resets h1-h6 to
+// font-weight: inherit, so without it an h6 renders identically to a paragraph. Colour is a semantic
+// token re-pointed by `.dark`, so no variant carries a `dark:` class.
+const h6 = cva('font-primary text-body leading-body font-medium', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+interface IH6Props extends VariantProps<typeof h6> {
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * The lightest heading, an `h6` at the body size, rendered medium — the deepest level the ladder
+ * offers, because the weight lever runs out here.
+ *
+ * @Guarantees — enforced on every render
+ * - Renders an `h6`; its outline level and the body role are one choice, not two (docs/adr/0005).
+ * - Reads `--font-primary`, sized by `--text-body`, medium so it stands apart from a paragraph.
+ * - `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 `h6` sits under an `h5`, not under an `h4`.
+ */
+export const H6: FunctionComponent<IH6Props> = ({
+  children,
+  color,
+  testId,
+}) => (
+  <h6 className={h6({ color })} data-testid={testId}>
+    {children}
+  </h6>
+);

package/src/Display/Typography/P/P.tsx

@@ -0,0 +1,38 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// The body role, shared with h4-h6 which add a weight to stand apart from it (docs/adr/0005). Weight
+// inherits. Colour is a semantic token re-pointed by `.dark`, so no variant carries a `dark:` class.
+// P owns no reading measure - that belongs to whatever owns the reading column (Prose #21).
+const p = cva('font-primary text-body leading-body', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+interface IPProps extends VariantProps<typeof p> {
+  children: ReactNode;
+  testId?: string;
+}
+
+/**
+ * A paragraph of body copy, a `p` at the body type role. Unbounded — usable in a form, a card or a
+ * table cell — because the reading measure belongs to whatever owns the reading column (Prose #21).
+ *
+ * @Guarantees — enforced on every render
+ * - Renders a `p`, reading `--font-primary`, sized by `--text-body` and led by `--leading-body`.
+ * - `color` selects the `foreground` or `muted` role; nothing else paints text.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Where line length matters, place the paragraph inside whatever bounds the reading measure; `P`
+ *   does not constrain its own width.
+ * - For a paragraph inside a reading column, reach for `Prose.Body`, which is measure-bounded by its
+ *   `Prose.Root`; `P` is for a paragraph with no reading column around it.
+ */
+export const P: FunctionComponent<IPProps> = ({ children, color, testId }) => (
+  <p className={p({ color })} data-testid={testId}>
+    {children}
+  </p>
+);

package/src/Display/Typography/Prose/Prose.tsx

@@ -0,0 +1,91 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// The reading column. It caps every child at --measure and sets no font-size, so the ch measure
+// keeps resolving against inherited body type - the same rule Form follows when it takes the measure.
+// The sibling gap is the type-scale --space-stack, never a one-idea-per-screen gap: the air the block
+// wants is at its edges (the 66ch measure) and inside the type, not between the blocks. It sets no
+// margin, so the page - not the component - owns the vertical rhythm around the column.
+const proseRoot = cva(
+  'flex max-w-[var(--measure)] flex-col gap-[var(--space-stack)]',
+);
+
+// The opening paragraph, at the new lede role: larger than body and led tighter (docs/adr/0004), but
+// still running-text leading, not a heading's. Colour is the foreground token, re-pointed by `.dark`.
+const proseLede = cva('font-primary text-lede leading-lede text-foreground');
+
+// The body role inside the column - the same utilities P emits, restated because the no-cross-import
+// rule forbids reusing P's recipe. A test pins the two equal so they cannot drift. Colour is a
+// semantic token re-pointed by `.dark`, so no variant carries a `dark:` class.
+const proseBody = cva('font-primary text-body leading-body', {
+  variants: {
+    color: { foreground: 'text-foreground', muted: 'text-muted' },
+  },
+  defaultVariants: { color: 'foreground' },
+});
+
+// The stepped-down closing note: the small role, always muted. small carries the enforced 15px floor.
+const proseTail = cva('font-primary text-small text-muted');
+
+interface IProseRootProps {
+  children?: ReactNode;
+  testId?: string;
+}
+
+interface IProseLedeProps {
+  children?: ReactNode;
+}
+
+interface IProseBodyProps extends VariantProps<typeof proseBody> {
+  children?: ReactNode;
+}
+
+interface IProseTailProps {
+  children?: ReactNode;
+}
+
+const ProseRoot: FunctionComponent<IProseRootProps> = ({
+  children,
+  testId,
+}) => (
+  <div className={proseRoot()} data-testid={testId}>
+    {children}
+  </div>
+);
+
+const ProseLede: FunctionComponent<IProseLedeProps> = ({ children }) => (
+  <p className={proseLede()}>{children}</p>
+);
+
+const ProseBody: FunctionComponent<IProseBodyProps> = ({ color, children }) => (
+  <p className={proseBody({ color })}>{children}</p>
+);
+
+const ProseTail: FunctionComponent<IProseTailProps> = ({ children }) => (
+  <p className={proseTail()}>{children}</p>
+);
+
+/**
+ * A measure-bounded reading block: a lede, body paragraphs and an optional stepped-down muted tail,
+ * all capped at the reading measure - including inside a wider grid cell, which follows from `Root`
+ * bounding the column. Composed from the four members; the consumer supplies the copy.
+ *
+ * @Guarantees — enforced on every render
+ * - `Root` renders a `div` (never a `section`: it owns no landmark and no heading), capped at
+ *   `--measure`, setting no font-size so the `ch` measure resolves against inherited body type.
+ * - `Root` stacks its children on `--space-stack` and takes no outer margin: the page owns the
+ *   rhythm around the block, and the air the block wants is at its edges and inside the type.
+ * - `Lede` renders a `p` at the lede role; `Body` at the body role with a `foreground`/`muted`
+ *   `color`; `Tail` at the small role, muted. No drop cap or other invented device.
+ *
+ * @CallerMustEnsure — the component cannot see these and does not check them
+ * - Use `Prose.Body` for a paragraph inside this reading column; for a paragraph with no reading
+ *   column around it - in a form, a card, a table cell - use `P` instead.
+ */
+export const Prose = {
+  Root: ProseRoot,
+  Lede: ProseLede,
+  Body: ProseBody,
+  Tail: ProseTail,
+} as const;

package/src/Interaction/Button/Button.tsx

@@ -1,21 +1,26 @@
 import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
-import type { FunctionComponent, PropsWithChildren } from 'react';
+import type { FunctionComponent, ReactNode } from 'react';
 import type { Subject } from 'rxjs';
 
 // No `dark:` classes here by design: every colour below is a semantic token whose value is
 // re-pointed by the `.dark` class in tokens.css, so one set of classes serves both themes.
+// The colour transition is stated once in the base, on the motion token, so no variant can
+// disagree with it - see docs/adr/0001-motion-token-contract.md. The one focus ring is in the
+// 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.
 const button = cva(
-  '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 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-surface',
+  '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: {
         primary:
-          'px-4 sm:px-6 min-w-42 bg-primary text-primary-foreground rounded-lg transition-all duration-200 hover:bg-primary-hover focus-visible:ring-primary-ring',
+          'px-4 sm:px-6 min-w-42 bg-primary text-primary-foreground hover:bg-primary-hover',
         secondary:
-          'px-4 sm:px-6 min-w-42 bg-secondary text-secondary-foreground rounded-lg transition-all duration-200 hover:bg-secondary-hover focus-visible:ring-secondary-ring',
+          'px-4 sm:px-6 min-w-42 bg-secondary text-secondary-foreground hover:bg-secondary-hover',
         ghost:
-          'px-2 min-w-0 bg-transparent text-foreground hover:underline transition-all duration-200 focus-visible:ring-ring',
+          'px-2 min-w-0 bg-transparent text-foreground hover:underline hover:decoration-[length:var(--underline-thickness)] hover:underline-offset-[var(--underline-offset)]',
       },
     },
     defaultVariants: {
@@ -24,9 +29,9 @@ const button = cva(
   },
 );
 
-export interface IButtonProps
-  extends VariantProps<typeof button>,
-    PropsWithChildren {
+interface IButtonProps extends VariantProps<typeof button> {
+  /** Optional: an icon-only button renders none, and names itself with `ariaLabel` instead. */
+  children?: ReactNode;
   onClick$?: Subject<void>;
   disabled?: boolean;
   testId?: string;
@@ -51,13 +56,15 @@ export interface IButtonProps
  * - Provide visual feedback on hover/active states
  * - Ensure sufficient touch target size (minimum 44x44px) for mobile users
  * - Position primary actions on the right for multi-button layouts
+ * - A submit button's busy state is a label swap ("Send" to "Sending…"), never a spinner: it costs
+ *   nothing to render server-side and keeps a Form's `sending` state driver-agnostic
  *
  * @Accessibility
  * - Ensure adequate color contrast (4.5:1 minimum ratio)
  * - Provide focus styles for keyboard navigation
  * - Use appropriate ARIA attributes when needed
  */
-export const Button: FunctionComponent<PropsWithChildren<IButtonProps>> = ({
+export const Button: FunctionComponent<IButtonProps> = ({
   children,
   disabled,
   testId,

package/src/Interaction/Input/Input.tsx

@@ -0,0 +1,103 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import { type FunctionComponent, useId } from 'react';
+import type { Subject } from 'rxjs';
+
+// One recipe, deliberately not shared with TextArea (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 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).
+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',
+  {
+    variants: {
+      // text/email/url are visually identical; the axis only selects the control's `type`
+      // attribute (issue #5), so each option carries no class of its own.
+      variant: { text: '', email: '', url: '' },
+    },
+    defaultVariants: { variant: 'text' },
+  },
+);
+
+interface IInputProps extends VariantProps<typeof input> {
+  /** 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>;
+  testId?: string;
+}
+
+/**
+ * A labelled single-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 Input: FunctionComponent<IInputProps> = ({
+  label,
+  name,
+  variant,
+  required,
+  invalid,
+  disabled,
+  defaultValue,
+  placeholder,
+  autocomplete,
+  hint,
+  errorMessage,
+  onInput$,
+  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;
+
+  return (
+    <div className={'flex flex-col gap-[var(--space-stack)]'}>
+      <label htmlFor={controlId} className={'font-medium text-foreground'}>
+        {label}
+      </label>
+      <input
+        id={controlId}
+        name={name}
+        type={variant ?? 'text'}
+        className={input({ variant })}
+        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/Interaction/Link/Link.tsx

@@ -0,0 +1,70 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// One recipe, four treatments that behave differently, not one link with a colour prop (see
+// docs/adr/0006). The focus ring is in the base - a link is focusable - drawn with outline, colour at
+// rest so it never fades in (docs/adr/0002); no radius, a link has no box (docs/adr/0003). Colours are
+// 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.
+const link = cva(
+  'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  {
+    variants: {
+      treatment: {
+        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',
+        'label-link':
+          'text-inherit no-underline decoration-[length:var(--underline-thickness)] underline-offset-[var(--underline-offset)] hover:underline',
+        graphic: 'text-inherit no-underline',
+      },
+    },
+    defaultVariants: { treatment: 'prose' },
+  },
+);
+
+interface ILinkProps extends VariantProps<typeof link> {
+  /** Where the link points. Carried on the anchor, so the link navigates with JavaScript disabled. */
+  href: string;
+  /** The link text. */
+  children: ReactNode;
+  /** Opens in a new tab and severs the opener together - `target="_blank"` implies the `rel`, so
+   *  neither half is settable alone. */
+  external?: boolean;
+  /** Marks this link as the current page for assistive technology (`aria-current="page"`). Semantics
+   *  only: any visual current-page treatment belongs to the Header, not here. */
+  current?: boolean;
+  testId?: string;
+}
+
+/**
+ * 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.
+ */
+export const Link: FunctionComponent<ILinkProps> = ({
+  href,
+  children,
+  treatment,
+  external,
+  current,
+  testId,
+}) => {
+  return (
+    <a
+      href={href}
+      className={link({ treatment })}
+      target={external ? '_blank' : undefined}
+      rel={external ? 'noopener noreferrer' : undefined}
+      aria-current={current ? 'page' : undefined}
+      data-testid={testId}
+    >
+      {children}
+    </a>
+  );
+};

package/src/Interaction/TextArea/TextArea.tsx

@@ -0,0 +1,93 @@
+import { cva } from 'class-variance-authority';
+import { type FunctionComponent, useId } 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>;
+  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$,
+  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;
+
+  return (
+    <div className={'flex flex-col gap-[var(--space-stack)]'}>
+      <label htmlFor={controlId} className={'font-medium text-foreground'}>
+        {label}
+      </label>
+      <textarea
+        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>
+  );
+};