@adia-ai/web-components 0.0.11 → 0.0.13

package/components/field/field.js

@@ -0,0 +1,306 @@
+/**
+ * field-ui — Labeled field wrapper.
+ *
+ *   <field-ui label="Email" hint="We'll never share" required>
+ *     <input-ui value="you@example.com" type="email"></input-ui>
+ *     <span slot="trailing">Optional</span>
+ *     <button-ui slot="action" icon="x" aria-label="Clear"></button-ui>
+ *   </field-ui>
+ *
+ * Wraps a form control with its label + optional hint, error, trailing,
+ * and action regions. The host renders a real `<label for="…">` bound
+ * to the slotted control's id (auto-minted when missing) so clicking
+ * the label focuses the control — an affordance the previous
+ * `<input-ui label="…">` pattern lacked (no `for` attr, just a shadow
+ * slot).
+ *
+ * ### Layout — three internal flex rows
+ *
+ * field-ui owns three row wrappers inside its light DOM. Children are
+ * reparented into the row that matches their role so each row's cell
+ * widths are independent:
+ *
+ *   <div data-row="label">    label [+required marker] [+trailing]  </div>
+ *   <div data-row="control">  control [+action]                     </div>
+ *   <div data-row="message">  hint or error                         </div>
+ *
+ * Per-row flex means `trailing` no longer dictates the width of
+ * `action` (or vice versa). In the previous 2-column grid, column 2
+ * was shared across rows, so `trailing="Required"` pushed the
+ * `action` cell wider than the button needed. The three-row split
+ * fixes that.
+ *
+ * ### Inline mode
+ *
+ * `inline` collapses the three rows into a grid where label, trailing,
+ * control, and action share one row and the message row sits below.
+ * CSS uses `display: contents` on the label-row and control-row
+ * wrappers in inline mode so their children flow directly into the
+ * single grid row; no DOM restructure needed for the mode switch.
+ *
+ * A MutationObserver re-categorizes and re-parents children when the
+ * slotted tree changes (e.g. the A2UI renderer swapping the control
+ * during doc updates). Self-triggered mutations from our own
+ * reparenting are debounced via a guard flag to prevent a loop.
+ */
+import { AdiaElement } from '../../core/element.js';
+
+class AdiaField extends AdiaElement {
+  static properties = {
+    label:    { type: String,  default: '',    reflect: true },
+    hint:     { type: String,  default: '',    reflect: true },
+    error:    { type: String,  default: '',    reflect: true },
+    required: { type: Boolean, default: false, reflect: true },
+    inline:   { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #labelEl = null;
+  #labelMark = null;
+  #hintEl = null;
+  #errorEl = null;
+  #labelRow = null;
+  #controlRow = null;
+  #messageRow = null;
+  #mo = null;
+  #restructuring = false;   // guard against MutationObserver self-trigger
+
+  // Label click handler — the native <label for="x"> affordance calls
+  // .focus() on the element with id "x". For a custom-element control
+  // like input-ui, that focuses the shadow/light host (tabindex=-1 by
+  // default), so focus falls through to body. Work around by finding
+  // the first focusable descendant inside the slotted control and
+  // focusing it explicitly.
+  #onLabelClick = (e) => {
+    const ctrl = this.#findControl();
+    if (!ctrl) return;
+    const focusable = this.#firstFocusable(ctrl);
+    if (!focusable) return;
+    e.preventDefault();  // prevent the native <label for> focus-host fallback
+    focusable.focus();
+  };
+
+  connected() {
+    this.#ensureRowWrappers();
+    this.#ensureLabelElement();
+    this.#ensureHintElement();
+    this.#ensureErrorElement();
+    this.#restructure();
+    this.#bindForToControl();
+    this.#mo = new MutationObserver(() => {
+      if (this.#restructuring) return;
+      this.#restructure();
+      this.#bindForToControl();
+    });
+    this.#mo.observe(this, { childList: true, subtree: false });
+    this.#labelEl?.addEventListener('click', this.#onLabelClick);
+  }
+
+  disconnected() {
+    this.#mo?.disconnect();
+    this.#mo = null;
+    this.#labelEl?.removeEventListener('click', this.#onLabelClick);
+    this.#labelEl = null;
+    this.#labelMark = null;
+    this.#hintEl = null;
+    this.#errorEl = null;
+    this.#labelRow = null;
+    this.#controlRow = null;
+    this.#messageRow = null;
+  }
+
+  render() {
+    // Keep label / hint / error text in sync with reactive props.
+    if (this.#labelEl) this.#labelEl.childNodes[0] && (this.#labelEl.childNodes[0].nodeValue = this.label || '');
+    if (this.#labelMark) this.#labelMark.hidden = !this.required;
+    if (this.#hintEl) {
+      this.#hintEl.textContent = this.hint || '';
+      this.#hintEl.hidden = !this.hint || Boolean(this.error);
+    }
+    if (this.#errorEl) {
+      this.#errorEl.textContent = this.error || '';
+      this.#errorEl.hidden = !this.error;
+    }
+    // Collapse the message row entirely when both are empty so the
+    // field's trailing gap doesn't stick out.
+    if (this.#messageRow) {
+      this.#messageRow.hidden = !this.hint && !this.error;
+    }
+    this.#wireAriaDescribedBy();
+  }
+
+  // ── Private ───────────────────────────────────────────────────────
+
+  #ensureRowWrappers() {
+    this.#labelRow = this.querySelector(':scope > [data-row="label"]');
+    this.#controlRow = this.querySelector(':scope > [data-row="control"]');
+    this.#messageRow = this.querySelector(':scope > [data-row="message"]');
+    if (!this.#labelRow) {
+      this.#labelRow = this.#mkRow('label');
+      this.appendChild(this.#labelRow);
+    }
+    if (!this.#controlRow) {
+      this.#controlRow = this.#mkRow('control');
+      this.appendChild(this.#controlRow);
+    }
+    if (!this.#messageRow) {
+      this.#messageRow = this.#mkRow('message');
+      this.appendChild(this.#messageRow);
+    }
+  }
+
+  #mkRow(name) {
+    const d = document.createElement('div');
+    d.setAttribute('data-row', name);
+    return d;
+  }
+
+  #ensureLabelElement() {
+    this.#labelEl = this.querySelector(':scope [data-field-label]');
+    if (!this.#labelEl) {
+      const el = document.createElement('label');
+      el.setAttribute('data-field-label', '');
+      el.appendChild(document.createTextNode(this.label || ''));
+      this.#labelEl = el;
+    }
+    // Persistent required marker — hidden when !required. Lives as the
+    // label's last child so the stream reads "<label>*</label>".
+    this.#labelMark = this.#labelEl.querySelector('[data-field-required]');
+    if (!this.#labelMark) {
+      const mark = document.createElement('span');
+      mark.setAttribute('data-field-required', '');
+      mark.setAttribute('aria-hidden', 'true');
+      mark.textContent = '*';
+      mark.hidden = true;
+      this.#labelEl.appendChild(mark);
+      this.#labelMark = mark;
+    }
+  }
+
+  #ensureHintElement() {
+    this.#hintEl = this.querySelector(':scope [data-field-hint]');
+    if (this.#hintEl) return;
+    const el = document.createElement('div');
+    el.setAttribute('data-field-hint', '');
+    el.setAttribute('id', AdiaField.#nextMsgId('hint'));
+    el.hidden = true;
+    this.#hintEl = el;
+  }
+
+  #ensureErrorElement() {
+    this.#errorEl = this.querySelector(':scope [data-field-error]');
+    if (this.#errorEl) return;
+    const el = document.createElement('div');
+    el.setAttribute('data-field-error', '');
+    el.setAttribute('id', AdiaField.#nextMsgId('err'));
+    el.setAttribute('role', 'alert');
+    el.hidden = true;
+    this.#errorEl = el;
+  }
+
+  /** Sort light-DOM children into the appropriate row wrapper.
+   *  Idempotent — no-ops when a child already sits in its target row. */
+  #restructure() {
+    this.#restructuring = true;
+    try {
+      // Collect any children that are not already row wrappers or our
+      // managed elements. `Array.from` is snapshotted — moves during
+      // iteration don't re-index.
+      const loose = [...this.children].filter(
+        (ch) => ch !== this.#labelRow && ch !== this.#controlRow && ch !== this.#messageRow,
+      );
+      for (const ch of loose) {
+        this.#moveToRow(ch);
+      }
+      // Then relocate managed elements (they may have been created in
+      // a previous tick and still sit at :scope level).
+      if (this.#labelEl && this.#labelEl.parentElement !== this.#labelRow) {
+        this.#labelRow.prepend(this.#labelEl);
+      }
+      if (this.#hintEl && this.#hintEl.parentElement !== this.#messageRow) {
+        this.#messageRow.appendChild(this.#hintEl);
+      }
+      if (this.#errorEl && this.#errorEl.parentElement !== this.#messageRow) {
+        this.#messageRow.appendChild(this.#errorEl);
+      }
+      // Ensure the row order is label → control → message even after
+      // mutations re-append things.
+      if (this.lastElementChild !== this.#messageRow) {
+        this.appendChild(this.#messageRow);
+      }
+    } finally {
+      this.#restructuring = false;
+    }
+  }
+
+  #moveToRow(ch) {
+    const slot = ch.getAttribute?.('slot');
+    const target =
+      ch.matches?.('[data-field-label]') ? this.#labelRow :
+      slot === 'trailing'                 ? this.#labelRow :
+      ch.matches?.('[data-field-hint], [data-field-error]') ? this.#messageRow :
+      /* everything else (control, slot=action) */           this.#controlRow;
+    if (ch.parentElement !== target) target.appendChild(ch);
+  }
+
+  #bindForToControl() {
+    if (!this.#labelEl) return;
+    const control = this.#findControl();
+    if (!control) {
+      this.#labelEl.removeAttribute('for');
+      return;
+    }
+    if (!control.id) control.id = AdiaField.#nextId();
+    this.#labelEl.setAttribute('for', control.id);
+  }
+
+  /** Wire `aria-describedby` on the slotted control to the hint/error
+   *  ids. Keeps any consumer-set describedby ids; appends ours. */
+  #wireAriaDescribedBy() {
+    const ctrl = this.#findControl();
+    if (!ctrl) return;
+    const ours = new Set();
+    if (this.#hintEl && !this.#hintEl.hidden) ours.add(this.#hintEl.id);
+    if (this.#errorEl && !this.#errorEl.hidden) ours.add(this.#errorEl.id);
+    const existing = (ctrl.getAttribute('aria-describedby') || '')
+      .split(/\s+/).filter((s) => s && !s.startsWith('field-hint-') && !s.startsWith('field-err-'));
+    const merged = [...existing, ...ours].join(' ').trim();
+    if (merged) ctrl.setAttribute('aria-describedby', merged);
+    else ctrl.removeAttribute('aria-describedby');
+  }
+
+  /** The default-slot control — first child of control-row that isn't
+   *  assigned to `[slot="action"]`. */
+  #findControl() {
+    if (!this.#controlRow) return null;
+    for (const ch of this.#controlRow.children) {
+      if (ch.getAttribute('slot') === 'action') continue;
+      return ch;
+    }
+    return null;
+  }
+
+  /** First focusable descendant (or self) of `root`. Looks for native
+   *  `<input>`, `<textarea>`, `<select>`, `<button>`, `[contenteditable]`,
+   *  and any `[tabindex]` ≥ 0. Traverses light DOM only. */
+  #firstFocusable(root) {
+    const SEL = 'input, textarea, select, button, [contenteditable], [tabindex]:not([tabindex="-1"])';
+    if (root.matches?.(SEL)) return root;
+    return root.querySelector?.(SEL) ?? null;
+  }
+
+  static #idSeq = 0;
+  static #nextId() {
+    AdiaField.#idSeq += 1;
+    return `field-ctl-${AdiaField.#idSeq}`;
+  }
+  static #msgSeq = 0;
+  static #nextMsgId(kind) {
+    AdiaField.#msgSeq += 1;
+    return `field-${kind}-${AdiaField.#msgSeq}`;
+  }
+}
+
+customElements.define('field-ui', AdiaField);
+export { AdiaField };

package/components/field/field.test.js

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './field.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('field-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('renders a <label> element carrying the `label` attr text', () => {
+    const f = mount('<field-ui label="Email"><input id="e" /></field-ui>');
+    const label = f.querySelector('label[data-field-label]');
+    expect(label).not.toBeNull();
+    // The label's first child is the text node; a hidden required-marker
+    // span is its last child (mounted but hidden). Inspecting textContent
+    // of the text node isolates the label copy from the marker.
+    expect(label.firstChild.nodeValue).toBe('Email');
+  });
+
+  it('auto-mints an id on the slotted control when missing and binds label[for]', () => {
+    const f = mount('<field-ui label="Email"><input /></field-ui>');
+    const input = f.querySelector('input');
+    const label = f.querySelector('label[data-field-label]');
+    expect(input.id).toMatch(/^field-ctl-/);
+    expect(label.getAttribute('for')).toBe(input.id);
+  });
+
+  it('respects an existing id on the slotted control', () => {
+    const f = mount('<field-ui label="Email"><input id="existing" /></field-ui>');
+    const input = f.querySelector('input');
+    const label = f.querySelector('label[data-field-label]');
+    expect(input.id).toBe('existing');
+    expect(label.getAttribute('for')).toBe('existing');
+  });
+
+  it('ignores [slot="trailing"] and [slot="action"] when picking the control', () => {
+    const f = mount(`
+      <field-ui label="Search">
+        <span slot="trailing">⌘K</span>
+        <input />
+        <button slot="action">x</button>
+      </field-ui>
+    `);
+    const input = f.querySelector('input');
+    const label = f.querySelector('label[data-field-label]');
+    expect(label.getAttribute('for')).toBe(input.id);
+  });
+
+  it('updates label text when the `label` attr changes', async () => {
+    const f = mount('<field-ui label="Email"><input /></field-ui>');
+    const label = f.querySelector('label[data-field-label]');
+    expect(label.firstChild.nodeValue).toBe('Email');
+    f.setAttribute('label', 'Username');
+    await tick();
+    expect(label.firstChild.nodeValue).toBe('Username');
+  });
+
+  it('rebinds label[for] when children change', async () => {
+    const f = mount('<field-ui label="X"><input id="first" /></field-ui>');
+    const label = f.querySelector('label[data-field-label]');
+    expect(label.getAttribute('for')).toBe('first');
+    // Replace the control.
+    f.querySelector('input').remove();
+    const next = document.createElement('input');
+    next.id = 'second';
+    f.appendChild(next);
+    // MutationObserver fires async on microtask.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(label.getAttribute('for')).toBe('second');
+  });
+
+  it('reflects `inline` as a boolean attr (default false)', () => {
+    const f = mount('<field-ui label="X"><input /></field-ui>');
+    expect(f.hasAttribute('inline')).toBe(false);
+    f.inline = true;
+    expect(f.hasAttribute('inline')).toBe(true);
+    f.inline = false;
+    expect(f.hasAttribute('inline')).toBe(false);
+  });
+
+  it('renders without a label (label attr absent) — hides the <label> element', () => {
+    const f = mount('<field-ui><input /></field-ui>');
+    const label = f.querySelector('label[data-field-label]');
+    expect(label).not.toBeNull();
+    const input = f.querySelector('input');
+    expect(label.getAttribute('for')).toBe(input.id);
+  });
+
+  it('renders a hint element + wires aria-describedby when `hint` is set', async () => {
+    const f = mount('<field-ui label="E" hint="We keep it private"><input /></field-ui>');
+    await tick();
+    const hint = f.querySelector('[data-field-hint]');
+    const input = f.querySelector('input');
+    expect(hint?.textContent).toBe('We keep it private');
+    expect(hint?.hidden).toBe(false);
+    expect(input.getAttribute('aria-describedby')).toBe(hint.id);
+  });
+
+  it('hides hint when `hint` is empty', async () => {
+    const f = mount('<field-ui label="E"><input /></field-ui>');
+    await tick();
+    const hint = f.querySelector('[data-field-hint]');
+    expect(hint?.hidden).toBe(true);
+    const input = f.querySelector('input');
+    expect(input.hasAttribute('aria-describedby')).toBe(false);
+  });
+
+  it('renders an error element + suppresses hint when both set', async () => {
+    const f = mount('<field-ui label="E" hint="hi" error="Required"><input /></field-ui>');
+    await tick();
+    const hint = f.querySelector('[data-field-hint]');
+    const err  = f.querySelector('[data-field-error]');
+    expect(err?.textContent).toBe('Required');
+    expect(err?.hidden).toBe(false);
+    expect(err?.getAttribute('role')).toBe('alert');
+    expect(hint?.hidden).toBe(true);  // error wins
+    const input = f.querySelector('input');
+    expect(input.getAttribute('aria-describedby')).toBe(err.id);
+  });
+
+  it('renders the `*` required marker on the label when `required` is set', async () => {
+    const f = mount('<field-ui label="Email" required><input /></field-ui>');
+    await tick();
+    const label = f.querySelector('label[data-field-label]');
+    const mark = label.querySelector('[data-field-required]');
+    expect(mark?.textContent).toBe('*');
+    expect(mark?.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  it('updates hint/error text reactively when attrs change', async () => {
+    const f = mount('<field-ui label="E" hint="a"><input /></field-ui>');
+    await tick();
+    const hint = f.querySelector('[data-field-hint]');
+    expect(hint.textContent).toBe('a');
+    f.hint = 'b';
+    await tick();
+    expect(hint.textContent).toBe('b');
+  });
+});

package/components/field/field.yaml

@@ -0,0 +1,155 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdiaField
+tag: field-ui
+component: Field
+category: form
+version: 1
+description: >-
+  Labeled field wrapper. Composes a <label for="…"> with a form
+  control (input-ui, select-ui, textarea-ui, etc.) placed in the
+  default slot, plus optional [slot="trailing"] and [slot="action"]
+  regions. Auto-mints an id on the slotted control when missing so
+  clicking the label focuses the control — an accessibility upgrade
+  over setting label="…" on the control directly, which has no
+  [for] binding. Two layouts — stacked (default) and inline (the
+  `inline` mode attribute collapses everything to a single row).
+props:
+  label:
+    description: Label text rendered in the label row.
+    type: string
+    default: ""
+    reflect: true
+  hint:
+    description: >-
+      Help text rendered below the control in caption style. Wired
+      into the slotted control's aria-describedby so screen readers
+      announce it. Suppressed when `error` is set.
+    type: string
+    default: ""
+    reflect: true
+  error:
+    description: >-
+      Validation error message rendered below the control in danger
+      style. Takes precedence over `hint` in the same row, and
+      carries role="alert" so screen readers announce changes.
+    type: string
+    default: ""
+    reflect: true
+  required:
+    description: >-
+      Renders a "*" marker on the label. Does not itself enforce
+      validation — the slotted control's own `required` attr does
+      that; this is a visual signal only.
+    type: boolean
+    default: false
+    reflect: true
+  inline:
+    description: >-
+      Lay out label, trailing, control, and action on a single row
+      instead of the stacked default (mode attribute — changes grid
+      geometry, not tokens). Hint/error still render on their own
+      row below.
+    type: boolean
+    default: false
+    reflect: true
+slots:
+  default:
+    description: >-
+      The form control — input-ui, select-ui, textarea-ui,
+      check-ui, switch-ui, radio-ui, slider-ui, etc. Auto-id'd for
+      the label's [for] binding.
+  trailing:
+    description: >-
+      Secondary text or badge aligned with the label in the stacked
+      layout (right-aligned) or between label and control in the
+      inline layout.
+  action:
+    description: >-
+      Button adjacent to the control for inline actions (clear,
+      reset, help popover).
+states:
+  - name: idle
+    description: Default, ready for interaction.
+traits: []
+tokens:
+  --field-gap:
+    description: Gap between rows/cells of the field grid.
+  --field-label-color:
+    description: Label foreground color.
+  --field-label-size:
+    description: Label font size.
+  --field-label-weight:
+    description: Label font weight.
+  --field-required-color:
+    description: Color of the `*` required marker on the label.
+  --field-trailing-color:
+    description: Trailing text color.
+  --field-trailing-size:
+    description: Trailing text size.
+  --field-hint-color:
+    description: Hint text color.
+  --field-hint-size:
+    description: Hint text size.
+  --field-error-color:
+    description: Error text color (also drives the required-marker color).
+  --field-error-size:
+    description: Error text size.
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: stacked-email-field
+    description: >-
+      A simple stacked email field with a trailing "Required" hint
+      and a clear-button action adjacent to the input.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Field",
+          "label": "Email",
+          "children": ["email", "hint", "clear"]
+        },
+        { "id": "email", "component": "Input", "type": "email", "value": "you@example.com" },
+        { "id": "hint",  "component": "Text",  "slot": "trailing", "text": "Required" },
+        { "id": "clear", "component": "Button", "slot": "action", "icon": "x", "variant": "ghost" }
+      ]
+  - name: inline-search-field
+    description: >-
+      An inline search field — label beside the input, with a
+      trailing keyboard-shortcut hint.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Field",
+          "label": "Search",
+          "inline": true,
+          "children": ["q", "kbd"]
+        },
+        { "id": "q",   "component": "Input", "type": "search", "placeholder": "Type…" },
+        { "id": "kbd", "component": "Kbd",   "slot": "trailing", "text": "⌘K" }
+      ]
+keywords:
+  - field
+  - form
+  - label
+  - input
+  - wrapper
+synonyms:
+  form:
+    - field
+    - label
+    - input
+  label:
+    - field
+    - form
+related:
+  - input
+  - select
+  - textarea
+  - check
+  - radio
+  - switch
+  - slider

