@juwel-development/design-system 1.1.0 → 2.0.0

package/dist/types/Interaction/Button/Button.d.ts

@@ -1,10 +1,12 @@
 import type { VariantProps } from 'class-variance-authority';
-import type { FunctionComponent, PropsWithChildren } from 'react';
+import type { FunctionComponent, ReactNode } from 'react';
 import type { Subject } from 'rxjs';
 declare const button: (props?: ({
     variant?: "primary" | "secondary" | "ghost" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-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;
@@ -28,11 +30,13 @@ export interface IButtonProps extends VariantProps<typeof button>, PropsWithChil
  * - 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 declare const Button: FunctionComponent<PropsWithChildren<IButtonProps>>;
+export declare const Button: FunctionComponent<IButtonProps>;
 export {};

package/dist/types/Interaction/Input/Input.d.ts

@@ -0,0 +1,29 @@
+import type { VariantProps } from 'class-variance-authority';
+import { type FunctionComponent } from 'react';
+import type { Subject } from 'rxjs';
+declare const input: (props?: ({
+    variant?: "text" | "email" | "url" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+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 declare const Input: FunctionComponent<IInputProps>;
+export {};

package/dist/types/Interaction/Link/Link.d.ts

@@ -0,0 +1,27 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+declare const link: (props?: ({
+    treatment?: "prose" | "quiet" | "label-link" | "graphic" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+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 declare const Link: FunctionComponent<ILinkProps>;
+export {};

package/dist/types/Interaction/TextArea/TextArea.d.ts

@@ -0,0 +1,25 @@
+import { type FunctionComponent } from 'react';
+import type { Subject } from 'rxjs';
+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 declare const TextArea: FunctionComponent<ITextAreaProps>;
+export {};

package/dist/types/Layout/Footer/Footer.d.ts

@@ -0,0 +1,34 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+declare const footer: (props?: ({
+    edge?: "none" | "rule" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+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 declare const Footer: FunctionComponent<IFooterProps>;
+export {};

package/dist/types/Layout/Form/Form.d.ts

@@ -0,0 +1,31 @@
+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';
+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 declare const Form: FunctionComponent<IFormProps>;
+export {};

package/dist/types/Layout/Header/Header.d.ts

@@ -0,0 +1,41 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+declare const header: (props?: ({
+    edge?: "none" | "rule" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+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 declare const Header: FunctionComponent<IHeaderProps>;
+export {};

package/dist/types/Layout/Hero/Hero.d.ts

@@ -0,0 +1,46 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+declare const hero: (props?: ({
+    place?: "center" | "start" | "between" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+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 declare const Hero: FunctionComponent<IHeroProps>;
+export {};

package/dist/types/Layout/PageHead/PageHead.d.ts

@@ -0,0 +1,36 @@
+import type { FunctionComponent, ReactNode } from 'react';
+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 declare const PageHead: FunctionComponent<IPageHeadProps>;

package/dist/types/Layout/Section/Section.d.ts

@@ -0,0 +1,38 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+declare const section: (props?: ({
+    bleed?: "full" | "inset" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+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 declare const Section: FunctionComponent<ISectionProps>;
+export {};

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

@@ -23,25 +23,44 @@ export type PaletteTokens = {
     muted: string;
     /** Hairlines and dividers. */
     border: string;
+    /** The boundary of a control with no fill of its own, so it is the only thing separating the
+     *  control from the surface. Constraint (WCAG 2.2 SC 1.4.11): at least 3:1 against `surface`
+     *  in the same theme. */
+    controlBorder: string;
+    /** The structural rule that marks where a block's structure is, weightier than `border`'s hairline
+     *  dividers and lighter than `controlBorder`'s control edge. It serves three consumers: a table's
+     *  heavier top line above the first row, a checklist's tick, and a page section's join to the
+     *  section before it. A mid-neutral, so it structures without boxing. Constraint: at least 3:1
+     *  against `surface` in the same theme. */
+    rule: string;
+    /** The plate behind content that has not painted - an image still loading, or one that failed and
+     *  is showing its alt text. Constraint: at least 4.5:1 against `foreground` in the same theme,
+     *  because a failed image renders its alt text on this plate and that text must stay legible. That
+     *  keeps it near `surface` rather than a mid grey. */
+    backing: string;
     /** The main call-to-action fill. */
     primary: string;
     primaryHover: string;
     /** Text and icons drawn on top of `primary`. */
     primaryForeground: string;
-    /** Focus ring for primary surfaces - lighter than the fill so it reads against it. */
-    primaryRing: string;
     /** The alternative action fill, for choices that sit beside a primary one. */
     secondary: string;
     secondaryHover: string;
     secondaryForeground: string;
-    secondaryRing: string;
-    /** Fill for controls that cannot be interacted with. */
+    /** The tone a control takes when it cannot be interacted with - its fill, or its border when
+     *  the fill is transparent. */
     disabled: string;
     /** Kept distinct from `disabled` so a disabled control still absorbs hover rather than
      *  appearing to respond to it. */
     disabledHover: string;
-    /** Focus ring for surfaces that have no fill of their own, such as a ghost button. */
-    ring: string;
+    /** The one focus ring, drawn by every focusable primitive regardless of variant - a focus ring
+     *  states keyboard position, not the control's importance. Constraint (WCAG 2.2 SC 1.4.11): at
+     *  least 3:1 against `surface` in the same theme. */
+    focusRing: string;
+    /** The colour of a prose link. A link is told apart by its underline, never by hue, so this
+     *  carries the text threshold, not the 3:1 the ring takes. Constraint (WCAG 2.2 SC 1.4.3): at
+     *  least 4.5:1 against `surface` in the same theme. */
+    link: string;
     /** Status colours. Not yet consumed by a component - they complete the role set so the
      *  first Alert or Toast has names to reach for instead of inventing them. */
     success: string;

package/dist/types/index.d.ts

@@ -1,5 +1,29 @@
 import './styles.css';
-export type { IButtonProps } from 'Interaction/Button/Button';
+export { Brandmark } from 'Display/Brandmark/Brandmark';
+export { Checklist } from 'Display/Checklist/Checklist';
+export { DefinitionList } from 'Display/DefinitionList/DefinitionList';
+export { Figure } from 'Display/Figure/Figure';
+export { Rail } from 'Display/Rail/Rail';
+export { Table } from 'Display/Table/Table';
+export { Eyebrow } from 'Display/Typography/Eyebrow/Eyebrow';
+export { H1 } from 'Display/Typography/H1/H1';
+export { H2 } from 'Display/Typography/H2/H2';
+export { H3 } from 'Display/Typography/H3/H3';
+export { H4 } from 'Display/Typography/H4/H4';
+export { H5 } from 'Display/Typography/H5/H5';
+export { H6 } from 'Display/Typography/H6/H6';
+export { P } from 'Display/Typography/P/P';
+export { Prose } from 'Display/Typography/Prose/Prose';
 export { Button } from 'Interaction/Button/Button';
+export { Input } from 'Interaction/Input/Input';
+export { Link } from 'Interaction/Link/Link';
+export { TextArea } from 'Interaction/TextArea/TextArea';
+export { Footer } from 'Layout/Footer/Footer';
+export type { FormState } from 'Layout/Form/Form';
+export { Form } from 'Layout/Form/Form';
+export { Header } from 'Layout/Header/Header';
+export { Hero } from 'Layout/Hero/Hero';
+export { PageHead } from 'Layout/PageHead/PageHead';
+export { Section } from 'Layout/Section/Section';
 export type { PaletteTokens } from 'Theme/Palette';
 export { dark, light } from 'Theme/Palette';

package/package.json

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

package/src/Display/Brandmark/Brandmark.tsx

@@ -0,0 +1,97 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// The whole recipe is one class: `inline-flex`. An SVG inside a plain inline span sits on the text
+// baseline and reserves descender space beneath it - a silent few-pixel misalignment nobody sees
+// until a mark is measured against a nav's right edge. `inline-flex` removes it. The component paints
+// nothing else: it sets no colour and no dimension, so there is no `dark:` class and no token here.
+//
+// `cut` selects only the `data-cut` attribute - each option carries no class of its own, the way
+// `Input`'s `variant` selects only the control's `type`. Its real job is being required: a caller
+// cannot place a mark without stating which cut it is, so "has the reduction row been done?" is asked
+// at every call site. There is deliberately no default variant.
+const brandmark = cva('inline-flex', {
+  variants: {
+    cut: { full: '', compact: '' },
+  },
+});
+
+export interface IBrandmarkProps extends VariantProps<typeof brandmark> {
+  /**
+   * What the mark says. Required so the decision is forced at the call site. Empty string is a
+   * legitimate value - a mark beside the product name already set as text - and is not rejected.
+   */
+  name: string;
+  /** The consumer's inline SVG. */
+  children?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * Names a consumer-supplied inline mark and makes its cut explicit. It hosts no asset: the SVG is the
+ * consumer's, passed as `children` and rendered unmodified. A brand mark is text that has stopped
+ * being text - drawn as outlines, it carries no accessible name of its own - so naming it is the job,
+ * and the one thing a consumer most reliably gets wrong.
+ *
+ * `role="img"` makes the element a leaf in the accessibility tree, so nothing inside the SVG - a stray
+ * `<title>`, `<text>` or `<desc>` - contributes, and the mark is announced exactly once.
+ *
+ * @Guarantees — enforced on every render
+ * - A named mark (`name` non-empty) renders `role="img"` and `aria-label={name}`, announced exactly
+ *   once and never through its SVG's own contents.
+ * - A decorative mark (`name=""`) renders `aria-hidden="true"` with no `role` and no `aria-label`, so
+ *   it leaves the accessibility tree entirely - an unnamed `role="img"` would be worse than absent.
+ * - The cut in use is always stated and always readable from the DOM, via required `cut` -> `data-cut`.
+ * - `children` renders unmodified; the component adds nothing to and strips nothing from the SVG, and
+ *   sets no colour, dimension, margin or link of its own.
+ *
+ * @UXGuidelines
+ * - One mark is not one asset - do the reduction row before you accept a mark. Measured on the lockup
+ *   that prompted this: a 15-character full lockup is illegible at 32px, while its accent dot survives
+ *   to 17px. A single SVG used at every size is the default and it is usually wrong. Expect at least
+ *   two cuts out of any mark, which is why `cut` is required. There is no width-based swapping and no
+ *   threshold token: a threshold is one wordmark's measurement, and keeping both cuts in the DOM to
+ *   swap in CSS doubles the payload of the element inlined to keep LCP off the network. The component
+ *   renders whichever single cut it is given; which slot it is in is known by whoever places it.
+ * - The sanctioned accent, and how narrow it is. A fill-only colour that fails 3:1 as text may sit
+ *   inside a letterform only where it carries no information and the glyph reads without it - a lifted
+ *   `i`-dot qualifies because the `i` keeps its stem. The library sets no fill inside a consumer's
+ *   mark and cannot check this; it is guidance to whoever draws the mark, not a token constraint.
+ * - Inline the SVG rather than requesting it where the mark is the largest object on the first screen
+ *   and therefore the LCP element - inlining means LCP depends on no font and no network round-trip.
+ */
+export const Brandmark: FunctionComponent<IBrandmarkProps> = ({
+  name,
+  cut,
+  children,
+  testId,
+}) => {
+  // The two paths differ in markup, not just in an attribute, so they are two branches: an empty
+  // `name` must leave the accessibility tree, and a `span` carrying `aria-label` with no `role` is
+  // both wrong and rejected by the a11y lint. `role="img"` is what makes `aria-label` valid here.
+  if (name === '') {
+    return (
+      <span
+        aria-hidden={'true'}
+        data-cut={cut}
+        className={brandmark({ cut })}
+        data-testid={testId}
+      >
+        {children}
+      </span>
+    );
+  }
+
+  return (
+    <span
+      role={'img'}
+      aria-label={name}
+      data-cut={cut}
+      className={brandmark({ cut })}
+      data-testid={testId}
+    >
+      {children}
+    </span>
+  );
+};

package/src/Display/Checklist/Checklist.tsx

@@ -0,0 +1,75 @@
+import { cva } from 'class-variance-authority';
+import type { FunctionComponent, ReactNode } from 'react';
+
+// The marker is a rule, not a glyph - and this is worth writing down because it outlives this one
+// component and there is no ADR carrying it. A checkbox character, dingbat or icon is an *invented
+// graphic*, and in a design language built from 1px rules and type an invented graphic is the thing
+// that reads as borrowed. So the tick is the structural hairline already on the page, doing one more
+// job - and it is unconditional: no prop removes it, reshapes it or swaps it. A future primitive
+// needing a marker for some other job has nowhere else to find this stance; it is here on purpose.
+
+// The ul: an unstyled list. `list-none` strips the browser marker (so no bullet is ever drawn) and
+// resets its default indent; `role="list"` is restored in the markup because `list-style: none`
+// silently drops list semantics in Safari/VoiceOver. Colours are semantic tokens re-pointed by
+// `.dark`, so no selector carries a `dark:` class.
+const checklistRoot = cva('m-0 list-none p-0');
+
+// The li: body copy in `foreground` - items are content, not annotation, so they are not muted. The
+// tick is drawn as a `::before` pseudo-element, the only route to a rule: CSS `::marker` styles just
+// colour, font and content, so it cannot draw a line, and a `✓` in the content would be announced on
+// every single item. The li is a flex row so the tick sits in a left gutter with the text hanging
+// indented beside it; `before:mt-[0.7em]` drops the rule to the optical middle of the first line. Its
+// colour is the `rule` role - a table's top rule and a list's tick are one job, a 1px mark at the
+// weight where structure becomes visible - its length and thickness the two named tick tokens, no
+// literal here. Hairlines sit *between* items in the `border` colour, with no rule above the first or
+// below the last, so the list is open at both ends - deliberately unlike a closed list, which closes
+// at the foot. The between-item gap reads `--space-stack`, split above and below the hairline so it
+// sits centred in the gap.
+const checklistItem = cva(
+  [
+    'flex items-start gap-3 font-primary text-body leading-body text-foreground',
+    "before:mt-[0.7em] before:h-[var(--tick-thickness)] before:w-[var(--tick-length)] before:shrink-0 before:bg-[var(--color-rule)] before:content-['']",
+    '[&:not(:first-child)]:mt-[var(--space-stack)] [&:not(:first-child)]:border-border [&:not(:first-child)]:border-t [&:not(:first-child)]:border-solid [&:not(:first-child)]:pt-[var(--space-stack)]',
+  ].join(' '),
+);
+
+interface IChecklistRootProps {
+  children?: ReactNode;
+  testId?: string;
+}
+
+interface IChecklistItemProps {
+  children?: ReactNode;
+}
+
+const ChecklistRoot: FunctionComponent<IChecklistRootProps> = ({
+  children,
+  testId,
+}) => (
+  // biome-ignore lint/a11y/noRedundantRoles: list-style:none silently strips the ul's list semantics in Safari/VoiceOver; the explicit role restores them (issue #13)
+  <ul className={checklistRoot()} role={'list'} data-testid={testId}>
+    {children}
+  </ul>
+);
+
+const ChecklistItem: FunctionComponent<IChecklistItemProps> = ({
+  children,
+}) => <li className={checklistItem()}>{children}</li>;
+
+/**
+ * A list of things to confirm or prepare, composed from its two members. Each item is hairline-separated
+ * and marked by a short rule sitting in the left indent - never a checkbox, bullet, dingbat or icon.
+ * This is a reading device, not a form control: it renders no interactive checkbox and owns no state.
+ *
+ * @Guarantees — enforced on every render
+ * - `Root` renders a `ul` carrying `role="list"`; `Item` renders an `li`. Works with JavaScript off.
+ * - The marker is a `::before` rule reading `--color-rule`, `--tick-length` and `--tick-thickness` - no
+ *   glyph, character, dingbat, icon or `::marker` content, and nothing is announced on each item.
+ * - Items render at the body type role in `foreground`; they are content, not annotation.
+ * - Hairlines in `border` separate items, with no rule above the first or below the last, so the list
+ *   is open at both ends. The between-item gap reads `--space-stack`.
+ */
+export const Checklist = {
+  Root: ChecklistRoot,
+  Item: ChecklistItem,
+} as const;