@nqmcreative/ui 0.4.0 → 0.4.2

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/FileInput.svelte

@@ -1,6 +1,5 @@
 <script lang="ts">
 	import { formatSize as toReadableSize, sortFiles, type RejectedFile } from '../../core/files.js';
-	import { useLocale } from '../../core/locale.svelte.js';
 	import { toneFocusWithinBorder, type Tone } from '../../core/tones.js';
 	import type { InputSize } from './Input.svelte';
 
@@ -18,9 +17,9 @@
 		size?: InputSize;
 		tone?: Tone;
 		invalid?: boolean;
-		/** Text on the button. Defaults to the locale's `chooseFile`. */
+		/** Text on the button. Defaults to `Choose file`. */
 		label?: string;
-		/** Shown while nothing is chosen. Defaults to the locale's `noFile`. */
+		/** Shown while nothing is chosen. Defaults to `No file chosen`. */
 		placeholder?: string;
 		/** Show the list of held files below the row. */
 		showList?: boolean;
@@ -50,18 +49,16 @@
 		class: className = ''
 	}: Props = $props();
 
-	const t = useLocale();
-
 	let input: HTMLInputElement | null = $state(null);
 	let rejected = $state<RejectedFile[]>([]);
 
-	const formatSize = (bytes: number) => toReadableSize(bytes, t.current.byteUnits);
+	const formatSize = (bytes: number) => toReadableSize(bytes);
 
 	/** One file reads as its name and weight; several read as a count. */
 	const summary = $derived.by(() => {
-		if (files.length === 0) return placeholder ?? t.current.noFile;
+		if (files.length === 0) return placeholder ?? 'No file chosen';
 		if (files.length === 1) return `${files[0].name} · ${formatSize(files[0].size)}`;
-		return `${files.length} ${t.current.selected}`;
+		return `${files.length} $selected`;
 	});
 
 	function add(incoming: FileList | File[] | null) {
@@ -90,9 +87,9 @@
 	}
 
 	const reasons: Record<RejectedFile['reason'], string> = $derived({
-		type: t.current.rejectedType,
-		size: t.current.rejectedSize,
-		count: t.current.rejectedCount
+		type: 'wrong file type',
+		size: 'too large',
+		count: 'over the file limit'
 	});
 
 	const sizes: Record<InputSize, string> = {
@@ -124,7 +121,7 @@
 			class="shrink-0 rounded border border-hairline-strong bg-bg-alt font-sans font-medium text-text-secondary transition-colors duration-150 hover:bg-bg-inset hover:text-text focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current
 				{buttons[size]}"
 		>
-			{label ?? t.current.chooseFile}
+			{label ?? 'Choose file'}
 		</button>
 
 		<span
@@ -137,7 +134,7 @@
 			<button
 				type="button"
 				onclick={clear}
-				aria-label={t.current.remove}
+				aria-label="Remove"
 				class="mr-1 shrink-0 rounded p-1 text-text-muted transition-colors duration-150 hover:bg-bg-inset hover:text-danger focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-danger"
 			>
 				<svg class="size-3.5" viewBox="0 0 14 14" fill="none" aria-hidden="true">
@@ -185,7 +182,7 @@
 					<button
 						type="button"
 						onclick={() => (files = files.filter((_, at) => at !== i))}
-						aria-label="{t.current.remove} {file.name}"
+						aria-label="Remove {file.name}"
 						class="-m-1 shrink-0 rounded p-1 text-text-muted transition-colors duration-150 hover:bg-bg-inset hover:text-danger focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-danger"
 					>
 						<svg class="size-3.5" viewBox="0 0 14 14" fill="none" aria-hidden="true">

package/dist/styles/paper/FileInput.svelte.d.ts

@@ -15,9 +15,9 @@ interface Props {
     size?: InputSize;
     tone?: Tone;
     invalid?: boolean;
-    /** Text on the button. Defaults to the locale's `chooseFile`. */
+    /** Text on the button. Defaults to `Choose file`. */
     label?: string;
-    /** Shown while nothing is chosen. Defaults to the locale's `noFile`. */
+    /** Shown while nothing is chosen. Defaults to `No file chosen`. */
     placeholder?: string;
     /** Show the list of held files below the row. */
     showList?: boolean;

package/dist/styles/paper/Footer.svelte

@@ -22,7 +22,7 @@
 		columns?: FooterColumn[];
 		/** Logo, wordmark and a line of copy on the left. */
 		brand?: Snippet;
-		/** Right side of the bottom bar — social links, a locale picker. */
+		/** Right side of the bottom bar — social links, a language picker. */
 		bottom?: Snippet;
 		/** Left side of the bottom bar. Ignored when `bottom` covers both. */
 		copyright?: string;
@@ -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/Footer.svelte.d.ts

@@ -15,7 +15,7 @@ interface Props {
     columns?: FooterColumn[];
     /** Logo, wordmark and a line of copy on the left. */
     brand?: Snippet;
-    /** Right side of the bottom bar — social links, a locale picker. */
+    /** Right side of the bottom bar — social links, a language picker. */
     bottom?: Snippet;
     /** Left side of the bottom bar. Ignored when `bottom` covers both. */
     copyright?: string;

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

@@ -2,7 +2,6 @@
 	import type { Snippet } from 'svelte';
 	import { iconLg } from './icon.js';
 	import type { HTMLDialogAttributes } from 'svelte/elements';
-	import { useLocale } from '../../core/locale.svelte.js';
 	import { isBackdropClick, syncDialog } from '../../core/dialog.svelte.js';
 
 	export type ModalSize = 'sm' | 'md' | 'lg';
@@ -40,7 +39,8 @@
 		...rest
 	}: Props = $props();
 
-	const t = useLocale();
+	const uid = $props.id();
+
 	let dialog: HTMLDialogElement | null = $state(null);
 
 	const closable = $derived(showClose ?? dismissible);
@@ -66,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) => {
@@ -82,17 +84,19 @@
 				{#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}
 					<button
 						type="button"
 						onclick={close}
-						aria-label={t.current.close}
+						aria-label="Close"
 						class="-m-1 shrink-0 rounded-md p-1 text-text-muted transition-colors duration-150 hover:bg-bg-inset hover:text-text focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand"
 					>
 						<svg class="size-4" viewBox="0 0 14 14" fill="none" aria-hidden="true">

package/dist/styles/paper/MultiSelect.svelte

@@ -16,7 +16,6 @@
 	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 { useLocale } from '../../core/locale.svelte.js';
 	import { iconMd, iconSm } from './icon.js';
 	import { toneFocusWithinBorder, toneSoft, toneText, type Tone } from '../../core/tones.js';
 
@@ -58,8 +57,6 @@
 		class: className = ''
 	}: Props = $props();
 
-	const t = useLocale();
-
 	let open = $state(false);
 	let query = $state('');
 	let wrapper: HTMLElement | null = $state(null);
@@ -149,7 +146,7 @@
 			class="inline-flex items-center rounded-md px-2 py-0.5 text-xs font-medium {toneSoft[tone]}"
 		>
 			{chosen.length}
-			{t.current.selected}
+			selected
 		</span>
 	{:else}
 		{#each chosen as option (option.value)}
@@ -162,7 +159,7 @@
 				<button
 					type="button"
 					onclick={() => remove(option)}
-					aria-label="{t.current.removeItem} {option.label}"
+					aria-label="Remove {option.label}"
 					class="inline-flex size-4 items-center justify-center rounded transition-colors duration-150 hover:bg-bg/70 focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-current"
 				>
 					<svg class="size-2.5" viewBox="0 0 14 14" fill="none" aria-hidden="true">
@@ -189,7 +186,7 @@
 		aria-expanded={open}
 		aria-controls="{id ?? 'multiselect'}-listbox"
 		aria-invalid={invalid ? 'true' : undefined}
-		placeholder={chosen.length ? '' : (placeholder ?? t.current.comboboxPlaceholder)}
+		placeholder={chosen.length ? '' : (placeholder ?? 'Search…')}
 		oninput={() => {
 			open = true;
 			cursor.index = 0;
@@ -211,7 +208,7 @@
 				onchange?.([]);
 				inputEl?.focus();
 			}}
-			aria-label={t.current.clear}
+			aria-label="Clear selection"
 			class="shrink-0 rounded p-1 text-text-muted transition-colors duration-150 hover:bg-bg-inset hover:text-text focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current"
 		>
 			<svg class="size-3.5" viewBox="0 0 14 14" fill="none" aria-hidden="true">
@@ -239,7 +236,7 @@
 	>
 		{#if flat.length === 0}
 			<p class="px-3 py-6 text-center text-sm text-text-muted">
-				{emptyText ?? t.current.noMatches}
+				{emptyText ?? 'No matches'}
 			</p>
 		{:else}
 			{#each groups as [group, items] (group)}

package/dist/styles/paper/Navbar.svelte

@@ -16,7 +16,6 @@
 
 <script lang="ts">
 	import type { Snippet } from 'svelte';
-	import { useLocale } from '../../core/locale.svelte.js';
 	import { iconMd } from './icon.js';
 	import { focusRing, toneRing, toneSoft, toneText, type Tone } from '../../core/tones.js';
 	import Drawer from './Drawer.svelte';
@@ -53,8 +52,6 @@
 		class: className = ''
 	}: Props = $props();
 
-	const t = useLocale();
-
 	// paper gives the active link a pill rather than a colour change, so the
 	// current page is legible without relying on hue alone.
 	const link =
@@ -66,10 +63,7 @@
 		? 'border-b border-hairline'
 		: ''} {className}"
 >
-	<nav
-		aria-label={t.current.navigation}
-		class="mx-auto flex h-16 w-full max-w-6xl items-center gap-6 px-6"
-	>
+	<nav aria-label="Navigation" class="mx-auto flex h-16 w-full max-w-6xl items-center gap-6 px-6">
 		{#if brand}
 			<div class="flex shrink-0 items-center">{@render brand()}</div>
 		{/if}
@@ -117,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}
@@ -140,7 +134,7 @@
 			<button
 				type="button"
 				onclick={() => (menuOpen = true)}
-				aria-label={t.current.openMenu}
+				aria-label="Open menu"
 				aria-expanded={menuOpen}
 				class="inline-flex size-9 items-center justify-center rounded-md text-text-secondary transition-colors duration-150 hover:bg-bg-inset hover:text-text md:hidden {focusRing} {toneRing[
 					tone
@@ -159,7 +153,7 @@
 	</nav>
 </header>
 
-<Drawer bind:open={menuOpen} side="right" size="sm" title={t.current.navigation}>
+<Drawer bind:open={menuOpen} side="right" size="sm" title="Navigation">
 	<ul class="flex flex-col gap-0.5">
 		{#each items as item (item.label)}
 			<li>
@@ -170,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/Pagination.svelte

@@ -1,7 +1,6 @@
 <script lang="ts">
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { focusRing, toneRing, toneSolid, type Tone } from '../../core/tones.js';
-	import { useLocale } from '../../core/locale.svelte.js';
 	import { pageRange } from '../../core/pagination.js';
 
 	interface Props extends Omit<HTMLAttributes<HTMLElement>, 'onchange'> {
@@ -25,8 +24,6 @@
 		...rest
 	}: Props = $props();
 
-	const t = useLocale();
-
 	const pages = $derived(pageRange(page, total, siblings));
 
 	function go(next: number) {
@@ -39,12 +36,12 @@
 	const cell = `inline-flex h-9 min-w-9 items-center justify-center rounded-md px-2 font-sans text-sm font-medium tabular-nums transition-colors duration-150 ease-brand-out disabled:opacity-40 disabled:pointer-events-none ${focusRing}`;
 </script>
 
-<nav aria-label={t.current.pagination} class="flex items-center gap-1 {className}" {...rest}>
+<nav aria-label="Pagination" class="flex items-center gap-1 {className}" {...rest}>
 	<button
 		type="button"
 		class="{cell} {toneRing[tone]} text-text-secondary hover:bg-bg-inset"
 		disabled={page <= 1}
-		aria-label={t.current.previousPage}
+		aria-label="Previous page"
 		onclick={() => go(page - 1)}
 	>
 		<svg class="size-4" viewBox="0 0 16 16" fill="none" aria-hidden="true">
@@ -73,7 +70,7 @@
 		type="button"
 		class="{cell} {toneRing[tone]} text-text-secondary hover:bg-bg-inset"
 		disabled={page >= total}
-		aria-label={t.current.nextPage}
+		aria-label="Next page"
 		onclick={() => go(page + 1)}
 	>
 		<svg class="size-4" viewBox="0 0 16 16" fill="none" aria-hidden="true">

package/dist/styles/paper/PinInput.svelte

@@ -1,5 +1,4 @@
 <script lang="ts">
-	import { useLocale } from '../../core/locale.svelte.js';
 	import { caretIndex, clearFrom, fillFrom, sanitisePin, type PinMode } from '../../core/pin.js';
 	import { toneFocusBorder, type Tone } from '../../core/tones.js';
 
@@ -38,8 +37,6 @@
 		class: className = ''
 	}: Props = $props();
 
-	const t = useLocale();
-
 	let boxes: HTMLInputElement[] = $state([]);
 
 	const chars = $derived(Array.from({ length }, (_, i) => value[i] ?? ''));
@@ -119,7 +116,7 @@
 			autocapitalize="characters"
 			spellcheck="false"
 			maxlength={length}
-			aria-label="{t.current.digit} {index + 1}"
+			aria-label="Digit {index + 1}"
 			aria-invalid={invalid ? 'true' : undefined}
 			oninput={(event) => onInput(event, index)}
 			onkeydown={(event) => onKeydown(event, index)}

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>