@oneli8/core 1.0.0-beta.5 → 1.0.0-beta.7

package/src/molecules/choice-chip/choice-chip.css

@@ -0,0 +1,214 @@
+/**
+ * Oneli8 · Choice Chip (MOLECULE) — the Soft Hexagon
+ * Figma: Select and Combobox / Choice Chip / Soft Hexagon 636:847 (8 variants)
+ *
+ * GEOMETRY, read from all four sizes in Figma:
+ *   size         target  visible  rail inset  gap  label
+ *   compact        48      30         9        9   12 / 18
+ *   standard       48      36        12        9   12 / 18
+ *   comfortable    48      42        15        9   16 / 24
+ *   large          60      42        15        9   16 / 24
+ * The terminal is a fixed 12 at every size and never scales with the label,
+ * so peer chips of different lengths keep one shoulder depth and side angle.
+ *
+ * The visible silhouette sits inside a taller protected target, which is why
+ * `min-block-size` is the target and the rail carries the visible height.
+ */
+
+.ol8-chip {
+  --_height: var(--ol8-component-choice-chip-height-standard);
+  --_target: var(--ol8-component-choice-chip-target-standard);
+  --_inset:  var(--ol8-component-choice-chip-rail-inset-standard);
+  --_label-size: var(--ol8-font-size-012);
+  --_label-line: var(--ol8-font-line-018);
+
+  /* Inactive is the quiet Neutral treatment; Selected is Primary Soft. */
+  --_surface: var(--ol8-color-surface-sunken);
+  --_edge:    var(--ol8-color-border-subtle);
+  --_ink:     var(--ol8-color-text-primary);
+
+  /* The ring is painted at every state and is simply invisible until focus,
+     so focus never changes the geometry, only the colour. */
+  --_focus-outer: transparent;
+  --_focus-inner: transparent;
+
+  box-sizing: border-box;
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  min-block-size: var(--_target);
+  font-family: var(--ol8-font-family-functional);
+  font-variation-settings: "ARRR" var(--ol8-font-axis-arrr-baseline);
+  color: var(--_ink);
+  cursor: pointer;
+}
+.ol8-chip[data-ol8-availability="disabled"] { cursor: not-allowed; }
+
+/* ---- Size ------------------------------------------------------------ */
+.ol8-chip[data-ol8-size="compact"] {
+  --_height: var(--ol8-component-choice-chip-height-compact);
+  --_inset:  var(--ol8-component-choice-chip-rail-inset-compact);
+}
+.ol8-chip[data-ol8-size="standard"] {
+  --_height: var(--ol8-component-choice-chip-height-standard);
+  --_inset:  var(--ol8-component-choice-chip-rail-inset-standard);
+}
+.ol8-chip[data-ol8-size="comfortable"] {
+  --_height: var(--ol8-component-choice-chip-height-comfortable);
+  --_inset:  var(--ol8-component-choice-chip-rail-inset-comfortable);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+}
+.ol8-chip[data-ol8-size="large"] {
+  --_height: var(--ol8-component-choice-chip-height-large);
+  --_target: var(--ol8-component-choice-chip-target-large);
+  --_inset:  var(--ol8-component-choice-chip-rail-inset-large);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+}
+
+/* ---- Selection ------------------------------------------------------- */
+/* Never colour alone: the native checked state carries the same fact, and the
+   selected edge is a stronger contrast than the inactive one. */
+.ol8-chip[data-ol8-selection="selected"] {
+  --_surface: var(--ol8-color-selection-surface);
+  --_edge:    var(--ol8-color-primary-360);
+  --_ink:     var(--ol8-color-selection-content);
+}
+.ol8-chip[data-ol8-availability="disabled"] {
+  --_surface: var(--ol8-color-surface-disabled);
+  --_edge:    var(--ol8-color-border-disabled);
+  --_ink:     var(--ol8-color-text-disabled);
+}
+
+.ol8-chip__input {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* ---- Terminals ------------------------------------------------------- */
+/* One viewBox serves every height: Figma's terminal paths share identical X
+   values at 30, 36 and 42, and Y values that are the same fractions of the
+   height, so stretching Y alone is exact rather than approximate. */
+.ol8-chip__terminal {
+  flex: none;
+  inline-size: var(--ol8-component-choice-chip-terminal);
+  block-size: var(--_height);
+  /* The point reaches 0.15 beyond the box, as it does in Figma, and the focus
+     ring is painted outside the silhouette. Neither may be clipped. */
+  overflow: visible;
+}
+/* The trailing terminal is the leading one mirrored, so they cannot drift. */
+.ol8-chip__terminal--trailing { transform: scaleX(-1); }
+
+.ol8-chip__fill { fill: var(--_surface); }
+
+/* Double width, clipped to the fill: the outer half is cut away and what
+   remains is an inside edge of exactly one border width, matching the rail's
+   own inside border. A centred stroke would stand 1px proud of the rail and
+   show a step at the shoulder. */
+.ol8-chip__edge {
+  fill: none;
+  stroke: var(--_edge);
+  stroke-width: calc(var(--ol8-border-width-standard) * 2);
+  vector-effect: non-scaling-stroke;
+}
+
+/* Both rings are painted before the fill and at double width, so the inner
+   half of each lands under the fill and only the outer half shows. This is how
+   the ring follows the hexagon instead of boxing it. */
+.ol8-chip__focus-outer,
+.ol8-chip__focus-inner { fill: none; vector-effect: non-scaling-stroke; }
+.ol8-chip__focus-outer {
+  stroke: var(--_focus-outer);
+  stroke-width: calc((var(--ol8-focus-ring-outerwidth) + var(--ol8-focus-ring-innerwidth)) * 2);
+}
+.ol8-chip__focus-inner {
+  stroke: var(--_focus-inner);
+  stroke-width: calc(var(--ol8-focus-ring-innerwidth) * 2);
+}
+
+.ol8-chip:has(> .ol8-chip__input:focus-visible) {
+  --_focus-outer: var(--ol8-color-focus-outer);
+  --_focus-inner: var(--ol8-color-focus-inner);
+}
+
+/* ---- Centre rail ----------------------------------------------------- */
+/* Only the rail grows with the label. It owns the top and bottom of the
+   perimeter; the terminals own the angled ends. */
+.ol8-chip__rail {
+  box-sizing: border-box;
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--ol8-component-choice-gap-standard);
+  block-size: var(--_height);
+  padding-inline: var(--_inset);
+  background: var(--_surface);
+  border-block: var(--ol8-border-width-standard) solid var(--_edge);
+}
+
+/* The ring's flat runs, continuing the terminals' strokes across the rail.
+   Two colours in one band, ordered outward from the silhouette. */
+.ol8-chip__rail::before,
+.ol8-chip__rail::after {
+  content: "";
+  position: absolute;
+  inset-inline: 0;
+  block-size: calc(var(--ol8-focus-ring-outerwidth) + var(--ol8-focus-ring-innerwidth));
+}
+.ol8-chip__rail::before {
+  inset-block-end: 100%;
+  background: linear-gradient(
+    var(--_focus-outer) 0 var(--ol8-focus-ring-outerwidth),
+    var(--_focus-inner) var(--ol8-focus-ring-outerwidth) 100%);
+}
+.ol8-chip__rail::after {
+  inset-block-start: 100%;
+  background: linear-gradient(
+    var(--_focus-inner) 0 var(--ol8-focus-ring-innerwidth),
+    var(--_focus-outer) var(--ol8-focus-ring-innerwidth) 100%);
+}
+
+.ol8-chip__label {
+  font-size: var(--_label-size);
+  line-height: var(--_label-line);
+  font-weight: var(--ol8-font-weight-regular);
+  color: var(--_ink);
+}
+
+/* ---- Mark ------------------------------------------------------------ */
+/* Figma places the mark BEFORE the label in every variant, Remove included. */
+.ol8-chip__mark {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--ol8-component-choicechip-mark);
+  block-size: var(--ol8-component-choicechip-mark);
+  color: var(--_ink);
+}
+
+/* The Check does not scale with its slot. Figma's `Icon / Selection / Check`
+   is a governed small master, not an Icon Frame instance: Size=Small and
+   Size=Standard both carry the same 10.2 x 6.9 artwork at the same 1.8 stroke,
+   centred in an 18 or 24 box. So the source box stays 24 units and overflows
+   the smaller slot, exactly as Figma draws it. */
+.ol8-chip__mark > svg {
+  display: block;
+  flex: none;
+  inline-size: var(--ol8-size-icon-standard);
+  block-size: var(--ol8-size-icon-standard);
+  overflow: visible;
+}
+
+/* Both marks read at the one governed optical stroke, which is what Figma
+   draws and what the iconography contract calls contextual stroke
+   normalization: peer marks in one family match apparent weight. */
+.ol8-chip__mark > svg > * {
+  vector-effect: non-scaling-stroke;
+  stroke-width: var(--ol8-component-choice-optical-stroke);
+}

