@adia-ai/web-components 0.6.32 → 0.6.34

package/components/slider/slider.css

@@ -7,8 +7,8 @@
        Variables
          W    = track width  (100% of the track element)
          t    = thumb width  (full outer width including internal padding)
-         h    = track height (var(--slider-track-height))
-         pad  = internal padding on the thumb (var(--slider-thumb-padding))
+         h    = track height (var(--slider-track-height, var(--slider-track-height-default)))
+         pad  = internal padding on the thumb (var(--slider-thumb-padding, var(--slider-thumb-padding-default)))
          p    = progress     (0.0 → 1.0, written by JS as --slider-pct)
 
        The thumb consists of two layers:
@@ -44,8 +44,8 @@
        In CSS (percentages relative to W):
 
          left = calc(t/2 + p · (W − t))
-              = calc(var(--slider-thumb-width) / 2
-                     + var(--slider-pct) * (100% - var(--slider-thumb-width)))
+              = calc(var(--slider-thumb-width, var(--slider-thumb-width-default)) / 2
+                     + var(--slider-pct, var(--slider-pct-default)) * (100% - var(--slider-thumb-width, var(--slider-thumb-width-default))))
 
        The element is shifted back by 50% via transform so its
        geometric center lands on the computed point.
@@ -60,50 +60,50 @@
        ═══════════════════════════════════════════════════════════════ */
 
     /* ── Layout ── */
-    --slider-gap:               var(--a-space-1);
-    --slider-readout-gap:       var(--a-space-0-5);
-    --slider-radius:            var(--a-radius-full);
+    --slider-gap-default:               var(--a-space-1);
+    --slider-readout-gap-default:       var(--a-space-0-5);
+    --slider-radius-default:            var(--a-radius-full);
 
     /* Track height scales with the universal [size] attribute
        via --a-toggle-size: 16 sm / 20 md / 24 lg at density=1.
        Override --slider-track-height directly for custom sizes. */
-    --slider-track-height:      var(--a-toggle-size);
+    --slider-track-height-default:      var(--a-toggle-size);
 
     /* Thumb padding: internal breathing room on all sides.
        The visual pill sits pad px away from the container edge. */
-    --slider-thumb-padding:     2px;
+    --slider-thumb-padding-default:     2px;
 
     /* Visual thumb height: track height minus top and bottom padding. */
-    --slider-thumb-visual-h:    calc(var(--slider-track-height) - 2 * var(--slider-thumb-padding));
+    --slider-thumb-visual-h-default:    calc(var(--slider-track-height, var(--slider-track-height-default)) - 2 * var(--slider-thumb-padding, var(--slider-thumb-padding-default)));
 
     /* Visual thumb width: 2×1 pill ratio. */
-    --slider-thumb-visual-w:    calc(var(--slider-thumb-visual-h) * 2);
+    --slider-thumb-visual-w-default:    calc(var(--slider-thumb-visual-h, var(--slider-thumb-visual-h-default)) * 2);
 
     /* Container / geometry thumb width: visual width plus left and
        right padding.  This is the width used in the travel equation. */
-    --slider-thumb-width:       calc(var(--slider-thumb-visual-w) + 2 * var(--slider-thumb-padding));
+    --slider-thumb-width-default:       calc(var(--slider-thumb-visual-w, var(--slider-thumb-visual-w-default)) + 2 * var(--slider-thumb-padding, var(--slider-thumb-padding-default)));
 
     /* Progress fraction (0.0 → 1.0) written by JS. */
-    --slider-pct:               0;
+    --slider-pct-default:               0;
 
     /* ── Colors ──
        Track: dim recessed surface  |  Fill: primary  |  Thumb: white chrome */
-    --slider-track-bg:          var(--a-bg-muted);
-    --slider-fill-bg:           var(--a-primary-bg);
-    --slider-thumb-bg:          var(--a-chrome-light);
-    --slider-fill-bg-disabled:  var(--a-border-subtle);
-    --slider-thumb-bg-disabled: var(--a-fg-muted);
+    --slider-track-bg-default:          var(--a-bg-muted);
+    --slider-fill-bg-default:           var(--a-primary-bg);
+    --slider-thumb-bg-default:          var(--a-chrome-light);
+    --slider-fill-bg-disabled-default:  var(--a-border-subtle);
+    --slider-thumb-bg-disabled-default: var(--a-fg-muted);
 
     /* ── Typography ── */
