@nqmcreative/ui 0.4.1 → 0.4.2

package/dist/styles/paper/Checkbox.svelte

@@ -25,6 +25,8 @@
 		...rest
 	}: Props = $props();
 
+	const uid = $props.id();
+
 	let el: HTMLInputElement | null = $state(null);
 
 	$effect(() => {
@@ -32,44 +34,61 @@
 	});
 </script>
 
-<label
-	class="group inline-flex items-start gap-2.5 font-sans text-sm
-		{disabled ? 'pointer-events-none opacity-50' : 'cursor-pointer'} {className}"
+<div
+	class="inline-block font-sans text-sm {disabled
+		? 'pointer-events-none opacity-50'
+		: ''} {className}"
 >
-	<input bind:this={el} type="checkbox" bind:checked {disabled} class="peer sr-only" {...rest} />
-	<span
-		class="mt-0.5 flex size-[18px] shrink-0 items-center justify-center rounded border border-hairline-strong bg-bg shadow-xs transition-colors duration-150 ease-brand-out
+	<label class="group inline-flex items-start gap-2.5 {disabled ? '' : 'cursor-pointer'}">
+		<input
+			bind:this={el}
+			type="checkbox"
+			bind:checked
+			{disabled}
+			aria-describedby={description ? `${uid}-description` : undefined}
+			class="peer sr-only"
+			{...rest}
+		/>
+		<span
+			class="mt-0.5 flex size-[18px] shrink-0 items-center justify-center rounded border border-hairline-strong bg-bg shadow-xs transition-colors duration-150 ease-brand-out
 			{tonePeerChecked[tone]} {peerFocusRing} {tonePeerFocus[tone]}"
