@helloimjolopez-pathway/pathway-components 0.0.0-stage → 0.1.0

package/components/_shared/use-reduced-motion.jsx

@@ -0,0 +1,49 @@
+/**
+ * useReducedMotion: does this viewer want motion suppressed?
+ *
+ * WHY A HOOK AND NOT A MEDIA QUERY. The obvious fix for
+ * `prefers-reduced-motion` is a stylesheet rule, and that is exactly what
+ * `widget.jsx` does, correctly, because its transitions live in a `<style>`
+ * block on a class. Every other component in this family sets `transition`
+ * as an INLINE STYLE, and an inline style outranks any stylesheet rule short
+ * of `!important`. So a media query cannot reach them, and on 2026-10-13 the
+ * Accessibility Gate found Dropdown, Action Icon and Dashboard animating at
+ * 150ms for a viewer who had asked for no animation. The value has to be
+ * decided in JS because that is where the value is written.
+ *
+ * Read synchronously in the initialiser rather than in an effect: an effect
+ * runs after the first paint, so a reduced-motion viewer would see one frame
+ * of the thing they opted out of. The listener is still there for a viewer who
+ * changes the setting while the page is open.
+ *
+ * The `typeof window` guard is for a server render and for the jsdom pass in
+ * `check-stories-render.js`, where `matchMedia` may not exist.
+ */
+import { useEffect, useState } from "react";
+
+const QUERY = "(prefers-reduced-motion: reduce)";
+
+const current = () =>
+  typeof window !== "undefined" && typeof window.matchMedia === "function"
+    ? window.matchMedia(QUERY).matches
+    : false;
+
+export function useReducedMotion() {
+  const [reduced, setReduced] = useState(current);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const mq = window.matchMedia(QUERY);
+    setReduced(mq.matches);
+    const onChange = (e) => setReduced(e.matches);
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, []);
+
+  return reduced;
+}
+
+/** `motion(reduced, "background 150ms ease")` → that string, or "none". */
+export function motionOr(reduced, transition) {
+  return reduced ? "none" : transition;
+}

package/components/button/button.jsx

