@nqmcreative/ui 0.4.1 → 0.4.3

package/README.md

@@ -8,7 +8,7 @@ look. Eight tones, light and dark, no runtime dependencies.
 | -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
 | `matte`  | `@nqmcreative/ui/matte`  | Flat and sharp-cornered — no radius, no shadow, no gloss. Hairline rules and mono micro-labels do the work borders usually do. |
 | `paper`  | `@nqmcreative/ui/paper`  | The neutral one. Start here if unsure: soft corners, light shadows, generous spacing, and nothing that fights the content.     |
-| `sprout` | `@nqmcreative/ui/sprout` | Warm and fully rounded — leaf green on cream, pill buttons, and a round display face. For school, community and family sites.  |
+| `sprout` | `@nqmcreative/ui/sprout` | Warm and fully rounded — leaf green on white, pill buttons, and a round display face. For school, community and family sites.  |
 
 The docs site lives in this repo — every component with a live demo, plus
 theming and contributing guides. `bun run dev` to read it.

package/dist/core/index.d.ts

@@ -8,7 +8,7 @@
  * Styles are free to ignore any of it — but there is no `matte` version of a
  * focus trap, so none of them should have to write one.
  */
-export { TONES, focusRing, peerFocusRing, toneBorder, toneBorderLeft, toneBorderSoft, toneFill, toneFocusBorder, toneFocusWithinBorder, toneHoverBorder, toneHoverText, tonePeerChecked, tonePeerFocus, toneRing, toneSoft, toneSoftHover, toneSolid, toneSolidHover, toneSurface, toneText } from './tones.js';
+export { TONES, focusRing, peerFocusRing, toneBorder, toneBorderLeft, toneBorderSoft, toneFill, toneFocusBorder, toneFocusWithinBorder, focusWithinRing, toneFocusWithinRing, toneHoverBorder, toneHoverText, tonePeerChecked, tonePeerFocus, toneRing, toneSoft, toneSoftHover, toneSolid, toneSolidHover, toneSurface, toneText } from './tones.js';
 export type { Tone } from './tones.js';
 export { anchored } from './actions/anchor.js';
 export type { Placement, AnchorOptions } from './actions/anchor.js';

package/dist/core/index.js

@@ -9,7 +9,7 @@
  * focus trap, so none of them should have to write one.
  */
 /* --- tones --- */
-export { TONES, focusRing, peerFocusRing, toneBorder, toneBorderLeft, toneBorderSoft, toneFill, toneFocusBorder, toneFocusWithinBorder, toneHoverBorder, toneHoverText, tonePeerChecked, tonePeerFocus, toneRing, toneSoft, toneSoftHover, toneSolid, toneSolidHover, toneSurface, toneText } from './tones.js';
+export { TONES, focusRing, peerFocusRing, toneBorder, toneBorderLeft, toneBorderSoft, toneFill, toneFocusBorder, toneFocusWithinBorder, focusWithinRing, toneFocusWithinRing, toneHoverBorder, toneHoverText, tonePeerChecked, tonePeerFocus, toneRing, toneSoft, toneSoftHover, toneSolid, toneSolidHover, toneSurface, toneText } from './tones.js';
 /* --- actions --- */
 export { anchored } from './actions/anchor.js';
 export { clickOutside, focusTrap, focusable, navigateList, portal } from './actions/dismissable.js';

package/dist/core/tones.d.ts

@@ -30,6 +30,16 @@ export declare const toneRing: Record<Tone, string>;
 export declare const focusRing = "focus-visible:outline-2 focus-visible:outline-offset-2";
 /** Border colour applied while the control itself has focus. */
 export declare const toneFocusBorder: Record<Tone, string>;