package/src/molecules/choice-chip/choice-chip.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Choice Chip (MOLECULE) — the Soft Hexagon. A real checkbox wearing the
+ * approved quiet chip appearance, so selection is carried by native checked
+ * state and a stronger edge, never by colour alone.
+ */
+export type Ol8ChipSize = 'compact' | 'standard' | 'comfortable' | 'large';
+
+export declare const OL8_CHIP_SIZES: readonly Ol8ChipSize[];
+
+export interface Ol8ChoiceChipOptions {
+  size?: Ol8ChipSize;
+  /** Figma's Selection axis. Maps to the input's checked state. */
+  selected?: boolean;
+  /** Figma's Show Mark boolean: the optional Check inside a selected chip. */
+  showMark?: boolean;
+  disabled?: boolean;
+  name?: string;
+  value?: string;
+  id?: string;
+  className?: string;
+}
+
+export declare function renderChoiceChip(label: string, options?: Ol8ChoiceChipOptions): string;
+
+/** Mirrors each chip's input state onto the attribute the stylesheet reads. */
+export declare function hydrateChoiceChips(root?: ParentNode): number;
+export declare function syncChip(chip: Element): void;

package/src/molecules/choice-chip/choice-chip.js

@@ -0,0 +1,170 @@
+/**
+ * Oneli8 · Choice Chip (MOLECULE) — the Soft Hexagon.
+ *
+ * Figma: Select and Combobox / Choice Chip / Soft Hexagon 636:847 (8 variants,
+ * Size x Selection, plus a Label text property and a Show Mark boolean).
+ *
+ * From the Figma description:
+ *   "Compact/Standard/Comfortable/Large use approved 30/36/42/42px visible
+ *    geometry inside protected 48/48/48/60px targets. Fixed 12px terminals and
+ *    tokenized 9/12/15/15px inner rail insets preserve one silhouette at every
+ *    label width."
+ *
+ * Figma builds the silhouette from three boxes, and so does this: a fixed 12px
+ * left terminal, a centre rail that grows with the label, and a mirrored right
+ * terminal. Only the rail grows, which is why a short chip and a long chip keep
+ * the same shoulder depth and side angle. The contract is explicit that ends
+ * which scale with the text are prohibited.
+ *
+ * WHY SVG RATHER THAN clip-path
+ * The terminals are not polygons. Each has three small curves softening the
+ * shoulders and the point, and the contract rejects approximating that softness
+ * with extra vertices because it reads as an Octagon. `clip-path: polygon()`
+ * can only draw straight vertices, so the terminals are real paths.
+ *
+ * HOW ONE PATH SERVES FOUR HEIGHTS
+ * Read from Figma, every terminal path at 30, 36 and 42 has identical X values
+ * and Y values that scale exactly with the height: 1/36, 1/12, 5/12, 11/24,
+ * 13/24, 7/12, 11/12, 35/36 of the height, at every size. So one viewBox of
+ * 12 x 30 with `preserveAspectRatio="none"` and a fixed 12px width reproduces
+ * Figma at all four sizes: the height stretches, the width cannot.
+ * `vector-effect="non-scaling-stroke"` keeps the edge an even 2px through that
+ * uneven stretch.
+ *
+ * THE OPEN EDGE
+ * Figma draws two vectors per terminal: a closed fill and an open outline that
+ * "deliberately omits the hidden vertical closing edge", so the rail's own top
+ * and bottom borders continue the perimeter without a doubled seam. This keeps
+ * that construction. Figma reaches an inside stroke by scaling the outline path
+ * to 98.75% of the width; here the edge is clipped to the fill instead, which
+ * is the same rendered result stated directly.
+ */
+import { renderIconSvg } from '../../atoms/icon/icon.js';
+
+export const OL8_CHIP_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+
+/**
+ * The terminal, in the 12 x 30 space Figma draws it in. The closed path is the
+ * fill; the open one is the perimeter, missing the seam edge at x=12.
+ */
+export const OL8_CHIP_TERMINAL_FILL =
+  'M12 0 L8.96202541 0 C7.44303812 0 6.43037944 0.83333333 5.92405035 2.5 ' +
+  'L0.45569618 12.5 C-0.15189877 13.75 -0.15189877 16.25 0.45569618 17.5 ' +
+  'L5.92405035 27.5 C6.43037944 29.16666667 7.44303812 30 8.96202541 30 L12 30 Z';
+export const OL8_CHIP_TERMINAL_EDGE =
+  'M12 0 L8.96202541 0 C7.44303812 0 6.43037944 0.83333333 5.92405035 2.5 ' +
+  'L0.45569618 12.5 C-0.15189877 13.75 -0.15189877 16.25 0.45569618 17.5 ' +
+  'L5.92405035 27.5 C6.43037944 29.16666667 7.44303812 30 8.96202541 30 L12 30';
+
+/**
+ * One terminal. `side` only picks a class; the right terminal is the left one
+ * mirrored in CSS, so the two can never drift apart.
+ *
+ * The focus bands are strokes on the same path, painted before the fill and at
+ * double width, so their inner half lands under the fill and the visible half
+ * sits outside the silhouette. That is how a ring follows a hexagon instead of
+ * boxing it.
+ */
+function renderTerminal(uid, side) {
+  const clip = `${uid}-clip-${side}`;
+  return `<svg class="ol8-chip__terminal ol8-chip__terminal--${side}" viewBox="0 0 12 30" ` +
+    `preserveAspectRatio="none" aria-hidden="true" focusable="false">` +
+    `<clipPath id="${clip}"><path d="${OL8_CHIP_TERMINAL_FILL}"/></clipPath>` +
+    `<path class="ol8-chip__focus-outer" d="${OL8_CHIP_TERMINAL_EDGE}"/>` +
+    `<path class="ol8-chip__focus-inner" d="${OL8_CHIP_TERMINAL_EDGE}"/>` +
+    `<path class="ol8-chip__fill" d="${OL8_CHIP_TERMINAL_FILL}"/>` +
+    `<path class="ol8-chip__edge" d="${OL8_CHIP_TERMINAL_EDGE}" clip-path="url(#${clip})"/>` +
+    `</svg>`;
+}
+
+/**
+ * The silhouette plus its rail contents. Private: Figma names this the
+ * "Choice Chip / Geometry Owner" and both the public chip and the Token
+ * instantiate it rather than redrawing it.
+ *
+ * `mark` is markup for the rail's trailing slot, or an empty string. The mark
+ * follows the label, which is the anatomy the contract writes down as "Label +
+ * optional Remove mark", and one position serves Check and Remove alike so
+ * peer marks never end up on opposite sides.
+ */
+export function renderChipShape(uid, label, mark = '') {
+  return renderTerminal(uid, 'leading') +
+    `<span class="ol8-chip__rail">` +
+      `<span class="ol8-chip__label">${escapeText(label)}</span>` +
+      mark +
+    `</span>` +
+    renderTerminal(uid, 'trailing');
+}
+
+/**
+ * A Choice Chip is a real checkbox. The contract is explicit: "Every option is
+ * a real Checkbox rendered with the approved quiet Choice Chip appearance",
+ * with "native checked state" among the redundant cues, so selection is never
+ * carried by colour alone.
+ *
+ * @param {string} label
+ * @param {{size?:string,selected?:boolean,showMark?:boolean,disabled?:boolean,
+ *          name?:string,value?:string,id?:string,className?:string}} [options]
+ */
+export function renderChoiceChip(label, options = {}) {
+  const {
+    size = 'standard', selected = false, showMark = false, disabled = false,
+    name, value, id, className,
+  } = options;
+
+  if (!OL8_CHIP_SIZES.includes(size)) throw new Error(`[ol8] unknown chip size "${size}"`);
+  if (!label || !String(label).trim()) throw new Error('[ol8] Choice Chip requires a label');
+
+  const uid = id ?? `ol8-chip-${Math.random().toString(36).slice(2, 9)}`;
+  const mark = showMark
+    ? `<span class="ol8-chip__mark" aria-hidden="true">${renderIconSvg('check')}</span>`
+    : '';
+
+  const inputAttrs = [
+    'type="checkbox"', 'class="ol8-chip__input"', `id="${uid}"`,
+    name ? `name="${escapeAttr(name)}"` : '',
+    value !== undefined ? `value="${escapeAttr(value)}"` : '',
+    selected ? 'checked' : '', disabled ? 'disabled' : '',
+  ].filter(Boolean).join(' ');
+
+  const rowAttrs = [
+    `class="ol8-chip${className ? ` ${className}` : ''}"`,
+    `for="${uid}"`,
+    `data-ol8-size="${size}"`,
+    `data-ol8-selection="${selected ? 'selected' : 'inactive'}"`,
+    `data-ol8-availability="${disabled ? 'disabled' : 'enabled'}"`,
+  ].filter(Boolean).join(' ');
+
+  return `<label ${rowAttrs}><input ${inputAttrs}>${renderChipShape(uid, label, mark)}</label>`;
+}
+
+/**
+ * Keeps each chip's Selection attribute in step with its input. A chip in a
+ * group is an ordinary checkbox, so the browser owns the toggling; this only
+ * mirrors the result onto the attribute the stylesheet reads.
+ */
+export function hydrateChoiceChips(root = document) {
+  const chips = [...root.querySelectorAll('.ol8-chip')];
+  for (const chip of chips) {
+    const input = chip.querySelector(':scope > .ol8-chip__input');
+    if (!input) continue;
+    syncChip(chip);
+    if (chip.dataset.ol8ChipBound === 'true') continue;
+    input.addEventListener('change', () => syncChip(chip));
+    chip.dataset.ol8ChipBound = 'true';
+  }
+  return chips.length;
+}
+
+/** Repaints one chip from the live state of its input. */
+export function syncChip(chip) {
+  const input = chip.querySelector(':scope > .ol8-chip__input');
+  if (!input) return;
+  chip.dataset.ol8Selection = input.checked ? 'selected' : 'inactive';
+  chip.dataset.ol8Availability = input.disabled ? 'disabled' : 'enabled';
+}
+
+/* Private. Exported only so Token can reuse the same escaping; neither name
+   reaches the package index. */
+export function escapeAttr(v) { return String(v).replace(/&/g,'&amp;').replace(/"/g,'&quot;').replace(/</g,'&lt;'); }
+function escapeText(v) { return String(v).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;'); }

package/src/molecules/choice-chip/index.d.ts

@@ -0,0 +1,2 @@
+export { OL8_CHIP_SIZES, renderChoiceChip, hydrateChoiceChips, syncChip } from './choice-chip.js';
+export type { Ol8ChipSize, Ol8ChoiceChipOptions } from './choice-chip.js';

package/src/molecules/choice-chip/index.js

@@ -0,0 +1,10 @@
+/**
+ * The public surface. The terminal paths, the shape composer and the escape
+ * helpers stay module private on purpose: Figma names the terminals "Private
+ * Geometry" and the contract is explicit that they "are private construction
+ * inside the canonical Choice Chip molecule ... not published cap atoms, layer
+ * variants, or independently swappable components". Token reaches them by
+ * importing the module directly, exactly as its Figma counterpart instantiates
+ * the Geometry Owner.
+ */
+export { OL8_CHIP_SIZES, renderChoiceChip, hydrateChoiceChips, syncChip } from './choice-chip.js';

package/src/molecules/form-message/form-message.css

@@ -0,0 +1,46 @@
+/**
+ * Oneli8 · Form Message (MOLECULE)
+ * Figma: Form Message 177:13, five tones.
+ *
+ * Anatomy read from Figma: a horizontal row, gap Component / Text Field / Gap /
+ * Status, items centred, one Small status icon beside twelve over eighteen
+ * regular text. Tone changes exactly one thing, the inline content colour,
+ * which both the icon stroke and the text take.
+ */
+
+.ol8-form-message {
+  display: flex;
+  align-items: center;
+  gap: var(--ol8-component-textfield-gap-status);
+  color: var(--_tone);
+  font-family: var(--ol8-font-family-functional);
+  font-size: var(--ol8-font-size-012);
+  font-weight: var(--ol8-font-weight-regular);
+  line-height: var(--ol8-font-line-018);
+}
+
+.ol8-form-message__icon { flex: none; color: var(--_tone); }
+
+/* ---- Tone ------------------------------------------------------------- */
+.ol8-form-message[data-ol8-tone="critical"]    { --_tone: var(--ol8-color-feedbackcritical-inlinecontent); }
+.ol8-form-message[data-ol8-tone="caution"]     { --_tone: var(--ol8-color-feedbackcaution-inlinecontent); }
+.ol8-form-message[data-ol8-tone="positive"]    { --_tone: var(--ol8-color-feedbackpositive-inlinecontent); }
+.ol8-form-message[data-ol8-tone="informative"] { --_tone: var(--ol8-color-feedbackinformative-inlinecontent); }
+
+/* Pending reads as informative text, and Figma gives its loading mark the
+   primary icon colour rather than a feedback colour, because nothing has been
+   decided yet. */
+.ol8-form-message[data-ol8-tone="pending"] {
+  --_tone: var(--ol8-color-feedbackinformative-inlinecontent);
+}
+.ol8-form-message[data-ol8-tone="pending"] .ol8-form-message__icon {
+  color: var(--ol8-color-icon-primary);
+}
+
+/* Same treatment the Button gives its busy mark: rotation is opt in and motion
+   guarded, and Reduced Motion keeps the static mark. */
+@media (prefers-reduced-motion: no-preference) {
+  .ol8-form-message[data-ol8-tone="pending"] .ol8-form-message__icon > svg {
+    animation: ol8-spin 900ms linear infinite;
+  }
+}

package/src/molecules/form-message/form-message.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Form Message (MOLECULE). Figma 177:13. Tone maps to semantic message tone;
+ * Pending is the validating state rather than a fifth error tone.
+ */
+export type Ol8FormMessageTone = 'critical' | 'caution' | 'positive' | 'informative' | 'pending';
+
+export declare const OL8_FORM_MESSAGE_TONES: readonly Ol8FormMessageTone[];
+export declare const OL8_FORM_MESSAGE_ICONS: Readonly<Record<Ol8FormMessageTone, string>>;
+
+export interface Ol8FormMessageOptions {
+  tone?: Ol8FormMessageTone;
+  /** Figma's Show Icon. */
+  icon?: boolean;
+  /** Give it an id so a field can point aria-describedby at it. */
+  id?: string;
+  className?: string;
+}
+
+/** @throws on an unknown tone. */
+export declare function renderFormMessage(message: string, options?: Ol8FormMessageOptions): string;
+
+/** Enforces role and live region on existing `.ol8-form-message` markup. */
+export declare function hydrateFormMessages(root?: ParentNode): void;

package/src/molecules/form-message/form-message.js

@@ -0,0 +1,73 @@
+/**
+ * Oneli8 · Form Message — headless behavior.
+ *
+ * Figma (177:13): "Canonical Oneli8 Form Message molecule. Tone maps to
+ * semantic message tone; Pending is resolved through validationStatus rather
+ * than treated as a fifth error tone. Icon and Message remain modular content
+ * atoms. Runtime role, status announcement and relationships live in code."
+ *
+ * So this module owns what Figma says code owns: the live region, the role that
+ * follows from the tone, and the icon each tone carries.
+ */
+import { renderIcon } from '../../atoms/icon/index.js';
+
+/** The five tones Figma enumerates. Pending is the validating state, not an error. */
+export const OL8_FORM_MESSAGE_TONES = ['critical', 'caution', 'positive', 'informative', 'pending'];
+
+/** Figma pairs one status icon with each tone. Pending carries the loading mark. */
+export const OL8_FORM_MESSAGE_ICONS = {
+  critical: 'critical',
+  caution: 'caution',
+  positive: 'positive',
+  informative: 'informative',
+  pending: 'loading',
+};
+
+/**
+ * @param {string} message
+ * @param {{tone?:string,icon?:boolean,id?:string,className?:string}} [options]
+ */
+export function renderFormMessage(message, options = {}) {
+  const { tone = 'critical', icon = true, id, className } = options;
+
+  if (!OL8_FORM_MESSAGE_TONES.includes(tone)) {
+    throw new Error(`[ol8] unknown form message tone "${tone}"`);
+  }
+
+  // Critical is the only tone a screen reader must interrupt for. Pending is
+  // progress, so it is polite. The rest report a result that already happened.
+  const live = tone === 'critical' ? 'assertive' : 'polite';
+
+  const attrs = [
+    `class="ol8-form-message${className ? ` ${className}` : ''}"`,
+    id ? `id="${escapeAttr(id)}"` : '',
+    `data-ol8-tone="${tone}"`,
+    tone === 'critical' ? 'role="alert"' : 'role="status"',
+    `aria-live="${live}"`,
+  ].filter(Boolean).join(' ');
+
+  const mark = icon
+    ? renderIcon(OL8_FORM_MESSAGE_ICONS[tone], { size: 18, className: 'ol8-form-message__icon' })
+    : '';
+
+  return `<div ${attrs}>${mark}<span class="ol8-form-message__text">${escapeText(message)}</span></div>`;
+}
+
+/** Enforces the runtime contract on existing markup. Idempotent. */
+export function hydrateFormMessages(root = document) {
+  for (const el of root.querySelectorAll('.ol8-form-message')) {
+    const tone = el.dataset.ol8Tone || 'critical';
+    if (!OL8_FORM_MESSAGE_TONES.includes(tone)) {
+      console.warn(`[ol8] unknown form message tone "${tone}"`, el);
+      continue;
+    }
+    el.dataset.ol8Tone = tone;
+    if (!el.hasAttribute('role')) el.setAttribute('role', tone === 'critical' ? 'alert' : 'status');
+    if (!el.hasAttribute('aria-live')) {
+      el.setAttribute('aria-live', tone === 'critical' ? 'assertive' : 'polite');
+    }
+  }
+}
+
+function escapeAttr(v) { return String(v).replace(/&/g,'&amp;').replace(/"/g,'&quot;').replace(/</g,'&lt;'); }
+function escapeText(v) { return String(v).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;'); }

package/src/molecules/form-message/index.d.ts

@@ -0,0 +1 @@
+export * from './form-message.js';

package/src/molecules/form-message/index.js

@@ -0,0 +1 @@
+export { renderFormMessage, hydrateFormMessages, OL8_FORM_MESSAGE_TONES, OL8_FORM_MESSAGE_ICONS } from './form-message.js';

package/src/molecules/index.d.ts

@@ -2,3 +2,9 @@ export * from './button/index.js';
 export * from './icon-button/index.js';
 export * from './choice-item/index.js';
 export * from './selection-option/index.js';
+export * from './link/index.js';
+export * from './form-message/index.js';
+export * from './text-field/index.js';
+export * from './select/index.js';
+export * from './choice-chip/index.js';
+export * from './token/index.js';

package/src/molecules/index.js

@@ -1,4 +1,10 @@
 export * from './button/index.js';
+export * from './link/index.js';
 export * from './icon-button/index.js';
 export * from './choice-item/index.js';
 export * from './selection-option/index.js';
+export * from './form-message/index.js';
+export * from './text-field/index.js';
+export * from './select/index.js';
+export * from './choice-chip/index.js';
+export * from './token/index.js';

package/src/molecules/link/index.d.ts

@@ -0,0 +1 @@
+export * from './link.js';

package/src/molecules/link/index.js

@@ -0,0 +1 @@
+export * from './link.js';