@oneli8/core 1.0.0-beta.3

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

@@ -0,0 +1,153 @@
+/**
+ * Oneli8 · Choice Item (MOLECULE) — headless behavior.
+ *
+ * Figma (252:301): "Native input, name/value, required, reset, form
+ * submission, and onCheckedChange live in code." This module is that code —
+ * and deliberately nothing more. It does not reimplement toggling, focus or
+ * form participation; a real <input> already does all of it.
+ *
+ * The one thing that genuinely cannot be expressed in markup or CSS is
+ * `indeterminate`, which is a JS-only property. That is why the Mixed state
+ * needs hydration and the other states do not.
+ */
+import { renderSelectionIndicator } from '../../atoms/selection-indicator/selection-indicator.js';
+
+export const OL8_CHOICE_KINDS = ['checkbox', 'radio', 'switch'];
+export const OL8_CHOICE_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+
+/** The molecule's four sizes map onto the atom's two. */
+export function indicatorSizeFor(size) {
+  return size === 'comfortable' || size === 'large' ? 'comfortable' : 'compact';
+}
+
+/** Figma's Selection axis, derived from native input state. */
+export function selectionStateFor(kind, { checked = false, mixed = false } = {}) {
+  if (kind === 'checkbox') return mixed ? 'mixed' : checked ? 'checked' : 'unchecked';
+  if (kind === 'radio') return checked ? 'selected' : 'unselected';
+  return checked ? 'on' : 'off';
+}
+
+/**
+ * @param {'checkbox'|'radio'|'switch'} kind
+ * @param {string} label
+ * @param {{size?:string,checked?:boolean,mixed?:boolean,disabled?:boolean,invalid?:boolean,
+ *          description?:string,name?:string,value?:string,required?:boolean,
+ *          id?:string,material?:string,className?:string}} [options]
+ */
+export function renderChoiceItem(kind, label, options = {}) {
+  if (!OL8_CHOICE_KINDS.includes(kind)) throw new Error(`[ol8] unknown choice kind "${kind}"`);
+  const {
+    size = 'standard', checked = false, mixed = false, disabled = false, invalid = false,
+    description, name, value, required = false, id, material = 'regular', className,
+  } = options;
+
+  if (!OL8_CHOICE_SIZES.includes(size)) throw new Error(`[ol8] unknown choice size "${size}"`);
+  if (mixed && kind !== 'checkbox') throw new Error('[ol8] only a checkbox has a Mixed state');
+  if (!label || !String(label).trim()) throw new Error('[ol8] Choice Item requires a label');
+
+  const uid = id ?? `ol8-choice-${Math.random().toString(36).slice(2, 9)}`;
+  const descId = description ? `${uid}-desc` : null;
+  const selection = selectionStateFor(kind, { checked, mixed });
+
+  const inputAttrs = [
+    `type="${kind === 'radio' ? 'radio' : 'checkbox'}"`,
+    kind === 'switch' ? 'role="switch"' : '',
+    `class="ol8-choice__input"`,
+    `id="${uid}"`,
+    name ? `name="${escapeAttr(name)}"` : '',
+    value !== undefined ? `value="${escapeAttr(value)}"` : '',
+    checked ? 'checked' : '',
+    disabled ? 'disabled' : '',
+    required ? 'required' : '',
+    invalid ? 'aria-invalid="true"' : '',
+    descId ? `aria-describedby="${descId}"` : '',
+  ].filter(Boolean).join(' ');
+
+  const rowAttrs = [
+    `class="ol8-choice ol8-choice--${kind}${className ? ` ${className}` : ''}"`,
+    `for="${uid}"`,
+    `data-ol8-size="${size}"`,
+    `data-ol8-kind="${kind}"`,
+    `data-ol8-availability="${disabled ? 'disabled' : 'enabled'}"`,
+    invalid ? 'data-ol8-invalid="true"' : '',
+    mixed ? 'data-ol8-mixed="true"' : '',
+    material === 'gem' ? 'data-ol8-material="gem"' : '',
+  ].filter(Boolean).join(' ');
+
+  const indicator = renderSelectionIndicator(kind, {
+    selection, size: indicatorSizeFor(size), disabled,
+  });
+
+  return `<label ${rowAttrs}>` +
+    `<input ${inputAttrs}>` +
+    `<span class="ol8-choice__surface" aria-hidden="true"></span>` +
+    `<span class="ol8-choice__indicator">${indicator}</span>` +
+    `<span class="ol8-choice__content">` +
+      `<span class="ol8-choice__label">${escapeText(label)}</span>` +
+      (description ? `<span class="ol8-choice__description" id="${descId}">${escapeText(description)}</span>` : '') +
+    `</span></label>`;
+}
+
+/**
+ * Binds every `.ol8-choice` under `root`. Idempotent.
+ * Applies `indeterminate` (JS-only) and keeps the indicator in step with the
+ * input — including radios, where selecting one silently clears its siblings.
+ */
+export function hydrateChoiceItems(root = document) {
+  const rows = [...root.querySelectorAll('.ol8-choice')];
+
+  for (const row of rows) {
+    const input = row.querySelector(':scope > .ol8-choice__input');
+    if (!input) continue;
+
+    input.indeterminate = row.dataset.ol8Mixed === 'true';
+    syncIndicator(row);
+
+    if (row.dataset.ol8ChoiceBound === 'true') continue;
+    input.addEventListener('change', () => {
+      // Any interaction resolves Mixed; the browser has already cleared
+      // `indeterminate` on click, so mirror that in our own state.
+      delete row.dataset.ol8Mixed;
+      syncIndicator(row);
+      // A radio turning on turns its whole group off — repaint the siblings.
+      if (input.type === 'radio' && input.name) {
+        for (const other of (row.ownerDocument ?? document)
+          .querySelectorAll(`input.ol8-choice__input[type="radio"][name="${CSS.escape(input.name)}"]`)) {
+          const otherRow = other.closest('.ol8-choice');
+          if (otherRow && otherRow !== row) syncIndicator(otherRow);
+        }
+      }
+    });
+    row.dataset.ol8ChoiceBound = 'true';
+  }
+  return rows.length;
+}
+
+/** Repaints one row's indicator from the live state of its input. */
+export function syncIndicator(row) {
+  const input = row.querySelector(':scope > .ol8-choice__input');
+  const slot = row.querySelector(':scope > .ol8-choice__indicator');
+  if (!input || !slot) return;
+
+  const kind = row.dataset.ol8Kind ?? 'checkbox';
+  const selection = selectionStateFor(kind, { checked: input.checked, mixed: input.indeterminate });
+
+  row.dataset.ol8Availability = input.disabled ? 'disabled' : 'enabled';
+  slot.innerHTML = renderSelectionIndicator(kind, {
+    selection,
+    size: indicatorSizeFor(row.dataset.ol8Size ?? 'standard'),
+    disabled: input.disabled,
+  });
+}
+
+/** Sets the Mixed (indeterminate) state on a checkbox row. */
+export function setChoiceMixed(row, mixed) {
+  const input = row.querySelector(':scope > .ol8-choice__input');
+  if (!input) return;
+  input.indeterminate = !!mixed;
+  if (mixed) row.dataset.ol8Mixed = 'true'; else delete row.dataset.ol8Mixed;
+  syncIndicator(row);
+}
+
+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-item/index.d.ts

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

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

@@ -0,0 +1 @@
+export * from './choice-item.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,4 @@
+export * from './button/index.js';
+export * from './icon-button/index.js';
+export * from './choice-item/index.js';
+export * from './selection-option/index.js';

package/src/molecules/index.js

@@ -0,0 +1,4 @@
+export * from './button/index.js';
+export * from './icon-button/index.js';
+export * from './choice-item/index.js';
+export * from './selection-option/index.js';

package/src/molecules/selection-option/index.d.ts

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

package/src/molecules/selection-option/index.js

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