-		aria-hidden="true"
-	>
-		{#if indeterminate}
-			<span class="h-0.5 w-2.5 rounded-full bg-text-muted"></span>
-		{:else}
-			<svg
-				class="size-3 text-text-inverse opacity-0 transition-opacity duration-150 group-has-[:checked]:opacity-100"
-				viewBox="0 0 12 12"
-				fill="none"
-			>
-				<path
-					d="m2 6 2.6 2.6L10 3.2"
-					stroke="currentColor"
-					stroke-width="2"
-					stroke-linecap="round"
-					stroke-linejoin="round"
-				/>
-			</svg>
-		{/if}
-	</span>
-	{#if label || description || children}
-		<span class="flex flex-col gap-0.5">
-			{#if children}
-				{@render children()}
-			{:else if label}
-				<span class="leading-snug text-text">{label}</span>
-			{/if}
-			{#if description}
-				<span class="text-[13px] leading-snug text-text-muted">{description}</span>
+			aria-hidden="true"
+		>
+			{#if indeterminate}
+				<span class="h-0.5 w-2.5 rounded-full bg-text-muted"></span>
+			{:else}
+				<svg
+					class="size-3 text-text-inverse opacity-0 transition-opacity duration-150 group-has-[:checked]:opacity-100"
+					viewBox="0 0 12 12"
+					fill="none"
+				>
+					<path
+						d="m2 6 2.6 2.6L10 3.2"
+						stroke="currentColor"
+						stroke-width="2"
+						stroke-linecap="round"
+						stroke-linejoin="round"
+					/>
+				</svg>
 			{/if}
 		</span>
+		{#if label || children}
+			<span class="flex flex-col gap-0.5">
+				{#if children}
+					{@render children()}
+				{:else if label}
+					<span class="leading-snug text-text">{label}</span>
+				{/if}
+			</span>
+		{/if}
+	</label>
+	{#if description}
+		<!-- ponytail: the indent tracks the 18px box plus the label's gap; move one, move both. -->
+		<span
+			id="{uid}-description"
+			class="mt-0.5 block pl-[28px] text-[13px] leading-snug text-text-muted"
+		>
+			{description}
+		</span>
 	{/if}
-</label>
+</div>

package/dist/styles/paper/CheckboxGroup.svelte

@@ -50,6 +50,11 @@
 		...rest
 	}: Props = $props();
 
+	const uid = $props.id();
+	// The group's own hint and error sit outside every control in it, so the
+	// fieldset is what has to point at them.
+	const messageId = $derived(error ? `${uid}-error` : hint ? `${uid}-hint` : undefined);
+
 	const full = $derived(max > 0 && value.length >= max);
 
 	function toggle(option: CheckboxOption) {
@@ -60,11 +65,17 @@
 	}
 </script>
 
-<fieldset class="flex flex-col gap-3 border-0 p-0 {className}" {...rest}>
+<fieldset
+	aria-describedby={messageId}
+	class="flex flex-col gap-3 border-0 p-0 {className}"
+	{...rest}
+>
 	{#if legend}
 		<legend class="mb-1 font-sans text-sm font-medium text-text">
 			{legend}
-			{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span>{/if}
+			{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span><span
+					class="sr-only">(required)</span
+				>{/if}
 		</legend>
 	{/if}
 
@@ -110,8 +121,8 @@
 	</div>
 
 	{#if error}
-		<p class="font-sans text-[13px] text-danger">{error}</p>
+		<p id="{uid}-error" role="alert" class="font-sans text-[13px] text-danger">{error}</p>
 	{:else if hint}
-		<p class="font-sans text-[13px] text-text-muted">{hint}</p>
+		<p id="{uid}-hint" class="font-sans text-[13px] text-text-muted">{hint}</p>
 	{/if}
 </fieldset>

package/dist/styles/paper/Combobox.svelte

@@ -3,7 +3,14 @@
 	import { anchored } from '../../core/actions/anchor.js';
 	import { clickOutside, portal } from '../../core/actions/dismissable.js';
 	import { ListCursor, groupItems, matchQuery, revealIndex } from '../../core/list.svelte.js';
-	import { toneFocusWithinBorder, toneSoft, toneText, type Tone } from '../../core/tones.js';
+	import {
+		focusWithinRing,
+		toneFocusWithinBorder,
+		toneFocusWithinRing,
+		toneSoft,
+		toneText,
+		type Tone
+	} from '../../core/tones.js';
 	import { iconMd } from './icon.js';
 
 	export interface ComboboxOption {
@@ -143,7 +150,9 @@
 
 <div
 	bind:this={wrapper}
-	class="relative inline-flex w-full items-center gap-2 rounded-md border bg-bg pr-1.5 pl-3 shadow-xs transition-colors duration-150 ease-brand-out
+	class="relative inline-flex w-full items-center gap-2 rounded-md border bg-bg pr-1.5 pl-3 shadow-xs transition-colors duration-150 ease-brand-out {focusWithinRing} {toneFocusWithinRing[
+		tone
+	]}
 		{invalid ? 'border-danger' : `border-hairline-strong ${toneFocusWithinBorder[tone]}`}
 		{disabled ? 'pointer-events-none opacity-50' : ''} {className}"
 >

package/dist/styles/paper/ConfirmDialog.svelte

@@ -36,6 +36,8 @@
 		children
 	}: Props = $props();
 
+	const uid = $props.id();
+
 	async function confirm() {
 		try {
 			loading = true;
@@ -55,6 +57,8 @@
 
 <Modal
 	bind:open
+	aria-labelledby="{uid}-title"
+	aria-describedby={description ? `${uid}-description` : undefined}
 	size="sm"
 	dismissible={!loading}
 	showClose={false}
@@ -73,9 +77,11 @@
 			{/if}
 		</span>
 		<div class="flex min-w-0 flex-1 flex-col gap-1.5">
-			<h2 class="font-heading text-base font-semibold text-text">{title}</h2>
+			<h2 id="{uid}-title" class="font-heading text-base font-semibold text-text">{title}</h2>
 			{#if description}
-				<p class="text-[13px] leading-relaxed text-text-secondary">{description}</p>
+				<p id="{uid}-description" class="text-[13px] leading-relaxed text-text-secondary">
+					{description}
+				</p>
 			{/if}
 			{#if children}
 				{@render children()}

package/dist/styles/paper/DatePicker.svelte

@@ -3,7 +3,12 @@
 	import { clickOutside, portal } from '../../core/actions/dismissable.js';
 	import { dateHint } from '../../core/calendar.js';
 	import { formatISO, parseFormatted, type DateFormat } from '../../core/date.js';
-	import { toneFocusWithinBorder, type Tone } from '../../core/tones.js';
+	import {
+		focusWithinRing,
+		toneFocusWithinBorder,
+		toneFocusWithinRing,
+		type Tone
+	} from '../../core/tones.js';
 	import Calendar from './Calendar.svelte';
 
 	interface Props {
@@ -94,7 +99,9 @@
 
 <div
 	bind:this={wrapper}
-	class="inline-flex w-full items-center gap-1 rounded-md border bg-bg pr-1 pl-3 shadow-xs transition-colors duration-150 ease-brand-out
+	class="inline-flex w-full items-center gap-1 rounded-md border bg-bg pr-1 pl-3 shadow-xs transition-colors duration-150 ease-brand-out {focusWithinRing} {toneFocusWithinRing[
+		tone
+	]}
 		{invalid ? 'border-danger' : `border-hairline-strong ${toneFocusWithinBorder[tone]}`}
 		{disabled ? 'pointer-events-none opacity-50' : ''} {className}"
 >

package/dist/styles/paper/Divider.svelte

@@ -20,7 +20,7 @@
 		{...rest}
 	></div>
 {:else if label}
-	<div class="flex items-center gap-3 {className}" {...rest}>
+	<div role="separator" class="flex items-center gap-3 {className}" {...rest}>
 		<span class="h-px flex-1 bg-hairline"></span>
 		<span class="font-sans text-xs font-medium text-text-muted">{label}</span>
 		<span class="h-px flex-1 bg-hairline"></span>

package/dist/styles/paper/Drawer.svelte

@@ -38,6 +38,8 @@
 		...rest
 	}: Props = $props();
 
+	const uid = $props.id();
+
 	let dialog: HTMLDialogElement | null = $state(null);
 
 	const horizontal = $derived(side === 'left' || side === 'right');
@@ -80,6 +82,8 @@
 
 <dialog
 	bind:this={dialog}
+	aria-labelledby={title ? `${uid}-title` : undefined}
+	aria-describedby={description ? `${uid}-description` : undefined}
 	onclose={close}
 	onclick={(event) => {
 		if (dismissible && isBackdropClick(event, dialog)) close();
@@ -97,10 +101,12 @@
 				{#if icon}<span class={iconLg}>{@render icon()}</span>{/if}
 				<div class="flex min-w-0 flex-1 flex-col gap-1">
 					{#if title}
-						<h2 class="font-heading text-base font-semibold text-text">{title}</h2>
+						<h2 id="{uid}-title" class="font-heading text-base font-semibold text-text">{title}</h2>
 					{/if}
 					{#if description}
-						<p class="font-sans text-[13px] text-text-muted">{description}</p>
+						<p id="{uid}-description" class="font-sans text-[13px] text-text-muted">
+							{description}
+						</p>
 					{/if}
 				</div>
 				{#if dismissible}

package/dist/styles/paper/Field.svelte

@@ -24,9 +24,65 @@
 		children,
 		...rest
 	}: Props = $props();
+
+	const uid = $props.id();
+	const messageId = $derived(error ? `${uid}-error` : hint ? `${uid}-hint` : undefined);
+
+	interface Described {
+		for?: string;
+		messageId?: string;
+		required: boolean;
+		invalid: boolean;
+	}
+
+	/**
+	 * A hint nobody can hear is not a hint. `aria-describedby` has to sit on the
+	 * control, and the control arrives through `children` — out of reach of this
+	 * template — so the field finds it once the DOM exists and keeps the three
+	 * attributes in step itself. It touches only what it set: an `aria-invalid`
+	 * the control already carries from its own `invalid` prop stays that
+	 * control's business.
+	 */
+	function describes(node: HTMLElement, state: Described) {
+		let ourId: string | undefined;
+		let ownsInvalid = false;
+
+		const apply = (next: Described) => {
+			const control =
+				(next.for ? node.querySelector<HTMLElement>(`#${CSS.escape(next.for)}`) : null) ??
+				node.querySelector<HTMLElement>('input, select, textarea');
+			if (!control) return;
+
+			const ids = (control.getAttribute('aria-describedby') ?? '')
+				.split(/\s+/)
+				.filter((id) => id && id !== ourId);
+			if (next.messageId) ids.push(next.messageId);
+			if (ids.length) control.setAttribute('aria-describedby', ids.join(' '));
+			else control.removeAttribute('aria-describedby');
+			ourId = next.messageId;
+
+			if (next.required) control.setAttribute('aria-required', 'true');
+			else control.removeAttribute('aria-required');
+
+			if (next.invalid) {
+				ownsInvalid ||= !control.hasAttribute('aria-invalid');
+				control.setAttribute('aria-invalid', 'true');
+			} else if (ownsInvalid) {
+				control.removeAttribute('aria-invalid');
+				ownsInvalid = false;
+			}
+		};
+
+		apply(state);
+		return { update: apply };
+	}
 </script>
 
-<div class="flex w-full flex-col gap-1.5 {className}" {...rest}>
+<div
+	use:describes={{ for: htmlFor, messageId, required, invalid: Boolean(error) }}
+	class="flex w-full flex-col gap-1.5 {className}"
+	{...rest}
+>
 	{#if label}
 		<label for={htmlFor} class="font-sans text-sm font-medium text-text">
 			{label}
@@ -35,8 +91,8 @@
 	{/if}
 	{@render children()}
 	{#if error}
-		<p class="font-sans text-[13px] text-danger">{error}</p>
+		<p id="{uid}-error" role="alert" class="font-sans text-[13px] text-danger">{error}</p>
 	{:else if hint}
-		<p class="font-sans text-[13px] text-text-muted">{hint}</p>
+		<p id="{uid}-hint" class="font-sans text-[13px] text-text-muted">{hint}</p>
 	{/if}
 </div>

package/dist/styles/paper/Footer.svelte

@@ -59,15 +59,26 @@
 											<a
 												href={item.href}
 												target={item.external ? '_blank' : undefined}
-												rel={item.external ? 'noreferrer' : undefined}
+												rel={item.external ? 'noopener noreferrer' : undefined}
 												class="inline-flex items-center gap-2 font-sans text-[13px] text-text-muted transition-colors duration-150 ease-brand-out {toneHoverText[
 													tone
 												]}"
 											>
 												{#if item.icon}<span class={iconSm}>{@render item.icon()}</span
 													>{/if}{item.label}
-												{#if item.external}<span aria-hidden="true" class="text-[0.85em]">↗</span
-													>{/if}
+												{#if item.external}<svg
+														class="inline-block size-[0.85em] align-[-0.05em]"
+														viewBox="0 0 14 14"
+														fill="none"
+														aria-hidden="true"
+														><path
+															d="M5.5 2.5h6v6M11.5 2.5 3.5 10.5"
+															stroke="currentColor"
+															stroke-width="1.5"
+															stroke-linecap="round"
+															stroke-linejoin="round"
+														/></svg
+													><span class="sr-only">(opens in a new tab)</span>{/if}
 											</a>
 										</li>
 									{/each}

package/dist/styles/paper/Input.svelte

@@ -1,7 +1,12 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import type { HTMLInputAttributes } from 'svelte/elements';
-	import { toneFocusWithinBorder, type Tone } from '../../core/tones.js';
+	import {
+		focusWithinRing,
+		toneFocusWithinBorder,
+		toneFocusWithinRing,
+		type Tone
+	} from '../../core/tones.js';
 
 	export type InputSize = 'sm' | 'md' | 'lg';
 
@@ -37,7 +42,9 @@
 </script>
 
 <span
-	class="inline-flex w-full items-center gap-2 rounded-md border bg-bg px-3 shadow-xs transition-colors duration-150 ease-brand-out
+	class="inline-flex w-full items-center gap-2 rounded-md border bg-bg px-3 shadow-xs transition-colors duration-150 ease-brand-out {focusWithinRing} {toneFocusWithinRing[
+		tone
+	]}
 		{sizes[size]}
 		{invalid
 		? 'border-danger focus-within:border-danger'

package/dist/styles/paper/Label.svelte

@@ -12,5 +12,7 @@
 
 <label class="font-sans text-sm font-medium text-text {className}" {...rest}>
 	{@render children()}
-	{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span>{/if}
+	{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span><span class="sr-only"
+			>(required)</span
+		>{/if}
 </label>

package/dist/styles/paper/Link.svelte

@@ -40,7 +40,7 @@
 
 <a
 	target={external ? '_blank' : undefined}
-	rel={external ? 'noreferrer' : undefined}
+	rel={external ? 'noopener noreferrer' : undefined}
 	class="inline-flex items-center gap-1 rounded-sm font-sans transition-colors duration-150 ease-brand-out
 		{muted ? `text-text-secondary ${toneHoverText[tone]}` : toneText[tone]}
 		{underlines[underline]} {focusRing} {toneRing[tone]} {className}"
@@ -49,5 +49,16 @@
 	{#if icon}<span class={iconSm}>{@render icon()}</span>{/if}
 	{@render children()}
 	{#if iconEnd}<span class={iconSm}>{@render iconEnd()}</span>{/if}
-	{#if external}<span aria-hidden="true" class="text-[0.85em]">↗</span>{/if}
+	{#if external}
+		<svg class="size-[0.85em] shrink-0" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+			<path
+				d="M5.5 2.5h6v6M11.5 2.5 3.5 10.5"
+				stroke="currentColor"
+				stroke-width="1.5"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+			/>
+		</svg>
+		<span class="sr-only">(opens in a new tab)</span>
+	{/if}
 </a>

package/dist/styles/paper/MenuItem.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import type { HTMLButtonAttributes } from 'svelte/elements';
-	import { toneSoftHover, toneText, type Tone } from '../../core/tones.js';
+	import { toneSoft, toneSoftHover, toneText, type Tone } from '../../core/tones.js';
 	import { iconMd } from './icon.js';
 
 	interface Props extends HTMLButtonAttributes {
@@ -28,6 +28,11 @@
 		children,
 		...rest
 	}: Props = $props();
+
+	// A chosen row speaks in the brand, the same as an active nav link — a tick
+	// alone leaves it the same grey as every row above it. An item that already
+	// carries a tone (a red `Delete`) keeps its own.
+	const chosen = $derived(toneSoft[tone === 'neutral' ? 'brand' : tone]);
 </script>
 
 <svelte:element
@@ -39,9 +44,11 @@
 	aria-disabled={disabled ? 'true' : undefined}
 	tabindex={disabled ? undefined : -1}
 	class="mx-1 flex items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-sm transition-colors duration-100 ease-brand-out focus:outline-none disabled:pointer-events-none disabled:opacity-40
-		{tone === 'neutral'
-		? 'text-text-secondary hover:bg-bg-inset focus-visible:bg-bg-inset'
-		: `${toneText[tone]} ${toneSoftHover[tone]}`}
+		{selected
+		? `${chosen} font-medium`
+		: tone === 'neutral'
+			? 'text-text-secondary hover:bg-bg-inset focus-visible:bg-bg-inset'
+			: `${toneText[tone]} ${toneSoftHover[tone]}`}
 		{className}"
 	{...rest}
 >

package/dist/styles/paper/Modal.svelte

@@ -39,6 +39,8 @@
 		...rest
 	}: Props = $props();
 
+	const uid = $props.id();
+
 	let dialog: HTMLDialogElement | null = $state(null);
 
 	const closable = $derived(showClose ?? dismissible);
@@ -64,6 +66,8 @@
 
 <dialog
 	bind:this={dialog}
+	aria-labelledby={title ? `${uid}-title` : undefined}
+	aria-describedby={description ? `${uid}-description` : undefined}
 	onclose={close}
 	onclick={onBackdrop}
 	oncancel={(event) => {
@@ -80,10 +84,12 @@
 				{#if icon}<span class={iconLg}>{@render icon()}</span>{/if}
 				<div class="flex min-w-0 flex-1 flex-col gap-1">
 					{#if title}
-						<h2 class="font-heading text-base font-semibold text-text">{title}</h2>
+						<h2 id="{uid}-title" class="font-heading text-base font-semibold text-text">{title}</h2>
 					{/if}
 					{#if description}
-						<p class="font-sans text-[13px] text-text-muted">{description}</p>
+						<p id="{uid}-description" class="font-sans text-[13px] text-text-muted">
+							{description}
+						</p>
 					{/if}
 				</div>
 				{#if closable}

package/dist/styles/paper/Navbar.svelte

@@ -111,7 +111,7 @@
 							class="{link} {focusRing} {toneRing[tone]} {item.active
 								? toneSoft[tone]
 								: 'text-text-secondary hover:bg-bg-inset hover:text-text'} {item.disabled
-								? 'pointer-events-none opacity-50'
+								? 'pointer-events-none opacity-40'
 								: ''}"
 						>
 							{#if item.icon}<span class={iconMd}>{@render item.icon()}</span>{/if}
@@ -164,7 +164,7 @@
 					class="flex items-center justify-between gap-3 rounded-md px-3 py-2.5 font-sans text-sm font-medium {item.active
 						? `${toneSoft[tone]}`
 						: 'text-text-secondary hover:bg-bg-inset'} {item.disabled
-						? 'pointer-events-none opacity-50'
+						? 'pointer-events-none opacity-40'
 						: ''}"
 				>
 					<span class="flex min-w-0 items-center gap-2.5">

package/dist/styles/paper/Radio.svelte

@@ -24,32 +24,51 @@
 		children,
 		...rest
 	}: Props = $props();
+
+	const uid = $props.id();
 </script>
 
-<label
-	class="group inline-flex items-start gap-2.5 font-sans text-sm
-		{disabled ? 'pointer-events-none opacity-50' : 'cursor-pointer'} {className}"
+<div
+	class="inline-block font-sans text-sm {disabled
+		? 'pointer-events-none opacity-50'
+		: ''} {className}"
 >
-	<input type="radio" bind:group {value} {disabled} class="peer sr-only" {...rest} />
-	<span
-		class="mt-0.5 flex size-[18px] shrink-0 items-center justify-center rounded-full border border-hairline-strong bg-bg shadow-xs transition-colors duration-150 ease-brand-out
+	<label class="group inline-flex items-start gap-2.5 {disabled ? '' : 'cursor-pointer'}">
+		<input
+			type="radio"
+			bind:group
+			{value}
+			{disabled}
+			aria-describedby={description ? `${uid}-description` : undefined}
+			class="peer sr-only"
+			{...rest}
+		/>
+		<span
+			class="mt-0.5 flex size-[18px] shrink-0 items-center justify-center rounded-full border border-hairline-strong bg-bg shadow-xs transition-colors duration-150 ease-brand-out
 			{tonePeerChecked[tone]} {peerFocusRing} {tonePeerFocus[tone]}"
-		aria-hidden="true"
-	>
+			aria-hidden="true"
+		>
+			<span
+				class="size-1.5 rounded-full bg-text-inverse opacity-0 transition-opacity duration-150 group-has-[:checked]:opacity-100"
+			></span>
+		</span>
+		{#if label || children}
+			<span class="flex flex-col gap-0.5">
+				{#if children}
+					{@render children()}
+				{:else if label}
+					<span class="leading-snug text-text">{label}</span>
+				{/if}
+			</span>
+		{/if}
+	</label>
+	{#if description}
+		<!-- ponytail: the indent tracks the 18px dot plus the label's gap; move one, move both. -->
 		<span
-			class="size-1.5 rounded-full bg-text-inverse opacity-0 transition-opacity duration-150 group-has-[:checked]:opacity-100"
-		></span>
-	</span>
-	{#if label || description || children}
-		<span class="flex flex-col gap-0.5">
-			{#if children}
-				{@render children()}
-			{:else if label}
-				<span class="leading-snug text-text">{label}</span>
-			{/if}
-			{#if description}
-				<span class="text-[13px] leading-snug text-text-muted">{description}</span>
-			{/if}
+			id="{uid}-description"
+			class="mt-0.5 block pl-[28px] text-[13px] leading-snug text-text-muted"
+		>
+			{description}
 		</span>
 	{/if}
-</label>
+</div>

package/dist/styles/paper/RadioGroup.svelte

@@ -44,13 +44,24 @@
 		children,
 		...rest
 	}: Props = $props();
+
+	const uid = $props.id();
+	// The group's own hint and error sit outside every control in it, so the
+	// fieldset is what has to point at them.
+	const messageId = $derived(error ? `${uid}-error` : hint ? `${uid}-hint` : undefined);
 </script>
 
-<fieldset class="flex flex-col gap-3 border-0 p-0 {className}" {...rest}>
+<fieldset
+	aria-describedby={messageId}
+	class="flex flex-col gap-3 border-0 p-0 {className}"
+	{...rest}
+>
 	{#if legend}
 		<legend class="mb-1 font-sans text-sm font-medium text-text">
 			{legend}
-			{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span>{/if}
+			{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span><span
+					class="sr-only">(required)</span
+				>{/if}
 		</legend>
 	{/if}
 
@@ -94,8 +105,8 @@
 	</div>
 
 	{#if error}
-		<p class="font-sans text-[13px] text-danger">{error}</p>
+		<p id="{uid}-error" role="alert" class="font-sans text-[13px] text-danger">{error}</p>
 	{:else if hint}
-		<p class="font-sans text-[13px] text-text-muted">{hint}</p>
+		<p id="{uid}-hint" class="font-sans text-[13px] text-text-muted">{hint}</p>
 	{/if}
 </fieldset>