package/components/index.js

@@ -43,6 +43,7 @@ export { AdiaAlert } from './alert/alert.js';
 export { AdiaKbd } from './kbd/kbd.js';
 export { AdiaTag } from './tag/tag.js';
 export { AdiaCol }   from './col/col.js';
+export { AdiaField } from './field/field.js';
 export { AdiaRow }   from './row/row.js';
 export { AdiaGrid }  from './grid/grid.js';
 export { AdiaStack } from './stack/stack.js';

package/components/input/input.css

@@ -5,7 +5,8 @@
     --input-fg:              var(--a-ui-text);
     --input-border:          var(--a-ui-border);
     --input-border-hover:    var(--a-ui-border-hover);
-    --input-border-focus:    var(--a-ui-border-active);
+    --input-focus-ring:      var(--a-focus-ring);
+    --input-focus-ring-invalid: var(--a-focus-ring-invalid);
     --input-radius:          var(--a-radius);
     --input-height:          var(--a-size);
     --input-px:              var(--a-ui-px);
@@ -79,9 +80,16 @@
     color: var(--input-affix-fg-hover);
   }
   :scope:not([disabled]):focus-within [slot="field"] {
-    border-color: var(--input-border-focus);
+    /* Canonical ring — consumes the L3 --input-focus-ring token
+       which aliases --a-focus-ring. Border stays stable; the ring
+       is the focus affordance (WCAG 2.2 SC 2.4.11/2.4.13). */
+    box-shadow: var(--input-focus-ring);
     color: var(--input-fg-focus);
   }
