@oneli8/core 1.0.0-beta.3

package/src/molecules/button/button.css

@@ -0,0 +1,193 @@
+/**
+ * Oneli8 · Button
+ * Figma: section "Button" (1034:9968) — Primary 15:823, Secondary 15:824,
+ *        Quiet 15:825, Destructive 15:826. 4 families × 4 sizes × 6 states.
+ *
+ * The governing rule comes from the Figma component description itself:
+ *
+ *   "State → deterministic visual evidence … Runtime-only native button
+ *    semantics, disabled, loading, pressed, fullWidth and iconMotion remain
+ *    implemented and tested in code; they must not become fake visual axes."
+ *
+ * So the six Figma States are NOT six markup variants:
+ *   Default  → the base rule
+ *   Hover    → :hover
+ *   Pressed  → :active  (and [aria-pressed="true"] for toggles)
+ *   Focus    → :focus-visible
+ *   Disabled → [disabled]           (native, not a class)
+ *   Loading  → [data-ol8-loading]   (which also implies disabled + aria-busy)
+ *
+ * There is no .ol8-btn--hover. Emitting one is a bug.
+ */
+
+.ol8-btn {
+  /* Per-variant channels. Families set these; the base rule never hardcodes. */
+  --_bg: transparent;
+  --_fg: currentColor;
+  --_bd: transparent;
+  --_bw: 0px;
+
+  /* Size channels, defaulted to Standard. */
+  --_h:    var(--ol8-component-button-height-standard);
+  --_px:   var(--ol8-component-button-paddinginline-standard);
+  --_r:    var(--ol8-component-button-radius-standard);
+  --_gap:  var(--ol8-component-button-gap-compact);
+  --_icon: var(--ol8-size-icon-small);
+
+  box-sizing: border-box;          /* Figma strokes are inside the frame */
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--_gap);
+  block-size: var(--_h);
+  padding-inline: var(--_px);
+  padding-block: 0;
+  border: var(--_bw) solid var(--_bd);
+  border-radius: var(--_r);
+  background: var(--_bg);
+  color: var(--_fg);
+
+  font-family: var(--ol8-font-family-functional);
+  font-size: var(--ol8-font-size-016);
+  line-height: var(--ol8-font-line-024);
+  font-weight: var(--ol8-font-weight-regular);
+  letter-spacing: 0;
+  /* AR One Sans variable axis. Figma sets this on every functional text node;
+     omitting it shifts glyph advances and the button measures narrow. */
+  font-variation-settings: var(--ol8-font-variation-functional);
+
+  cursor: pointer;
+  user-select: none;
+  white-space: nowrap;
+  text-decoration: none;           /* when rendered as <a class="ol8-btn"> */
+  -webkit-appearance: none;
+  appearance: none;
+}
+
+.ol8-btn__label { white-space: nowrap; }
+
+/* Button size governs icon size — the Figma Icon Frame is driven by the
+   button, never set on the glyph. Higher specificity than .ol8-icon's own
+   [data-ol8-icon-size] rule, deliberately. */
+.ol8-btn .ol8-icon { --_ol8-icon-size: var(--_icon); }
+
+/* ---- Size (Figma: Size variant axis) --------------------------------- */
+.ol8-btn[data-ol8-size="compact"] {
+  --_h: var(--ol8-component-button-height-compact);
+  --_px: var(--ol8-component-button-paddinginline-compact);
+  --_r: var(--ol8-component-button-radius-compact);
+  --_gap: var(--ol8-component-button-gap-compact);
+  --_icon: var(--ol8-size-icon-small);
+}
+.ol8-btn[data-ol8-size="standard"] {
+  --_h: var(--ol8-component-button-height-standard);
+  --_px: var(--ol8-component-button-paddinginline-standard);
+  --_r: var(--ol8-component-button-radius-standard);
+  --_gap: var(--ol8-component-button-gap-compact);      /* shared, by design */
+  --_icon: var(--ol8-size-icon-small);
+}
+.ol8-btn[data-ol8-size="comfortable"] {
+  --_h: var(--ol8-component-button-height-comfortable);
+  --_px: var(--ol8-component-button-paddinginline-comfortable);
+  --_r: var(--ol8-component-button-radius-comfortable);
+  --_gap: var(--ol8-component-button-gap-comfortable);
+  --_icon: var(--ol8-size-icon-standard);
+}
+.ol8-btn[data-ol8-size="large"] {
+  --_h: var(--ol8-component-button-height-large);
+  --_px: var(--ol8-component-button-paddinginline-large);
+  --_r: var(--ol8-component-button-radius-large);
+  --_gap: var(--ol8-component-button-gap-comfortable);  /* shared, by design */
+  --_icon: var(--ol8-size-icon-standard);
+}
+
+/* ---- Family: Primary ------------------------------------------------- */
+.ol8-btn--primary { --_bg: var(--ol8-color-actionprimary-default); --_fg: var(--ol8-color-actionprimary-content); }
+.ol8-btn--primary:hover:not(:disabled):not([data-ol8-loading]) { --_bg: var(--ol8-color-actionprimary-hover); }
+.ol8-btn--primary:active:not(:disabled):not([data-ol8-loading]),
+.ol8-btn--primary[aria-pressed="true"]:not(:disabled)          { --_bg: var(--ol8-color-actionprimary-pressed); }
+.ol8-btn--primary:disabled, .ol8-btn--primary[data-ol8-loading] {
+  --_bg: var(--ol8-color-actionprimary-disabled);
+  --_fg: var(--ol8-color-actionprimary-disabledcontent);
+}
+
+/* ---- Family: Destructive (same shape as Primary) --------------------- */
+.ol8-btn--destructive { --_bg: var(--ol8-color-actiondestructive-default); --_fg: var(--ol8-color-actiondestructive-content); }
+.ol8-btn--destructive:hover:not(:disabled):not([data-ol8-loading]) { --_bg: var(--ol8-color-actiondestructive-hover); }
+.ol8-btn--destructive:active:not(:disabled):not([data-ol8-loading]),
+.ol8-btn--destructive[aria-pressed="true"]:not(:disabled)          { --_bg: var(--ol8-color-actiondestructive-pressed); }
+.ol8-btn--destructive:disabled, .ol8-btn--destructive[data-ol8-loading] {
+  --_bg: var(--ol8-color-actiondestructive-disabled);
+  --_fg: var(--ol8-color-actiondestructive-disabledcontent);
+}
+
+/* ---- Family: Secondary ----------------------------------------------
+   Secondary and Quiet carry byte-identical color roles in Figma. The ONLY
+   differentiator is this boundary: Secondary has a 2px stroke whose color
+   tracks the content color; Quiet has none. Verified — Quiet's node binds no
+   --ol8-component-button-secondaryboundary at all.                        */
+.ol8-btn--secondary {
+  --_bw: var(--ol8-component-button-secondaryboundary);
+  --_bg: var(--ol8-color-actionsecondary-surfacedefault);
+  --_fg: var(--ol8-color-actionsecondary-contentdefault);
+  --_bd: var(--ol8-color-actionsecondary-contentdefault);
+}
+.ol8-btn--secondary:hover:not(:disabled):not([data-ol8-loading]) {
+  --_bg: var(--ol8-color-actionsecondary-surfacehover);
+  --_fg: var(--ol8-color-actionsecondary-contenthover);
+  --_bd: var(--ol8-color-actionsecondary-contenthover);
+}
+.ol8-btn--secondary:active:not(:disabled):not([data-ol8-loading]),
+.ol8-btn--secondary[aria-pressed="true"]:not(:disabled) {
+  --_bg: var(--ol8-color-actionsecondary-surfacepressed);
+  --_fg: var(--ol8-color-actionsecondary-contentpressed);
+  --_bd: var(--ol8-color-actionsecondary-contentpressed);
+}
+.ol8-btn--secondary:disabled, .ol8-btn--secondary[data-ol8-loading] {
+  --_bg: var(--ol8-color-actionsecondary-surfacedisabled);
+  --_fg: var(--ol8-color-actionsecondary-contentdisabled);
+  --_bd: var(--ol8-color-actionsecondary-contentdisabled);
+}
+
+/* ---- Family: Quiet (identical colors, no boundary) ------------------- */
+.ol8-btn--quiet {
+  --_bg: var(--ol8-color-actionquiet-surfacedefault);
+  --_fg: var(--ol8-color-actionquiet-contentdefault);
+}
+.ol8-btn--quiet:hover:not(:disabled):not([data-ol8-loading]) {
+  --_bg: var(--ol8-color-actionquiet-surfacehover);
+  --_fg: var(--ol8-color-actionquiet-contenthover);
+}
+.ol8-btn--quiet:active:not(:disabled):not([data-ol8-loading]),
+.ol8-btn--quiet[aria-pressed="true"]:not(:disabled) {
+  --_bg: var(--ol8-color-actionquiet-surfacepressed);
+  --_fg: var(--ol8-color-actionquiet-contentpressed);
+}
+.ol8-btn--quiet:disabled, .ol8-btn--quiet[data-ol8-loading] {
+  --_bg: var(--ol8-color-actionquiet-surfacedisabled);
+  --_fg: var(--ol8-color-actionquiet-contentdisabled);
+}
+
+/* ---- Focus ----------------------------------------------------------
+   Figma draws the focus ring as an INSIDE stroke, so the focused variant is
+   exactly the same size as the unfocused one (83×42 either way, Standard).
+   An inset box-shadow reproduces that without disturbing layout or fighting
+   Secondary's own 2px boundary — `outline` would sit outside and grow it.  */
+.ol8-btn:focus-visible {
+  outline: none;
+  box-shadow: inset 0 0 0 var(--ol8-focus-ring-innerwidth) var(--ol8-color-focus-outer);
+}
+
+/* ---- Disabled / Loading --------------------------------------------- */
+.ol8-btn:disabled, .ol8-btn[data-ol8-loading] { cursor: not-allowed; }
+.ol8-btn[data-ol8-loading] { cursor: progress; }
+
+/* "Platform motion adapters may rotate it; Reduced Motion keeps the static
+   busy mark." — Figma 379:7. Rotation is opt-in and motion-guarded. */
+@media (prefers-reduced-motion: no-preference) {
+  .ol8-btn[data-ol8-loading] .ol8-btn__spinner > svg { animation: ol8-spin 900ms linear infinite; }
+}
+@keyframes ol8-spin { to { transform: rotate(360deg); } }
+
+/* ---- fullWidth (runtime-only, per the Figma description) ------------- */
+.ol8-btn[data-ol8-fullwidth] { display: flex; inline-size: 100%; }

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

