@adia-ai/web-components 0.6.33 → 0.6.35

package/components/spinner/spinner.test.js

@@ -0,0 +1,272 @@
+/**
+ * spinner-ui tests — covers SPEC-001 § Verification.
+ *
+ * The component is a CSS-only animation (no stamped DOM, no JS timers).
+ * Tests fall in two categories:
+ *
+ *   1. Behavioral — props reflect to host attributes, defaults apply,
+ *      ARIA wiring is in place, element is not a focus target.
+ *   2. CSS source — happy-dom doesn't resolve @scope rules through
+ *      getComputedStyle(), so the size-ladder, tone-mapping, and
+ *      reduced-motion fallback are validated against the CSS source
+ *      directly (same recipe as tag-ui / description-list / text).
+ */
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SPINNER_CSS = readFileSync(resolve(HERE, 'spinner.css'), 'utf8');
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+beforeAll(async () => {
+  await import('./spinner.js');
+});
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+// ── 1. Defaults + property reflection ──────────────────────────────────
+
+describe('spinner-ui — defaults', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('renders without props using documented defaults', async () => {
+    const s = mount('<spinner-ui></spinner-ui>');
+    await tick();
+    expect(s.size).toBe('md');
+    expect(s.variant).toBe('arc');
+    expect(s.tone).toBe('current');
+    expect(s.paused).toBe(false);
+    expect(s.label).toBe('Loading');
+  });
+
+  it('sets role="progressbar" on the host', async () => {
+    const s = mount('<spinner-ui></spinner-ui>');
+    await tick();
+    expect(s.getAttribute('role')).toBe('progressbar');
+  });
+
+  it('sets aria-busy="true" on the host', async () => {
+    const s = mount('<spinner-ui></spinner-ui>');
+    await tick();
+    expect(s.getAttribute('aria-busy')).toBe('true');
+  });
+
+  it('sets aria-valuetext to the default label', async () => {
+    const s = mount('<spinner-ui></spinner-ui>');
+    await tick();
+    expect(s.getAttribute('aria-valuetext')).toBe('Loading');
+  });
+});
+
+// ── 2. Reflected props ─────────────────────────────────────────────────
+
+describe('spinner-ui — reflected attributes', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('reflects size="sm" / "lg" to the host attribute', async () => {
+    const sm = mount('<spinner-ui size="sm"></spinner-ui>');
+    await tick();
+    expect(sm.getAttribute('size')).toBe('sm');
+
+    const lg = mount('<spinner-ui size="lg"></spinner-ui>');
+    await tick();
+    expect(lg.getAttribute('size')).toBe('lg');
+  });
+
+  it('reflects variant="ring" / "dots" to the host attribute', async () => {
+    const ring = mount('<spinner-ui variant="ring"></spinner-ui>');
+    await tick();
+    expect(ring.getAttribute('variant')).toBe('ring');
+
+    const dots = mount('<spinner-ui variant="dots"></spinner-ui>');
+    await tick();
+    expect(dots.getAttribute('variant')).toBe('dots');
+  });
+
+  it('reflects tone="subtle" / "accent" / "inverse" to the host attribute', async () => {
+    const subtle  = mount('<spinner-ui tone="subtle"></spinner-ui>');
+    const accent  = mount('<spinner-ui tone="accent"></spinner-ui>');
+    const inverse = mount('<spinner-ui tone="inverse"></spinner-ui>');
+    await tick();
+    expect(subtle.getAttribute('tone')).toBe('subtle');
+    expect(accent.getAttribute('tone')).toBe('accent');
+    expect(inverse.getAttribute('tone')).toBe('inverse');
+  });
+
+  it('reflects [paused] as a boolean attribute', async () => {
+    const s = mount('<spinner-ui paused></spinner-ui>');
+    await tick();
+    expect(s.hasAttribute('paused')).toBe(true);
+    expect(s.paused).toBe(true);
+  });
+});
+
+// ── 3. Accessibility wiring ────────────────────────────────────────────
+
+describe('spinner-ui — accessibility', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('mirrors a custom [label] to aria-valuetext', async () => {
+    const s = mount('<spinner-ui label="Saving"></spinner-ui>');
+    await tick();
+    expect(s.getAttribute('aria-valuetext')).toBe('Saving');
+  });
+
+  it('updates aria-valuetext when label is set programmatically', async () => {
+    const s = mount('<spinner-ui></spinner-ui>');
+    await tick();
+    s.label = 'Uploading';
+    await tick();
+    expect(s.getAttribute('aria-valuetext')).toBe('Uploading');
+  });
+
+  it('is NOT a focus target (no tabindex set, body tabIndex chain skips it)', async () => {
+    const s = mount('<spinner-ui></spinner-ui>');
+    await tick();
+    expect(s.hasAttribute('tabindex')).toBe(false);
+    // tabIndex defaults to -1 for non-focusable elements in happy-dom
+    expect(s.tabIndex).toBeLessThan(0);
+  });
+
+  it('does not stamp any internal DOM (static template = null)', async () => {
+    const s = mount('<spinner-ui></spinner-ui>');
+    await tick();
+    // The visual is entirely pseudo-element-driven; the host has no
+    // element children of its own.
+    expect(s.children.length).toBe(0);
+  });
+
+  it('preserves user-supplied role / aria-busy when set in markup', async () => {
+    const s = mount('<spinner-ui role="status" aria-busy="false"></spinner-ui>');
+    await tick();
+    // connected() only sets the default ARIA when absent
+    expect(s.getAttribute('role')).toBe('status');
+    expect(s.getAttribute('aria-busy')).toBe('false');
+  });
+});
+
+// ── 4. CSS source contract ─────────────────────────────────────────────
+// happy-dom doesn't resolve @scope rules through getComputedStyle, so we
+// validate the CSS source shape directly. Same recipe as tag-ui.
+
+describe('spinner-ui — CSS source contract', () => {
+  it('opens with the canonical @scope (spinner-ui) block', () => {
+    expect(SPINNER_CSS).toMatch(/^@scope \(spinner-ui\)/);
+  });
+
+  it('declares both the :where(:scope) token block and a :scope base block', () => {
+    expect(SPINNER_CSS).toMatch(/:where\(:scope\)\s*\{/);
+    expect(SPINNER_CSS).toMatch(/^\s*:scope\s*\{/m);
+  });
+
+  it('declares all 7 component tokens', () => {
+    for (const tok of [
+      '--spinner-size',
+      '--spinner-color',
+      '--spinner-stroke',
+      '--spinner-duration',
+      '--spinner-track-opacity',
+      '--spinner-dot-size',
+      '--spinner-dot-gap',
+    ]) {
+      expect(SPINNER_CSS).toContain(tok);
+    }
+  });
+
+  it('size="sm" / "md" / "lg" all override --spinner-size-default', () => {
+    // The two-token convention (--{prop}-default for defaults +
+    // var(--{prop}, var(--{prop}-default)) at use sites) means size
+    // variants flip the -default token; consumer overrides write to
+    // the bare --{prop} which wins via the var() fallback chain.
+    expect(SPINNER_CSS).toMatch(/:scope\[size="sm"\][^}]*--spinner-size-default:\s*0\.875rem/);
+    expect(SPINNER_CSS).toMatch(/:scope\[size="md"\][^}]*--spinner-size-default:\s*1rem/);
+    expect(SPINNER_CSS).toMatch(/:scope\[size="lg"\][^}]*--spinner-size-default:\s*1\.25rem/);
+  });
+
+  it('tone="subtle" / "accent" / "inverse" override --spinner-color-default via semantic tokens', () => {
+    expect(SPINNER_CSS).toMatch(/:scope\[tone="subtle"\][^}]*--spinner-color-default:\s*var\(--a-fg-subtle\)/);
+    expect(SPINNER_CSS).toMatch(/:scope\[tone="accent"\][^}]*--spinner-color-default:\s*var\(--a-accent-strong\)/);
+    expect(SPINNER_CSS).toMatch(/:scope\[tone="inverse"\][^}]*--spinner-color-default:\s*var\(--a-chrome-light\)/);
+  });
+
+  it('arc variant uses a rotating quarter-circle border on ::before', () => {
+    expect(SPINNER_CSS).toMatch(/:scope\[variant="arc"\]::before/);
+    // The arc colors three borders transparent + the top currentColor
+    expect(SPINNER_CSS).toMatch(/border-color:\s*currentColor\s+transparent\s+transparent\s+transparent/);
+    expect(SPINNER_CSS).toMatch(/animation:\s*spinner-ui-rotate/);
+  });
+
+  it('ring variant uses a full ring with one rotating colored segment', () => {
+    expect(SPINNER_CSS).toMatch(/:scope\[variant="ring"\]::before/);
+    expect(SPINNER_CSS).toMatch(/border-top-color:\s*currentColor/);
+  });
+
+  it('dots variant uses 3 stamped [data-spinner-dot] children with bounce keyframes', () => {
+    // Pre-fix: ::before painted dot1 + a box-shadow middle dot, ::after
+    // painted dot3. Spacing was uneven (box-shadow doesn't participate
+    // in flex-gap math) and the middle dot couldn't animate. Post-fix
+    // (spinner.class.js #syncDots): three real <span data-spinner-dot=N>
+    // children stamped on connect; flex-gap distributes the row evenly
+    // and each child carries an independent animation-delay so the
+    // bounce reads as a left-to-right wave.
+    expect(SPINNER_CSS).toMatch(/:scope\[variant="dots"\]\s*>\s*\[data-spinner-dot\]/);
+    expect(SPINNER_CSS).toMatch(/:scope\[variant="dots"\]\s*>\s*\[data-spinner-dot="1"\]/);
+    expect(SPINNER_CSS).toMatch(/:scope\[variant="dots"\]\s*>\s*\[data-spinner-dot="2"\]/);
+    expect(SPINNER_CSS).toMatch(/:scope\[variant="dots"\]\s*>\s*\[data-spinner-dot="3"\]/);
+    expect(SPINNER_CSS).toMatch(/animation:\s*spinner-ui-bounce/);
+  });
+
+  it('knight variant uses a sliding ::before thumb with knight keyframes', () => {
+    expect(SPINNER_CSS).toMatch(/:scope\[variant="knight"\]\s*\{/);
+    expect(SPINNER_CSS).toMatch(/:scope\[variant="knight"\]::before/);
+    expect(SPINNER_CSS).toMatch(/animation:\s*spinner-ui-knight/);
+    // Keyframe math: translateX((1/ratio - 1) * 100%) sweeps the thumb
+    // from x=0 to x=(track - thumb) px, expressed in thumb-relative %.
+    expect(SPINNER_CSS).toMatch(/@keyframes\s+spinner-ui-knight/);
+  });
+
+  it('knight stamps NO data-spinner-dot children (pseudo-element paint only)', async () => {
+    const k = mount('<spinner-ui variant="knight"></spinner-ui>');
+    await tick();
+    expect(k.querySelectorAll(':scope > [data-spinner-dot]').length).toBe(0);
+  });
+
+  it('dots stamps exactly 3 data-spinner-dot children on connect', async () => {
+    const d = mount('<spinner-ui variant="dots"></spinner-ui>');
+    await tick();
+    const dots = d.querySelectorAll(':scope > [data-spinner-dot]');
+    expect(dots.length).toBe(3);
+    expect(dots[0].getAttribute('data-spinner-dot')).toBe('1');
+    expect(dots[1].getAttribute('data-spinner-dot')).toBe('2');
+    expect(dots[2].getAttribute('data-spinner-dot')).toBe('3');
+  });
+
+  it('paused state freezes the animation via animation-play-state', () => {
+    expect(SPINNER_CSS).toMatch(/:scope\[paused\][^}]*animation-play-state:\s*paused/);
+  });
+
+  it('reduced-motion media query replaces the animation with a static ellipsis', () => {
+    expect(SPINNER_CSS).toMatch(/@media\s*\(prefers-reduced-motion:\s*reduce\)/);
+    expect(SPINNER_CSS).toMatch(/content:\s*"…"/);
+  });
+
+  it('uses semantic --a-* tokens for color tones; no raw hex / rgb / oklch in the file', () => {
+    // Lints adjacent to the token contract: no raw colors in component CSS.
+    expect(SPINNER_CSS).not.toMatch(/#[0-9a-fA-F]{3,8}\b/);
+    expect(SPINNER_CSS).not.toMatch(/\brgb\s*\(/);
+    expect(SPINNER_CSS).not.toMatch(/\boklch\s*\(/);
+  });
+
+  it('declares a linear rotation timing function (load-bearing for smooth spin)', () => {
+    expect(SPINNER_CSS).toMatch(/spinner-ui-rotate[^;]*linear/);
+  });
+});

package/components/spinner/spinner.yaml

@@ -0,0 +1,238 @@
+# Hand-authored per SPEC-001 (docs/specs/implementation-ready/SPEC-001-spinner-loader.md).
+# Edit this file; run `npm run build:components` to regenerate spinner.a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UISpinner
+tag: spinner-ui
+status: stable
+component: Spinner
+category: feedback
+version: 1
+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.
+props:
+  size:
+    description: Diameter — matches icon-ui's ladder (sm 14px, md 16px, lg 20px).
+    type: string
+    default: md
+    enum:
+      - sm
+      - md
+      - lg
+    reflect: true
+  variant:
+    description: >-
+      Visual flavor —
+      `arc` (rotating quarter-circle, the default glyph spinner),
+      `ring` (full ring with one colored segment rotating around it),
+      `dots` (three bouncing dots — animated in a left-to-right wave),
+      `knight` (horizontal "knight-rider" bar — a sliding thumb that
+      bounces back-and-forth across a track; widest variant, reads as
+      a determinate-looking bar but is indeterminate by intent).
+    type: string
+    default: arc
+    enum:
+      - arc
+      - ring
+      - dots
+      - knight
+    reflect: true
+  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
+    default: current
+    enum:
+      - current
+      - accent
+      - subtle
+      - inverse
+    reflect: true
+  paused:
+    description: Pause the animation in-place. Useful for screenshot tests and explicit-control flows.
+    type: boolean
+    default: false
+    reflect: true
+  label:
+    description: Accessible operation name surfaced via `aria-valuetext`. Override for context-specific labels ("Saving", "Uploading").
+    type: string
+    default: Loading
+events: {}
+slots: {}
+states:
+  - name: running
+    description: Default; animation active.
+  - name: paused
+    description: Animation frozen at the current frame.
+    attribute: paused
+  - name: reduced
+    description: Triggered by prefers-reduced-motion. Animation replaced with a static ellipsis. Detected via CSS, not JS.
+traits: []
+tokens:
+  --spinner-size:
+    description: Diameter of the spinner box.
+    default: 1rem
+  --spinner-color:
+    description: Color of the active arc / ring / dots. Defaults to currentColor so a tone-driven cascade resolves naturally.
+    default: currentColor
+  --spinner-stroke:
+    description: Border thickness for the arc / ring variants.
+    default: 2px
+  --spinner-duration:
+    description: One full rotation duration.
+    default: var(--a-duration-slow)
+  --spinner-track-opacity:
+    description: Opacity for the non-rotating ring track (variant=ring only).
+    default: '0.25'
+a2ui:
+  rules:
+    - >-
+      Use <Spinner> for INDETERMINATE loading where the duration is
+      unknown. For determinate progress (a known fraction complete), use
+      <Progress> (linear) instead. For known-shape placeholder loading,
+      use <Skeleton>.
+    - >-
+      When a Spinner is inside a Button, set tone="current" so it
+      matches the button label color, and disable the button while the
+      operation is in progress.
+    - >-
+      When overriding [label], use a present-progressive verb form
+      ("Loading", "Saving", "Uploading"). Never use "Spin" or "Wait" —
+      they describe the visual, not the operation.
+    - >-
+      Do not nest <Spinner> inside <Skeleton>; they are siblings (two
+      different loading idioms), not parent/child.
+    - >-
+      Do not stack multiple sibling <Spinner>s in the same viewport
+      region. Use one parent-level Spinner instead — multiple spinners
+      add visual noise without extra information.
+anti_patterns:
+  - wrong: |
+      {"component": "Spinner", "label": "Spin", "value": 0.42}
+    why: |
+      Spinner is INDETERMINATE only. `value` and any quantitative
+      progress field belongs on Progress, not Spinner. Also "Spin" is
+      not a valid operation label.
+    fix: |
+      {"component": "Progress", "value": 42, "max": 100}
+  - wrong: |
+      {"component": "Skeleton", "variant": "circle", "animation": "rotate"}
+    why: |
+      Skeleton is a placeholder; rotation is not part of its contract.
+      A rotating circle is a Spinner.
+    fix: |
+      {"component": "Spinner", "size": "md"}
+  - wrong: |
+      {"component": "Card", "children": [
+        {"component": "Spinner"},
+        {"component": "Spinner"},
+        {"component": "Spinner"}
+      ]}
+    why: |
+      Multiple sibling spinners in one region produce visual noise
+      without extra information. Use one parent-level Spinner.
+    fix: |
+      {"component": "Card", "children": [
+        {"component": "Spinner", "size": "lg"}
+      ]}
+examples:
+  - name: button-saving
+    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: >-
+      [
+        {
+          "id": "btn-save",
+          "component": "Button",
+          "text": "Saving",
+          "variant": "primary",
+          "disabled": true,
+          "children": ["sp-1"]
+        },
+        {
+          "id": "sp-1",
+          "component": "Spinner",
+          "size": "sm",
+          "tone": "current",
+          "label": "Saving"
+        }
+      ]
+  - name: centered-card-loading
+    description: Standalone centered spinner inside a card while body content fetches.
+    a2ui: >-
+      [
+        {
+          "id": "card",
+          "component": "Card",
+          "children": ["row"]
+        },
+        {
+          "id": "row",
+          "component": "Row",
+          "justify": "center",
+          "align": "center",
+          "children": ["sp"]
+        },
+        {
+          "id": "sp",
+          "component": "Spinner",
+          "size": "lg",
+          "tone": "subtle",
+          "label": "Loading dashboard"
+        }
+      ]
+  - name: typing-indicator
+    description: Three bouncing dots — good for chat / typing indicators.
+    a2ui: >-
+      [
+        {
+          "id": "sp",
+          "component": "Spinner",
+          "variant": "dots",
+          "tone": "subtle",
+          "label": "Assistant is typing"
+        }
+      ]
+keywords:
+  - spinner
+  - loader
+  - loading
+  - indeterminate
+  - progress
+  - busy
+  - feedback
+  - circular
+synonyms:
+  spinner:
+    - spinner
+    - loader
+    - progress
+  loader:
+    - spinner
+    - loading
+    - progress
+  loading:
+    - spinner
+    - loading
+    - progress
+    - skeleton
+  busy:
+    - spinner
+    - loading
+  indeterminate:
+    - spinner
+    - progress
+  saving:
+    - spinner
+    - loading
+  uploading:
+    - spinner
+    - loading
+related:
+  - Progress
+  - Skeleton
+  - Button
+  - EmptyState

package/components/stack/stack.css

@@ -1,12 +1,12 @@
 @scope (stack-ui) {
   :where(:scope) {
-    --stack-align: center;
+    --stack-align-default: center;
   }
 
   :scope {
     box-sizing: border-box;
     display: grid;
-    place-items: var(--stack-align);
+    place-items: var(--stack-align, var(--stack-align-default));
     /* Universal [padding] / [margin] opt-in — see tokens.css for scale. */
     padding: var(--a-padding, 0);
     margin: var(--a-margin, 0);
@@ -19,13 +19,13 @@
   }
 
   /* Alignment */
-  :scope[align="center"]       { --stack-align: center; }
-  :scope[align="top-left"]     { --stack-align: start start; }
-  :scope[align="top-right"]    { --stack-align: start end; }
-  :scope[align="bottom-left"]  { --stack-align: end start; }
-  :scope[align="bottom-right"] { --stack-align: end end; }
-  :scope[align="top"]          { --stack-align: start center; }
-  :scope[align="bottom"]       { --stack-align: end center; }
-  :scope[align="left"]         { --stack-align: center start; }
-  :scope[align="right"]        { --stack-align: center end; }
+  :scope[align="center"]       { --stack-align-default: center; }
+  :scope[align="top-left"]     { --stack-align-default: start start; }
+  :scope[align="top-right"]    { --stack-align-default: start end; }
+  :scope[align="bottom-left"]  { --stack-align-default: end start; }
+  :scope[align="bottom-right"] { --stack-align-default: end end; }
+  :scope[align="top"]          { --stack-align-default: start center; }
+  :scope[align="bottom"]       { --stack-align-default: end center; }
+  :scope[align="left"]         { --stack-align-default: center start; }
+  :scope[align="right"]        { --stack-align-default: center end; }
 }

package/components/stack/stack.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIStack } from './class.js';
+import { UIStack } from './stack.class.js';
 
 defineIfFree('stack-ui', UIStack);
 

