@spaethtech/svelte-ui 0.4.1-dev.20.b3f6fb8 → 0.4.1-dev.21.2ccc703

package/.claude/skills/svelte-ui/SKILL.md

@@ -57,6 +57,47 @@ the components use:
 
 Both accept a responsive map too, e.g. `size={{ base: "sm", md: "lg" }}`.
 
+## Field chrome (label / help / error)
+
+Every field-shaped control — `Input`, `Select`, `TextArea`, `Checkbox`, `Toggle`, and the specialized
+inputs — renders its own label + help/error frame from a shared set of props. **Don't hand-wrap fields
+in `<label>` + hint spans** — use these:
+
+- **`label`** (string) — rendered **above** the control, left-aligned. Uniform for *every* control
+  (checkbox/toggle labels sit above too), so a row of mixed controls at the same `size` lines up
+  pixel-perfect. For any other placement, omit `label` and bring your own `<label>`.
+- **`aside`** (Snippet) — right-aligned in the label row: a char count, status badge, link, button.
+- **`error`** (string | Snippet) — inline error row; also flips the error border + `aria-invalid`.
+  String is rendered as `{@html}`.
+- **`description`** (string | Snippet) — muted help row below the error (they coexist). String is
+  `{@html}` — **author-controlled markup only**, never untrusted input (use the Snippet form for that).
+- **`required`** — appends `*` to the label + sets `aria-required`.
+- **`id`** — auto-generated if omitted; wires `<label for>` + `aria-describedby`.
+
+`label`/aria wiring is automatic. Omit all of them and the field renders bare, exactly as a plain
+control.
+
+```svelte
+<Input
+  label="Slug"
+  description="Lowercase, hyphens only."
+  error={slugTaken ? "That slug is already taken." : null}
+  bind:value={slug}
+/>
+
+<!-- Mixed controls in a grid all align on the same label row + control baseline: -->
+<div class="grid grid-cols-4 gap-4 items-start">
+  <Input label="Name" bind:value={name} />
+  <Select label="Role" {options} bind:value={role} />
+  <Toggle label="Notifications" bind:checked={notify} />
+  <Checkbox label="Agree" bind:checked={agree} required />
+</div>
+```
+
+**Validation vs. error:** the built-in `validate={(v) => true | "message"}` (on Input/TextArea)
+surfaces through the **native validity tooltip** (shown on form submit); the controlled **`error`**
+prop is the inline row. Both flip the field's error border.
+
 ## Icons — no `<Icon>` component
 
 Import an MDI icon component from `~icons/mdi/*` and render it into a component's **`icon` snippet**;

package/dist/components/Checkbox.svelte

@@ -12,13 +12,19 @@
  * lg 40px — same as Input), with the box centred inside. Drop it next to a `size`-matched Input/Select
  * and everything lines up on the same baseline; the full-height wrapper is the click target while the
  * box itself stays box-sized.
+ *
+ * FIELD CHROME: `label`/`aside`/`error`/`description` (see FieldChrome.spec.md). When any is set the
+ * control is wrapped in the shared FieldChrome (label ABOVE, error/description below); with none set it
+ * renders bare + inline exactly as before (zero-regression).
  */
 -->
 <script lang="ts">
   import type { HTMLInputAttributes } from "svelte/elements";
+  import type { Snippet } from "svelte";
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
   import { variantToken, type Variant } from "../types/variants.js";
+  import FieldChrome, { nextFieldId } from "./FieldChrome.svelte";
 
   let {
     checked = $bindable(false),
@@ -27,6 +33,12 @@
     size = "md",
     variant = "primary",
     class: cls = "",
+    label = null,
+    aside,
+    error = null,
+    description = null,
+    id,
+    required = false,
     ...rest
   }: {
     checked?: boolean;
@@ -36,6 +48,11 @@
     /** The colour of the "checked" state (default primary). */
     variant?: Variant;
     class?: string;
+    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
   } & Omit<HTMLInputAttributes, "size" | "type" | "class"> = $props();
 
   // Per size: visible box dimension. Same scale as icons (14 / 16 / 20 px) so the box aligns with
@@ -71,6 +88,14 @@
     `color-mix(in srgb, var(--ui-color-background) 80%, var(${variantToken[variant]}))`,
   );
 
+  // Field chrome wiring.
+  const generatedId = nextFieldId();
+  const controlId = $derived(id ?? generatedId);
+  const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
+  const hasError = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
+  const hasDesc = $derived(isSnippet(description) ? true : !!(description && String(description).trim()));
+  const hasChrome = $derived(!!label || !!aside || hasError || hasDesc);
+
   let el = $state<HTMLInputElement>();
   // `indeterminate` is a DOM property, not an attribute — sync it imperatively so the real
   // checkbox reports the tri-state to a11y and form serialization.