+  :scope[aria-invalid="true"]:not([disabled]):focus-within [slot="field"],
+  :scope[error]:not([disabled]):focus-within [slot="field"] {
+    box-shadow: var(--input-focus-ring-invalid);
+  }
   :scope:not([disabled]):focus-within [slot="label"] {
     color: var(--input-label-fg-focus);
   }
@@ -154,7 +162,6 @@
     --input-bg: transparent;
     --input-border: transparent;
     --input-border-hover: transparent;
-    --input-border-focus: transparent;
   }
   :scope[variant="ghost"]:hover {
     --input-bg: var(--a-bg-muted);

package/components/range/range.css

@@ -11,7 +11,9 @@
     --range-fill-label-fg:   var(--a-ui-text-subtle);
     --range-border:          var(--a-ui-border);
     --range-border-hover:    var(--a-ui-border-hover);
-    --range-border-focus:    var(--a-ui-border-active);
+    --range-border-dragging: var(--a-ui-border-active);
+    --range-focus-ring:      var(--a-focus-ring);
+    --range-focus-ring-invalid: var(--a-focus-ring-invalid);
     --range-radius:          var(--a-radius);
     --range-height:          var(--a-size);
     --range-px:              var(--a-ui-px);
@@ -64,7 +66,12 @@
   }
   :scope:focus-visible { outline: none; }
   :scope:focus-visible [slot="field"] {
-    border-color: var(--range-border-focus);
+    /* Canonical ring via L3 token (see semantics.css FOCUS block). */
+    box-shadow: var(--range-focus-ring);
+  }
+  :scope[aria-invalid="true"]:focus-visible [slot="field"],
+  :scope[error]:focus-visible [slot="field"] {
+    box-shadow: var(--range-focus-ring-invalid);
   }
 
   /* ── Dual-layer fill: identical layouts, overlay clipped to fill % ── */
@@ -127,7 +134,7 @@
 
   /* Dragging: deepest fill, sharper border, instant (no transition lag on the clip) */
   :scope[data-dragging] [slot="field"] {
-    border-color: var(--range-border-focus);
+    border-color: var(--range-border-dragging);
   }
   :scope[data-dragging] [data-layer="fill"] {
     background: var(--range-fill-bg-active);