package/components/stat/stat.css

@@ -2,19 +2,19 @@
   :where(:scope) {
     /* ── Tokens ──
        Use size-responsive tokens so stat shrinks when parent card has size="sm". */
-    --stat-value-size:   var(--a-title-size);
-    --stat-value-weight: var(--a-weight-bold);
-    --stat-value-fg:     var(--a-fg-strong);
-    --stat-label-size:   var(--a-ui-size);
-    --stat-label-fg:     var(--a-fg);
-    --stat-change-size:  var(--a-ui-size);
-    --stat-up-fg:        var(--a-success-bg);
-    --stat-down-fg:      var(--a-danger-bg);
-    --stat-icon-fg:      var(--a-fg-muted);
+    --stat-value-size-default:   var(--a-title-size);
+    --stat-value-weight-default: var(--a-weight-bold);
+    --stat-value-fg-default:     var(--a-fg-strong);
+    --stat-label-size-default:   var(--a-ui-size);
+    --stat-label-fg-default:     var(--a-fg);
+    --stat-change-size-default:  var(--a-ui-size);
+    --stat-up-fg-default:        var(--a-success-bg);
+    --stat-down-fg-default:      var(--a-danger-bg);
+    --stat-icon-fg-default:      var(--a-fg-muted);
 
     /* ── Spacing ── */
-    --stat-column-gap:   var(--a-gap);
-    --stat-row-gap:      var(--a-gap-sm);
+    --stat-column-gap-default:   var(--a-gap);
+    --stat-row-gap-default:      var(--a-gap-sm);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
 }
 
