@zyncat/ui 0.10.0 → 0.12.0

package/src/components/primitives/checkbox/checkbox.css

@@ -1,177 +1,182 @@
-/* Checkbox - on/off + indeterminate; native input hidden, box painted from :has()-set flags read via calc(). */
+@layer zyncat.tokens, zyncat.components;
 
-.cbx {
-  --cbx-fill: linear-gradient(180deg, var(--accent), var(--accent-hover));
-  --cbx-on: var(--accent);
-  --cbx-off: var(--border-strong);
-  --cbx-ring: var(--ring-accent);
-  --cbx-size: var(--control-box);
-  --cbx-radius: var(--radius-sm);
-  --tick-len: 14px; /* needs a unit so the calc() dashoffset is a valid <length>; ~ the polyline path length */
-  --fill: 0;
-  --tick: 0;
-  --dash: 0;
-  --press: 1;
+@layer zyncat.components {
+  /* Checkbox - on/off + indeterminate; native input hidden, box painted from :has()-set flags read via calc(). */
 
-  display: inline-flex;
-  align-items: flex-start;
-  gap: var(--space-2);
-  padding: var(--space-2);
-  border-radius: var(--radius-md);
-  cursor: pointer;
-  -webkit-tap-highlight-color: transparent;
-  transition: background-color var(--duration-base) var(--ease-standard);
+  .cbx {
+    --cbx-fill: linear-gradient(180deg, var(--accent), var(--accent-hover));
+    --cbx-on: var(--accent);
+    --cbx-off: var(--border-strong);
+    --cbx-ring: var(--ring-accent);
+    --cbx-size: var(--control-box);
+    --cbx-radius: var(--radius-sm);
+    --cbx-tick-len: 14px; /* needs a unit so the calc() dashoffset is a valid <length>; ~ the polyline path length */
+    --cbx-checked: 0;
+    --cbx-tick: 0;
+    --cbx-dash: 0;
+    --cbx-press: 1;
 
-  /* later rule wins, so indeterminate beats checked */
-  &:has(:checked) {
-    --fill: 1;
-    --tick: 1;
-  }
-  &:has(:indeterminate) {
-    --fill: 1;
-    --tick: 0;
-    --dash: 1;
+    display: inline-flex;
+    align-items: flex-start;
+    gap: var(--space-2);
+    padding: var(--space-2);
+    border-radius: var(--radius-md);
+    cursor: pointer;
+    -webkit-tap-highlight-color: transparent;
+    transition: background-color var(--duration-base) var(--ease-standard);
+
+    /* later rule wins, so indeterminate beats checked */
+    &:has(:checked) {
+      --cbx-checked: 1;
+      --cbx-tick: 1;
+    }
+    &:has(:indeterminate) {
+      --cbx-checked: 1;
+      --cbx-tick: 0;
+      --cbx-dash: 1;
+    }
+
+    &:not(.cbx--disabled):hover {
+      background: var(--neutral-wash);
+    }
+    /* accent the empty box on hover */
+    &:not(.cbx--disabled):hover:not(:has(:checked, :indeterminate)) {
+      --cbx-off: var(--cbx-on);
+    }
+    &:not(.cbx--disabled):active {
+      --cbx-press: 0.88;
+    }
+    &:has(:focus-visible) .cbx__box {
+      box-shadow: var(--cbx-ring);
+    }
   }
 
-  &:not(.cbx--disabled):hover {
-    background: var(--neutral-wash);
+  .cbx__input {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    opacity: 0;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    overflow: hidden;
   }
-  /* accent the empty box on hover */
-  &:not(.cbx--disabled):hover:not(:has(:checked, :indeterminate)) {
-    --cbx-off: var(--cbx-on);
+
+  .cbx__box {
+    position: relative;
+    flex: none;
+    display: grid;
+    place-items: center;
+    width: var(--cbx-size);
+    height: var(--cbx-size);
+    margin-top: calc((var(--leading-body) - var(--cbx-size)) / 2);
+    border: var(--border-hairline) solid
+      color-mix(in oklab, var(--cbx-on) calc(var(--cbx-checked) * 100%), var(--cbx-off));
+    border-radius: var(--cbx-radius);
+    background: var(--bg-surface);
+    transform: scale(var(--cbx-press));
+    transition:
+      border-color var(--duration-fast) var(--ease-standard),
+      background-color var(--duration-fast) var(--ease-standard),
+      box-shadow var(--duration-fast) var(--ease-standard),
+      transform var(--duration-base) var(--ease-spring);
+
+    &::before {
+      content: '';
+      position: absolute;
+      inset: 0;
+
+      /* inner corner = outer radius - border, so the fill reaches the corners (no --bg-inset showing) */
+      border-radius: calc(var(--cbx-radius) - var(--border-hairline));
+      background: var(--cbx-fill);
+      opacity: var(--cbx-checked);
+      transform: scale(calc(0.4 + 0.6 * var(--cbx-checked)));
+      transition:
+        transform var(--duration-base) var(--ease-spring),
+        opacity var(--duration-fast) var(--ease-standard);
+    }
   }
-  &:not(.cbx--disabled):active {
-    --press: 0.88;
+
+  /* stagger lives in the delay: draw-on waits a beat (calc - --cbx-tick), retract fires immediately */
+  .cbx__mark {
+    position: relative;
+    display: block;
+    width: 100%;
+    height: 100%;
+    color: var(--text-on-accent);
+    pointer-events: none;
   }
-  &:has(:focus-visible) .cbx__box {
-    box-shadow: var(--cbx-ring);
+  .cbx__tick {
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 2;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+    stroke-dasharray: var(--cbx-tick-len);
+    stroke-dashoffset: calc(var(--cbx-tick-len) * (1 - var(--cbx-tick)));
+    transition: stroke-dashoffset var(--duration-base) var(--ease-entrance) calc(var(--cbx-tick) * var(--duration-fast));
   }
-}
-
-.cbx__input {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  margin: 0;
-  padding: 0;
-  border: 0;
-  opacity: 0;
-  clip-path: inset(50%);
-  white-space: nowrap;
-  overflow: hidden;
-}
 
-.cbx__box {
-  position: relative;
-  flex: none;
-  display: grid;
-  place-items: center;
-  width: var(--cbx-size);
-  height: var(--cbx-size);
-  margin-top: calc((var(--leading-body) - var(--cbx-size)) / 2);
-  border: var(--border-hairline) solid color-mix(in oklab, var(--cbx-on) calc(var(--fill) * 100%), var(--cbx-off));
-  border-radius: var(--cbx-radius);
-  background: var(--bg-inset);
-  transform: scale(var(--press));
-  transition:
-    border-color var(--duration-fast) var(--ease-standard),
-    background-color var(--duration-fast) var(--ease-standard),
-    box-shadow var(--duration-fast) var(--ease-standard),
-    transform var(--duration-base) var(--ease-spring);
-
-  &::before {
-    content: '';
+  .cbx__dash {
     position: absolute;
-    inset: 0;
-
-    /* inner corner = outer radius - border, so the fill reaches the corners (no --bg-inset showing) */
-    border-radius: calc(var(--cbx-radius) - var(--border-hairline));
-    background: var(--cbx-fill);
-    opacity: var(--fill);
-    transform: scale(calc(0.4 + 0.6 * var(--fill)));
+    width: 56%;
+    height: 2px;
+    border-radius: var(--border-hairline);
+    background: var(--text-on-accent);
+    pointer-events: none;
+    opacity: var(--cbx-dash);
+    transform: scaleX(var(--cbx-dash));
     transition:
       transform var(--duration-base) var(--ease-spring),
       opacity var(--duration-fast) var(--ease-standard);
   }
-}
 
-/* stagger lives in the delay: draw-on waits a beat (calc - --tick), retract fires immediately */
-.cbx__mark {
-  position: relative;
-  display: block;
-  width: 100%;
-  height: 100%;
-  color: var(--text-on-accent);
-  pointer-events: none;
-}
-.cbx__tick {
-  fill: none;
-  stroke: currentColor;
-  stroke-width: 2;
-  stroke-linecap: round;
-  stroke-linejoin: round;
-  stroke-dasharray: var(--tick-len);
-  stroke-dashoffset: calc(var(--tick-len) * (1 - var(--tick)));
-  transition: stroke-dashoffset var(--duration-base) var(--ease-entrance) calc(var(--tick) * var(--duration-fast));
-}
-
-.cbx__dash {
-  position: absolute;
-  width: 56%;
-  height: 2px;
-  border-radius: var(--border-hairline);
-  background: var(--text-on-accent);
-  pointer-events: none;
-  opacity: var(--dash);
-  transform: scaleX(var(--dash));
-  transition:
-    transform var(--duration-base) var(--ease-spring),
-    opacity var(--duration-fast) var(--ease-standard);
-}
-
-.cbx__text {
-  display: grid;
-  gap: var(--space-1);
-}
-.cbx__label {
-  font: var(--type-label);
-  color: var(--text-strong);
-}
-.cbx__desc {
-  font: var(--type-caption);
-  color: var(--text-muted);
-}
-
-.cbx--sm {
-  --cbx-size: var(--space-4);
-  & .cbx__label {
-    font: var(--type-caption);
-    font-weight: var(--weight-medium);
+  .cbx__text {
+    display: grid;
+    gap: var(--space-1);
+  }
+  .cbx__label {
+    font: var(--type-label);
     color: var(--text-strong);
   }
-  & .cbx__box {
-    margin-top: calc((var(--leading-caption) - var(--cbx-size)) / 2);
+  .cbx__desc {
+    font: var(--type-caption);
+    color: var(--text-muted);
   }
-}
 
-.cbx--error {
-  --cbx-fill: linear-gradient(180deg, var(--danger), var(--danger));
-  --cbx-on: var(--danger);
-  --cbx-off: var(--danger);
-  --cbx-ring: var(--ring-danger);
-}
+  .cbx--sm {
+    --cbx-size: var(--space-4);
+    & .cbx__label {
+      font: var(--type-caption);
+      font-weight: var(--weight-medium);
+      color: var(--text-strong);
+    }
+    & .cbx__box {
+      margin-top: calc((var(--leading-caption) - var(--cbx-size)) / 2);
+    }
+  }
 
-/* disabled leaves the state flags untouched, so the mark still matches checked state */
-.cbx--disabled {
-  cursor: not-allowed;
-  --cbx-fill: var(--border-strong);
-  --cbx-on: var(--border-default);
-  --cbx-off: var(--border-subtle);
-  & .cbx__box {
-    background: var(--bg-muted);
+  .cbx--error {
+    --cbx-fill: linear-gradient(180deg, var(--danger), var(--danger));
+    --cbx-on: var(--danger);
+    --cbx-off: var(--danger);
+    --cbx-ring: var(--ring-danger);
   }
-  & .cbx__label,
-  & .cbx__desc {
-    color: var(--text-disabled);
+
+  /* disabled leaves the state flags untouched, so the mark still matches checked state */
+  .cbx--disabled {
+    cursor: not-allowed;
+    --cbx-fill: var(--border-strong);
+    --cbx-on: var(--border-default);
+    --cbx-off: var(--border-subtle);
+    & .cbx__box {
+      background: var(--bg-muted);
+    }
+    & .cbx__label,
+    & .cbx__desc {
+      color: var(--text-disabled);
+    }
   }
 }

package/src/components/primitives/collapse/Collapse.tsx

@@ -1,9 +1,10 @@
 'use client';
 
 import './collapse.css';
+
 import type { CSSProperties, HTMLAttributes, JSX, ReactNode } from 'react';
+
 import type { DataAttributes } from '../../../dom-props';
-import type { DurationToken, EaseToken } from '../../../tokens/motion-scale';
 import {
   timingVars,
   type AnimationTiming,
@@ -11,6 +12,7 @@ import {
   type DisableableAnimation,
   type TimingProps,
 } from '../../../motion/timing';
+import type { DurationToken, EaseToken } from '../../../tokens/motion-scale';
 import { cx } from '../../internal/utils/cx';
 
 /** Motion-scale duration tokens - the only values Collapse timing accepts. */

package/src/components/primitives/collapse/Collapse.usage.md

@@ -0,0 +1,17 @@
+# Collapse - @zyncat/ui/collapse
+
+Group: primitives
+Docs: https://ui.zyncat.app/collapse
+
+Layout-transition primitive; eases height open/closed, never teleports.
+
+Closed content also leaves the tab order, accessibility tree and hit-testing once the exit
+completes; reopening is focusable immediately. animation takes motion tokens ONLY - { duration, ease
+}, each one token (fast|base|slow|slower|slowest / standard|entrance|exit|spring|glide) or
+per-direction { open, close }.
+
+```tsx
+<Collapse open={open} animation={{ duration: { close: 'fast' }, ease: { close: 'exit' } }}>
+  <div>...revealed content...</div>
+</Collapse>
+```

package/src/components/primitives/collapse/collapse.css

@@ -1,18 +1,5 @@
-/* Collapse - animates open/closed via a grid track interpolating 0fr and 1fr (never `auto`).
+@layer zyncat.tokens, zyncat.components;
 
-   Closed content leaves the page semantics, not just the paint: the root turns
-   visibility:hidden, dropping children out of the tab order, the accessibility tree and
-   hit-testing. The flip is directional by construction. Closing lists visibility with a
-   delay equal to the size duration, so removal lands only after the exit finishes and
-   nothing pops. Opening omits visibility from its transition list entirely, so content is
-   focusable the same frame it opens, before the entrance runs. The delay rides the duration
-   tokens, so the global reduced-motion collapse (~1ms) applies to it as well. The open state
-   deliberately declares no `visibility: visible` - it inherits instead, so a Collapse nested
-   inside a closed ancestor cannot poke a focusable hole through it. */
-
-/* Timing overrides - set inline by Collapse.tsx from the token-typed duration/ease props.
-   Registered non-inheriting so one Collapse's timing can never leak into a Collapse nested
-   inside it; where unset they resolve invalid and the var() fallbacks supply the defaults. */
 @property --collapse-dur-open {
   syntax: '*';
   inherits: false;
@@ -30,59 +17,81 @@
   inherits: false;
 }
 
-.collapse {
-  display: grid;
-  grid-template-rows: 0fr;
-  transition:
-    grid-template-rows var(--collapse-dur-close, var(--duration-slow)) var(--collapse-ease-close, var(--ease-entrance)),
-    grid-template-columns var(--collapse-dur-close, var(--duration-slow))
-      var(--collapse-ease-close, var(--ease-entrance)),
-    visibility 0s linear var(--collapse-dur-close, var(--duration-slow));
-}
-.collapse[data-open='false'] {
-  visibility: hidden;
-}
-.collapse[data-open='true'] {
-  grid-template-rows: 1fr;
-  transition:
-    grid-template-rows var(--collapse-dur-open, var(--duration-slow)) var(--collapse-ease-open, var(--ease-entrance)),
-    grid-template-columns var(--collapse-dur-open, var(--duration-slow)) var(--collapse-ease-open, var(--ease-entrance));
-}
+@layer zyncat.components {
+  /* Collapse - animates open/closed via a grid track interpolating 0fr and 1fr (never `auto`).
 
-.collapse[data-axis='width'] {
-  grid-template-rows: 1fr;
-  grid-template-columns: 0fr;
-}
-.collapse[data-axis='width'][data-open='true'] {
-  grid-template-columns: 1fr;
-}
+   Closed content leaves the page semantics, not just the paint: the root turns
+   visibility:hidden, dropping children out of the tab order, the accessibility tree and
+   hit-testing. The flip is directional by construction. Closing lists visibility with a
+   delay equal to the size duration, so removal lands only after the exit finishes and
+   nothing pops. Opening omits visibility from its transition list entirely, so content is
+   focusable the same frame it opens, before the entrance runs. The delay rides the duration
+   tokens, so the global reduced-motion collapse (~1ms) applies to it as well. The open state
+   deliberately declares no `visibility: visible` - it inherits instead, so a Collapse nested
+   inside a closed ancestor cannot poke a focusable hole through it. */
 
-/* min-size:0 is what lets the grid track collapse to 0. */
-.collapse__inner {
-  overflow: hidden;
-  min-height: 0;
-  min-width: 0;
-}
+  /* Timing overrides - set inline by Collapse.tsx from the token-typed duration/ease props.
+   Registered non-inheriting so one Collapse's timing can never leak into a Collapse nested
+   inside it; where unset they resolve invalid and the var() fallbacks supply the defaults. */
 
-.collapse--fade .collapse__inner {
-  opacity: 0;
-  transition: opacity var(--collapse-dur-close, var(--duration-base)) var(--collapse-ease-close, var(--ease-standard));
-}
-.collapse--fade[data-open='true'] .collapse__inner {
-  opacity: 1;
-  /* fade in slightly after the size opens */
-  transition: opacity var(--collapse-dur-open, var(--duration-slow)) var(--collapse-ease-open, var(--ease-entrance))
-    60ms;
-}
+  .collapse {
+    --collapse-fade-stagger: 60ms;
+
+    display: grid;
+    grid-template-rows: 0fr;
+    transition:
+      grid-template-rows var(--collapse-dur-close, var(--duration-slow))
+        var(--collapse-ease-close, var(--ease-entrance)),
+      grid-template-columns var(--collapse-dur-close, var(--duration-slow))
+        var(--collapse-ease-close, var(--ease-entrance)),
+      visibility 0s linear var(--collapse-dur-close, var(--duration-slow));
+  }
+  .collapse[data-open='false'] {
+    visibility: hidden;
+  }
+  .collapse[data-open='true'] {
+    grid-template-rows: 1fr;
+    transition:
+      grid-template-rows var(--collapse-dur-open, var(--duration-slow)) var(--collapse-ease-open, var(--ease-entrance)),
+      grid-template-columns var(--collapse-dur-open, var(--duration-slow))
+        var(--collapse-ease-open, var(--ease-entrance));
+  }
+
+  .collapse[data-axis='width'] {
+    grid-template-rows: 1fr;
+    grid-template-columns: 0fr;
+  }
+  .collapse[data-axis='width'][data-open='true'] {
+    grid-template-columns: 1fr;
+  }
+
+  /* min-size:0 is what lets the grid track collapse to 0. */
+  .collapse__inner {
+    overflow: hidden;
+    min-height: 0;
+    min-width: 0;
+  }
 
-@media (prefers-reduced-motion: reduce) {
-  .collapse,
   .collapse--fade .collapse__inner {
-    transition-duration: 1ms;
+    opacity: 0;
+    transition: opacity var(--collapse-dur-close, var(--duration-base)) var(--collapse-ease-close, var(--ease-standard));
+  }
+  .collapse--fade[data-open='true'] .collapse__inner {
+    opacity: 1;
+    /* fade in slightly after the size opens */
+    transition: opacity var(--collapse-dur-open, var(--duration-slow)) var(--collapse-ease-open, var(--ease-entrance))
+      var(--collapse-fade-stagger);
   }
-  /* drop the fade-in stagger so content is visible immediately; the visibility delay needs
+
+  @media (prefers-reduced-motion: reduce) {
+    .collapse,
+    .collapse--fade .collapse__inner {
+      transition-duration: 1ms;
+    }
+    /* drop the fade-in stagger so content is visible immediately; the visibility delay needs
      no override - it rides the duration tokens, which this media query collapses to 1ms */
-  .collapse--fade .collapse__inner {
-    transition-delay: 0ms;
+    .collapse--fade .collapse__inner {
+      transition-delay: 0ms;
+    }
   }
 }

package/src/components/primitives/collapse/collapse.typecheck.tsx

@@ -1,3 +1,5 @@
+'use client';
+
 import { Collapse } from './Collapse';
 
 export const ok = (

package/src/components/primitives/input/NumberField.tsx

@@ -1,13 +1,22 @@
 'use client';
 
 import './input.css';
-import { useState } from 'react';
+
+import { useId, useState } from 'react';
 import type { CSSProperties, InputHTMLAttributes } from 'react';
-import { Icon } from '../../internal/icon/Icon';
-import { FieldLabel, FieldMessage, type FieldCoreMessagingProps, type FieldIdProps } from './field-chrome';
-import { useControllable } from '../../internal/hooks/use-controllable';
+
 import type { DataAttributes } from '../../../dom-props';
+import { useControllable } from '../../internal/hooks/use-controllable';
+import { Icon } from '../../internal/icon/Icon';
 import { cx } from '../../internal/utils/cx';
+import {
+  FieldLabel,
+  FieldMessage,
+  fieldMessageId,
+  joinIds,
+  type FieldCoreMessagingProps,
+  type FieldIdProps,
+} from './field-chrome';
 
 interface NumberFieldOwnProps extends FieldIdProps, FieldCoreMessagingProps {
   /** Unit suffix shown inside the field (e.g. "days", "%"). */
@@ -61,6 +70,9 @@ export function NumberField({
   style,
   htmlProps,
 }: NumberFieldProps) {
+  const autoId = useId();
+  const message = error || helper;
+  const msgId = fieldMessageId(id ?? autoId, message);
   const resolvedValue = value === undefined ? undefined : typeof value === 'number' ? value : parseFloat(value) || 0;
   const [num, setNum] = useControllable<number>(resolvedValue, defaultValue, onChange);
   const [draft, setDraft] = useState<string | null>(null);
@@ -110,6 +122,7 @@ export function NumberField({
             if (e.key === 'Enter') commit(v);
           }}
           {...htmlProps}
+          aria-describedby={joinIds(msgId, htmlProps?.['aria-describedby'])}
         />
         {unit && <span className="numf__unit">{unit}</span>}
         <div className="numf__steppers">
@@ -133,7 +146,7 @@ export function NumberField({
           </button>
         </div>
       </div>
-      <FieldMessage message={error || helper} icon={error ? 'warning-circle' : null} />
+      <FieldMessage id={msgId} message={message} icon={error ? 'warning-circle' : null} />
     </div>
   );
 }

package/src/components/primitives/input/NumberField.usage.md

@@ -0,0 +1,12 @@
+# NumberField - @zyncat/ui/number-field
+
+Group: forms
+Docs: https://ui.zyncat.app/number-field
+
+Tabular figures, caret steppers, unit suffix, clamp to [min,max].
+
+onChange(value: number).
+
+```tsx
+<NumberField id="seats" label="Seats" unit="users" min={1} max={50} value={n} onChange={setN} />
+```

package/src/components/primitives/input/OtpField.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import './input.css';
+
 import { useRef } from 'react';
 import type {
   ChangeEvent,
@@ -12,6 +13,7 @@ import type {
   MouseEvent,
   ReactNode,
 } from 'react';
+
 import type { DataAttributes } from '../../../dom-props';
 import { cx } from '../../internal/utils/cx';
 

package/src/components/primitives/input/OtpField.usage.md

@@ -0,0 +1,12 @@
+# OtpField - @zyncat/ui/otp-field
+
+Group: forms
+Docs: https://ui.zyncat.app/otp-field
+
+Segmented one-time code; auto-advance, paste-to-fill.
+
+length, group, error, size.
+
+```tsx
+<OtpField length={6} group={3} value={code} onChange={setCode} />
+```

package/src/components/primitives/input/TextField.tsx

@@ -1,13 +1,22 @@
 'use client';
 
 import './input.css';
-import { useRef } from 'react';
+
+import { useId, useRef } from 'react';
 import type { CSSProperties, InputHTMLAttributes, ReactNode } from 'react';
+
+import type { DataAttributes } from '../../../dom-props';
 import { Icon } from '../../internal/icon/Icon';
 import { IconSlot } from '../../internal/icon/IconSlot';
-import { FieldLabel, FieldMessage, resolveFieldMessage, type FieldMessagingProps } from './field-chrome';
-import type { DataAttributes } from '../../../dom-props';
 import { cx } from '../../internal/utils/cx';
+import {
+  FieldLabel,
+  FieldMessage,
+  fieldMessageId,
+  joinIds,
+  resolveFieldMessage,
+  type FieldMessagingProps,
+} from './field-chrome';
 
 /** The native <input> props TextField surfaces at the top level (the rest live in `htmlProps`). */
 type TextFieldNative = Pick<
@@ -62,6 +71,8 @@ export function TextField({
 }: TextFieldProps) {
   const { state, msg, msgIcon } = resolveFieldMessage(error, warning, success, helper);
   const inputRef = useRef<HTMLInputElement>(null);
+  const autoId = useId();
+  const msgId = fieldMessageId(rest.id ?? autoId, msg);
   const showClear = clearable && value && !rest.disabled && !rest.readOnly;
 
   function clear() {
@@ -97,6 +108,7 @@ export function TextField({
           aria-invalid={error ? true : undefined}
           {...rest}
           {...htmlProps}
+          aria-describedby={joinIds(msgId, htmlProps?.['aria-describedby'])}
         />
         {showClear && (
           <button type="button" className="fld__action" aria-label="Clear" onClick={clear}>
@@ -104,7 +116,7 @@ export function TextField({
           </button>
         )}
       </div>
-      <FieldMessage message={msg} icon={msgIcon} />
+      <FieldMessage id={msgId} message={msg} icon={msgIcon} />
     </div>
   );
 }