-    --slider-font-size:         var(--a-ui-size);
-    --slider-value-weight:      var(--a-weight-bold);
+    --slider-font-size-default:         var(--a-ui-size);
+    --slider-value-weight-default:      var(--a-weight-bold);
 
     /* ── Transition ── */
-    --slider-duration:          var(--a-duration-fast);
-    --slider-easing:            var(--a-easing);
+    --slider-duration-default:          var(--a-duration-fast);
+    --slider-easing-default:            var(--a-easing);
 
     /* ── Focus ── */
-    --slider-focus-ring:        var(--a-focus-ring);
+    --slider-focus-ring-default:        var(--a-focus-ring);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
 }
 
@@ -112,7 +112,7 @@
     box-sizing: border-box;
     display: flex;
     flex-direction: column;
-    gap: var(--slider-gap);
+    gap: var(--slider-gap, var(--slider-gap-default));
   }
 
   :scope[data-direction="row"] {
@@ -126,7 +126,7 @@
     display: flex;
     align-items: baseline;
     justify-content: space-between;
-    font-size: var(--slider-font-size);
+    font-size: var(--slider-font-size, var(--slider-font-size-default));
   }
 
   [slot="label"] {
@@ -136,12 +136,12 @@
   [slot="readout"] {
     display: flex;
     align-items: baseline;
-    gap: var(--slider-readout-gap);
+    gap: var(--slider-readout-gap, var(--slider-readout-gap-default));
   }
 
   [slot="value"] {
     color: var(--a-fg);
-    font-weight: var(--slider-value-weight);
+    font-weight: var(--slider-value-weight, var(--slider-value-weight-default));
     font-variant-numeric: tabular-nums;
   }
 
@@ -152,9 +152,9 @@
   /* Track: the reference frame W for all geometry calculations. */
   [slot="track"] {
     position: relative;
-    height: var(--slider-track-height);
-    border-radius: var(--slider-radius);
-    background: var(--slider-track-bg);
+    height: var(--slider-track-height, var(--slider-track-height-default));
+    border-radius: var(--slider-radius, var(--slider-radius-default));
+    background: var(--slider-track-bg, var(--slider-track-bg-default));
     cursor: pointer;
     touch-action: none;
   }
@@ -166,10 +166,10 @@
     left: 0;
     height: 100%;
     border-radius: inherit;
-    background: var(--slider-fill-bg);
+    background: var(--slider-fill-bg, var(--slider-fill-bg-default));
     pointer-events: none;
-    width: calc(var(--slider-thumb-width)
-                + var(--slider-pct) * (100% - var(--slider-thumb-width)));
+    width: calc(var(--slider-thumb-width, var(--slider-thumb-width-default))
+                + var(--slider-pct, var(--slider-pct-default)) * (100% - var(--slider-thumb-width, var(--slider-thumb-width-default))));
   }
 
   /* Thumb CONTAINER: full track height, geometry width.
@@ -178,18 +178,18 @@
   [slot="thumb"] {
     position: absolute;
     top: 50%;
-    left: calc(var(--slider-thumb-width) / 2
-               + var(--slider-pct) * (100% - var(--slider-thumb-width)));
-    width: var(--slider-thumb-width);
-    height: var(--slider-track-height);
-    border-radius: var(--slider-radius);
+    left: calc(var(--slider-thumb-width, var(--slider-thumb-width-default)) / 2
+               + var(--slider-pct, var(--slider-pct-default)) * (100% - var(--slider-thumb-width, var(--slider-thumb-width-default))));
+    width: var(--slider-thumb-width, var(--slider-thumb-width-default));
+    height: var(--slider-track-height, var(--slider-track-height-default));
+    border-radius: var(--slider-radius, var(--slider-radius-default));
     background: transparent;
     transform: translate(-50%, -50%);
     cursor: grab;
     touch-action: none;
     transition:
-      left     var(--slider-duration) var(--slider-easing),
-      transform var(--slider-duration) var(--slider-easing);
+      left     var(--slider-duration, var(--slider-duration-default)) var(--slider-easing, var(--slider-easing-default)),
+      transform var(--slider-duration, var(--slider-duration-default)) var(--slider-easing, var(--slider-easing-default));
     z-index: 1;
   }
 
@@ -200,15 +200,15 @@
   [slot="thumb"]::before {
     content: '';
     position: absolute;
-    inset: var(--slider-thumb-padding);
+    inset: var(--slider-thumb-padding, var(--slider-thumb-padding-default));
     border-radius: inherit;
-    background: var(--slider-thumb-bg);
+    background: var(--slider-thumb-bg, var(--slider-thumb-bg-default));
   }
 
   /* During drag: kill the left transition so the thumb follows
      the pointer frame-by-frame without CSS interpolation lag. */
   :scope[data-dragging] [slot="thumb"] {
-    transition: transform var(--slider-duration) var(--slider-easing);
+    transition: transform var(--slider-duration, var(--slider-duration-default)) var(--slider-easing, var(--slider-easing-default));
   }
 
   [slot="thumb"]:hover {
@@ -221,13 +221,13 @@
   }
 
   :scope:focus-visible { outline: none; }