@@ -31,8 +31,8 @@
       "label  icon"
       "value  value"
       "change change";
-    column-gap: var(--stat-column-gap);
-    row-gap: var(--stat-row-gap);
+    column-gap: var(--stat-column-gap, var(--stat-column-gap-default));
+    row-gap: var(--stat-row-gap, var(--stat-row-gap-default));
     align-items: baseline;
   }
 
@@ -71,8 +71,8 @@
   /* ── Label (eyebrow) ── */
   [slot="label"] {
     grid-area: label;
-    font-size: var(--stat-label-size);
-    color: var(--stat-label-fg);
+    font-size: var(--stat-label-size, var(--stat-label-size-default));
+    color: var(--stat-label-fg, var(--stat-label-fg-default));
     line-height: 1.4;
     min-width: 0;
     overflow: hidden;
@@ -86,7 +86,7 @@
     display: inline-flex;
     align-items: center;
     gap: 0.25em;
-    font-size: var(--stat-change-size);
+    font-size: var(--stat-change-size, var(--stat-change-size-default));
     line-height: 1;
     justify-self: start;
   }
@@ -94,9 +94,9 @@
   /* ── Value ── */
   [slot="value"] {
     grid-column: 1 / -1;
-    font-size: var(--stat-value-size);
-    font-weight: var(--stat-value-weight);
-    color: var(--stat-value-fg);
+    font-size: var(--stat-value-size, var(--stat-value-size-default));
+    font-weight: var(--stat-value-weight, var(--stat-value-weight-default));
+    color: var(--stat-value-fg, var(--stat-value-fg-default));
     line-height: 1.2;
     min-width: 0;
     overflow: hidden;
@@ -107,29 +107,29 @@
   /* Trend arrows via ::before */
   :scope[trend="up"] [slot="change"]::before {
     content: "\25B2";
-    color: var(--stat-up-fg);
+    color: var(--stat-up-fg, var(--stat-up-fg-default));
   }
   :scope[trend="up"] [slot="change"] {
-    color: var(--stat-up-fg);
+    color: var(--stat-up-fg, var(--stat-up-fg-default));
   }
 
   :scope[trend="down"] [slot="change"]::before {
     content: "\25BC";
-    color: var(--stat-down-fg);
+    color: var(--stat-down-fg, var(--stat-down-fg-default));
   }
   :scope[trend="down"] [slot="change"] {
-    color: var(--stat-down-fg);
+    color: var(--stat-down-fg, var(--stat-down-fg-default));
   }
 
   :scope[trend="neutral"] [slot="change"] {
-    color: var(--stat-label-fg);
+    color: var(--stat-label-fg, var(--stat-label-fg-default));
   }
 
   /* ── Icon ── */
   [slot="icon"] {
     grid-area: icon;
     align-self: start;
-    color: var(--stat-icon-fg);
+    color: var(--stat-icon-fg, var(--stat-icon-fg-default));
     --a-icon-size: 1.25rem;
   }