@oneli8/core 1.0.0-beta.10

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/icon-button/icon-button.css

@@ -0,0 +1,222 @@
+/**
+ * Oneli8 · Icon Button
+ * Figma: section "Icon Button" (1034:10546) — Primary 86:2, Secondary 87:26,
+ *        Quiet 88:50, Destructive 89:74, plus the four Circle sets.
+ *        4 families × 2 shapes × 4 sizes × 6 states = 192 components.
+ *
+ * Documentation (85:9):
+ *   "Visible boxes: 36/42/48/60px · protected targets: 48/48/48/60px
+ *    Artwork: 18/18/24/36px
+ *    Hover changes the container only; the symbol never translates, rotates
+ *    or scales. Accessible name is mandatory. Rounded Square is the canonical
+ *    base; Circle is a governed presentation extension."
+ *
+ * The component is TWO boxes, and that is the whole point:
+ *   .ol8-icon-btn           — the protected TARGET. Transparent, no paint.
+ *                             Never smaller than 48px even when the visible
+ *                             box is 36px, so the hit area stays compliant.
+ *   .ol8-icon-btn__surface  — the VISIBLE box. Carries bg, 2px border, radius.
+ *
+ * Collapsing these into one element would silently shrink the touch target
+ * to 36px at Compact. Don't.
+ */
+
+.ol8-icon-btn {
+  --_target:  var(--ol8-component-iconbutton-target-standard);
+  --_box:     var(--ol8-component-iconbutton-box-standard);
+  --_radius:  var(--ol8-component-iconbutton-radius-standard);
+  --_artwork: var(--ol8-component-iconbutton-artwork-standard);
+
+  --_bg: transparent;
+  --_bd: transparent;
+  --_ink: var(--ol8-color-icon-primary);
+
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--_target);
+  block-size: var(--_target);
+  padding: 0;
+  border: 0;
+  background: none;          /* the target paints nothing */
+  cursor: pointer;
+  -webkit-appearance: none;
+  appearance: none;
+}
+
+.ol8-icon-btn__surface {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--_box);
+  block-size: var(--_box);
+  border: var(--ol8-border-width-standard) solid var(--_bd);
+  border-radius: var(--_radius);
+  background: var(--_bg);
+  color: var(--_ink);
+}
+
+/* The surface governs artwork size — never set a size on the glyph. */
+.ol8-icon-btn .ol8-icon { --_ol8-icon-size: var(--_artwork); }
+
+/* "the symbol never translates, rotates, or scales" — no transform on the
+   glyph in any state. Hover changes the container only. */
+
+/* ---- Size ------------------------------------------------------------ */
+.ol8-icon-btn[data-ol8-size="compact"] {
+  --_target: var(--ol8-component-iconbutton-target-compact);
+  --_box: var(--ol8-component-iconbutton-box-compact);
+  --_radius: var(--ol8-component-iconbutton-radius-compact);
+  --_artwork: var(--ol8-component-iconbutton-artwork-compact);
+}
+.ol8-icon-btn[data-ol8-size="standard"] {
+  --_target: var(--ol8-component-iconbutton-target-standard);
+  --_box: var(--ol8-component-iconbutton-box-standard);
+  --_radius: var(--ol8-component-iconbutton-radius-standard);
+  --_artwork: var(--ol8-component-iconbutton-artwork-standard);
+}
+.ol8-icon-btn[data-ol8-size="comfortable"] {
+  --_target: var(--ol8-component-iconbutton-target-comfortable);
+  --_box: var(--ol8-component-iconbutton-box-comfortable);
+  --_radius: var(--ol8-component-iconbutton-radius-comfortable);
+  --_artwork: var(--ol8-component-iconbutton-artwork-comfortable);
+}
+.ol8-icon-btn[data-ol8-size="large"] {
+  --_target: var(--ol8-component-iconbutton-target-large);
+  --_box: var(--ol8-component-iconbutton-box-large);
+  --_radius: var(--ol8-component-iconbutton-radius-large);
+  --_artwork: var(--ol8-component-iconbutton-artwork-large);
+}
+
+/* ---- Shape: Circle is a governed presentation extension -------------- */
+.ol8-icon-btn[data-ol8-shape="circle"] { --_radius: var(--ol8-shape-radius-full); }
+
+/* ---- Family: Primary ------------------------------------------------- */
+/* The glyph binds to the action's CONTENT colour, not the neutral ink role.
+   Figma binds --ol8-color-icon-primary (#151817) here, which lands a near-black
+   glyph on a #2c438b surface: 1.94:1, against the 3:1 WCAG 1.4.11 minimum for
+   graphical objects. --ol8-color-actionprimary-content measures 8.81:1. */
+.ol8-icon-btn--primary {
+  --_bg: var(--ol8-color-actionprimary-default);
+  --_bd: var(--ol8-color-actionprimary-default);
+  --_ink: var(--ol8-color-actionprimary-content);
+}
+.ol8-icon-btn--primary:hover:not(:disabled):not([data-ol8-loading]) > .ol8-icon-btn__surface,
+.ol8-icon-btn--primary[data-ol8-loading] > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionprimary-hover); --_bd: var(--ol8-color-actionprimary-hover);
+}
+.ol8-icon-btn--primary:active:not(:disabled) > .ol8-icon-btn__surface,
+.ol8-icon-btn--primary[aria-pressed="true"]:not(:disabled) > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionprimary-pressed); --_bd: var(--ol8-color-actionprimary-pressed);
+}
+.ol8-icon-btn--primary:disabled > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionprimary-disabled);
+  --_bd: var(--ol8-color-border-disabled);
+  /* Disabled flips to a LIGHT surface, so the glyph flips back to dark ink. */
+  --_ink: var(--ol8-color-actionprimary-disabledcontent);
+}
+
+/* ---- Family: Destructive --------------------------------------------- */
+/* Same defect as Primary: #151817 on #922824 measures 2.17:1. */
+.ol8-icon-btn--destructive {
+  --_bg: var(--ol8-color-actiondestructive-default);
+  --_bd: var(--ol8-color-actiondestructive-default);
+  --_ink: var(--ol8-color-actiondestructive-content);
+}
+.ol8-icon-btn--destructive:hover:not(:disabled):not([data-ol8-loading]) > .ol8-icon-btn__surface,
+.ol8-icon-btn--destructive[data-ol8-loading] > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actiondestructive-hover); --_bd: var(--ol8-color-actiondestructive-hover);
+}
+.ol8-icon-btn--destructive:active:not(:disabled) > .ol8-icon-btn__surface,
+.ol8-icon-btn--destructive[aria-pressed="true"]:not(:disabled) > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actiondestructive-pressed); --_bd: var(--ol8-color-actiondestructive-pressed);
+}
+.ol8-icon-btn--destructive:disabled > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actiondestructive-disabled);
+  --_bd: var(--ol8-color-border-disabled);
+  --_ink: var(--ol8-color-actiondestructive-disabledcontent);
+}
+
+/* ---- Family: Secondary (bordered, transparent) ----------------------- */
+.ol8-icon-btn--secondary {
+  --_bg: var(--ol8-color-actionsecondary-surfacedefault);
+  --_bd: var(--ol8-color-actionsecondary-contentdefault);
+  --_ink: var(--ol8-color-actionsecondary-contentdefault);
+}
+.ol8-icon-btn--secondary:hover:not(:disabled):not([data-ol8-loading]) > .ol8-icon-btn__surface,
+.ol8-icon-btn--secondary[data-ol8-loading] > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionsecondary-surfacehover);
+  --_bd: var(--ol8-color-actionsecondary-contenthover);
+  --_ink: var(--ol8-color-actionsecondary-contenthover);
+}
+.ol8-icon-btn--secondary:active:not(:disabled) > .ol8-icon-btn__surface,
+.ol8-icon-btn--secondary[aria-pressed="true"]:not(:disabled) > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionsecondary-surfacepressed);
+  --_bd: var(--ol8-color-actionsecondary-contentpressed);
+  --_ink: var(--ol8-color-actionsecondary-contentpressed);
+}
+.ol8-icon-btn--secondary:disabled > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionsecondary-surfacedisabled);
+  --_bd: var(--ol8-color-border-disabled);
+  --_ink: var(--ol8-color-actionsecondary-contentdisabled);
+}
+
+/* ---- Family: Quiet (no boundary) ------------------------------------- */
+.ol8-icon-btn--quiet {
+  --_bg: var(--ol8-color-actionquiet-surfacedefault);
+  --_bd: transparent;
+  --_ink: var(--ol8-color-actionquiet-contentdefault);
+}
+.ol8-icon-btn--quiet:hover:not(:disabled):not([data-ol8-loading]) > .ol8-icon-btn__surface,
+.ol8-icon-btn--quiet[data-ol8-loading] > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionquiet-surfacehover); --_ink: var(--ol8-color-actionquiet-contenthover);
+}
+.ol8-icon-btn--quiet:active:not(:disabled) > .ol8-icon-btn__surface,
+.ol8-icon-btn--quiet[aria-pressed="true"]:not(:disabled) > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionquiet-surfacepressed); --_ink: var(--ol8-color-actionquiet-contentpressed);
+}
+.ol8-icon-btn--quiet:disabled > .ol8-icon-btn__surface {
+  --_bg: var(--ol8-color-actionquiet-surfacedisabled); --_ink: var(--ol8-color-actionquiet-contentdisabled);
+}
+
+/* ---- Pressed scrim ---------------------------------------------------
+   Figma layers a 3px inset scrim over the pressed surface, in addition to
+   the darker fill. Reproduced as an inset shadow rather than an extra node. */
+.ol8-icon-btn:active:not(:disabled) > .ol8-icon-btn__surface,
+.ol8-icon-btn[aria-pressed="true"]:not(:disabled) > .ol8-icon-btn__surface {
+  box-shadow: inset 0 0 0 3px var(--ol8-component-iconbutton-pressedscrim);
+}
+
+/* ---- Focus -----------------------------------------------------------
+   OUTSIDE two-tone ring, unlike the labelled Button's inside stroke.
+
+   Figma declares the 6px outer shadow FIRST, and box-shadow paints the first
+   shadow on top — so the 6px dark spread completely covers the 3px light one
+   and only a flat dark band renders. Sampling the Figma export confirms it:
+   uniform #101b3a at every perimeter position and at both 2px and 4px depth.
+
+   The inner band is declared here first so both are visible: light from the
+   edge out to 3px, dark from 3px to 6px. That is the ring the two tokens
+   describe. To restore the Figma-exact single-band ring, swap these two
+   lines back.
+
+   Both focus-ring tokens are BAND THICKNESSES (3px each). box-shadow spread is
+   cumulative from the edge, so the outer band's spread is the sum of the two —
+   3px light from the edge, then dark from 3px out to 6px. Do not pass
+   --ol8-focus-ring-outerwidth here on its own: that would paint the dark band
+   at the same 3px radius as the light one and hide it completely. */
+.ol8-icon-btn:focus-visible { outline: none; }
+.ol8-icon-btn:focus-visible > .ol8-icon-btn__surface {
+  box-shadow:
+    0 0 0 var(--ol8-focus-ring-innerwidth) var(--ol8-color-focus-inner),
+    0 0 0 calc(var(--ol8-focus-ring-innerwidth) + var(--ol8-focus-ring-outerwidth)) var(--ol8-color-focus-outer);
+}
+
+/* ---- Disabled / Loading ---------------------------------------------- */
+.ol8-icon-btn:disabled { cursor: not-allowed; }
+.ol8-icon-btn[data-ol8-loading] { cursor: progress; }
+@media (prefers-reduced-motion: no-preference) {
+  .ol8-icon-btn[data-ol8-loading] .ol8-icon > svg { animation: ol8-spin 900ms linear infinite; }
+}