@@ -0,0 +1,51 @@
+/**
+ * Button (MOLECULE) — headless behavior. Native semantics, disabled, loading,
+ * pressed and fullWidth live here, never as visual-only axes.
+ */
+import type { Ol8IconName } from '../../atoms/icon/icons.generated.js';
+
+export type Ol8ButtonVariant = 'primary' | 'secondary' | 'quiet' | 'destructive';
+export type Ol8ButtonSize = 'compact' | 'standard' | 'comfortable' | 'large';
+export type Ol8Material = 'regular' | 'gem';
+/** Gem is approved for Primary and Secondary only (Figma 100:3). */
+export type Ol8GemVariant = 'primary' | 'secondary';
+
+export declare const OL8_BUTTON_VARIANTS: readonly Ol8ButtonVariant[];
+export declare const OL8_BUTTON_SIZES: readonly Ol8ButtonSize[];
+export declare const OL8_MATERIALS: readonly Ol8Material[];
+export declare const GEM_VARIANTS: readonly Ol8GemVariant[];
+
+/** Compact+Standard take the 18px icon; Comfortable+Large take 24px. */
+export declare function iconSizeForButton(size: Ol8ButtonSize): 18 | 24;
+
+export interface Ol8ButtonOptions {
+  variant?: Ol8ButtonVariant;
+  size?: Ol8ButtonSize;
+  leadingIcon?: Ol8IconName;
+  trailingIcon?: Ol8IconName;
+  disabled?: boolean;
+  loading?: boolean;
+  /** Emits aria-pressed. Omit entirely for a non-toggle button. */
+  pressed?: boolean;
+  fullWidth?: boolean;
+  /** Renders an <a> instead of a <button>. */
+  href?: string;
+  /** Ignored when href is set. Defaults to "button", never a stray submit. */
+  type?: 'button' | 'submit' | 'reset';
+  /** Throws for quiet and destructive: Gem has no approved treatment there. */
+  material?: Ol8Material;
+  /**
+   * By default the spinner takes the leading slot so the button never shows two
+   * competing glyphs. Set true for Figma's literal reading (icon AND spinner).
+   */
+  keepLeadingIconWhileLoading?: boolean;
+  className?: string;
+}
+
+/** @throws if variant, size or material is unknown, or Gem is asked for on quiet/destructive. */
+export declare function renderButton(label: string, options?: Ol8ButtonOptions): string;
+
+/** Enforces the runtime contract on existing `.ol8-btn` markup. Idempotent. */
+export declare function hydrateButtons(root?: ParentNode): void;
+
+export declare function setButtonLoading(el: Element, loading: boolean): void;