@@ -0,0 +1,512 @@
+/**
+ * Button, Pathway Design System
+ *
+ * Importable React component module. Source of truth for the Button
+ * implementation; the standalone demo (button.html) and the Storybook
+ * stories both consume this.
+ *
+ * Spec:  components/button/button-spec.md
+ * Figma: https://www.figma.com/design/3sw45aVcngFAmpbP6cfrXP/?node-id=40003293-93741
+ */
+
+import React, { useState, useEffect } from "react";
+
+// ─── TOKEN HELPERS ────────────────────────────────────────────────────────────
+// Every name below is MODELESS. The mode is resolved by selector from
+// themes/light.css and themes/midnight.css, so there is no "light-mode" segment
+// and no separate *inverse* token family: an inverted button is this same
+// button inside a [data-theme="midnight"] region. See CLAUDE.md §2.0.
+//
+// SC = semantic-color         (themes/light.css + themes/midnight.css)
+// SL = semantic-layout-units  (layout.css)
+// CL = contextual-layout-units(layout-contextual.css, component metrics)
+// ST = semantic-type          (type.css: a SCALE, composed below, not composites)
+const SC = (p) => `var(--semantic-color-${p})`;
+const SL = (p) => `var(--semantic-layout-units-${p})`;
+const CL = (p) => `var(--contextual-layout-units-${p})`;
+const ST = (p) => `var(--semantic-type-${p})`;
+
+// ─── FILL TOKENS ──────────────────────────────────────────────────────────────
+// Background colour by (buttonStyle, type, interactionState).
+// Outlined/Naked use transparent base + light overlay on hover/pressed.
+// Tertiary's own token family was deleted because it duplicated the quiet
+// primary ramp offset by one step, so Tertiary now reads
+// Fill/Action/Primary/Subtle. That group was called "Primary Dim" until
+// 2026-09-15, when the space-joined suffix was promoted to a real segment
+// because "Primary Dim" read as a tone name rather than a variant of Primary.
+// Negative moved under Status. Disabled is ONE token per tier, not one per type: a
+// disabled control is the same colour whatever it would have been.
+export const FILL = {
+  Fill: {
+    Primary:   { base: SC("fill-action-primary-strong-rest"),              hover: SC("fill-action-primary-strong-hover"),              pressed: SC("fill-action-primary-strong-pressed"),              disabled: SC("fill-action-disabled") },
+    Secondary: { base: SC("fill-action-secondary-rest"),            hover: SC("fill-action-secondary-hover"),            pressed: SC("fill-action-secondary-pressed"),            disabled: SC("fill-action-disabled") },
+    Tertiary:  { base: SC("fill-action-primary-subtle-rest"),          hover: SC("fill-action-primary-subtle-hover"),          pressed: SC("fill-action-primary-subtle-pressed"),          disabled: SC("fill-action-disabled") },
+    Negative:  { base: SC("fill-action-status-negative-strong-rest"),      hover: SC("fill-action-status-negative-strong-hover"),      pressed: SC("fill-action-status-negative-strong-pressed"),      disabled: SC("fill-action-disabled") },
+  },
+  // Outlined and Naked rest on nothing and tint on interaction. The Dim ramps
+  // are exactly that tint, which is what the retired *inverse* hovers were for.
+  Outlined: {
+    Primary:   { base: "transparent", hover: SC("fill-action-primary-subtle-hover"),          pressed: SC("fill-action-primary-subtle-pressed"),          disabled: "transparent" },
+    Secondary: { base: "transparent", hover: SC("fill-action-secondary-hover"),            pressed: SC("fill-action-secondary-pressed"),            disabled: "transparent" },
+    Tertiary:  { base: "transparent", hover: SC("fill-action-primary-subtle-hover"),          pressed: SC("fill-action-primary-subtle-pressed"),          disabled: "transparent" },
+    Negative:  { base: "transparent", hover: SC("fill-action-status-negative-subtle-hover"),  pressed: SC("fill-action-status-negative-subtle-pressed"),  disabled: "transparent" },
+  },
+};
+FILL.Naked = FILL.Outlined;
+
+// ─── FOREGROUND TOKENS ────────────────────────────────────────────────────────
+// Text and Icon were merged into one Foreground tier. That merge is deliberate,
+// not a rename for tidiness: a button is ONE interactive surface, so its label
+// and its icon must not resolve through two ramps that can drift apart.
+//
+// On a solid fill the foreground is Mono, which has only a rest step, white
+// stays white through hover and pressed, so all three states share it.
+export const FG = {
+  Fill: {
+    // READ OFF FIGMA 2026-10-02, node 40003293:93741. Every Fill/Primary variant
+    // binds the paint style Foreground/Action/Primary/On Strong on the label AND
+    // on both icon vectors, in Active, Hover, Focused and Pressed alike, which is
+    // why there is one token here rather than three.
+    //
+    // This said foreground-static-neutral-MONO, and had since before the
+    // September tier rename carried it forward unexamined. Mono is an inversion
+    // anchor, not a rung: #ffffff in Light but #181b2b in Midnight. So a primary
+    // button's label went near-black on a brand fill in Midnight, 3.04:1, under
+    // the 4.5 floor. It survived because both tokens are #ffffff in Light, so
+    // every screenshot looked right, and because the token gates check that a
+    // name RESOLVES, never that it is the right name.
+    Primary:   { base: SC("foreground-action-primary-on-strong"),        hover: SC("foreground-action-primary-on-strong"),        pressed: SC("foreground-action-primary-on-strong"),        disabled: SC("foreground-action-disabled") },
+    Secondary: { base: SC("foreground-action-secondary-rest"),        hover: SC("foreground-action-secondary-hover"),        pressed: SC("foreground-action-secondary-pressed"),        disabled: SC("foreground-action-disabled") },
+    Tertiary:  { base: SC("foreground-action-primary-on-subtle-rest"),          hover: SC("foreground-action-primary-on-subtle-hover"),          pressed: SC("foreground-action-primary-on-subtle-pressed"),          disabled: SC("foreground-action-disabled") },
+    // Same correction, same reason. Figma binds
+    // Foreground/Action/Status/Negative/On Strong here. Mono measured 2.85:1 on
+    // the negative fill in Midnight, which fails even the 3:1 non-text floor.
+    Negative:  { base: SC("foreground-action-status-negative-on-strong"), hover: SC("foreground-action-status-negative-on-strong"), pressed: SC("foreground-action-status-negative-on-strong"), disabled: SC("foreground-action-disabled") },
+  },
+  Outlined: {
+    Primary:   { base: SC("foreground-action-primary-on-subtle-rest"),          hover: SC("foreground-action-primary-on-subtle-hover"),          pressed: SC("foreground-action-primary-on-subtle-pressed"),          disabled: SC("foreground-action-disabled") },
+    Secondary: { base: SC("foreground-action-secondary-rest"),        hover: SC("foreground-action-secondary-hover"),        pressed: SC("foreground-action-secondary-pressed"),        disabled: SC("foreground-action-disabled") },
+    Tertiary:  { base: SC("foreground-action-primary-on-subtle-rest"),          hover: SC("foreground-action-primary-on-subtle-hover"),          pressed: SC("foreground-action-primary-on-subtle-pressed"),          disabled: SC("foreground-action-disabled") },
+    Negative:  { base: SC("foreground-action-status-negative-on-subtle-rest"),  hover: SC("foreground-action-status-negative-on-subtle-hover"),  pressed: SC("foreground-action-status-negative-on-subtle-pressed"),  disabled: SC("foreground-action-disabled") },
+  },
+};
+FG.Naked = FG.Outlined;
+
+// Label and icon read the same tier now, so these are the same table. They stay
+// as two names because the render code addresses them separately.
+const TEXT = FG;
+const ICON = FG;
+
+// ─── STROKE TOKENS (Outlined only) ────────────────────────────────────────────
+// Fill/Action/Primary/Subtle has no matching STROKE ramp, so Tertiary borrows
+// the Primary stroke. That group was called "Primary Dim" before 2026-09-15.
+export const STROKE = {
+  Primary:   { base: SC("stroke-action-primary-strong-rest"),          hover: SC("stroke-action-primary-strong-hover"),          pressed: SC("stroke-action-primary-strong-pressed"),          disabled: SC("stroke-action-disabled") },
+  Secondary: { base: SC("stroke-action-secondary-rest"),        hover: SC("stroke-action-secondary-hover"),        pressed: SC("stroke-action-secondary-pressed"),        disabled: SC("stroke-action-disabled") },
+  Tertiary:  { base: SC("stroke-action-primary-strong-rest"),          hover: SC("stroke-action-primary-strong-hover"),          pressed: SC("stroke-action-primary-strong-pressed"),          disabled: SC("stroke-action-disabled") },
+  Negative:  { base: SC("stroke-action-status-negative-rest"),  hover: SC("stroke-action-status-negative-hover"),  pressed: SC("stroke-action-status-negative-pressed"),  disabled: SC("stroke-action-disabled") },
+};
+
+// ─── LAYOUT & FOCUS TOKENS ────────────────────────────────────────────────────
+// Touch target: 48×48 minimum with 6px outer padding (WCAG 2.5.5 target size).
+// Focus ring: 6px white halo + 9px brand ring (box-shadow on Container.Main).
+// Figma spec: DROP_SHADOW spread:9 color:#a0b5e6 + spread:6 color:#ffffff
+// Component metrics live in layout-contextual.css under their OWN prefix,
+// --contextual-layout-units-*, not as a "contextual" branch of the semantic
+// layout scale. The focus ring moved out of Contextual to Stroke/FocusRing.
+export const T = {
+  // button-radius was deleted 2026-09-17: it duplicated Button/Corner Radius/Radius
+  // at the same 8px and carried ZERO Figma bindings, while the other carries 2,380.
+  // The dead one was the one this file referenced.
+  radius:      CL("button-cornerradius"),                          // 8px
+  border:      CL("button-borderwidth-rest"),                             // 1px
+  // Outlined buttons thicken their border on hover, focus and pressed. Figma
+  // applies Button/Border Width/Selected (1.5px) to 48 distinct Outlined variants
+  // across exactly those three states, and this component drew 1px in all of
+  // them, so every outlined hover was 0.5px thinner than the design.
+  //
+  // The token name says "Selected" and its usage says hover/focus/pressed. There
+  // is no selected or toggled state on this component. Named here for what it
+  // does; the token name is flagged in the spec as a mismatch to settle.
+  borderEmphasis: CL("button-borderwidth-selected"),                      // 1.5px
+  gap:         CL("button-gap-horizontal"),                                  // 8px
+  touch:       { pad: 6, min: 48 },
+  // Focus ring drawn as outline + outline-offset rather than stacked shadows.
+  //
+  // Three reasons this changed on 2026-09-14:
+  //   1. It hardcoded #ffffff for the gap, so in Midnight Mode the ring sat in a
+  //      white halo on a dark surface.
+  //   2. The 6px gap + 3px ring ignored Focus Ring/Width and Focus Ring/Offset,
+  //      which existed and said 2px and 2px. Three tokens, zero references.
+  //   3. `outline` follows the element's own border-radius automatically, so the
+  //      focus shape can never disagree with the button's corner. A shadow-based
+  //      ring needs its own radius token, which is one more thing to keep in
+  //      step and was already wrong.
+  //
+  // The offset is not decoration. Stroke/FocusRing/Base measures 3.19:1 against
+  // the canvas but only 1.69:1 against the Primary fill, so a ring drawn on the
+  // fill would fail WCAG 2.4.11. The offset puts it on the surface instead.
+  focusOutline: `${CL("focusring-width")} solid ${SC("stroke-focusring-base")}`,
+  focusOffset: CL("focusring-offset"),
+};
+
+// Type is a scale now, not 111 composites, so each size composes its own five
+// values. The px in each comment is what the retired Label/Button composite
+// resolved to, kept so a drift here is obvious.
+const LABEL = (size, lineHeight, tracking) => ({
+  fontFamily:    ST("family-brand"),
+  fontSize:      ST(`font-size-${size}`),
+  fontWeight:    ST("weight-medium"),
+  lineHeight:    ST(`line-height-${lineHeight}`),
+  // Tracking is NOT uniform across the sizes and the helper used to pretend it
+  // was. Figma's Label/Button styles read, per size: Large 0.1, Base 0.1,
+  // Small 0.3, XSmall 0.6, tracking OPENS UP as the type gets smaller, which is
+  // what keeps a 12px label legible. It is passed in per size for that reason.
+  //
+  // It previously asked the SEMANTIC scale for a "compact" step, which does not
+  // exist there: that step is a primitive only. The reference resolved to
+  // nothing, the browser fell back to `normal`, and every button rendered at 0
+  // tracking against Figma's 0.1 to 0.6. Naming a token that does not exist
+  // fails silently, which is why it went unnoticed.
+  letterSpacing: ST(`letter-spacing-${tracking}`),
+});
+
+// ─── SIZE TABLE ────────────────────────────────────────────────────────────────
+export const SIZES = {
+  L: {
+    padH:      CL("button-padding-large-horizontal"),
+    padV:      CL("button-padding-large-vertical"),
+    iconWrap:  26,
+    iconInner: 18,
+    ...LABEL("m", "m-single", "wide"),        // was Label/Button/Large, 18 / 24
+  },
+  M: {
+    padH:      CL("button-padding-medium-horizontal"),
+    padV:      CL("button-padding-medium-vertical"),
+    iconWrap:  24,
+    iconInner: 16,
+    ...LABEL("r", "r-single", "wide"),        // was Label/Button/Base, 16 / 22
+  },
+  S: {
+    padH:      CL("button-padding-small-horizontal"),
+    padV:      CL("button-padding-small-vertical"),
+    iconWrap:  20,
+    iconInner: 14,
+    ...LABEL("s", "s-single", "spacious"),        // was Label/Button/Small, 14 / 20
+  },
+  // XS, added 2026-06-11 (Figma node 40007881:21300). 44×44 touch target preserved;
+  // padding 8/6. Figma defines XS for Primary/Secondary/Negative across
+  // Fill/Outlined/Naked: NOT Tertiary (see spec §Gaps).
+  XS: {
+    padH:      CL("button-padding-xsmall-horizontal"),
+    padV:      CL("button-padding-xsmall-vertical"),
+    iconWrap:  16,
+    iconInner: 12,
+    ...LABEL("xs", "xs-single", "extraspacious"),      // was Label/Button/XSmall, 12 / 18
+  },
+};
+
+// ─── SPINNER SPOKE DATA (from Pathway Spinner component) ───────────────────────
+const SPINNER_SPOKES = [
+  { d: "M6 1V3",             opacity: 1.00 },
+  { d: "M8.1 3.9L9.55 2.45", opacity: 0.87 },
+  { d: "M9 6H11",            opacity: 0.75 },
+  { d: "M8.1 8.1L9.55 9.55", opacity: 0.62 },
+  { d: "M6 9V11",            opacity: 0.50 },
+  { d: "M2.45 9.55L3.9 8.1", opacity: 0.37 },
+  { d: "M1 6H3",             opacity: 0.25 },
+  { d: "M2.45 2.45L3.9 3.9", opacity: 0.12 },
+];
+
+// Inject the keyframe animation once into the document head.
+let _keyframeInjected = false;
+function ensureSpinKeyframe() {
+  if (_keyframeInjected || typeof document === "undefined") return;
+  const style = document.createElement("style");
+  style.textContent =
+    "@keyframes pw-btn-spin { from { transform: rotate(0deg) } to { transform: rotate(360deg) } }" +
+    "@media (prefers-reduced-motion: reduce) { .pw-btn-spinner { animation: none !important; } }";
+  document.head.appendChild(style);
+  _keyframeInjected = true;
+}
+
+// ─── ButtonSpinner ─────────────────────────────────────────────────────────────
+// Inline 8-spoke spinner for the loading state. Uses currentColor so the
+// caller controls colour via the CSS `color` property.
+export function ButtonSpinner({ size = 20 }) {
+  return (
+    <svg
+      className="pw-btn-spinner"
+      width={size}
+      height={size}
+      viewBox="0 0 12 12"
+      aria-hidden="true"
+      style={{
+        animation: "pw-btn-spin var(--motion-duration-loop-fast) var(--motion-easing-linear) infinite",
+        flexShrink: 0,
+        display: "block",
+      }}
+    >
+      {SPINNER_SPOKES.map((spoke, i) => (
+        <path
+          key={i}
+          d={spoke.d}
+          stroke="currentColor"
+          strokeWidth="1"
+          strokeLinecap="round"
+          fill="none"
+          opacity={spoke.opacity}
+        />
+      ))}
+    </svg>
+  );
+}
+
+// ─── Button ────────────────────────────────────────────────────────────────────
+/**
+ * Props:
+ *   buttonStyle, "Fill" | "Outlined" | "Naked"   (default: "Fill")
+ *   size, "L" | "M" | "S" | "XS"           (default: "M")
+ *   type, "Primary" | "Secondary" | "Tertiary" | "Negative"  (default: "Primary")
+ *   text, button label                     (default: "Button")
+ *   leadingIcon, Material Symbols ligature string or React node | null
+ *   trailingIcon, Material Symbols ligature string or React node | null
+ *   showLeadingIcon, bool (default: false)
+ *   showTrailingIcon, bool (default: false)
+ *   showText, bool (default: true)
+ *   loading, bool, replaces content with spinner, sets aria-busy
+ *   disabled, bool, prevents interaction, sets aria-disabled
+ *   forceState, "hover"|"pressed"|"focused"|"disabled"|"loading"|null
+ *                  Visual-only override for Storybook StateMatrix. Does not
+ *                  affect real interaction in production.
+ *   onClick, (e) => void
+ *   ariaLabel, overrides accessible name (required when showText=false)
+ *   className, extra CSS class on the outer <button>
+ */
+export function Button({
+  buttonStyle = "Fill",
+  size        = "M",
+  type        = "Primary",
+  text        = "Button",
+  leadingIcon  = null,
+  trailingIcon = null,
+  showLeadingIcon  = false,
+  showTrailingIcon = false,
+  showText    = true,
+  loading     = false,
+  disabled    = false,
+  forceState  = null,
+  onClick,
+  ariaLabel,
+  className   = "",
+  /* Anything else goes straight onto the <button>. Needed so a composite can
+     use a real Button as the trigger for something and still put the ARIA that
+     describes that relationship on the element itself: without this, a Dropdown
+     wrapping a Button had nowhere to attach aria-haspopup and aria-expanded,
+     which is how the Glance filter ended up as a hand-rolled button instead of
+     this component. */
+  ...rest
+}) {
+  const [hovered, setHovered] = useState(false);
+  const [pressed, setPressed] = useState(false);
+  const [focused, setFocused] = useState(false);
+
+  useEffect(() => { ensureSpinKeyframe(); }, []);
+
+  // forceState drives visual simulation in Storybook; real props win in production
+  const forceLoading  = forceState === "loading";
+  const forceDisabled = forceState === "disabled";
+  const isDisabled    = disabled || loading || forceDisabled || forceLoading;
+
+  // Resolve the token-lookup key: forceState overrides live interaction when set
+  const stateKey = (() => {
+    if (forceState && !disabled && !loading) {
+      if (forceDisabled || forceLoading) return "disabled";
+      if (forceState === "focused")       return "base";   // focused = base bg + ring
+      if (forceState === "hover")         return "hover";
+      if (forceState === "pressed")       return "pressed";
+    }
+    return isDisabled ? "disabled"
+      : pressed  ? "pressed"
+      : hovered  ? "hover"
+      : "base";
+  })();
+
+  // Show focus ring only on keyboard navigation (not mouse click) or when forced
+  const showFocusRing = !isDisabled && (forceState === "focused" || focused);
+
+  const fillTokens   = FILL[buttonStyle]?.[type]  || FILL.Fill.Primary;
+  const textTokens   = TEXT[buttonStyle]?.[type]  || TEXT.Fill.Primary;
+  const iconTokens   = ICON[buttonStyle]?.[type]  || ICON.Fill.Primary;
+  const strokeTokens = STROKE[type] || STROKE.Primary;
+  const sz           = SIZES[size] || SIZES.M;
+
+  const bgColor     = fillTokens[stateKey];
+  const textColor   = textTokens[stateKey];
+  const iconColor   = iconTokens[stateKey];
+  const strokeColor = strokeTokens[stateKey];
+
+  const hasStroke = buttonStyle === "Outlined";
+
+  // Container.Main styles (the visible button surface)
+  const containerStyle = {
+    display:          "inline-flex",
+    alignItems:       "center",
+    justifyContent:   "center",
+    paddingLeft:      sz.padH,
+    paddingRight:     sz.padH,
+    paddingTop:       sz.padV,
+    paddingBottom:    sz.padV,
+    borderRadius:     T.radius,
+    backgroundColor:  bgColor,
+    // Hover, focus and pressed take the thicker weight, matching the 48 Outlined
+    // variants in Figma. Disabled and loading keep the rest weight.
+    border:           hasStroke
+      ? `${(!isDisabled && !loading && (stateKey === "hover" || stateKey === "pressed" || showFocusRing))
+          ? T.borderEmphasis : T.border} solid ${strokeColor}`
+      : "none",
+    // Figma's Container.Main has gap 0. The 8px separation is realised as
+    // padding INSIDE the icon and label containers (4px each side of each),
+    // so applying it again as a flex gap double-counts it: the icon drifts to
+    // 12px from the label, and the button ends up 16px on the icon side
+    // against 12px on the label side. Keep this 0 and let the slots pad
+    // themselves - see labelStyle and iconWrapStyle below.
+    gap:              0,
+    outline:          showFocusRing ? T.focusOutline : "none",
+    outlineOffset:    showFocusRing ? T.focusOffset : undefined,
+    transition:       "background-color var(--motion-duration-2) var(--motion-easing-standard), border-color var(--motion-duration-2) var(--motion-easing-standard), box-shadow var(--motion-duration-2) var(--motion-easing-standard), color var(--motion-duration-2) var(--motion-easing-standard)",
+    color:            iconColor,  // propagated to icons via currentColor
+  };
+
+  // Label styles. Figma's Container.Label carries pad=[0,4,0,4]; that half-gap
+  // on each side is what separates it from an adjacent icon and what keeps a
+  // text-only button symmetric. Derived from the gap token so the two cannot
+  // drift: half either side sums to the full gap between slots.
+  const halfGap = `calc(${T.gap} / 2)`;
+  const labelStyle = {
+    fontFamily:    sz.fontFamily,
+    fontWeight:    sz.fontWeight,
+    lineHeight:    sz.lineHeight,
+    letterSpacing: sz.letterSpacing,
+    fontSize:      sz.fontSize,
+    color:         textColor,
+    whiteSpace:    "nowrap",
+    paddingLeft:   halfGap,
+    paddingRight:  halfGap,
+    transition:    "color var(--motion-duration-2) var(--motion-easing-standard)",
+    userSelect:    "none",
+  };
+
+  // Icon slot wrapper, iconWrap = outer slot size, iconInner = rendered glyph size.
+  // fontVariationSettings overrides the global opsz:24 from preview-head.html, // all button icon sizes (14 to 18px) sit below the minimum opsz axis value (20),
+  // so opsz:20 is the correct optical size for the tightest stroke rendering.
+  const iconWrapStyle = {
+    display:              "inline-flex",
+    alignItems:           "center",
+    justifyContent:       "center",
+    width:                sz.iconWrap,
+    height:               sz.iconWrap,
+    flexShrink:           0,
+    fontSize:             sz.iconInner,
+    color:                iconColor,
+    transition:           "color var(--motion-duration-2) var(--motion-easing-standard)",
+    fontVariationSettings: "'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 20",
+  };
+
+  // Outer button element, handles the touch-target zone
+  const outerStyle = {
+    display:          "inline-flex",
+    alignItems:       "center",
+    justifyContent:   "center",
+    padding:          T.touch.pad,
+    minHeight:        T.touch.min,
+    minWidth:         T.touch.min,
+    background:       "transparent",
+    border:           "none",
+    borderRadius:     T.radius,
+    cursor:           isDisabled ? "not-allowed" : "pointer",
+    outline:          "none",
+    opacity:          1,
+    textDecoration:   "none",
+  };
+
+  return (
+    <button
+      type="button"
+      {...rest}
+      onClick={!isDisabled ? onClick : undefined}
+      disabled={isDisabled}
+      /* EVERY LABELLED BUTTON ANNOUNCED AS JUST "button" until 2026-10-08.
+         This read `ariaLabel || (showText ? undefined : text)`, on the
+         reasonable-sounding rule that a button showing its text does not need
+         a label because the text IS the name. That is true of an ordinary
+         button and was false here: the text sits inside
+         `pw-button__container`, which carried `aria-hidden="true"`, so the
+         name computation skipped it and the only named case was the
+         icon-only one, which is backwards.
+
+         The container's `aria-hidden` has been removed rather than patched
+         around, because the accessible name should come from the visible text:
+         that way it cannot drift from it, and it satisfies WCAG 2.5.3 Label in
+         Name without the caller doing anything. The icon spans carry their own
+         `aria-hidden`, so the ligature text ("add") was never the reason.
+
+         `text` is still used as the label in the two cases where there is no
+         visible text to read: icon-only, and loading, where the content is
+         replaced by a spinner. */
+      aria-label={ariaLabel
+        || (showText && !(loading || forceLoading) ? undefined : text)}
+      aria-busy={(loading || forceLoading) || undefined}
+      aria-disabled={isDisabled || undefined}
+      onMouseEnter={() => !isDisabled && setHovered(true)}
+      onMouseLeave={() => { setHovered(false); setPressed(false); }}
+      onMouseDown={() => !isDisabled && setPressed(true)}
+      onMouseUp={() => setPressed(false)}
+      onFocus={(e) => {
+        // Only show focus ring when navigating via keyboard (focus-visible heuristic).
+        // Mouse clicks focus the button but should not trigger the focus ring.
+        if (e.target.matches?.(':focus-visible')) setFocused(true);
+      }}
+      onBlur={() => { setFocused(false); setPressed(false); }}
+      onKeyDown={(e) => { if ((e.key === " " || e.key === "Enter") && !isDisabled) setPressed(true); }}
+      onKeyUp={() => setPressed(false)}
+      className={className}
+      style={outerStyle}
+    >
+      <span style={containerStyle} className="pw-button__container">
+        {(loading || forceLoading) ? (
+          // Loading state, spinner only, no label or icons
+          <ButtonSpinner size={sz.iconInner * 1.2} />
+        ) : (
+          <>
+            {showLeadingIcon && (
+              <span
+                style={iconWrapStyle}
+                className="material-symbols-rounded pw-button__icon pw-button__icon--leading"
+                aria-hidden="true"
+              >
+                {leadingIcon || "add"}
+              </span>
+            )}
+            {showText && (
+              <span style={labelStyle} className="pw-button__label">
+                {text}
+              </span>
+            )}
+            {showTrailingIcon && (
+              <span
+                style={iconWrapStyle}
+                className="material-symbols-rounded pw-button__icon pw-button__icon--trailing"
+                aria-hidden="true"
+              >
+                {trailingIcon || "arrow_forward"}
+              </span>
+            )}
+          </>
+        )}
+      </span>
+    </button>
+  );
+}
+
+export default Button;