@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/field-row/field-row.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   cloneElement,
   forwardRef,
@@ -8,16 +10,43 @@ import {
 } from "react";
 import { Slot } from "@radix-ui/react-slot";
 import { cn } from "../../lib/cn";
+import { hasRenderableContent } from "../../lib/has-renderable-content";
 import { Label } from "../label";
 
 export interface FieldRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
   /** Field label — rendered as a real `<label>`, click-to-focus associated with the control. */
   label: ReactNode;
-  /** Optional help/description text, always visible (not gated by an error). */
+  /**
+   * Optional help/description text, always visible (not gated by an error).
+   * Renders nothing — and contributes no id to `aria-describedby` — when
+   * `description` is falsy (`false`/`0`/`""`/`null`/`undefined`), an empty
+   * array, or an array containing only falsy values (`{list.map(...)}` on an
+   * empty list; `[a && "x", b && "y"]` with both false).
+   *
+   * **Known limit:** a value that is itself a COMPONENT that renders nothing
+   * (returns `null`/an empty fragment) is not knowable before render, so it
+   * still produces an empty paragraph that `aria-describedby` points at.
+   * `FieldDescription` and the wider React ecosystem share this limit — pass
+   * a falsy value instead of a component that may render nothing, e.g.
+   * `description={hasHint ? hintText : undefined}`, never
+   * `description={<MaybeRendersNull />}`.
+   */
   description?: ReactNode;
   /**
    * Validation error text. When present: sets `aria-invalid` on the control,
    * is appended to `aria-describedby`, and is announced via `role="alert"`.
+   * Renders nothing — and leaves `aria-invalid="false"` — when `error` is
+   * falsy (`false`/`0`/`""`/`null`/`undefined`), an empty array, or an array
+   * containing only falsy values (`{errors.map(...)}` on an empty list — the
+   * idiomatic "no errors" shape).
+   *
+   * **Known limit:** a value that is itself a COMPONENT that renders nothing
+   * (returns `null`/an empty fragment) is not knowable before render, so it
+   * still produces an empty `role="alert"` element that `aria-describedby`
+   * points at. `FieldError` and the wider React ecosystem share this limit —
+   * pass a falsy value instead of a component that may render nothing, e.g.
+   * `error={hasError ? message : undefined}`, never
+   * `error={<MaybeRendersNull />}`.
    */
   error?: ReactNode;
   /**
@@ -62,11 +91,19 @@ export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(function Field
   const childProps = control.props;
   const controlId = childProps.id ?? `${id}-control`;
 
+  // Same predicate `FieldDescription`/`FieldError` use (`../field/field.tsx`)
+  // — bare truthiness (`description ? … : null`) treats an empty/all-falsy
+  // ARRAY as content, since every array is truthy in JS. `errors.map(...)`
+  // on an empty list is the idiomatic "no errors" shape, so that gap is a
+  // real defect here, not a hypothetical (#93).
+  const hasDescription = hasRenderableContent(description);
+  const hasError = hasRenderableContent(error);
+
   const describedBy =
     [
       childProps["aria-describedby"] ?? null,
-      description ? descriptionId : null,
-      error ? errorId : null,
+      hasDescription ? descriptionId : null,
+      hasError ? errorId : null,
     ]
       .filter(Boolean)
       .join(" ") || undefined;
@@ -86,12 +123,19 @@ export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(function Field
       <Slot
         id={controlId}
         aria-describedby={describedBy}
-        aria-invalid={!!error}
+        // `FieldRoot.invalid` (`../field/field.tsx`) is intentionally
+        // INDEPENDENT of whether a `FieldError` with content is mounted — a
+        // caller can mark the control invalid before its message settles.
+        // `FieldRow` has no such prop: `error` is its only invalidity
+        // signal, so "no error content" must mean "not invalid" — deriving
+        // this from raw `!!error` marked `error={[]}` invalid with nothing
+        // to explain why (#93).
+        aria-invalid={hasError}
         data-slot="field-row-control"
       >
         {cloneElement(control, { id: controlId, "aria-describedby": describedBy })}
       </Slot>
-      {description ? (
+      {hasDescription ? (
         <p
           id={descriptionId}
           data-slot="field-row-description"
@@ -100,7 +144,7 @@ export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(function Field
           {description}
         </p>
       ) : null}
-      {error ? (
+      {hasError ? (
         <p
           id={errorId}
           role="alert"

package/src/components/file-upload/file-upload.stories.tsx

@@ -1,5 +1,6 @@
 import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "storybook/test";
 import {
   FileUpload,
   FileUploadDropzone,
@@ -106,6 +107,21 @@ export const Default: Story = {
       </FileUpload>
     </div>
   ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // #322 — the dropzone (`focus-ring-within`) is the sole compound focus
+    // indicator for this composite control; the inner "Browse files" button
+    // must delegate its own indicator to it, never paint a second one.
+    const browseButton = canvas.getByRole("button", { name: "Browse files" });
+    await userEvent.tab();
+    await expect(browseButton).toHaveFocus();
+    const dropzone = browseButton.closest('[data-slot="file-upload-dropzone"]');
+    await expect(dropzone).not.toBeNull();
+    const dropzoneStyle = getComputedStyle(dropzone as HTMLElement);
+    const buttonStyle = getComputedStyle(browseButton);
+    await expect(dropzoneStyle.outlineStyle).toBe("solid");
+    await expect(buttonStyle.outlineStyle).not.toBe("solid");
+  },
 };
 
 export const Uncontrolled: Story = {

package/src/components/file-upload/file-upload.test.tsx

@@ -15,21 +15,28 @@ function makeUploadFile(name = "test.txt", size = 1024): UploadFile {
 }
 
 describe("FileUpload", () => {
-  it("renders the dropzone with a label pointing to the hidden input", () => {
+  it("default dropzone exposes exactly one control: the Browse files button", () => {
     render(
       <FileUpload>
         <FileUploadDropzone />
       </FileUpload>,
     );
-    // The label wraps the input — label's htmlFor matches input's id
-    const label = document.querySelector("label[data-slot='file-upload-dropzone']");
-    expect(label).not.toBeNull();
-    const inputId = label!.getAttribute("for");
-    expect(inputId).toBeTruthy();
-    const input = document.getElementById(inputId!);
-    expect(input).not.toBeNull();
-    expect(input!.tagName.toLowerCase()).toBe("input");
-    expect(input).toHaveAttribute("type", "file");
+    const dropzone = document.querySelector("[data-slot='file-upload-dropzone']")!;
+    // The zone is a plain drop surface — no role, no tab stop — so the inner
+    // button is never nested inside another interactive element (axe
+    // `nested-interactive` / `aria-allowed-role`).
+    expect(dropzone.tagName.toLowerCase()).toBe("div");
+    expect(dropzone).not.toHaveAttribute("role");
+    expect(dropzone).not.toHaveAttribute("tabIndex");
+    expect(screen.getAllByRole("button")).toHaveLength(1);
+
+    const input = document.querySelector("input[type='file']") as HTMLInputElement;
+    const clickSpy = vi.spyOn(input, "click");
+    fireEvent.click(screen.getByRole("button", { name: "Browse files" }));
+    // One activation opens the picker once (the zone's click must not re-fire it).
+    expect(clickSpy).toHaveBeenCalledTimes(1);
+    fireEvent.click(dropzone);
+    expect(clickSpy).toHaveBeenCalledTimes(2);
   });
 
   it("hidden file input has sr-only class (visually hidden but real)", () => {
@@ -88,7 +95,11 @@ describe("FileUpload", () => {
     expect(onFilesChange.mock.calls[0]![0]).toHaveLength(0);
   });
 
-  it("FileUploadList renders role=status and aria-live=polite", () => {
+  it("FileUploadList announces via aria-live while keeping its native list role", () => {
+    // NOT role="status" — that would override the <ul>'s implicit `list`
+    // role and strip `listitem` from every <FileUploadItem> inside it
+    // (an axe `listitem` violation). `aria-live="polite"` alone still
+    // announces additions/removals to assistive tech.
     const f = makeUploadFile();
     render(
       <FileUpload files={[f]} onFilesChange={() => {}}>
@@ -97,8 +108,9 @@ describe("FileUpload", () => {
         </FileUploadList>
       </FileUpload>,
     );
-    const list = screen.getByRole("status");
+    const list = screen.getByRole("list");
     expect(list).toHaveAttribute("aria-live", "polite");
+    expect(list).not.toHaveAttribute("role");
   });
 
   it("FileUploadList returns null when no files and no children", () => {
@@ -151,6 +163,72 @@ describe("FileUpload", () => {
     expect(onFilesChange).toHaveBeenCalledWith([]);
   });
 
+  it("drag-and-drop rejects files that don't match `accept` and reports why", () => {
+    const onFilesChange = vi.fn();
+    const onFilesRejected = vi.fn();
+    render(
+      <FileUpload
+        files={[]}
+        onFilesChange={onFilesChange}
+        onFilesRejected={onFilesRejected}
+        accept=".png"
+      >
+        <FileUploadDropzone />
+      </FileUpload>,
+    );
+    const dropzone = document.querySelector("[data-slot='file-upload-dropzone']")!;
+    const wrongType = new File(["x"], "notes.txt", { type: "text/plain" });
+    fireEvent.drop(dropzone, { dataTransfer: { files: [wrongType] } });
+
+    // A drop bypasses the native <input accept> filter entirely — without
+    // this, a dragged-in .txt would be added even though the picker would
+    // never have offered it.
+    expect(onFilesChange).toHaveBeenCalledWith([]);
+    expect(onFilesRejected).toHaveBeenCalledWith([{ file: wrongType, reason: "accept" }]);
+  });
+
+  it("drag-and-drop of several files when multiple=false keeps only the first, rejects the rest", () => {
+    const onFilesChange = vi.fn();
+    const onFilesRejected = vi.fn();
+    render(
+      <FileUpload files={[]} onFilesChange={onFilesChange} onFilesRejected={onFilesRejected}>
+        <FileUploadDropzone />
+      </FileUpload>,
+    );
+    const dropzone = document.querySelector("[data-slot='file-upload-dropzone']")!;
+    const first = new File(["a"], "a.txt", { type: "text/plain" });
+    const second = new File(["b"], "b.txt", { type: "text/plain" });
+    fireEvent.drop(dropzone, { dataTransfer: { files: [first, second] } });
+
+    // `multiple` is only enforced by the browser for the picker dialog, never
+    // for a raw DataTransfer drop.
+    expect(onFilesChange.mock.calls[0]![0]).toHaveLength(1);
+    expect(onFilesChange.mock.calls[0]![0][0].file.name).toBe("a.txt");
+    expect(onFilesRejected).toHaveBeenCalledWith([{ file: second, reason: "multiple" }]);
+  });
+
+  it("a custom-children dropzone still opens the picker on Enter/Space (keyboard reachable)", () => {
+    render(
+      <FileUpload>
+        <FileUploadDropzone>Drop it here</FileUploadDropzone>
+      </FileUpload>,
+    );
+    // With custom `children` there is no fallback "Browse files" button —
+    // the zone itself must be the one control: a tab stop answering Enter/Space.
+    const dropzone = screen.getByRole("button");
+    expect(dropzone).toHaveTextContent("Drop it here");
+    expect(dropzone).toHaveAttribute("data-slot", "file-upload-dropzone");
+    expect(dropzone).toHaveAttribute("tabIndex", "0");
+
+    const input = document.querySelector("input[type='file']") as HTMLInputElement;
+    const clickSpy = vi.spyOn(input, "click");
+    fireEvent.keyDown(dropzone, { key: "Enter" });
+    expect(clickSpy).toHaveBeenCalledTimes(1);
+
+    fireEvent.keyDown(dropzone, { key: " " });
+    expect(clickSpy).toHaveBeenCalledTimes(2);
+  });
+
   it("disabled prop disables the file input and remove buttons", () => {
     const f = makeUploadFile();
     render(

package/src/components/file-upload/file-upload.tsx

@@ -18,6 +18,7 @@ import {
 import { X, Upload, FileIcon, CheckCircle2, AlertCircle } from "lucide-react";
 import { cn } from "../../lib/cn";
 import { Button } from "../button";
+import { useLocale } from "../locale-provider";
 import { Progress } from "../progress";
 
 // ---------------------------------------------------------------------------
@@ -39,6 +40,42 @@ export interface UploadFile {
   errorMessage?: string;
 }
 
+/** Why `addFiles` (picker OR drag-and-drop) declined a file. */
+export type FileRejectionReason = "accept" | "maxSize" | "maxFiles" | "multiple";
+
+export interface FileRejection {
+  file: File;
+  reason: FileRejectionReason;
+}
+
+/**
+ * Match a file against an `<input accept>`-style pattern list (comma-separated
+ * extensions like `.png`, exact MIME types like `image/png`, or wildcards like
+ * `image/*`). Drag-and-drop delivers files straight from `DataTransfer` — the
+ * browser only enforces `accept` for the native picker dialog, never for a
+ * drop — so this has to be re-applied by hand for the drop path to actually
+ * "respect `accept`".
+ */
+function fileMatchesAccept(file: File, accept: string | undefined): boolean {
+  if (!accept) return true;
+  const patterns = accept
+    .split(",")
+    .map((p) => p.trim().toLowerCase())
+    .filter(Boolean);
+  if (patterns.length === 0) return true;
+  const name = file.name.toLowerCase();
+  const type = file.type.toLowerCase();
+  return patterns.some((pattern) => {
+    if (pattern.startsWith(".")) return name.endsWith(pattern);
+    if (pattern.endsWith("/*")) return type.startsWith(pattern.slice(0, -1));
+    return type === pattern;
+  });
+}
+
+function makeUploadFileId(file: File): string {
+  return `${file.name}-${Date.now()}-${Math.random()}`;
+}
+
 // ---------------------------------------------------------------------------
 // Context
 // ---------------------------------------------------------------------------