package/src/molecules/button/button.js

@@ -0,0 +1,134 @@
+/**
+ * Oneli8 · Button — headless behavior.
+ *
+ * The Figma component description is explicit that native semantics, disabled,
+ * loading, pressed and fullWidth "remain implemented and tested in code; they
+ * must not become fake visual axes." This module is that code.
+ */
+import { renderIcon, renderIconSvg, isOl8IconName } from '../../atoms/icon/icon.js';
+
+export const OL8_BUTTON_VARIANTS = ['primary', 'secondary', 'quiet', 'destructive'];
+export const OL8_BUTTON_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+export const OL8_MATERIALS = ['regular', 'gem'];
+/** Gem is approved for Primary and Secondary only (Figma 100:3). */
+export const GEM_VARIANTS = ['primary', 'secondary'];
+
+/** Compact+Standard take the 18px icon; Comfortable+Large take 24px. */
+export function iconSizeForButton(size) {
+  return size === 'comfortable' || size === 'large' ? 24 : 18;
+}
+
+/**
+ * @param {string} label
+ * @param {{variant?:string,size?:string,leadingIcon?:string,trailingIcon?:string,
+ *          disabled?:boolean,loading?:boolean,pressed?:boolean,fullWidth?:boolean,
+ *          href?:string,type?:string,className?:string}} [options]
+ */
+export function renderButton(label, options = {}) {
+  const {
+    variant = 'primary', size = 'standard', leadingIcon, trailingIcon,
+    disabled = false, loading = false, pressed, fullWidth = false,
+    href, type = 'button', className, material = 'regular',
+    keepLeadingIconWhileLoading = false,
+  } = options;
+
+  if (!OL8_BUTTON_VARIANTS.includes(variant)) throw new Error(`[ol8] unknown button variant "${variant}"`);
+  if (!OL8_BUTTON_SIZES.includes(size)) throw new Error(`[ol8] unknown button size "${size}"`);
+  if (!OL8_MATERIALS.includes(material)) throw new Error(`[ol8] unknown material "${material}"`);
+  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.`);
+  }
+
+  const isLink = typeof href === 'string';
+  const inert = disabled || loading;
+  const iconSize = iconSizeForButton(size);
+
+  const attrs = [
+    `class="ol8-btn ol8-btn--${variant}${className ? ` ${className}` : ''}"`,
+    `data-ol8-size="${size}"`,
+    isLink ? (inert ? 'role="button" aria-disabled="true" tabindex="-1"' : `href="${escapeAttr(href)}"`)
+           : `type="${type}"`,
+    !isLink && inert ? 'disabled' : '',
+    loading ? 'data-ol8-loading="true" aria-busy="true"' : '',
+    pressed !== undefined ? `aria-pressed="${pressed}"` : '',
+    fullWidth ? 'data-ol8-fullwidth="true"' : '',
+    material === 'gem' ? 'data-ol8-material="gem"' : '',
+    loading && keepLeadingIconWhileLoading ? 'data-ol8-loading-keep-icon="true"' : '',
+  ].filter(Boolean).join(' ');
+
+  // Loading + leading icon is genuinely ambiguous in the source. Figma's
+  // codegen emits BOTH the leading icon and the spinner, but the measured
+  // Loading widths (101/107/122/134 = default + spinner + gap) come from
+  // variants that carry no leading icon, so they do not disambiguate.
+  //
+  // Default here: the spinner TAKES the leading slot, so the button never
+  // shows two competing leading glyphs and its width stays predictable.
+  // Pass keepLeadingIconWhileLoading to get Figma's literal reading.
+  const spinner = `<span class="ol8-btn__spinner ol8-icon" aria-hidden="true">${renderIconSvg('loading')}</span>`;
+  const leadingGlyph = leadingIcon ? renderIcon(leadingIcon, { size: iconSize }) : '';
+  const leading = loading
+    ? (keepLeadingIconWhileLoading ? leadingGlyph + spinner : spinner)
+    : leadingGlyph;
+  const trailing = trailingIcon ? renderIcon(trailingIcon, { size: iconSize }) : '';
+
+  const tag = isLink ? 'a' : 'button';
+  return `<${tag} ${attrs}>${leading}<span class="ol8-btn__label">${escapeText(label)}</span>${trailing}</${tag}>`;
+}
+
+/**
+ * Enforces the runtime contract on existing `.ol8-btn` markup. Idempotent.
+ *   - <button> gets an explicit type (default "button", never a stray submit)
+ *   - [data-ol8-loading] implies disabled + aria-busy and grows a spinner
+ *   - links can't be natively disabled, so they get aria-disabled + tabindex=-1
+ *     and their activation is swallowed
+ */
+export function hydrateButtons(root = document) {
+  for (const el of root.querySelectorAll('.ol8-btn')) {
+    const isLink = el.tagName === 'A';
+    const loading = el.dataset.ol8Loading === 'true';
+
+    if (!isLink && !el.hasAttribute('type')) el.setAttribute('type', 'button');
+
+    if (loading) {
+      el.setAttribute('aria-busy', 'true');
+      if (isLink) { el.setAttribute('aria-disabled', 'true'); el.setAttribute('tabindex', '-1'); }
+      else el.disabled = true;
+
+      if (!el.querySelector('.ol8-btn__spinner')) {
+        // Same call as renderButton: the spinner takes the leading slot unless
+        // data-ol8-loading-keep-icon opts into Figma's literal both-glyphs read.
+        if (el.dataset.ol8LoadingKeepIcon !== 'true') {
+          el.querySelector(':scope > .ol8-icon:first-child')?.remove();
+        }
+        const spinner = document.createElement('span');
+        spinner.className = 'ol8-btn__spinner ol8-icon';
+        spinner.setAttribute('aria-hidden', 'true');
+        spinner.innerHTML = renderIconSvg('loading');
+        const keep = el.dataset.ol8LoadingKeepIcon === 'true';
+        const after = keep ? el.querySelector(':scope > .ol8-icon:first-child') : null;
+        if (after) after.after(spinner); else el.prepend(spinner);
+      }
+    } else {
+      el.removeAttribute('aria-busy');
+      el.querySelector('.ol8-btn__spinner')?.remove();
+    }
+
+    if (isLink && (el.getAttribute('aria-disabled') === 'true') && !el.dataset.ol8InertBound) {
+      el.addEventListener('click', swallow);
+      el.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') swallow(e); });
+      el.dataset.ol8InertBound = 'true';
+    }
+  }
+}
+
+function swallow(event) { event.preventDefault(); event.stopPropagation(); }
+
+/** Flip a button into or out of its loading state at runtime. */
+export function setButtonLoading(el, loading) {
+  if (loading) el.dataset.ol8Loading = 'true';
+  else delete el.dataset.ol8Loading;
+  hydrateButtons(el.parentNode ?? document);
+}
+
+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/button/index.d.ts

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

package/src/molecules/button/index.js

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

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

@@ -0,0 +1,190 @@
+/**
+ * Oneli8 · Choice Item (MOLECULE)
+ * Figma: Documentation / Molecule / Choice Item
+ *   Checkbox 252:301 (24 variants) · Radio 331:1309 (16) · Switch 825:1591 (16)
+ *
+ * From the Figma description (252:301):
+ *   "Selection maps Unchecked/Checked/Mixed to checked/indeterminate;
+ *    Availability maps enabled/disabled ... The indicator is a shared
+ *    selection atom, not local artwork. Native input, name/value, required,
+ *    reset, form submission, and onCheckedChange live in code."
+ *
+ * So the molecule is: a real <input>, the selection-indicator atom, a label,
+ * an optional description — and NOTHING that duplicates native behaviour.
+ *
+ * ANATOMY (Figma 266:257 / 252:74 / 252:77)
+ *   <label class=ol8-choice>          the whole row is the target
+ *     input                            visually hidden, still focusable
+ *     __surface                        hover / pressed / gem wash, bleeds 9px inline
+ *     __indicator                      slot: indicator wide, label-line tall
+ *     __content                        label + optional description
+ *
+ * ROW GEOMETRY — every size resolves to the same 48px minimum row:
+ *   size         gap  indicator  slot h   label          padding-block
+ *   compact       6      18        18     Body/Small      15
+ *   standard      9      18        24     Body/Medium     12
+ *   comfortable   9      24        24     Body/Medium     12
+ *   large         9      24        30     Body/Large       9
+ * padding-block is derived: (48 - slot height) / 2.
+ */
+
+.ol8-choice {
+  --_gap:    var(--ol8-component-choice-gap-standard);
+  --_slot-h: var(--ol8-font-line-024);
+  --_pad:    calc((var(--ol8-component-choice-rowminimum) - var(--_slot-h)) / 2);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+  --_indicator: var(--ol8-size-icon-small);
+  /* The hover / pressed / focus wash bleeds outside the text column. */
+  --_bleed: var(--ol8-dimension-scale-009);
+
+  box-sizing: border-box;
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  gap: var(--_gap);
+  min-block-size: var(--ol8-component-choice-rowminimum);
+  padding-block: var(--_pad);
+  font-family: var(--ol8-font-family-functional);
+  font-variation-settings: var(--ol8-font-variation-functional);
+  cursor: pointer;
+}
+.ol8-choice[data-ol8-availability="disabled"] { cursor: not-allowed; }
+
+/* ---- Size ------------------------------------------------------------ */
+.ol8-choice[data-ol8-size="compact"] {
+  --_gap: var(--ol8-component-choice-gap-compact);
+  --_slot-h: var(--ol8-font-line-018);
+  --_label-size: var(--ol8-font-size-012);
+  --_label-line: var(--ol8-font-line-018);
+  --_indicator: var(--ol8-size-icon-small);
+}
+.ol8-choice[data-ol8-size="standard"] {
+  --_slot-h: var(--ol8-font-line-024);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+  --_indicator: var(--ol8-size-icon-small);
+}
+.ol8-choice[data-ol8-size="comfortable"] {
+  --_slot-h: var(--ol8-font-line-024);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+  --_indicator: var(--ol8-size-icon-standard);
+}
+.ol8-choice[data-ol8-size="large"] {
+  --_slot-h: var(--ol8-font-line-030);
+  --_label-size: var(--ol8-font-size-021);
+  --_label-line: var(--ol8-font-line-030);
+  --_indicator: var(--ol8-size-icon-standard);
+}
+/* Compact's label carries the Body/Small tracking. */
+.ol8-choice[data-ol8-size="compact"] .ol8-choice__label { letter-spacing: 1px; }
+
+/* ---- The native input owns everything semantic ----------------------- */
+.ol8-choice__input {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  opacity: 0;
+  pointer-events: none;
+  /* No margin reset needed — it is absolutely positioned, so margin cannot
+     affect layout. The structure lint would reject one regardless. */
+}
+
+/* ---- Wash: hover, pressed, focus, gem -------------------------------- */
+.ol8-choice__surface {
+  position: absolute;
+  inset-block: 0;
+  inset-inline: calc(-1 * var(--_bleed));
+  border-radius: var(--ol8-shape-radius-medium);
+  pointer-events: none;
+}
+.ol8-choice:hover:not([data-ol8-availability="disabled"]) > .ol8-choice__surface,
+.ol8-choice:active:not([data-ol8-availability="disabled"]) > .ol8-choice__surface {
+  background: var(--ol8-color-selection-surface);
+}
+
+/* Two nested rings, both visible — outer 3px, inner 3px at a 2px inset.
+   This is the same two-tone ring the Icon Button focus tokens describe. */
+.ol8-choice:has(> .ol8-choice__input:focus-visible) > .ol8-choice__surface {
+  border: var(--ol8-focus-ring-outerwidth) solid var(--ol8-color-focus-outer);
+}
+.ol8-choice:has(> .ol8-choice__input:focus-visible) > .ol8-choice__surface::after {
+  content: "";
+  position: absolute;
+  inset: 2px;
+  border: var(--ol8-focus-ring-innerwidth) solid var(--ol8-color-focus-inner);
+  border-radius: 7px;
+}
+
+/* ---- Indicator slot -------------------------------------------------- */
+.ol8-choice__indicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  flex: none;
+  inline-size: var(--_indicator);
+  block-size: var(--_slot-h);
+}
+
+/* Invalid draws an extra boundary over the indicator, same shape. */
+.ol8-choice[data-ol8-invalid="true"] .ol8-choice__indicator::after {
+  content: "";
+  position: absolute;
+  inline-size: var(--_indicator);
+  block-size: var(--_indicator);
+  border: var(--ol8-component-checkbox-boundary) solid var(--ol8-color-feedbackcritical-inlinecontent);
+  border-radius: var(--ol8-component-checkbox-radius-compact);
+  pointer-events: none;
+}
+.ol8-choice[data-ol8-size="comfortable"][data-ol8-invalid="true"] .ol8-choice__indicator::after,
+.ol8-choice[data-ol8-size="large"][data-ol8-invalid="true"] .ol8-choice__indicator::after {
+  border-radius: var(--ol8-component-checkbox-radius-comfortable);
+}
+.ol8-choice--radio[data-ol8-invalid="true"] .ol8-choice__indicator::after {
+  border-radius: var(--ol8-shape-radius-full);
+}
+
+/* ---- Content --------------------------------------------------------- */
+.ol8-choice__content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ol8-dimension-scale-003);
+  flex: 1 0 0;
+  min-inline-size: 0;
+  position: relative;
+}
+.ol8-choice__label {
+  font-size: var(--_label-size);
+  line-height: var(--_label-line);
+  font-weight: var(--ol8-font-weight-regular);
+  color: var(--ol8-color-text-primary);
+  overflow-wrap: break-word;
+}
+.ol8-choice__description {
+  font-size: var(--ol8-font-size-012);
+  line-height: var(--ol8-font-line-018);
+  letter-spacing: 0.12px;
+  color: var(--ol8-color-text-secondary);
+  overflow-wrap: break-word;
+}
+.ol8-choice[data-ol8-availability="disabled"] .ol8-choice__label,
+.ol8-choice[data-ol8-availability="disabled"] .ol8-choice__description {
+  color: var(--ol8-color-text-disabled);
+}
+
+/* ---- Gem material ----------------------------------------------------
+   "Gem is one Boolean material adapter over the same anatomy; Regular
+   remains the default." A wash on the row, not a different component. */
+.ol8-choice[data-ol8-material="gem"] > .ol8-choice__surface {
+  background: var(--ol8-material-gem-color-quiet-environmentalface);
+  border: 1px solid var(--ol8-material-gem-color-cutedge-high);
+  border-radius: var(--ol8-shape-radius-standard);
+  inset-inline: 0;
+}
+@media (prefers-reduced-transparency: reduce) {
+  .ol8-choice[data-ol8-material="gem"] > .ol8-choice__surface {
+    background: var(--ol8-material-gem-color-quiet-opaqueequivalent);
+  }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Choice Item (MOLECULE) — headless behavior around a real <input>. It does not
+ * reimplement toggling, focus or form participation; the native input does all
+ * of it. `indeterminate` is the one thing markup cannot express, which is why
+ * the Mixed state needs hydration and the other states do not.
+ */
+import type { Ol8IconName } from '../../atoms/icon/icons.generated.js';
+import type { Ol8Selection, Ol8SelectionSize } from '../../atoms/selection-indicator/selection-indicator.js';
+
+export type Ol8ChoiceKind = 'checkbox' | 'radio' | 'switch';
+export type Ol8ChoiceSize = 'compact' | 'standard' | 'comfortable' | 'large';
+
+export declare const OL8_CHOICE_KINDS: readonly Ol8ChoiceKind[];
+export declare const OL8_CHOICE_SIZES: readonly Ol8ChoiceSize[];
+
+/** The molecule's four sizes map onto the atom's two. */
+export declare function indicatorSizeFor(size: Ol8ChoiceSize): Ol8SelectionSize;
+
+/** Figma's Selection axis, derived from native input state. */
+export declare function selectionStateFor(
+  kind: Ol8ChoiceKind,
+  state?: { checked?: boolean; mixed?: boolean },
+): Ol8Selection;
+
+export interface Ol8ChoiceItemOptions {
+  size?: Ol8ChoiceSize;
+  checked?: boolean;
+  /** Checkbox only. Renders Mixed; the real indeterminate flag is set on hydrate. */
+  mixed?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  /** Associated with aria-describedby, kept out of the accessible name. */
+  description?: string;
+  name?: string;
+  value?: string;
+  required?: boolean;
+  id?: string;
+  material?: 'regular' | 'gem';
+  className?: string;
+}
+
+export declare function renderChoiceItem(
+  kind: Ol8ChoiceKind,
+  label: string,
+  options?: Ol8ChoiceItemOptions,
+): string;
+
+/** Applies the JS-only indeterminate flag to Mixed rows. Idempotent. */
+export declare function hydrateChoiceItems(root?: ParentNode): void;
+
+/** Repaints one row's indicator from its input's current state. */
+export declare function syncIndicator(row: Element): void;
+
+export declare function setChoiceMixed(row: Element, mixed: boolean): void;