-  :scope:focus-visible [slot="thumb"] { box-shadow: var(--slider-focus-ring); }
+  :scope:focus-visible [slot="thumb"] { box-shadow: var(--slider-focus-ring, var(--slider-focus-ring-default)); }
 
   /* Disabled */
   :scope[disabled] [slot="track"] { cursor: not-allowed; }
-  :scope[disabled] [slot="fill"]  { background: var(--slider-fill-bg-disabled); }
+  :scope[disabled] [slot="fill"]  { background: var(--slider-fill-bg-disabled, var(--slider-fill-bg-disabled-default)); }
   :scope[disabled] [slot="thumb"]::before {
-    background: var(--slider-thumb-bg-disabled);
+    background: var(--slider-thumb-bg-disabled, var(--slider-thumb-bg-disabled-default));
   }
 
   /* ── Hint (§184, v0.5.5, FEEDBACK-08 §7) ── */

package/components/spinner/class.js

@@ -0,0 +1,69 @@
+/**
+ * Non-side-effect class export for `<spinner-ui>`.
+ *
+ * Importing this file gives you the class without auto-registering the
+ * tag. Useful for test isolation, subclassing with tag-name override, or
+ * selective composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/spinner`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <spinner-ui size="md" variant="arc" tone="current" label="Loading"></spinner-ui>
+ * <spinner-ui variant="dots" tone="subtle" label="Assistant is typing"></spinner-ui>
+ * <spinner-ui paused size="lg"></spinner-ui>
+ *
+ * Circular animated indicator for INDETERMINATE loading. The visual is
+ * rendered entirely via `::before` (and per-variant peers) on the host;
+ * the component stamps no internal DOM (`static template = () => null`).
+ *
+ * Props (attributes):
+ *   size     — sm | md (default) | lg
+ *   variant  — arc (default) | ring | dots
+ *   tone     — current (default) | subtle | accent | inverse
+ *   paused   — freeze the animation in place (default: false)
+ *   label    — accessible operation name (default: "Loading")
+ *
+ * ARIA: role="progressbar" + aria-busy="true" + aria-valuetext=<label>.
+ * Reduced motion: when prefers-reduced-motion: reduce is active, the
+ * spinning animation is replaced with a static "…" ellipsis via CSS
+ * only — no JS observer required. WCAG 2.3.3.
+ *
+ * Lifecycle: pure-CSS animation. No timers, no observers. connected()
+ * sets the three ARIA attributes once; render() keeps aria-valuetext in
+ * sync with the [label] prop.
+ *
+ * @see SPEC-001 (docs/specs/implementation-ready/SPEC-001-spinner-loader.md)
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UISpinner extends UIElement {
+  static properties = {
+    size:    { type: String,  default: 'md',      reflect: true },
+    variant: { type: String,  default: 'arc',     reflect: true },
+    tone:    { type: String,  default: 'current', reflect: true },
+    paused:  { type: Boolean, default: false,     reflect: true },
+    label:   { type: String,  default: 'Loading', reflect: false },
+  };
+
+  // No stamped children. The visual is pure CSS (::before / per-variant
+  // peers) on the host. Same shape as the spec calls out for SPEC-003
+  // <visually-hidden-ui> — a CSS-styled wrapper with no internal stamp.
+  static template = () => null;
+
+  connected() {
+    // ARIA wiring — fixed for the lifetime of the element.
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'progressbar');
+    if (!this.hasAttribute('aria-busy')) this.setAttribute('aria-busy', 'true');
+    this.setAttribute('aria-valuetext', this.label || 'Loading');
+  }
+
+  render() {
+    // Keep aria-valuetext in sync if `label` changes after connect.
+    this.setAttribute('aria-valuetext', this.label || 'Loading');
+  }
+}

package/components/spinner/spinner.a2ui.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Spinner.json",
+  "title": "Spinner",
+  "description": "Circular animated indicator for indeterminate loading. Renders a rotating arc, full ring, or three bouncing dots inside a sized box; the animation runs while the element is in the DOM and `[paused]` is unset. Fills the circular-spinner gap left by <skeleton-ui> (rectangular placeholder) and <progress-ui> (linear determinate bar) — use <spinner-ui> when the wait duration is unknown and the shape of the eventual content is irregular or the region is too small for a placeholder block.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "Spinner"
+    },
+    "label": {
+      "description": "Accessible operation name surfaced via `aria-valuetext`. Override for context-specific labels (\"Saving\", \"Uploading\").",
+      "type": "string",
+      "default": "Loading"
+    },
+    "paused": {
+      "description": "Pause the animation in-place. Useful for screenshot tests and explicit-control flows.",
+      "type": "boolean",
+      "default": false
+    },
+    "size": {
+      "description": "Diameter — matches icon-ui's ladder (sm 14px, md 16px, lg 20px).",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "tone": {
+      "description": "Color tone — `current` inherits parent text color (matches button label), `accent` uses brand accent, `subtle` is muted, `inverse` flips for on-accent surfaces.",
+      "type": "string",
+      "enum": [
+        "current",
+        "accent",
+        "subtle",
+        "inverse"
+      ],
+      "default": "current"
+    },
+    "variant": {
+      "description": "Visual flavor — arc (rotating quarter-circle), ring (full ring with one colored segment), dots (three bouncing dots).",
+      "type": "string",
+      "enum": [
+        "arc",
+        "ring",
+        "dots"
+      ],
+      "default": "arc"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"Progress\", \"value\": 42, \"max\": 100}\n",
+        "why": "Spinner is INDETERMINATE only. `value` and any quantitative\nprogress field belongs on Progress, not Spinner. Also \"Spin\" is\nnot a valid operation label.\n",
+        "wrong": "{\"component\": \"Spinner\", \"label\": \"Spin\", \"value\": 0.42}\n"
+      },
+      {
+        "fix": "{\"component\": \"Spinner\", \"size\": \"md\"}\n",
+        "why": "Skeleton is a placeholder; rotation is not part of its contract.\nA rotating circle is a Spinner.\n",
+        "wrong": "{\"component\": \"Skeleton\", \"variant\": \"circle\", \"animation\": \"rotate\"}\n"
+      },
+      {
+        "fix": "{\"component\": \"Card\", \"children\": [\n  {\"component\": \"Spinner\", \"size\": \"lg\"}\n]}\n",
+        "why": "Multiple sibling spinners in one region produce visual noise\nwithout extra information. Use one parent-level Spinner.\n",
+        "wrong": "{\"component\": \"Card\", \"children\": [\n  {\"component\": \"Spinner\"},\n  {\"component\": \"Spinner\"},\n  {\"component\": \"Spinner\"}\n]}\n"
+      }
+    ],
+    "category": "feedback",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Loading button — primary action with a saving spinner. The button is disabled while the operation is in progress; the spinner matches the button label color via tone=\"current\".",
+        "a2ui": "[\n  {\n    \"id\": \"btn-save\",\n    \"component\": \"Button\",\n    \"text\": \"Saving\",\n    \"variant\": \"primary\",\n    \"disabled\": true,\n    \"children\": [\"sp-1\"]\n  },\n  {\n    \"id\": \"sp-1\",\n    \"component\": \"Spinner\",\n    \"size\": \"sm\",\n    \"tone\": \"current\",\n    \"label\": \"Saving\"\n  }\n]",
+        "name": "button-saving"
+      },
+      {
+        "description": "Standalone centered spinner inside a card while body content fetches.",
+        "a2ui": "[\n  {\n    \"id\": \"card\",\n    \"component\": \"Card\",\n    \"children\": [\"row\"]\n  },\n  {\n    \"id\": \"row\",\n    \"component\": \"Row\",\n    \"justify\": \"center\",\n    \"align\": \"center\",\n    \"children\": [\"sp\"]\n  },\n  {\n    \"id\": \"sp\",\n    \"component\": \"Spinner\",\n    \"size\": \"lg\",\n    \"tone\": \"subtle\",\n    \"label\": \"Loading dashboard\"\n  }\n]",
+        "name": "centered-card-loading"
+      },
+      {
+        "description": "Three bouncing dots — good for chat / typing indicators.",
+        "a2ui": "[\n  {\n    \"id\": \"sp\",\n    \"component\": \"Spinner\",\n    \"variant\": \"dots\",\n    \"tone\": \"subtle\",\n    \"label\": \"Assistant is typing\"\n  }\n]",
+        "name": "typing-indicator"
+      }
+    ],
+    "keywords": [
+      "spinner",
+      "loader",
+      "loading",
+      "indeterminate",
+      "progress",
+      "busy",
+      "feedback",
+      "circular"
+    ],
+    "name": "UISpinner",
+    "related": [
+      "Progress",
+      "Skeleton",
+      "Button",
+      "EmptyState"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default; animation active.",
+        "name": "running"
+      },
+      {
+        "description": "Animation frozen at the current frame.",
+        "attribute": "paused",
+        "name": "paused"
+      },
+      {
+        "description": "Triggered by prefers-reduced-motion. Animation replaced with a static ellipsis. Detected via CSS, not JS.",
+        "name": "reduced"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "busy": [
+        "spinner",
+        "loading"
+      ],
+      "indeterminate": [
+        "spinner",
+        "progress"
+      ],
+      "loader": [
+        "spinner",
+        "loading",
+        "progress"
+      ],
+      "loading": [
+        "spinner",
+        "loading",
+        "progress",
+        "skeleton"
+      ],
+      "saving": [
+        "spinner",
+        "loading"
+      ],
+      "spinner": [
+        "spinner",
+        "loader",
+        "progress"
+      ],
+      "uploading": [
+        "spinner",
+        "loading"
+      ]
+    },
+    "tag": "spinner-ui",
+    "tokens": {
+      "--spinner-color": {
+        "description": "Color of the active arc / ring / dots. Defaults to currentColor so a tone-driven cascade resolves naturally.",
+        "default": "currentColor"
+      },
+      "--spinner-duration": {
+        "description": "One full rotation duration.",
+        "default": "var(--a-duration-slow)"
+      },
+      "--spinner-size": {
+        "description": "Diameter of the spinner box.",
+        "default": "1rem"
+      },
+      "--spinner-stroke": {
+        "description": "Border thickness for the arc / ring variants.",
+        "default": "2px"
+      },
+      "--spinner-track-opacity": {
+        "description": "Opacity for the non-rotating ring track (variant=ring only).",
+        "default": "0.25"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/spinner/spinner.css

@@ -0,0 +1,165 @@
+@scope (spinner-ui) {
+  /* ── Block 1 — TOKENS ─────────────────────────────────────────────
+     Spinner inherits the icon ladder for sizing (matches icon-ui's
+     `:scope[size="..."]` rems). The semantic colors come via `tone=…`
+     re-assigning --spinner-color. Stroke is 2px (raw px allowed for
+     borders 1-2px per component-token-contract §"Forbidden patterns"). */
+  :where(:scope) {
+    --spinner-size-default:           1rem;                       /* icon-ui md */
+    --spinner-color-default:          currentColor;
+    --spinner-stroke-default:         2px;
+    --spinner-duration-default:       var(--a-duration-slow);
+    --spinner-track-opacity-default:  0.25;
+    --spinner-dot-size-default:       calc(var(--spinner-size, var(--spinner-size-default)) / 4);
+    --spinner-dot-gap-default:        calc(var(--spinner-size, var(--spinner-size-default)) / 8);
+  }
+
+  /* ── Block 2 — BASE ────────────────────────────────────────────── */
+  :scope {
+    box-sizing: border-box;
+    display: inline-block;
+    width:  var(--spinner-size, var(--spinner-size-default));
+    height: var(--spinner-size, var(--spinner-size-default));
+    color:  var(--spinner-color, var(--spinner-color-default));
+    vertical-align: middle;
+    flex-shrink: 0;
+  }
+
+  /* ── Size ladder (mirrors icon-ui's local rem declarations) ─────── */
+  :scope[size="sm"]  { --spinner-size-default: 0.875rem; }   /* 14px */
+  :scope[size="md"]  { --spinner-size-default: 1rem; }       /* 16px */
+  :scope[size="lg"]  { --spinner-size-default: 1.25rem; }    /* 20px */
+
+  /* ── Tones (override --spinner-color token) ────────────────────── */
+  :scope[tone="current"] { --spinner-color-default: currentColor; }
+  :scope[tone="subtle"]  { --spinner-color-default: var(--a-fg-subtle); }
+  :scope[tone="accent"]  { --spinner-color-default: var(--a-accent-strong); }
+  :scope[tone="inverse"] { --spinner-color-default: var(--a-chrome-light); }
+
+  /* ── Variant: ARC (default) — rotating quarter-circle border ───── */
+  :scope[variant="arc"]::before,
+  :scope:not([variant])::before {
+    content: "";
+    box-sizing: border-box;
+    display: block;
+    width: 100%;
+    height: 100%;
+    border-radius: 50%;
+    border: var(--spinner-stroke, var(--spinner-stroke-default)) solid;
+    border-color: currentColor transparent transparent transparent;
+    animation: spinner-ui-rotate var(--spinner-duration, var(--spinner-duration-default)) linear infinite;
+  }
+
+  /* ── Variant: RING — full ring with one rotating colored segment ── */
+  :scope[variant="ring"]::before {
+    content: "";
+    box-sizing: border-box;
+    display: block;
+    width: 100%;
+    height: 100%;
+    border-radius: 50%;
+    border: var(--spinner-stroke, var(--spinner-stroke-default)) solid;
+    border-color: color-mix(in oklch, currentColor calc(var(--spinner-track-opacity, var(--spinner-track-opacity-default)) * 100%), transparent);
+    border-top-color: currentColor;
+    animation: spinner-ui-rotate var(--spinner-duration, var(--spinner-duration-default)) linear infinite;
+  }
+
+  /* ── Variant: DOTS — three bouncing dots ─────────────────────────
+     The dots layout uses inline-flex + three ::before/::after-style
+     children. Since pseudo-elements only give us two, we render dots
+     via three radial-gradient stops on a background animation that
+     translates each stop independently — but a simpler, more robust
+     shape is to overlay three identical dot pseudos via a flexbox
+     container of pseudo + two child pseudos isn't possible without
+     a stamped child. So we use a single ::before that paints all
+     three dots via background gradients + an animation on the
+     `--dot-bounce` custom property (animated via @property).
+
+     Pragmatic alternative: render the three dots using ::before +
+     ::after pseudos as the outer two dots, and a tightly-controlled
+     box-shadow on ::before to paint the middle dot. Animate each via
+     keyframes that stagger the bounce timing. */
+  :scope[variant="dots"] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: auto;             /* dots row is wider than tall */
+    min-width: var(--spinner-size, var(--spinner-size-default));
+    gap: var(--spinner-dot-gap, var(--spinner-dot-gap-default));
+  }
+
+  :scope[variant="dots"]::before,
+  :scope[variant="dots"]::after {
+    content: "";
+    display: block;
+    width:  var(--spinner-dot-size, var(--spinner-dot-size-default));
+    height: var(--spinner-dot-size, var(--spinner-dot-size-default));
+    border-radius: 50%;
+    background: currentColor;
+    animation: spinner-ui-bounce var(--spinner-duration, var(--spinner-duration-default)) ease-in-out infinite;
+  }
+
+  /* Stagger the trailing dot so the row reads as a wave. The middle
+     dot is painted via box-shadow on ::before — same dot diameter, a
+     dot-gap to the right, painted with the same currentColor. The
+     middle dot's animation phase is the average of the two pseudos. */
+  :scope[variant="dots"]::before {
+    box-shadow:
+      calc(var(--spinner-dot-size, var(--spinner-dot-size-default)) + var(--spinner-dot-gap, var(--spinner-dot-gap-default))) 0 0 currentColor;
+    margin-right: calc(var(--spinner-dot-size, var(--spinner-dot-size-default)) + var(--spinner-dot-gap, var(--spinner-dot-gap-default)));
+    animation-delay: 0s;
+  }
+
+  :scope[variant="dots"]::after {
+    animation-delay: calc(var(--spinner-duration, var(--spinner-duration-default)) / 3);
+  }
+
+  /* ── Paused state — freeze in place ────────────────────────────── */
+  :scope[paused]::before,
+  :scope[paused]::after {
+    animation-play-state: paused;
+  }
+
+  /* ── Reduced-motion replacement: static "…" ellipsis ────────────
+     WCAG 2.3.3 — animations of any duration are a vestibular risk.
+     The static replacement still announces aria-busy="true" via the
+     JS lifecycle. */
+  @media (prefers-reduced-motion: reduce) {
+    :scope::before,
+    :scope::after {
+      animation: none !important;
+    }
+    :scope::before {
+      content: "…";
+      border: none;
+      background: transparent;
+      box-shadow: none;
+      margin: 0;
+      width: 100%;
+      height: 100%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font: inherit;
+      line-height: 1;
+      text-align: center;
+      color: currentColor;
+    }
+    :scope[variant="dots"]::after {
+      display: none;
+    }
+    :scope[variant="dots"] {
+      width: var(--spinner-size, var(--spinner-size-default));   /* shrink back to a square in reduced mode */
+    }
+  }
+
+  /* ── Keyframes ─────────────────────────────────────────────────── */
+  @keyframes spinner-ui-rotate {
+    to { transform: rotate(360deg); }
+  }
+
+  @keyframes spinner-ui-bounce {
+    0%, 80%, 100% { transform: scale(0.6); opacity: 0.6; }
+    40%           { transform: scale(1);   opacity: 1; }
+  }
+}