package/src/molecules/icon-button/icon-button.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Icon Button (MOLECULE) — headless behavior. An accessible name is mandatory
+ * and enforced here rather than left to reviewers.
+ */
+import type { Ol8IconName } from '../../atoms/icon/icons.generated.js';
+
+export type Ol8IconButtonVariant = 'primary' | 'secondary' | 'quiet' | 'destructive';
+export type Ol8IconButtonSize = 'compact' | 'standard' | 'comfortable' | 'large';
+export type Ol8IconButtonShape = 'rounded' | 'circle';
+
+export declare const OL8_ICON_BUTTON_VARIANTS: readonly Ol8IconButtonVariant[];
+export declare const OL8_ICON_BUTTON_SIZES: readonly Ol8IconButtonSize[];
+export declare const OL8_ICON_BUTTON_SHAPES: readonly Ol8IconButtonShape[];
+
+/** Artwork sizes as BUILT in Figma: 18 / 18 / 24 / 24. */
+export declare function artworkSizeForIconButton(size: Ol8IconButtonSize): 18 | 24;
+
+export interface Ol8IconButtonOptions {
+  variant?: Ol8IconButtonVariant;
+  size?: Ol8IconButtonSize;
+  shape?: Ol8IconButtonShape;
+  disabled?: boolean;
+  loading?: boolean;
+  pressed?: boolean;
+  type?: 'button' | 'submit' | 'reset';
+  material?: 'regular' | 'gem';
+  className?: string;
+}
+
+/**
+ * @param icon  registry name, e.g. "add"
+ * @param label accessible name — REQUIRED, throws if empty
+ */
+export declare function renderIconButton(
+  icon: Ol8IconName,
+  label: string,
+  options?: Ol8IconButtonOptions,
+): string;
+
+export declare function hydrateIconButtons(root?: ParentNode): void;