@@ -58,6 +95,22 @@ interface FileUploadContextValue {
   inputId: string;
 }
 
+/** Read `accept`/`multiple`/`maxSize`/`maxFiles` off a rejection for a default message. */
+export function describeFileRejection(rejection: FileRejection): string {
+  switch (rejection.reason) {
+    case "accept":
+      return `${rejection.file.name} is not an accepted file type.`;
+    case "maxSize":
+      return `${rejection.file.name} is too large.`;
+    case "maxFiles":
+      return `${rejection.file.name} was not added — the file limit was reached.`;
+    case "multiple":
+      return `${rejection.file.name} was not added — only one file is allowed.`;
+    default:
+      return `${rejection.file.name} was not added.`;
+  }
+}
+
 const FileUploadContext = createContext<FileUploadContextValue | null>(null);
 
 function useFileUpload(): FileUploadContextValue {
@@ -75,6 +128,12 @@ export interface FileUploadProps extends HTMLAttributes<HTMLDivElement> {
   files?: UploadFile[];
   /** Called when files are added or removed. */
   onFilesChange?: (files: UploadFile[]) => void;
+  /**
+   * Called with the files a picker selection OR a drag-and-drop declined —
+   * wrong type (`accept`), over `maxSize`, over `maxFiles`, or extra files
+   * dropped when `multiple` is false — each with its {@link FileRejectionReason}.
+   */
+  onFilesRejected?: (rejections: FileRejection[]) => void;
   /** Accepted MIME types / extensions (forwarded to <input accept>). */
   accept?: string;
   /** Allow multiple files at once. */
@@ -102,6 +161,7 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(function F
   {
     files: filesProp,
     onFilesChange,
+    onFilesRejected,
     accept,
     multiple = false,
     maxSize,
@@ -134,19 +194,45 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(function F
 
   const addFiles = useCallback(
     (incoming: File[]) => {
-      const toAdd = incoming.filter((f) => {
-        if (maxSize && f.size > maxSize) return false;
-        return true;
-      });
+      const rejections: FileRejection[] = [];
+
+      // A drop can deliver more files than the native picker ever would —
+      // `multiple` is only enforced by the browser for the `<input>` dialog,
+      // never for `DataTransfer`, so re-apply it here for the drop path too.
+      let candidates = incoming;
+      if (!multiple && candidates.length > 1) {
+        rejections.push(
+          ...candidates.slice(1).map((file) => ({ file, reason: "multiple" as const })),
+        );
+        candidates = candidates.slice(0, 1);
+      }
+
+      const toAdd: File[] = [];
+      for (const f of candidates) {
+        if (!fileMatchesAccept(f, accept)) {
+          rejections.push({ file: f, reason: "accept" });
+          continue;
+        }
+        if (maxSize && f.size > maxSize) {
+          rejections.push({ file: f, reason: "maxSize" });
+          continue;
+        }
+        toAdd.push(f);
+      }
 
       const next = [...files];
       for (const f of toAdd) {
-        if (maxFiles && next.length >= maxFiles) break;
-        next.push({ id: `${f.name}-${Date.now()}-${Math.random()}`, file: f });
+        if (maxFiles && next.length >= maxFiles) {
+          rejections.push({ file: f, reason: "maxFiles" });
+          continue;
+        }
+        next.push({ id: makeUploadFileId(f), file: f });
       }
+
       commit(next);
+      if (rejections.length > 0) onFilesRejected?.(rejections);
     },
-    [files, maxSize, maxFiles, commit],
+    [files, accept, multiple, maxSize, maxFiles, commit, onFilesRejected],
   );
 
   const removeFile = useCallback(
@@ -256,30 +342,61 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(function F
 // FileUploadDropzone
 // ---------------------------------------------------------------------------
 
-export interface FileUploadDropzoneProps extends HTMLAttributes<HTMLElement> {
-  /** Label for the visually-hidden file picker link (for SR users). */
+export interface FileUploadDropzoneProps extends HTMLAttributes<HTMLDivElement> {
+  /** Label for the default "Browse files" button. */
   browseLabel?: string;
 }
 
 /**
  * FileUploadDropzone — the drag-and-drop target.
  *
- * Uses a `<label>` wrapping the hidden `<input>` so the ENTIRE zone is ONE hit
- * target — no `<div onClick>`.  Keyboard users get the Browse button as a
- * complementary path.
+ * A plain `<div>` drop surface with exactly ONE keyboard-reachable control:
+ *
+ * - Default content: a real `<button>` ("Browse files") is the tab stop; the
+ *   zone itself carries no role and no tab stop, so nothing interactive is
+ *   nested inside another interactive element.
+ * - Custom `children`: there is no inner button, so the zone itself becomes
+ *   the control (`role="button"`, a tab stop, Enter/Space). Custom children
+ *   must then be non-interactive content.
+ *
+ * A pointer click anywhere on the zone also opens the picker — a mouse
+ * convenience on top of the keyboard path above, never the only path.
  */
-export const FileUploadDropzone = forwardRef<HTMLElement, FileUploadDropzoneProps>(
+export const FileUploadDropzone = forwardRef<HTMLDivElement, FileUploadDropzoneProps>(
   function FileUploadDropzone(
-    { className, children, browseLabel = "Browse files", ...props },
+    { className, children, browseLabel, onClick, onKeyDown, ...props },
     ref,
   ) {
-    const { isDragging, disabled, inputId, openPicker } = useFileUpload();
+    const { isDragging, disabled, openPicker } = useFileUpload();
+    const { t } = useLocale();
+    const resolvedBrowseLabel = browseLabel ?? t("ui.fileUpload.browseFiles");
+    // With custom children there is no inner button, so the zone owns the
+    // one keyboard path itself.
+    const isSelfControl = children != null;
 
     return (
-      // label wraps the hidden input — clicking anywhere on the zone opens the picker
-      <label
-        ref={ref as React.Ref<HTMLLabelElement>}
-        htmlFor={inputId}
+      <div
+        ref={ref}
+        role={isSelfControl ? "button" : undefined}
+        tabIndex={isSelfControl && !disabled ? 0 : undefined}
+        // Also on the default (role-less) zone: it marks the dimmed copy as
+        // inactive UI, which WCAG 1.4.3 exempts from contrast — the same
+        // exemption a `<label>` of a disabled control gets.
+        aria-disabled={disabled || undefined}
+        onClick={(e) => {
+          onClick?.(e);
+          if (disabled || e.defaultPrevented) return;
+          openPicker();
+        }}
+        onKeyDown={(e) => {
+          onKeyDown?.(e);
+          if (!isSelfControl || disabled || e.defaultPrevented) return;
+          if (e.target !== e.currentTarget) return;
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            openPicker();
+          }
+        }}
         data-slot="file-upload-dropzone"
         data-dragging={isDragging || undefined}
         data-disabled={disabled || undefined}
@@ -289,7 +406,7 @@ export const FileUploadDropzone = forwardRef<HTMLElement, FileUploadDropzoneProp
           "hover:border-ring hover:bg-accent/50",
           "data-[dragging]:border-primary data-[dragging]:bg-primary/5",
           "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
-          "focus-within:outline-none focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background",
+          "focus-ring-within focus-within:ring-offset-2 focus-within:ring-offset-background",
           className,
         )}
         {...props}
@@ -300,29 +417,37 @@ export const FileUploadDropzone = forwardRef<HTMLElement, FileUploadDropzoneProp
               <Upload className="size-5 text-muted-foreground" aria-hidden="true" />
             </div>
             <div className="flex flex-col items-center gap-1 text-center">
-              <p className="text-sm font-medium text-foreground">Drag & drop files here</p>
-              <p className="text-xs text-muted-foreground">
+              <p className="text-body font-medium text-foreground">
+                {t("ui.fileUpload.dragDropHere")}
+              </p>
+              <p className="text-meta text-muted-foreground">
                 or{" "}
                 <button
                   type="button"
                   disabled={disabled}
                   onClick={(e) => {
-                    e.preventDefault();
+                    // The zone's own click handler opens the picker; stop the
+                    // bubble so one activation opens it exactly once.
+                    e.stopPropagation();
                     openPicker();
                   }}
                   className={cn(
                     // #399 — inline text trigger inside a sentence → `-text` rung.
-                    "text-primary-text underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm",
+                    "text-primary-text underline-offset-2 hover:underline focus-ring rounded-sm",
+                    // #322 — the dropzone's `focus-ring-within` (above) is the
+                    // one compound indicator for this composite control; this
+                    // button delegates rather than painting a second one.
+                    "focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0",
                     "disabled:pointer-events-none disabled:opacity-50",
                   )}
                 >
-                  {browseLabel}
+                  {resolvedBrowseLabel}
                 </button>
               </p>
             </div>
           </>
         )}
-      </label>
+      </div>
     );
   },
 );
@@ -340,14 +465,19 @@ export type FileUploadListProps = HTMLAttributes<HTMLUListElement>;
 export const FileUploadList = forwardRef<HTMLUListElement, FileUploadListProps>(
   function FileUploadList({ className, children, ...props }, ref) {
     const { files } = useFileUpload();
+    const { t } = useLocale();
     if (files.length === 0 && !children) return null;
 
     return (
+      // `aria-live="polite"` alone is enough to announce additions/removals —
+      // it does NOT require `role="status"`. Adding that role here used to
+      // override the `<ul>`'s implicit `list` role, which strips the
+      // `listitem` role from every `<FileUploadItem>` (`<li>`) inside it and
+      // fails axe's `listitem` rule the moment the list is non-empty.
       <ul
         ref={ref}
-        role="status"
         aria-live="polite"
-        aria-label="Selected files"
+        aria-label={t("ui.fileUpload.selectedFiles")}
         data-slot="file-upload-list"
         className={cn("flex flex-col gap-2", className)}
         {...props}
@@ -412,10 +542,10 @@ export const FileUploadItem = forwardRef<HTMLLIElement, FileUploadItemProps>(
       >
         <div className="flex items-center gap-2">
           {statusIcon[resolvedStatus]}
-          <span className="flex-1 min-w-0 truncate text-sm text-foreground">
+          <span className="flex-1 min-w-0 truncate text-body text-foreground">
             {uploadFile.file.name}
           </span>
-          <span className="shrink-0 text-xs tabular-nums text-muted-foreground">
+          <span className="shrink-0 text-meta tabular-nums text-muted-foreground">
             {formatFileSize(uploadFile.file.size)}
           </span>
           <Button
@@ -434,7 +564,10 @@ export const FileUploadItem = forwardRef<HTMLLIElement, FileUploadItemProps>(
           <Progress value={resolvedProgress} className="h-1" />
         )}
         {isError && resolvedError && (
-          <p role="alert" className="text-xs text-destructive">
+          // #124: this is running text (the rejection reason), so it takes the
+          // >=4.5:1 ink rung `text-destructive-text` — not the 3:1 mark rung the
+          // `statusIcon.error` glyph above correctly keeps.
+          <p role="alert" className="text-meta text-destructive-text">
             {resolvedError}
           </p>
         )}

package/src/components/form/form.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   createContext,
   forwardRef,
@@ -80,7 +82,8 @@ export const FormLabel = forwardRef<
       htmlFor={formItemId}
       className={cn(
         "transition-colors duration-fast ease-standard",
-        error && "text-destructive",
+        // #124: the label's own error-state text, not a mark — ink rung.
+        error && "text-destructive-text",
         className,
       )}
       {...props}
@@ -113,7 +116,7 @@ export const FormDescription = forwardRef<
     <p
       ref={ref}
       id={formDescriptionId}
-      className={cn("text-sm text-muted-foreground", className)}
+      className={cn("text-body text-muted-foreground", className)}
       {...props}
     />
   );
@@ -129,7 +132,9 @@ export const FormMessage = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLP
         ref={ref}
         id={formMessageId}
         className={cn(
-          "text-sm font-medium text-destructive animate-in fade-in slide-in-from-top-1 ease-entrance",
+          // #124: the error message body is running text — ink rung, not the
+          // 3:1 mark rung `text-destructive` guarantees.
+          "text-body font-medium text-destructive-text animate-in fade-in slide-in-from-top-1 ease-entrance",
           className,
         )}
         {...props}

package/src/components/hover-card/hover-card.tsx

@@ -12,6 +12,7 @@ export const HoverCardContent = forwardRef<
   return (
     <HoverCardPrimitive.Content
       ref={ref}
+      data-slot="hover-card-content"
       align={align}
       sideOffset={sideOffset}
       className={cn(

package/src/components/icon-button/icon-button.test.tsx

@@ -59,7 +59,7 @@ describe("IconButton", () => {
     );
     const wrapper = document.querySelector('[data-slot="icon-button"]')!;
     expect(wrapper).toHaveAttribute("tabindex", "0");
-    expect(wrapper.className).toContain("focus-visible:ring-ring");
+    expect(wrapper.className).toContain("focus-ring");
     await userEvent.tab();
     expect(wrapper).toHaveFocus();
   });

package/src/components/icon-button/icon-button.tsx

@@ -97,12 +97,12 @@ export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(functio
             data-slot="icon-button"
             tabIndex={disabled ? 0 : undefined}
             className={cn(
-              "inline-flex rounded-md",
+              "inline-flex rounded-control",
               // While disabled this span IS the focus target (the button is out
               // of the tab order), so it must carry the system's focus ring —
               // without this it falls back to the UA default outline, which is
-              // a hardcoded browser blue identical in all three themes.
-              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+              // a hardcoded browser blue identical in every theme.
+              "focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
               disabled && "cursor-not-allowed",
             )}
           >