package/components/spinner/spinner.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `<spinner-ui>` — Circular animated indicator for indeterminate loading. Renders a rotating arc, full ring, or three bouncing dots inside a sized box; the animation runs while the element is in the DOM and `[paused]` is unset. Fills the circular-spinner gap left by <skeleton-ui> (rectangular placeholder) and <progress-ui> (linear determinate bar) — use <spinner-ui> when the wait duration is unknown and the shape of the eventual content is irregular or the region is too small for a placeholder block.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/spinner
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UISpinner extends UIElement {
+  /** Accessible operation name surfaced via `aria-valuetext`. Override for context-specific labels ("Saving", "Uploading"). */
+  label: string;
+  /** Pause the animation in-place. Useful for screenshot tests and explicit-control flows. */
+  paused: boolean;
+  /** Diameter — matches icon-ui's ladder (sm 14px, md 16px, lg 20px). */
+  size: 'sm' | 'md' | 'lg';
+  /** Color tone — `current` inherits parent text color (matches button label), `accent` uses brand accent, `subtle` is muted, `inverse` flips for on-accent surfaces. */
+  tone: 'current' | 'accent' | 'subtle' | 'inverse';
+  /** Visual flavor — arc (rotating quarter-circle), ring (full ring with one colored segment), dots (three bouncing dots). */
+  variant: 'arc' | 'ring' | 'dots';
+}