package/src/molecules/icon-button/icon-button.js

@@ -0,0 +1,121 @@
+/**
+ * Oneli8 · Icon Button — headless behavior.
+ *
+ * Figma (86:2): "Icon is an INSTANCE_SWAP sourced from the governed 24px Icon
+ * Library atom and resized only through Icon Frame; Accessible Name is
+ * mandatory. Size and State are deterministic visual evidence. Runtime
+ * disabled, loading, pressed, motion, tooltip policy, and native button
+ * semantics live in code."
+ *
+ * "Accessible Name is mandatory" is enforced here, not left to reviewers.
+ */
+import { renderIcon, renderIconSvg, isOl8IconName } from '../../atoms/icon/icon.js';
+import { GEM_VARIANTS } from '../button/button.js';
+
+export const OL8_ICON_BUTTON_VARIANTS = ['primary', 'secondary', 'quiet', 'destructive'];
+export const OL8_ICON_BUTTON_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+export const OL8_ICON_BUTTON_SHAPES = ['rounded', 'circle'];
+
+/** Artwork sizes as BUILT in Figma: 18 / 18 / 24 / 24. */
+export function artworkSizeForIconButton(size) {
+  return size === 'comfortable' || size === 'large' ? 24 : 18;
+}
+
+/**
+ * @param {string} icon    registry name, e.g. "add"
+ * @param {string} label   accessible name — REQUIRED
+ * @param {{variant?:string,size?:string,shape?:string,disabled?:boolean,
+ *          loading?:boolean,pressed?:boolean,type?:string,className?:string}} [options]
+ */
+export function renderIconButton(icon, label, options = {}) {
+  const {
+    variant = 'primary', size = 'standard', shape = 'rounded',
+    disabled = false, loading = false, pressed, type = 'button', className, material = 'regular',
+  } = options;
+
+  if (!isOl8IconName(icon)) throw new Error(`[ol8] unknown icon "${icon}"`);
+  if (!OL8_ICON_BUTTON_VARIANTS.includes(variant)) throw new Error(`[ol8] unknown icon-button variant "${variant}"`);
+  if (!OL8_ICON_BUTTON_SIZES.includes(size)) throw new Error(`[ol8] unknown icon-button size "${size}"`);
+  if (!OL8_ICON_BUTTON_SHAPES.includes(shape)) throw new Error(`[ol8] unknown icon-button shape "${shape}"`);
+  if (material === 'gem' && !GEM_VARIANTS.includes(variant)) {
+    throw new Error(`[ol8] Gem has no approved treatment for "${variant}" — Figma 100:3 says Quiet and Destructive use the regular material.`);
+  }
+  if (!label || !String(label).trim()) {
+    throw new Error('[ol8] Icon Button requires an accessible name — Figma marks it mandatory (86:2).');
+  }
+
+  const artwork = artworkSizeForIconButton(size);
+  const glyph = loading
+    ? `<span class="ol8-icon" aria-hidden="true">${renderIconSvg('loading')}</span>`
+    : renderIcon(icon, { size: artwork });
+
+  const attrs = [
+    `class="ol8-icon-btn ol8-icon-btn--${variant}${className ? ` ${className}` : ''}"`,
+    `type="${type}"`,
+    `data-ol8-size="${size}"`,
+    shape === 'circle' ? 'data-ol8-shape="circle"' : '',
+    `aria-label="${escapeAttr(label)}"`,
+    disabled || loading ? 'disabled' : '',
+    loading ? 'data-ol8-loading="true" aria-busy="true"' : '',
+    pressed !== undefined ? `aria-pressed="${pressed}"` : '',
+    material === 'gem' ? 'data-ol8-material="gem"' : '',
+  ].filter(Boolean).join(' ');
+
+  return `<button ${attrs}><span class="ol8-icon-btn__surface">${glyph}</span></button>`;
+}
+
+/**
+ * Enforces the runtime contract on existing `.ol8-icon-btn` markup. Idempotent.
+ * Wraps a bare glyph in the required surface, and reports any button that has
+ * no accessible name — the one rule Figma calls mandatory.
+ */
+export function hydrateIconButtons(root = document) {
+  const unnamed = [];
+  for (const el of root.querySelectorAll('.ol8-icon-btn')) {
+    if (!el.hasAttribute('type') && el.tagName === 'BUTTON') el.setAttribute('type', 'button');
+
+    // The protected target must always wrap a visible surface.
+    if (!el.querySelector(':scope > .ol8-icon-btn__surface')) {
+      const surface = document.createElement('span');
+      surface.className = 'ol8-icon-btn__surface';
+      while (el.firstChild) surface.appendChild(el.firstChild);
+      el.appendChild(surface);
+    }
+
+    const loading = el.dataset.ol8Loading === 'true';
+    if (loading) {
+      el.setAttribute('aria-busy', 'true');
+      el.disabled = true;
+      const surface = el.querySelector(':scope > .ol8-icon-btn__surface');
+      if (!surface.querySelector('[data-ol8-loading-glyph]')) {
+        surface.innerHTML = `<span class="ol8-icon" aria-hidden="true" data-ol8-loading-glyph="true">${renderIconSvg('loading')}</span>`;
+      }
+    } else {
+      el.removeAttribute('aria-busy');
+    }
+
+    if (!accessibleName(el)) unnamed.push(el);
+  }
+  if (unnamed.length) {
+    console.error(`[ol8] ${unnamed.length} icon button(s) have no accessible name; Figma marks it mandatory.`, unnamed);
+  }
+  return { unnamed };
+}
+
+function accessibleName(el) {
+  const aria = el.getAttribute('aria-label');
+  if (aria && aria.trim()) return aria.trim();
+  const labelledby = el.getAttribute('aria-labelledby');
+  if (labelledby) {
+    const text = labelledby.split(/\s+/)
+      .map(id => el.ownerDocument.getElementById(id)?.textContent ?? '')
+      .join(' ').trim();
+    if (text) return text;
+  }
+  // Visible text that is not aria-hidden also names the control.
+  const clone = el.cloneNode(true);
+  for (const h of clone.querySelectorAll('[aria-hidden="true"]')) h.remove();
+  return clone.textContent.trim();
+}
+
+function escapeAttr(v) { return String(v).replace(/&/g,'&amp;').replace(/"/g,'&quot;').replace(/</g,'&lt;'); }

package/src/molecules/icon-button/index.d.ts

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

package/src/molecules/icon-button/index.js

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

package/src/molecules/index.d.ts

@@ -0,0 +1,10 @@
+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

@@ -0,0 +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';