+/**
+ * Focus-ring geometry for a shell that holds the real control — `Input`'s
+ * wrapper, an input group. The ring belongs on the box the reader sees, not on
+ * the bare `<input>` inside it, so it is keyed off a focused descendant.
+ * `:has(:focus-visible)` rather than `:focus-within` so a pointer click into a
+ * field does not draw a keyboard affordance.
+ */
+export declare const focusWithinRing = "has-[:focus-visible]:outline-2 has-[:focus-visible]:outline-offset-2";
+/** Ring colour for `focusWithinRing`. */
+export declare const toneFocusWithinRing: Record<Tone, string>;
 /** Border colour applied while a descendant has focus (wrapped controls). */
 export declare const toneFocusWithinBorder: Record<Tone, string>;
 /** Tinted surface only (no text colour) — alerts, callouts, table rows. */

package/dist/core/tones.js

@@ -128,6 +128,25 @@ export const toneFocusBorder = {
     danger: 'focus:border-danger',
     neutral: 'focus:border-neutral'
 };
+/**
+ * Focus-ring geometry for a shell that holds the real control — `Input`'s
+ * wrapper, an input group. The ring belongs on the box the reader sees, not on
+ * the bare `<input>` inside it, so it is keyed off a focused descendant.
+ * `:has(:focus-visible)` rather than `:focus-within` so a pointer click into a
+ * field does not draw a keyboard affordance.
+ */
+export const focusWithinRing = 'has-[:focus-visible]:outline-2 has-[:focus-visible]:outline-offset-2';
+/** Ring colour for `focusWithinRing`. */
+export const toneFocusWithinRing = {
+    brand: 'has-[:focus-visible]:outline-brand',
+    accent: 'has-[:focus-visible]:outline-accent',
+    violet: 'has-[:focus-visible]:outline-violet',
+    info: 'has-[:focus-visible]:outline-info',
+    success: 'has-[:focus-visible]:outline-success',
+    warning: 'has-[:focus-visible]:outline-warning',
+    danger: 'has-[:focus-visible]:outline-danger',
+    neutral: 'has-[:focus-visible]:outline-neutral'
+};
 /** Border colour applied while a descendant has focus (wrapped controls). */
 export const toneFocusWithinBorder = {
     brand: 'focus-within:border-brand',

package/dist/core/trigger.d.ts

@@ -31,6 +31,14 @@ export declare function popupTrigger(node: HTMLElement, options: PopupTriggerOpt
  * wrapper, so screen readers announce the state on the thing being pressed.
  */
 export declare function describeTrigger(wrapper: HTMLElement | null, kind: 'menu' | 'dialog' | 'listbox', open: boolean): void;
+/**
+ * Points the real control inside a wrapper at the element that describes it —
+ * a tooltip's text. Same reason as `describeTrigger`: the control is whatever
+ * the consumer passed in a snippet, so the attribute has to be attached rather
+ * than written in the template. Without it a tooltip is decoration: sighted
+ * hover users get the hint, keyboard and screen-reader users get nothing.
+ */
+export declare function describedBy(wrapper: HTMLElement | null, id: string): void;
 /** The menu items a roving-focus menu should walk, in DOM order. */
 export declare function menuItems(menu: HTMLElement | null): HTMLElement[];
 /**

package/dist/core/trigger.js

@@ -71,6 +71,17 @@ export function describeTrigger(wrapper, kind, open) {
     control.setAttribute('aria-haspopup', kind);
     control.setAttribute('aria-expanded', String(open));
 }
+/**
+ * Points the real control inside a wrapper at the element that describes it —
+ * a tooltip's text. Same reason as `describeTrigger`: the control is whatever
+ * the consumer passed in a snippet, so the attribute has to be attached rather
+ * than written in the template. Without it a tooltip is decoration: sighted
+ * hover users get the hint, keyboard and screen-reader users get nothing.
+ */
+export function describedBy(wrapper, id) {
+    const control = wrapper?.querySelector('button, a, input, select, textarea, [tabindex]:not([tabindex="-1"])');
+    control?.setAttribute('aria-describedby', id);
+}
 /** The menu items a roving-focus menu should walk, in DOM order. */
 export function menuItems(menu) {
     return menu ? [...menu.querySelectorAll('[role="menuitem"]:not([disabled])')] : [];

package/dist/styles/matte/Alert.svelte

@@ -69,7 +69,7 @@
 
 		<div class="flex min-w-0 flex-1 flex-col gap-1">
 			{#if title}
-				<p class="text-[15px] leading-snug font-medium {toneText[tone]}">{title}</p>
+				<p class="font-heading text-[15px] leading-snug font-medium {toneText[tone]}">{title}</p>
 			{/if}
 			{#if children}
 				<div class="text-sm leading-relaxed text-text-secondary">{@render children()}</div>

package/dist/styles/matte/Avatar.svelte

@@ -47,6 +47,12 @@
 		xl: 'grid place-items-center *:size-8'
 	};
 
+	// A src that 404s left the reader with the browser's broken-image mark while
+	// the initials sat right there unused. Holding the failed URL rather than a
+	// flag means a new src is tried again on its own.
+	let failed = $state('');
+	const broken = $derived(failed !== '' && failed === src);
+
 	const initials = $derived(
 		name
 			.trim()
@@ -60,11 +66,18 @@
 
 <span
 	class="inline-flex shrink-0 items-center justify-center overflow-hidden font-mono font-medium select-none
-		{squared ? '' : 'rounded-full'} {sizes[size]} {src ? 'bg-bg-inset' : toneSoft[tone]} {className}"
+		{squared ? '' : 'rounded-full'} {sizes[size]} {src && !broken
+		? 'bg-bg-inset'
+		: toneSoft[tone]} {className}"
 	{...rest}
 >
-	{#if src}
-		<img {src} alt={alt ?? name} class="size-full object-cover" />
+	{#if src && !broken}
+		<img
+			{src}
+			alt={alt ?? name}
+			onerror={() => (failed = src ?? '')}
+			class="size-full object-cover"
+		/>
 	{:else if fallback}
 		<span class={glyphs[size]}>{@render fallback()}</span>
 	{:else}

package/dist/styles/matte/Button.svelte

@@ -63,7 +63,10 @@
 	}: Props = $props();
 
 	const base =
-		'inline-flex items-center justify-center gap-2 border font-sans font-medium whitespace-nowrap transition-all duration-150 ease-brand-out disabled:opacity-50 disabled:pointer-events-none aria-disabled:opacity-50 aria-disabled:pointer-events-none';
+		// The press: matte can't sink or scale, so a click reads as the whole
+		// button dimming a notch (brightness, not a shadow or a transform).
+		// Snaps in at 75ms, settles back over the base 150ms on release.
+		'inline-flex items-center justify-center gap-2 border font-sans font-medium whitespace-nowrap transition-[color,background-color,border-color,box-shadow,gap,filter] duration-150 ease-brand-out active:brightness-90 active:duration-75 disabled:opacity-50 disabled:pointer-events-none aria-disabled:opacity-50 aria-disabled:pointer-events-none';
 
 	const sizes: Record<ButtonSize, string> = {
 		sm: 'h-8 px-3.5 text-[13px]',
@@ -105,6 +108,10 @@
 	const iconClass = $derived(size === 'sm' ? iconSm : iconMd);
 
 	async function handleClick(event: MouseEvent) {
+		if (inert) {
+			event.preventDefault();
+			return;
+		}
 		const result = onclick?.(event);
 		// Anything else is a plain handler: nothing to wait for, nothing to lock.
 		if (!(result instanceof Promise)) return;
@@ -123,7 +130,7 @@
 	disabled={href ? undefined : inert}
 	aria-disabled={href && inert ? 'true' : undefined}
 	aria-busy={busy ? 'true' : undefined}
-	role={href ? 'button' : undefined}
+	tabindex={href && inert ? -1 : undefined}
 	class="{base} {focusRing} {toneRing[tone]} {variantClass} {isLink
 		? ''
 		: iconOnly

package/dist/styles/matte/Checkbox.svelte

@@ -25,6 +25,8 @@
 		...rest
 	}: Props = $props();
 
+	const uid = $props.id();
+
 	let el: HTMLInputElement | null = $state(null);
 
 	$effect(() => {
@@ -32,38 +34,55 @@
 	});
 </script>
 
-<label
-	class="group inline-flex items-start gap-3 font-sans text-[15px]
-		{disabled ? 'pointer-events-none opacity-50' : 'cursor-pointer'} {className}"
+<div
+	class="inline-block font-sans text-[15px] {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 border border-hairline-strong bg-bg transition-colors duration-150 ease-brand-out
+	<label class="group inline-flex items-start gap-3 {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 border border-hairline-strong bg-bg transition-colors duration-150 ease-brand-out
 			{tonePeerChecked[tone]} {peerFocusRing} {tonePeerFocus[tone]}"
-		aria-hidden="true"
-	>
-		{#if indeterminate}
-			<span class="h-px w-2.5 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="1.8" />
-			</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-sm leading-snug text-text-muted">{description}</span>
+			aria-hidden="true"
+		>
+			{#if indeterminate}
+				<span class="h-px w-2.5 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="1.8" />
+				</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-[30px] text-sm leading-snug text-text-muted"
+		>
+			{description}
+		</span>
 	{/if}
-</label>
+</div>

package/dist/styles/matte/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="text-danger" aria-hidden="true">*</span>{/if}
+			{#if required}<span class="text-danger" aria-hidden="true">*</span><span class="sr-only"
+					>(required)</span
+				>{/if}
 		</legend>
 	{/if}
 
@@ -108,8 +119,8 @@
 	</div>
 
 	{#if error}
-		<p class="font-sans text-sm text-danger">{error}</p>
+		<p id="{uid}-error" role="alert" class="font-sans text-sm text-danger">{error}</p>
 	{:else if hint}
-		<p class="font-sans text-sm text-text-muted">{hint}</p>
+		<p id="{uid}-hint" class="font-sans text-sm text-text-muted">{hint}</p>
 	{/if}
 </fieldset>

package/dist/styles/matte/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 border bg-bg pr-2 pl-3.5 transition-colors duration-150 ease-brand-out
+	class="relative inline-flex w-full items-center gap-2 border bg-bg pr-2 pl-3.5 transition-colors duration-150 ease-brand-out {focusWithinRing} {toneFocusWithinRing[
+		tone
+	]}
 		{invalid ? 'border-danger' : `border-hairline ${toneFocusWithinBorder[tone]}`}
 		{disabled ? 'pointer-events-none opacity-50' : ''} {className}"
 >
@@ -205,7 +214,7 @@
 		use:clickOutside={{ onoutside: () => (open = false), ignore: [wrapper] }}
 		id="{id ?? 'combobox'}-listbox"
 		role="listbox"
-		class="z-50 max-h-64 overflow-y-auto border border-hairline bg-bg py-1 font-sans"
+		class="z-50 max-h-64 animate-reveal overflow-y-auto border border-hairline bg-bg py-1 font-sans"
 	>
 		{#if flat.length === 0}
 			<p class="px-3 py-6 text-center text-sm text-text-muted">

package/dist/styles/matte/CommandPalette.svelte

@@ -160,7 +160,7 @@
 	onclick={(event) => {
 		if (event.target === dialog) open = false;
 	}}
-	class="mx-auto mt-[12vh] mb-auto w-[min(36rem,calc(100vw-2rem))] max-w-none border border-hairline bg-bg p-0 text-text backdrop:bg-text/40 {className}"
+	class="mx-auto mt-[12vh] mb-auto w-[min(36rem,calc(100vw-2rem))] max-w-none animate-enter border border-hairline bg-bg p-0 text-text backdrop:bg-text/40 {className}"
 >
 	<div use:focusTrap={{ autofocus: false }} onkeydown={onKeydown} role="none" class="flex flex-col">
 		<div class="flex items-center gap-3 border-b border-hairline px-3.5">

package/dist/styles/matte/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,13 @@
 			{/if}
 		</span>
 		<div class="flex min-w-0 flex-1 flex-col gap-2">
-			<h2 class="font-heading text-lg font-medium tracking-tight text-text">{title}</h2>
+			<h2 id="{uid}-title" class="font-heading text-lg font-medium tracking-tight text-text">
+				{title}
+			</h2>
 			{#if description}
-				<p class="text-sm leading-relaxed text-text-secondary">{description}</p>
+				<p id="{uid}-description" class="text-sm leading-relaxed text-text-secondary">
+					{description}
+				</p>
 			{/if}
 			{#if children}
 				{@render children()}

package/dist/styles/matte/ContextMenu.svelte

@@ -78,7 +78,7 @@
 		role="menu"
 		aria-label={label ?? 'Menu'}
 		tabindex="-1"
-		class="z-50 flex max-h-[min(24rem,80vh)] min-w-44 flex-col overflow-y-auto border border-hairline bg-bg py-1 font-sans {menuClass}"
+		class="z-50 flex max-h-[min(24rem,80vh)] min-w-44 animate-reveal flex-col overflow-y-auto border border-hairline bg-bg py-1 font-sans {menuClass}"
 	>
 		{@render menu()}
 	</div>

package/dist/styles/matte/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 border bg-bg pr-1 pl-3.5 transition-colors duration-150 ease-brand-out
+	class="inline-flex w-full items-center gap-1 border bg-bg pr-1 pl-3.5 transition-colors duration-150 ease-brand-out {focusWithinRing} {toneFocusWithinRing[
+		tone
+	]}
 		{invalid ? 'border-danger' : `border-hairline ${toneFocusWithinBorder[tone]}`}
 		{disabled ? 'pointer-events-none opacity-50' : ''} {className}"
 >
@@ -162,7 +169,7 @@
 		use:anchored={{ anchor: wrapper, placement: 'bottom-start', offset: 4 }}
 		use:clickOutside={{ onoutside: () => (open = false), ignore: [wrapper] }}
 		id="{id ?? 'datepicker'}-calendar"
-		class="z-50 border border-hairline bg-bg"
+		class="z-50 animate-reveal border border-hairline bg-bg"
 	>
 		<Calendar
 			bind:value

package/dist/styles/matte/Divider.svelte

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

package/dist/styles/matte/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,14 @@
 				{#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-lg font-medium tracking-tight">{title}</h2>
+						<h2 id="{uid}-title" class="font-heading text-lg font-medium tracking-tight">
+							{title}
+						</h2>
 					{/if}
 					{#if description}
-						<p class="font-sans text-sm text-text-secondary">{description}</p>
+						<p id="{uid}-description" class="font-sans text-sm text-text-secondary">
+							{description}
+						</p>
 					{/if}
 				</div>
 				{#if dismissible}

package/dist/styles/matte/Dropdown.svelte

@@ -84,7 +84,7 @@
 		role="menu"
 		aria-label={label ?? 'Menu'}
 		tabindex="-1"
-		class="z-50 flex max-h-[min(24rem,80vh)] min-w-44 flex-col overflow-y-auto border border-hairline bg-bg py-1 font-sans {className}"
+		class="z-50 flex max-h-[min(24rem,80vh)] min-w-44 animate-reveal flex-col overflow-y-auto border border-hairline bg-bg py-1 font-sans {className}"
 	>
 		{@render children()}
 	</div>

package/dist/styles/matte/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-2 {className}" {...rest}>
+<div
+	use:describes={{ for: htmlFor, messageId, required, invalid: Boolean(error) }}
+	class="flex w-full flex-col gap-2 {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-sm text-danger">{error}</p>
+		<p id="{uid}-error" role="alert" class="font-sans text-sm text-danger">{error}</p>
 	{:else if hint}
-		<p class="font-sans text-sm text-text-muted">{hint}</p>
+		<p id="{uid}-hint" class="font-sans text-sm text-text-muted">{hint}</p>
 	{/if}
 </div>

package/dist/styles/matte/Footer.svelte

@@ -61,15 +61,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-sm text-text-secondary 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/matte/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 border bg-bg px-3.5 transition-colors duration-150 ease-brand-out
+	class="inline-flex w-full items-center gap-2 border bg-bg px-3.5 transition-colors duration-150 ease-brand-out {focusWithinRing} {toneFocusWithinRing[
+		tone
+	]}
 		{sizes[size]}
 		{invalid
 		? 'border-danger focus-within:border-danger'

package/dist/styles/matte/Label.svelte

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