@@ -79,53 +104,69 @@
   });
 </script>
 
-<label
-  class="relative inline-flex shrink-0 items-center justify-center {heightClass} {disabled
-    ? 'cursor-not-allowed opacity-50'
-    : 'cursor-pointer'} {cls}"
->
-  <!-- Real checkbox — invisible, covering the whole control so a click anywhere toggles it and
-	     keyboard/focus/screen-reader behavior is native. -->
-  <input
-    bind:this={el}
-    type="checkbox"
-    bind:checked
-    {disabled}
-    class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
-    {...rest}
-  />
-  <span
-    class="relative inline-flex items-center justify-center rounded-[3px] border transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {boxSize}"
-    style={boxStyle}
+{#snippet controlMarkup(cid: string | undefined, describedBy: string | undefined)}
+  <label
+    class="relative inline-flex shrink-0 items-center justify-center {heightClass} {disabled
+      ? 'cursor-not-allowed opacity-50'
+      : 'cursor-pointer'} {hasChrome ? 'self-start' : cls}"
   >
-    {#if indeterminate}
-      <!-- Dash for indeterminate — mid-line, contrasting mark on the filled background. -->
-      <svg
-        viewBox="0 0 16 16"
-        class={iconSizeCls}
-        style="color: {markColor}"
-        fill="none"
-        stroke="currentColor"
-        stroke-width="2.5"
-        stroke-linecap="round"
-      >
-        <line x1="4" y1="8" x2="12" y2="8" />
-      </svg>
-    {:else if checked}
-      <!-- Checkmark — sits inside the filled box. Stroke uses currentColor; `markColor` picks white
+    <!-- Real checkbox — invisible, covering the whole control so a click anywhere toggles it and
+		     keyboard/focus/screen-reader behavior is native. -->
+    <input
+      bind:this={el}
+      type="checkbox"
+      bind:checked
+      {disabled}
+      {required}
+      id={cid}
+      aria-describedby={describedBy}
+      aria-invalid={hasError || undefined}
+      class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
+      {...rest}
+    />
+    <span
+      class="relative inline-flex items-center justify-center rounded-[3px] border transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {boxSize}"
+      style={boxStyle}
+    >
+      {#if indeterminate}
+        <!-- Dash for indeterminate — mid-line, contrasting mark on the filled background. -->
+        <svg
+          viewBox="0 0 16 16"
+          class={iconSizeCls}
+          style="color: {markColor}"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2.5"
+          stroke-linecap="round"
+        >
+          <line x1="4" y1="8" x2="12" y2="8" />
+        </svg>
+      {:else if checked}
+        <!-- Checkmark — sits inside the filled box. Stroke uses currentColor; `markColor` picks white
 			     on accent fills, the background colour on neutral/ghost (which are text-coloured). -->
-      <svg
-        viewBox="0 0 16 16"
-        class={iconSizeCls}
-        style="color: {markColor}"
-        fill="none"
-        stroke="currentColor"
-        stroke-width="2.5"
-        stroke-linecap="round"
-        stroke-linejoin="round"
-      >
-        <polyline points="3.5,8.5 6.5,11.5 12.5,5" />
-      </svg>
-    {/if}
-  </span>
-</label>
+        <svg
+          viewBox="0 0 16 16"
+          class={iconSizeCls}
+          style="color: {markColor}"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2.5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <polyline points="3.5,8.5 6.5,11.5 12.5,5" />
+        </svg>
+      {/if}
+    </span>
+  </label>
+{/snippet}
+
+{#if hasChrome}
+  <FieldChrome {label} {aside} {error} {description} required={!!required} {controlId} {size} class={cls}>
+    {#snippet control({ describedBy })}
+      {@render controlMarkup(controlId, describedBy)}
+    {/snippet}
+  </FieldChrome>
+{:else}
+  {@render controlMarkup(undefined, undefined)}
+{/if}

package/dist/components/Checkbox.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { HTMLInputAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
 import type { Size } from "../types/sizes.js";
 import { type Responsive } from "../types/responsive.js";
 import { type Variant } from "../types/variants.js";
@@ -10,6 +11,11 @@ type $$ComponentProps = {
     /** The colour of the "checked" state (default primary). */
     variant?: Variant;
     class?: string;
+    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
 } & Omit<HTMLInputAttributes, "size" | "type" | "class">;
 declare const Checkbox: import("svelte").Component<$$ComponentProps, {}, "checked">;
 type Checkbox = ReturnType<typeof Checkbox>;

package/dist/components/FieldChrome.svelte

@@ -0,0 +1,104 @@
+<script lang="ts" module>
+  // Interim SSR-stable id source (Svelte has no built-in useId). A module counter is deterministic
+  // per render order, so SSR + hydration agree as long as fields render in the same order — good
+  // enough until we adopt a first-class scheme. Consumers can always pass an explicit `id`.
+  let _uid = 0;
+  export function nextFieldId(): string {
+    return `ui-field-${++_uid}`;
+  }
+</script>
+
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { Size } from "../types/sizes.js";
+  import { responsiveClasses, type Responsive } from "../types/responsive.js";
+
+  /**
+   * FieldChrome — the shared label/aside/error/description shell for every field-shaped component
+   * (Input, Select, TextArea, Checkbox, Toggle, Radio). See FieldChrome.spec.md.
+   *
+   * Renders, top to bottom (each row omitted when empty):
+   *   [ label{*} ⟷ aside ]   label row (flex justify-between; shown iff label || aside)
+   *   { control() }          the actual field, via the `control` snippet
+   *   { error }              --ui-color-error; string → {@html}
+   *   { description }        muted; string → {@html} (author-controlled markup only)
+   *
+   * The field owns its control + its error *state* (border/aria-invalid) — this only renders the
+   * chrome and hands the control snippet the `aria-describedby` string that links error/description.
+   */
+  interface Props {
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
+    required?: boolean;
+    /** Resolved control id (the field passes its `id ?? nextFieldId()`). Wires `<label for>` + aria. */
+    controlId: string;
+    size?: Responsive<Size>;
+    class?: string;
+    /** Renders the control; receives the `aria-describedby` string to apply to the input. */
+    control: Snippet<[{ describedBy: string | undefined }]>;
+  }
+
+  let {
+    label = null,
+    aside,
+    error = null,
+    description = null,
+    required = false,
+    controlId,
+    size = "md",
+    class: cls = "",
+    control,
+  }: Props = $props();
+
+  // Label tracks the size axis; error/description sit one tier smaller.
+  const labelTextMap: Record<Size, string> = { sm: "text-xs", md: "text-sm", lg: "text-base" };
+  const subTextMap: Record<Size, string> = { sm: "text-[0.6875rem]", md: "text-xs", lg: "text-sm" };
+  const labelText = $derived(responsiveClasses(size, labelTextMap));
+  const subText = $derived(responsiveClasses(size, subTextMap));
+
+  const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
+  const hasError = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
+  const hasDesc = $derived(isSnippet(description) ? true : !!(description && String(description).trim()));
+
+  const errorId = $derived(`${controlId}-error`);
+  const descId = $derived(`${controlId}-desc`);
+  const describedBy = $derived(
+    [hasError ? errorId : null, hasDesc ? descId : null].filter(Boolean).join(" ") || undefined,
+  );
+</script>
+
+<div class="flex w-full flex-col gap-1 {cls}">
+  {#if label || aside}
+    <div class="flex items-center justify-between gap-2">
+      {#if label}
+        <label
+          for={controlId}
+          class="{labelText} truncate font-medium [color:var(--ui-color-text)]"
+        >
+          {label}{#if required}<span aria-hidden="true" class="[color:var(--ui-color-error)]"> *</span
+            >{/if}
+        </label>
+      {:else}
+        <span></span>
+      {/if}
+      {#if aside}
+        <div class="{subText} flex shrink-0 items-center gap-2">{@render aside()}</div>
+      {/if}
+    </div>
+  {/if}
+
+  {@render control({ describedBy })}
+
+  {#if hasError}
+    <div id={errorId} class="{subText} [color:var(--ui-color-error)]">
+      {#if isSnippet(error)}{@render error()}{:else}{@html error}{/if}
+    </div>
+  {/if}
+  {#if hasDesc}
+    <div id={descId} class="{subText} [color:color-mix(in_srgb,var(--ui-color-text)_65%,transparent)]">
+      {#if isSnippet(description)}{@render description()}{:else}{@html description}{/if}
+    </div>
+  {/if}
+</div>

package/dist/components/FieldChrome.svelte.d.ts

@@ -0,0 +1,35 @@
+export declare function nextFieldId(): string;
+import type { Snippet } from "svelte";
+import type { Size } from "../types/sizes.js";
+import { type Responsive } from "../types/responsive.js";
+/**
+ * FieldChrome — the shared label/aside/error/description shell for every field-shaped component
+ * (Input, Select, TextArea, Checkbox, Toggle, Radio). See FieldChrome.spec.md.
+ *
+ * Renders, top to bottom (each row omitted when empty):
+ *   [ label{*} ⟷ aside ]   label row (flex justify-between; shown iff label || aside)
+ *   { control() }          the actual field, via the `control` snippet
+ *   { error }              --ui-color-error; string → {@html}
+ *   { description }        muted; string → {@html} (author-controlled markup only)
+ *
+ * The field owns its control + its error *state* (border/aria-invalid) — this only renders the
+ * chrome and hands the control snippet the `aria-describedby` string that links error/description.
+ */
+interface Props {
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
+    required?: boolean;
+    /** Resolved control id (the field passes its `id ?? nextFieldId()`). Wires `<label for>` + aria. */
+    controlId: string;
+    size?: Responsive<Size>;
+    class?: string;
+    /** Renders the control; receives the `aria-describedby` string to apply to the input. */
+    control: Snippet<[{
+        describedBy: string | undefined;
+    }]>;
+}
+declare const FieldChrome: import("svelte").Component<Props, {}, "">;
+type FieldChrome = ReturnType<typeof FieldChrome>;
+export default FieldChrome;

package/dist/components/Input.svelte

@@ -4,6 +4,7 @@
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, type Responsive } from "../types/responsive.js";
   import type { Variant } from "../types/variants.js";
+  import FieldChrome, { nextFieldId } from "./FieldChrome.svelte";
 
   // Omit the native `size` attribute (character width, a number) — we repurpose `size` as the
   // shared sm/md/lg axis; the native one is meaningless on our flex-based input anyway.
@@ -33,6 +34,16 @@
     valid?: boolean;
     touched?: boolean;
     element?: HTMLInputElement;
+    /** The bordered field box (bindable) — lets a wrapper (e.g. Select) anchor an overlay to the
+     *  field itself rather than the whole chrome stack. */
+    fieldElement?: HTMLDivElement;
+    /** Field chrome (see FieldChrome.spec.md). `label` renders above; `aside` is a right-aligned
+     *  snippet in the label row; `error` (string → {@html}) is the inline error row; `description`
+     *  (string → {@html}) is the muted help row. `required`/`id` inherited from input attrs. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
   }
 
   let {
@@ -51,9 +62,18 @@
     valid = $bindable(true),
     touched = $bindable(false),
     element = $bindable(),
+    fieldElement = $bindable(),
     type = "text",
     disabled = false,
     readonly = false,
+    // Field chrome. `id`/`required` are pulled out of the inherited input attrs so we can wire the
+    // label + aria and re-apply them explicitly on the <input>.
+    label = null,
+    aside,
+    error = null,
+    description = null,
+    id,
+    required = false,
     // Pulled out of restProps so the wrapping handlers below can't be clobbered by the
     // `{...restProps}` spread on the <input>; we still forward the consumer's callbacks.
     oninput: oninputProp,
@@ -61,6 +81,17 @@
     ...restProps
   }: Props = $props();
 
+  // Resolve the control id for label `for` + aria wiring: consumer-provided, else a stable generated
+  // one (generated ONCE — deriving `nextFieldId()` would remint it every render).
+  const generatedId = nextFieldId();
+  const controlId = $derived(id ?? generatedId);
+
+  const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
+  // Chrome `error` present? (drives the shared error STATE — border + aria-invalid — alongside a
+  // failing `validate`; the message channels differ: error → inline row, validate → native tooltip.)
+  const hasErrorProp = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
+  const invalid = $derived(hasErrorProp || (touched && !valid));
+
   let inputElement: HTMLInputElement;
 
   // Sync element binding
@@ -143,11 +174,6 @@
   const svgClass = $derived(responsiveClasses(size, svgMap));
 
   // Computed classes
-  let containerClasses = $derived.by(() => {
-    const base = "relative w-full";
-    return `${base} ${containerClass}`.trim();
-  });
-
   let wrapperClasses = $derived.by(() => {
     const base = `w-full ${heightClass} flex items-center [border-radius:var(--ui-border-radius)]`;
 
@@ -170,8 +196,12 @@
     // surface stays uniform under any theme). `borderless` overrides it with transparent (the field's
     // own background) — the 1px box stays, so the field never jumps, and the focus outline still fires.
     const frameStyles = borderless ? "[border-color:transparent]" : borderVariantClass[variant];
+    // Field background follows the variant axis: `ghost` is transparent (chromeless); every other
+    // variant fills with --ui-color-background so the field reads as a field on a non-white page.
+    const fieldBg =
+      variant === "ghost" ? "bg-transparent" : "[background-color:var(--ui-color-background)]";
     const themeStyles = [
-      "bg-transparent",
+      fieldBg,
       "border", // 1px — matches --ui-border (List/TextArea); uniform across the library
       paddingClasses,
       frameStyles,
@@ -179,9 +209,9 @@
       "focus-within:[outline-offset:0px]",
     ].join(" ");
 
-    // Validation state overrides
+    // Error state (shared): chrome `error` set OR a failing `validate` (once touched).
     let validationStyles = "";
-    if (touched && !valid) {
+    if (invalid) {
       validationStyles =
         "[border-color:var(--ui-color-error)] focus-within:[ring-color:var(--ui-color-error)]";
     }
@@ -281,9 +311,19 @@
   </span>
 {/snippet}
 
-<div class={containerClasses}>
-  <div class={wrapperClasses} style="user-select: none;">
-    {#if icon && iconPosition === "left"}
+<FieldChrome
+  {label}
+  {aside}
+  {error}
+  {description}
+  required={!!required}
+  {controlId}
+  {size}
+  class={containerClass}
+>
+  {#snippet control({ describedBy })}
+    <div bind:this={fieldElement} class="relative {wrapperClasses}" style="user-select: none;">
+      {#if icon && iconPosition === "left"}
       {#if iconClickable}
         <div
           class={iconClasses}
@@ -305,18 +345,23 @@
       {/if}
     {/if}
 
-    <input
-      bind:this={inputElement}
-      {type}
-      {value}
-      {disabled}
-      {readonly}
-      oninput={handleInput}
-      onfocus={handleFocus}
-      {...restProps}
-      class="{inputClasses} ui-input"
-      style="border: none !important; user-select: text !important;"
-    />
+      <input
+        bind:this={inputElement}
+        {type}
+        {value}
+        {disabled}
+        {readonly}
+        oninput={handleInput}
+        onfocus={handleFocus}
+        {...restProps}
+        id={controlId}
+        {required}
+        aria-describedby={describedBy}
+        aria-invalid={invalid || undefined}
+        aria-required={required || undefined}
+        class="{inputClasses} ui-input"
+        style="border: none !important; user-select: text !important;"
+      />
 
     {#if icon && iconPosition === "right"}
       {#if iconClickable}
@@ -340,13 +385,14 @@
       {/if}
     {/if}
 
-    {#if actions}
-      <div class="flex h-full shrink-0 items-center gap-1">
-        {@render actions()}
-      </div>
-    {/if}
-  </div>
-</div>
+      {#if actions}
+        <div class="flex h-full shrink-0 items-center gap-1">
+          {@render actions()}
+        </div>
+      {/if}
+    </div>
+  {/snippet}
+</FieldChrome>
 
 <style>
   /* Kill the UA focus ring/box-shadow without inline !important (which would also defeat the

package/dist/components/Input.svelte.d.ts

@@ -29,7 +29,17 @@ interface Props extends Omit<HTMLInputAttributes, "size"> {
     valid?: boolean;
     touched?: boolean;
     element?: HTMLInputElement;
+    /** The bordered field box (bindable) — lets a wrapper (e.g. Select) anchor an overlay to the
+     *  field itself rather than the whole chrome stack. */
+    fieldElement?: HTMLDivElement;
+    /** Field chrome (see FieldChrome.spec.md). `label` renders above; `aside` is a right-aligned
+     *  snippet in the label row; `error` (string → {@html}) is the inline error row; `description`
+     *  (string → {@html}) is the muted help row. `required`/`id` inherited from input attrs. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
 }
-declare const Input: import("svelte").Component<Props, {}, "element" | "value" | "valid" | "touched">;
+declare const Input: import("svelte").Component<Props, {}, "element" | "value" | "valid" | "touched" | "fieldElement">;
 type Input = ReturnType<typeof Input>;
 export default Input;

package/dist/components/Select.svelte

@@ -82,6 +82,9 @@
   let isOpen = $state(false);
   let containerElement = $state<HTMLElement>();
   let inputElement = $state<HTMLInputElement>();
+  // The trigger Input's bordered field box — the dropdown anchors HERE (not the container), so field
+  // chrome forwarded to the trigger (label/description via ...restProps) doesn't shift the dropdown.
+  let triggerField = $state<HTMLDivElement>();
   let listElement = $state<any>();
 
   // Get display text for selected value
@@ -199,6 +202,7 @@
   {/if}
   <Input
     bind:element={inputElement}
+    bind:fieldElement={triggerField}
     value={selectedLabel()}
     {placeholder}
     readonly={true}
@@ -222,7 +226,7 @@
     `anchored` engine — so it flips up/down against the viewport, is never clipped, and reserves
     no layout space. Popup keeps the List mounted (hidden) while closed, preserving its cache.
   -->
-  <Popup anchor={containerElement} bind:open={isOpen} matchWidth offset={4}>
+  <Popup anchor={triggerField ?? containerElement} bind:open={isOpen} matchWidth offset={4}>
     <List
       bind:this={listElement}
       {options}

package/dist/components/TextArea.svelte

@@ -1,10 +1,12 @@
 <script lang="ts">
   import ContentCopy from "~icons/mdi/content-copy";
   import type { HTMLTextareaAttributes } from "svelte/elements";
+  import type { Snippet } from "svelte";
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, resolveScalar, type Responsive } from "../types/responsive.js";
   import type { Variant } from "../types/variants.js";
   import { DEV } from "esm-env";
+  import FieldChrome, { nextFieldId } from "./FieldChrome.svelte";
 
   type TextAreaCopy = "none" | "selection" | "button";
 
@@ -29,6 +31,11 @@
     /** Drop the visible frame while keeping the 1px box + focus outline (border → transparent). */
     borderless?: boolean;
     required?: boolean;
+    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE; error/description below. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
     /** How the text can be copied — one exclusive mode:
      *  `'selection'` (default) — copy via native text selection only, no button;
      *  `'button'` — also show the copy-to-clipboard button;
@@ -95,12 +102,24 @@
     variant = "secondary",
     borderless = false,
     required = false,
+    label = null,
+    aside,
+    error = null,
+    description = null,
+    id,
     copy = "selection",
     oncopy,
     readonly = false,
     ...restProps
   }: Props = $props();
 
+  // Field chrome wiring. Error state = chrome `error` set OR a failing `validate` (once touched).
+  const generatedId = nextFieldId();
+  const controlId = $derived(id ?? generatedId);
+  const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
+  const hasErrorProp = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
+  const invalid = $derived(hasErrorProp || (touched && !valid));
+
   // Size axis (see types/sizes.ts): text size, wrapper padding, and the line-height the autosize
   // math keys off (so smaller sizes aren't airy). An explicit lineHeightRem still wins.
   const textMap: Record<Size, string> = { sm: "text-xs", md: "text-sm", lg: "text-base" };
@@ -295,27 +314,26 @@
   });
 
   // Computed classes
-  let containerClasses = $derived.by(() => {
-    const base = "relative w-full";
-    return `${base} ${containerClass}`.trim();
-  });
-
   let wrapperClasses = $derived.by(() => {
     const base = `relative w-full [border-radius:var(--ui-border-radius)] border ${padClass}`;
 
     // Border colour from the variant map (same calc as Input); `borderless` → transparent (its own
     // background), keeping the 1px box + focus outline.
     const frameStyles = borderless ? "[border-color:transparent]" : borderVariantClass[variant];
+    // Field background follows the variant axis: `ghost` transparent; every other variant fills with
+    // --ui-color-background so the field reads as a field on a non-white surface.
+    const fieldBg =
+      variant === "ghost" ? "bg-transparent" : "[background-color:var(--ui-color-background)]";
     const themeStyles = [
-      "bg-transparent",
+      fieldBg,
       frameStyles,
       "focus-within:[outline:2px_solid_color-mix(in_srgb,currentColor_70%,transparent)]",
       "focus-within:[outline-offset:0px]",
     ].join(" ");
 
-    // Validation state overrides
+    // Error state (shared): chrome `error` set OR a failing `validate` (once touched).
     let validationStyles = "";
-    if (touched && !valid) {
+    if (invalid) {
       validationStyles =
         "[border-color:var(--ui-color-error)] focus-within:[outline:2px_solid_color-mix(in_srgb,var(--ui-color-error)_70%,transparent)]";
     }
@@ -660,11 +678,21 @@
   });
 </script>
 
-<div class={containerClasses}>
-  <div
-    bind:this={containerElement}
-    class={wrapperClasses}
-    onmouseenter={effectiveReadonly
+<FieldChrome
+  {label}
+  {aside}
+  {error}
+  {description}
+  required={!!required}
+  {controlId}
+  {size}
+  class={containerClass}
+>
+  {#snippet control({ describedBy })}
+    <div
+      bind:this={containerElement}
+      class={wrapperClasses}
+      onmouseenter={effectiveReadonly
       ? undefined
       : () => {
           hovered = true;
@@ -703,11 +731,10 @@
       {disabled}
       readonly={effectiveReadonly}
       {required}
+      id={controlId}
       tabindex={effectiveSelectable ? undefined : -1}
-      aria-invalid={touched && !valid ? "true" : "false"}
-      aria-describedby={touched && !valid && typeof validationResult === "string"
-        ? "textarea-error"
-        : undefined}></textarea>
+      aria-invalid={invalid ? "true" : undefined}
+      aria-describedby={describedBy}></textarea>
 
     {#if effectiveCopyable && effectiveContent}
       <div
@@ -750,8 +777,9 @@
         aria-label="Scroll thumb"
       ></div>
     {/if}
-  </div>
-</div>
+    </div>
+  {/snippet}
+</FieldChrome>
 
 <style>
   /* Hide default scrollbar */

package/dist/components/TextArea.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { HTMLTextareaAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
 import type { Size } from "../types/sizes.js";
 import { type Responsive } from "../types/responsive.js";
 import type { Variant } from "../types/variants.js";
@@ -22,6 +23,11 @@ interface Props extends Omit<HTMLTextareaAttributes, "oncopy"> {
     /** Drop the visible frame while keeping the 1px box + focus outline (border → transparent). */
     borderless?: boolean;
     required?: boolean;
+    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE; error/description below. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
     /** How the text can be copied — one exclusive mode:
      *  `'selection'` (default) — copy via native text selection only, no button;
      *  `'button'` — also show the copy-to-clipboard button;

package/dist/components/Toggle.svelte

@@ -12,13 +12,19 @@
  * with the switch centred inside. So a Toggle dropped next to `size`-matched Inputs/Selects lines up on
  * the same baseline (and the full-height wrapper is the click target), while the switch itself stays
  * switch-sized rather than ballooning to the input height.
+ *
+ * FIELD CHROME: `label`/`aside`/`error`/`description` (see FieldChrome.spec.md). When any is set the
+ * control is wrapped in the shared FieldChrome (label ABOVE, error/description below); with none set it
+ * renders bare + inline exactly as before (zero-regression).
  */
 -->
 <script lang="ts">
   import type { HTMLInputAttributes } from "svelte/elements";
+  import type { Snippet } from "svelte";
   import type { Size } from "../types/sizes.js";
   import { responsiveClasses, resolveScalar, type Responsive } from "../types/responsive.js";
   import { variantToken, type Variant } from "../types/variants.js";
+  import FieldChrome, { nextFieldId } from "./FieldChrome.svelte";
 
   let {
     checked = $bindable(false),
@@ -26,6 +32,12 @@
     size = "md",
     variant = "primary",
     class: cls = "",
+    label = null,
+    aside,
+    error = null,
+    description = null,
+    id,
+    required = false,
     ...rest
   }: {
     checked?: boolean;
@@ -34,6 +46,11 @@
     /** The colour of the "on" state (default primary). */
     variant?: Variant;
     class?: string;
+    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
   } & Omit<HTMLInputAttributes, "size" | "type" | "class"> = $props();
 
   // Per size: track w/h + knob size are CLASSES (responsive); knob travel is an inline-style transform
@@ -66,28 +83,52 @@
   const knobStyle = $derived(
     `transform: ${checked ? onMap[resolveScalar(size, "md")] : "translateX(2px)"}; background-color: ${knobColor}`,
   );
+
+  // Field chrome wiring.
+  const generatedId = nextFieldId();
+  const controlId = $derived(id ?? generatedId);
+  const isSnippet = (v: unknown): v is Snippet => typeof v === "function";
+  const hasError = $derived(isSnippet(error) ? true : !!(error && String(error).trim()));
+  const hasDesc = $derived(isSnippet(description) ? true : !!(description && String(description).trim()));
+  const hasChrome = $derived(!!label || !!aside || hasError || hasDesc);
 </script>
 
-<label
-  class="relative inline-flex shrink-0 items-center {heightClass} {disabled
-    ? 'cursor-not-allowed opacity-50'
-    : 'cursor-pointer'} {cls}"
->
-  <!-- Real checkbox, invisible but covering the whole control so a click anywhere toggles it. -->
-  <input
-    type="checkbox"
-    bind:checked
-    {disabled}
-    class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
-    {...rest}
-  />
-  <span
-    class="relative inline-flex items-center rounded-full transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {trackCls}"
-    style={trackStyle}
+{#snippet controlMarkup(cid: string | undefined, describedBy: string | undefined)}
+  <label
+    class="relative inline-flex shrink-0 items-center {heightClass} {disabled
+      ? 'cursor-not-allowed opacity-50'
+      : 'cursor-pointer'} {hasChrome ? 'self-start' : cls}"
   >
+    <!-- Real checkbox, invisible but covering the whole control so a click anywhere toggles it. -->
+    <input
+      type="checkbox"
+      bind:checked
+      {disabled}
+      {required}
+      id={cid}
+      aria-describedby={describedBy}
+      aria-invalid={hasError || undefined}
+      class="peer absolute inset-0 z-10 m-0 cursor-pointer opacity-0 disabled:cursor-not-allowed"
+      {...rest}
+    />
     <span
-      class="inline-block rounded-full shadow transition-transform duration-150 {knobCls}"
-      style={knobStyle}
-    ></span>
-  </span>
-</label>
+      class="relative inline-flex items-center rounded-full transition-colors duration-150 peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:[outline-color:var(--ui-color-primary)] {trackCls}"
+      style={trackStyle}
+    >
+      <span
+        class="inline-block rounded-full shadow transition-transform duration-150 {knobCls}"
+        style={knobStyle}
+      ></span>
+    </span>
+  </label>
+{/snippet}
+
+{#if hasChrome}
+  <FieldChrome {label} {aside} {error} {description} required={!!required} {controlId} {size} class={cls}>
+    {#snippet control({ describedBy })}
+      {@render controlMarkup(controlId, describedBy)}
+    {/snippet}
+  </FieldChrome>
+{:else}
+  {@render controlMarkup(undefined, undefined)}
+{/if}

package/dist/components/Toggle.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { HTMLInputAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
 import type { Size } from "../types/sizes.js";
 import { type Responsive } from "../types/responsive.js";
 import { type Variant } from "../types/variants.js";
@@ -9,6 +10,11 @@ type $$ComponentProps = {
     /** The colour of the "on" state (default primary). */
     variant?: Variant;
     class?: string;
+    /** Field chrome (see FieldChrome.spec.md). Label renders ABOVE. */
+    label?: string | null;
+    aside?: Snippet;
+    error?: string | Snippet | null;
+    description?: string | Snippet | null;
 } & Omit<HTMLInputAttributes, "size" | "type" | "class">;
 declare const Toggle: import("svelte").Component<$$ComponentProps, {}, "checked">;
 type Toggle = ReturnType<typeof Toggle>;

package/docs/components.md

@@ -17,6 +17,30 @@ Most sizeable/themeable components share two props (defined in `types/variants.t
 - **`size`** — `sm` (24px), `md` (32px, **default**), `lg` (40px). Tied to the theme's
   `--ui-height-sm` / `--ui-height` / `--ui-height-lg`.
 
+## Field chrome (shared)
+
+Every field-shaped component — `Input`, `Select`, `TextArea`, `Checkbox`, `Toggle` (and the
+specialized inputs via `Input`) — accepts a shared label/help/error frame, rendered by one internal
+`FieldChrome` (source of truth: `src/lib/components/FieldChrome.spec.md`). With none set, the field
+renders exactly as before (zero-regression).
+
+- **`label`** (`string | null`) — rendered **above** the control, left-aligned (uniform for all
+  controls, so mixed-control rows at the same `size` align pixel-perfect). For other placements, omit
+  and supply your own `<label>`.
+- **`aside`** (`Snippet`) — right-aligned in the label row (char count, status, link, button).
+- **`error`** (`string | Snippet | null`) — inline error row (string → `{@html}`); also flips the
+  error border + `aria-invalid`. Coexists with `description`.
+- **`description`** (`string | Snippet | null`) — muted help row below the error (string → `{@html}`,
+  author-controlled markup only).
+- **`required`** (`boolean`) — appends `*` to the label + `aria-required`.
+- **`id`** (`string`) — auto-generated (SSR-stable) if omitted; wires `<label for>` + `aria-describedby`.
+
+`validate` (on `Input`/`TextArea`) is separate: it surfaces via the **native validity tooltip** (on
+form submit) and shares the error border; the controlled `error` prop is the inline row.
+
+Field **background** follows the variant axis: `ghost` → transparent, every other variant →
+`--ui-color-background`.
+
 ## Form Components
 
 ### Button

package/docs/usage.md

@@ -77,6 +77,45 @@ into a component's `icon` snippet — the library sizes and colors it:
 
 ## Component Examples
 
+### Field chrome (label / help / error)
+
+Every field-shaped component renders its own label + help/error frame — don't hand-wrap fields.
+
+```svelte
+<script>
+  import { Input, Select, Toggle, Checkbox } from "@spaethtech/svelte-ui";
+
+  let slug = $state("");
+  let slugTaken = $state(true);
+  let role = $state("editor");
+  let notify = $state(true);
+  let agree = $state(false);
+  const roles = [
+    { value: "admin", label: "Admin" },
+    { value: "editor", label: "Editor" },
+  ];
+</script>
+
+<!-- label above, muted description below, controlled error, char-count aside, required -->
+<Input
+  label="Slug"
+  required
+  description="Lowercase, hyphens only."
+  error={slugTaken ? "That slug is already taken." : null}
+  bind:value={slug}
+/>
+
+<!-- Mixed controls in a row all align on the same label row + control baseline -->
+<div class="grid grid-cols-3 gap-4 items-start">
+  <Select label="Role" options={roles} bind:value={role} />
+  <Toggle label="Notifications" bind:checked={notify} />
+  <Checkbox label="Agree to terms" bind:checked={agree} required />
+</div>
+```
+
+`validate` (on `Input`/`TextArea`) is separate — it shows the **native** validity tooltip on submit;
+the `error` prop is the inline row. Both flip the error border.
+
 ### Button
 
 ```svelte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.4.1-dev.20.b3f6fb8",
+  "version": "0.4.1-dev.21.2ccc703",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"