@tangle-network/ui 11.8.0 → 11.10.0

package/src/auth/auth.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import type * as React from "react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 import { Avatar, AvatarFallback, AvatarImage } from "../primitives/avatar";
 import { Button, type ButtonProps } from "../primitives/button";
@@ -120,7 +121,10 @@ export function UserMenu({
       <DropdownMenuTrigger asChild>
         <button
           type="button"
-          className="flex items-center gap-2 rounded-lg p-1.5 transition-colors hover:bg-accent focus:outline-none focus:ring-2 focus:ring-ring"
+          className={cn(
+            "flex items-center gap-2 rounded-lg p-1.5 transition-colors hover:bg-accent",
+            focusRing,
+          )}
         >
           <Avatar className="h-8 w-8">
             <AvatarImage src={undefined} alt={user.name ?? user.email} />

package/src/chat/agent-timeline.tsx

@@ -6,6 +6,7 @@ import {
   FileText,
   Info,
 } from "lucide-react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 import { type MessageRole } from "./chat-message";
 import { UserMessage } from "./user-message";
@@ -235,7 +236,11 @@ function ArtifactCard({ item }: { item: AgentTimelineArtifactItem }) {
           item.onClick?.();
         }
       }}
-      className="block w-full text-left transition-transform hover:-translate-y-0.5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/60"
+      // Rounded like the card inside it, so the focus ring follows its corners.
+      className={cn(
+        "block w-full rounded-[var(--radius-lg)] text-left transition-transform hover:-translate-y-0.5",
+        focusRing,
+      )}
     >
       {content}
     </div>

package/src/chat/chat-container.tsx

@@ -5,6 +5,7 @@ import {
   useRef,
 } from "react";
 import { ArrowDown } from "lucide-react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 import type { SessionMessage } from "../types/message";
 import type { SessionPart, TextPart, ToolPart } from "../types/parts";
@@ -459,7 +460,7 @@ export const ChatContainer = memo(
                 "flex items-center gap-1.5 px-3 py-1.5 rounded-full",
                 "border border-border bg-card shadow-[0_6px_16px_rgba(15,23,42,0.08)]",
                 "text-xs text-foreground transition-colors hover:bg-accent",
-                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/60",
+                focusRing,
               )}
             >
               <ArrowDown className="w-3 h-3" />

package/src/editor/document-editor-pane.test.tsx

@@ -32,6 +32,8 @@ async function paneWithoutPeers(message: string) {
   return { DocumentEditorPane, loaders };
 }
 
+// The pane is imported on a fresh module graph, which re-transforms its whole
+// dependency tree: seconds on a busy runner, past the 5s default.
 describe("DocumentEditorPane without the editor peers", () => {
   it("renders the preview, because only the edit tab needs the peers", async () => {
     const { DocumentEditorPane, loaders } = await paneWithoutPeers(
@@ -54,5 +56,5 @@ describe("DocumentEditorPane without the editor peers", () => {
     expect(loaders.loadDocumentEditorPeers).not.toHaveBeenCalled();
     expect(loaders.loadCollaborationPeers).not.toHaveBeenCalled();
     expect(loaders.loadEditorProviderPeers).not.toHaveBeenCalled();
-  });
+  }, 30_000);
 });

package/src/editor/document-editor-pane.tsx

@@ -4,6 +4,7 @@ import { type ReactNode, useEffect, useMemo, useState } from "react";
 import { PencilLine, Save, Users, Wifi, WifiOff } from "lucide-react";
 import { Markdown } from "../markdown/markdown";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "../primitives/tabs";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 import { ArtifactPane, type ArtifactPaneProps } from "../primitives/artifact-pane";
 import {
@@ -276,7 +277,10 @@ export function DocumentEditorPane({
             type="button"
             onClick={() => void onSave(draft)}
             disabled={saving || !isDirty}
-            className="inline-flex items-center gap-2 rounded-[var(--radius-full)] border border-border bg-card px-3 py-1.5 text-xs font-semibold text-foreground transition-colors hover:border-primary/40 hover:text-foreground disabled:cursor-not-allowed disabled:opacity-50"
+            className={cn(
+              "inline-flex items-center gap-2 rounded-[var(--radius-full)] border border-border bg-card px-3 py-1.5 text-xs font-semibold text-foreground transition-colors hover:border-[var(--border-strong)] hover:text-foreground disabled:cursor-not-allowed disabled:opacity-50",
+              focusRing,
+            )}
           >
             <Save className="h-3.5 w-3.5" />
             {saving ? "Saving..." : saveLabel}

package/src/editor/markdown-document-editor.test.tsx

@@ -29,6 +29,11 @@ async function freshEditor(load: () => Promise<EditorPeers.DocumentEditorPeers>)
   return (await import("./markdown-document-editor")).MarkdownDocumentEditor;
 }
 
+// The first render imports tiptap for real. A cold import on a busy runner
+// takes several seconds, well past waitFor's 1s and a test's 5s defaults.
+const PEERS_LOADED = { timeout: 15_000 };
+const LOADS_PEERS = 30_000;
+
 afterEach(() => {
   vi.doUnmock("./editor-peers");
   vi.resetModules();
@@ -42,7 +47,7 @@ describe("MarkdownDocumentEditor", () => {
 
     await waitFor(() => {
       expect(container.querySelector(".ProseMirror")).not.toBeNull();
-    });
+    }, PEERS_LOADED);
 
     const surface = container.querySelector(".ProseMirror");
     expect(surface?.querySelector("h1")?.textContent).toBe("Title");
@@ -50,7 +55,7 @@ describe("MarkdownDocumentEditor", () => {
     // StarterKit arrives through `peers.starterKit.default`. A broken hand-off
     // leaves the document without the heading node that StarterKit configures.
     expect(screen.getByTitle(/^Bold/)).toBeInTheDocument();
-  });
+  }, LOADS_PEERS);
 
   it("holds a placeholder while the peers are still loading", async () => {
     let releasePeers: (() => void) | null = null;
@@ -85,7 +90,7 @@ describe("MarkdownDocumentEditor", () => {
 
     await waitFor(() => {
       expect(container.querySelector(".ProseMirror")).not.toBeNull();
-    });
+    }, PEERS_LOADED);
 
     // The editor reports once when it parses the initial content. What must
     // not grow is the count across a value-prop write: pushing that back
@@ -98,7 +103,7 @@ describe("MarkdownDocumentEditor", () => {
       expect(container.querySelector(".ProseMirror h1")?.textContent).toBe("Changed");
     });
     expect(onChange).toHaveBeenCalledTimes(callsAfterMount);
-  });
+  }, LOADS_PEERS);
 
   it("fails with the install list when the peers cannot be loaded", async () => {
     const missing = "install @tiptap/react and @tiptap/starter-kit";

package/src/files/file-artifact-pane.tsx

@@ -5,6 +5,7 @@ import {
   type DocumentEditorMode,
   type DocumentEditorPaneCollaborationConfig,
 } from "../editor/document-editor-pane";
+import { focusRing } from "../lib/focus";
 import { ArtifactPane, type ArtifactPaneProps } from "../primitives/artifact-pane";
 import { detectFileFormat } from "./file-format";
 import { FilePreview, type FilePreviewProps } from "./file-preview";
@@ -99,7 +100,7 @@ export function FileArtifactPane({
           type="button"
           aria-label={`Download ${filename}`}
           onClick={onDownload}
-          className="rounded-[var(--radius-sm)] p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/60"
+          className={`rounded-[var(--radius-sm)] p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground ${focusRing}`}
         >
           <Download className="h-4 w-4" />
         </button>
@@ -109,7 +110,7 @@ export function FileArtifactPane({
           type="button"
           aria-label={`Close ${filename}`}
           onClick={onClose}
-          className="rounded-[var(--radius-sm)] p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/60"
+          className={`rounded-[var(--radius-sm)] p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground ${focusRing}`}
         >
           <X className="h-4 w-4" />
         </button>

package/src/files/file-preview.tsx

@@ -22,6 +22,7 @@ import {
   X,
   type LucideIcon,
 } from "lucide-react";
+import { focusRingInset } from "../lib/focus";
 import { cn } from "../lib/utils";
 import { Button } from "../primitives/button";
 import { Markdown } from "../markdown/markdown";
@@ -219,7 +220,8 @@ function ImagePreview({ src, filename }: { src: string; filename: string }) {
         aria-pressed={naturalSize}
         aria-label={naturalSize ? "Fit image to pane" : "Show image at natural size"}
         className={cn(
-          "flex items-center justify-center focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary/60",
+          "flex items-center justify-center",
+          focusRingInset,
           naturalSize ? "m-auto cursor-zoom-out" : "h-full w-full cursor-zoom-in p-4",
         )}
       >

package/src/files/file-tabs.tsx

@@ -3,6 +3,7 @@
  */
 
 import { X, FileText, FileCode, FileSpreadsheet } from "lucide-react";
+import { focusRing, focusRingInset } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 export interface FileTabData {
@@ -49,7 +50,10 @@ export function FileTabs({ tabs, activeId, onSelect, onClose, className }: FileT
             <button
               type="button"
               onClick={() => onSelect(tab.id)}
-              className="flex min-w-0 items-center gap-1.5 px-3 py-1.5 text-xs transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary/60"
+              className={cn(
+                "flex min-w-0 items-center gap-1.5 px-3 py-1.5 text-xs transition-colors hover:text-foreground",
+                focusRingInset,
+              )}
             >
               <Icon className="h-3 w-3 shrink-0" />
               <span className="max-w-[120px] truncate">{tab.name}</span>
@@ -59,7 +63,10 @@ export function FileTabs({ tabs, activeId, onSelect, onClose, className }: FileT
               type="button"
               aria-label={`Close ${tab.name}`}
               onClick={() => onClose(tab.id)}
-              className="mr-1 rounded p-0.5 opacity-0 transition-opacity hover:bg-accent focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/60 group-hover:opacity-100"
+              className={cn(
+                "mr-1 rounded p-0.5 opacity-0 transition-opacity hover:bg-accent focus-visible:opacity-100 group-hover:opacity-100",
+                focusRing,
+              )}
             >
               <X className="h-2.5 w-2.5" />
             </button>

package/src/lib/focus.ts

@@ -0,0 +1,63 @@
+/**
+ * The focus treatment every control shares, in two shapes over one palette
+ * (`--focus-border`, `--focus-halo` and `--border-strong` from
+ * `@tangle-network/brand`'s tokens.css).
+ *
+ * A FIELD — input, textarea, select trigger, composer — shows focus on its own
+ * border: the hairline shifts to `--focus-border` and a 3px `--focus-halo` ring
+ * spreads outside it. It keys off `:focus`, because a caret in a field needs the
+ * cue whether the field was clicked or tabbed into.
+ *
+ * A CONTROL — button, tab, switch, link, card — has no border to shift, so it
+ * draws a 1px `--focus-border` outline with the same 3px halo beyond it. It keys
+ * off `:focus-visible`, so a mouse click leaves no ring.
+ *
+ * The halo is a Tailwind ring, which renders as box-shadow: it follows
+ * border-radius and never moves layout, and a consumer removes it with
+ * `focus:ring-0` / `focus-visible:ring-0`, which tailwind-merge resolves against
+ * these classes. The control's line is an outline so that forced-colors mode,
+ * which drops box-shadows, still paints it. A field has its border for that, so
+ * it hides the outline with `outline-hidden`, which stays transparent-but-present
+ * in forced-colors mode.
+ */
+
+/**
+ * Resting hairline, neutral hover, and `:focus` border plus halo for a text
+ * field. The hover is a plain `hover:` class so a consumer's `hover:border-*`
+ * replaces it through tailwind-merge; the focus border outranks it because
+ * Tailwind emits `focus:` after `hover:`.
+ */
+export const focusField =
+  "border-border transition-[border-color,box-shadow] duration-150 ease-out hover:border-[var(--border-strong)] focus:outline-hidden focus:border-[var(--focus-border)] focus:ring-3 focus:ring-[var(--focus-halo)]";
+
+/**
+ * The field treatment for a container that wraps a borderless field, such as a
+ * composer around a textarea and its buttons. It lights while a FIELD inside
+ * has focus: a text input, textarea, native select or contenteditable editor. A
+ * focused button, checkbox or button-type input inside the container shows only
+ * its own ring, so a click on the send button does not read as field focus and
+ * a tab to it does not stack two indicators. `:focus-within` cannot tell the
+ * two apart, so the rule keys off `:has()`; a consumer's `focus-within:*` class
+ * therefore does not replace it. To style that container's focus differently,
+ * compose your own classes instead of this helper. The field selector is
+ * written out in full because Tailwind reads class names statically.
+ */
+export const focusFieldWithin =
+  "border-border transition-[border-color,box-shadow] duration-150 ease-out hover:border-[var(--border-strong)] has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:border-[var(--focus-border)] has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:ring-3 has-[:is(textarea,select,[contenteditable]:not([contenteditable=false]),input:not([type=button],[type=submit],[type=reset],[type=image],[type=checkbox],[type=radio],[type=range],[type=color],[type=file])):focus]:ring-[var(--focus-halo)]";
+
+/** Error state for a field: a danger hairline and the same focus shape in danger. Compose after `focusField`. */
+export const focusFieldInvalid =
+  "border-[var(--surface-danger-border)] hover:border-[var(--surface-danger-border)] focus:border-[var(--focus-border-danger)] focus:ring-[var(--focus-halo-danger)]";
+
+const focusRingBase =
+  "focus-visible:outline-1 focus-visible:outline-[var(--focus-border)] focus-visible:ring-4 focus-visible:ring-[var(--focus-halo)]";
+
+/** Keyboard-only focus for a control: a 1px focus line with the halo beyond it. */
+export const focusRing = `${focusRingBase} focus-visible:outline-offset-0`;
+
+/**
+ * `focusRing` drawn inside the box, for a control flush against a scroll
+ * container or its neighbours (a tab strip, a list row), where an outer ring
+ * would be clipped or would overlap them.
+ */
+export const focusRingInset = `${focusRingBase} focus-visible:-outline-offset-1 focus-visible:ring-inset`;

package/src/markdown/code-block.tsx

@@ -9,6 +9,7 @@ import {
 } from "react";
 import SyntaxHighlighter from "react-syntax-highlighter";
 import { Check, Copy } from "lucide-react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 // Theme-aware syntax highlighting — reads CSS custom properties at render time.
@@ -191,7 +192,10 @@ export const CopyButton = memo(({ text }: { text: string }) => {
   return (
     <button
       onClick={handleCopy}
-      className="flex items-center justify-center w-6 h-6 rounded-md bg-muted border border-border hover:border-primary/20 transition-colors"
+      className={cn(
+        "flex items-center justify-center w-6 h-6 rounded-md bg-muted border border-border hover:border-[var(--border-strong)] transition-colors",
+        focusRing,
+      )}
       title="Copy to clipboard"
     >
       {copied ? (

package/src/markdown/markdown.test.tsx

@@ -1,5 +1,5 @@
-import { describe, expect, it } from "vitest";
-import { render } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
 import { Markdown } from "./markdown";
 
 describe("Markdown", () => {
@@ -20,4 +20,28 @@ describe("Markdown", () => {
     expect(inlineCode).toHaveClass("bg-card");
     expect(inlineCode).toHaveClass("text-[var(--code-keyword)]");
   });
+
+  it("passes parsed URLs through the typed transform hook", () => {
+    const urlTransform = vi.fn((url: string, key: string) => (
+      key === "href" && url === "system/brief.md"
+        ? "/app/ws-1/vault?file=system%2Fbrief.md"
+        : url
+    ));
+
+    render(
+      <Markdown urlTransform={urlTransform}>
+        {'[Brief](system/brief.md)'}
+      </Markdown>,
+    );
+
+    expect(screen.getByRole("link", { name: "Brief" })).toHaveAttribute(
+      "href",
+      "/app/ws-1/vault?file=system%2Fbrief.md",
+    );
+    expect(urlTransform).toHaveBeenCalledWith(
+      "system/brief.md",
+      "href",
+      expect.objectContaining({ tagName: "a" }),
+    );
+  });
 });

package/src/markdown/markdown.tsx

@@ -1,5 +1,5 @@
 import { memo } from "react";
-import ReactMarkdown from "react-markdown";
+import ReactMarkdown, { type UrlTransform } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import rehypeSanitize from "rehype-sanitize";
 import { CodeBlock, CopyButton } from "./code-block";
@@ -8,13 +8,15 @@ import { cn } from "../lib/utils";
 export interface MarkdownProps {
   children: string;
   className?: string;
+  /** Transform parsed link and image URLs before sanitisation. */
+  urlTransform?: UrlTransform;
 }
 
 /**
  * Renders Markdown content with GFM support, XSS sanitisation, and
  * custom code block rendering via our CodeBlock component.
  */
-export const Markdown = memo(({ children, className }: MarkdownProps) => {
+export const Markdown = memo(({ children, className, urlTransform }: MarkdownProps) => {
   return (
     <div
       className={cn("tangle-prose max-w-none text-sm", className)}
@@ -22,6 +24,7 @@ export const Markdown = memo(({ children, className }: MarkdownProps) => {
       <ReactMarkdown
         remarkPlugins={[remarkGfm]}
         rehypePlugins={[rehypeSanitize]}
+        urlTransform={urlTransform}
         components={{
           pre({ children: preChildren }) {
             return <>{preChildren}</>;

package/src/primitives/badge.tsx

@@ -1,9 +1,10 @@
 import { cva, type VariantProps } from "class-variance-authority";
 import type * as React from "react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 const badgeVariants = cva(
-  "inline-flex items-center gap-1.5 rounded-full border px-2.5 py-0.5 font-medium text-xs transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+  `inline-flex items-center gap-1.5 rounded-full border px-2.5 py-0.5 font-medium text-xs transition-colors ${focusRing}`,
   {
     variants: {
       variant: {

package/src/primitives/button.tsx

@@ -1,10 +1,11 @@
 import { Slot } from "@radix-ui/react-slot";
 import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 const buttonVariants = cva(
-  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg font-medium text-sm transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  `inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg font-medium text-sm transition-all ${focusRing} disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0`,
   {
     variants: {
       variant: {

package/src/primitives/card.tsx

@@ -22,8 +22,7 @@ const Card = React.forwardRef<
         "rounded-[var(--radius-lg)] border text-card-foreground transition-[border-color,box-shadow]",
         "duration-[var(--transition-default)]",
         variants[variant],
-        hover &&
-          "cursor-pointer hover:border-primary/30",
+        hover && "cursor-pointer hover:border-[var(--border-strong)]",
         className,
       )}
       {...props}

package/src/primitives/dialog.tsx

@@ -1,6 +1,7 @@
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { X } from "lucide-react";
 import * as React from "react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 const Dialog = DialogPrimitive.Root;
@@ -58,7 +59,12 @@ const DialogContent = React.forwardRef<
         {...props}
       >
         {children}
-        <DialogPrimitive.Close className="absolute top-4 right-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
+        <DialogPrimitive.Close
+          className={cn(
+            "absolute top-4 right-4 rounded-sm opacity-70 transition-[opacity,box-shadow] hover:opacity-100 focus-visible:opacity-100 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground",
+            focusRing,
+          )}
+        >
           <X className="h-4 w-4" />
           <span className="sr-only">Close</span>
         </DialogPrimitive.Close>

package/src/primitives/input.tsx

@@ -1,16 +1,21 @@
 import * as React from "react";
+import { focusField, focusFieldInvalid } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 import { cva, type VariantProps } from "class-variance-authority";
 
 const inputVariants = cva(
-  "flex w-full rounded-lg border bg-card px-4 py-2 text-sm transition-all duration-200 placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-offset-0 disabled:cursor-not-allowed disabled:opacity-50 file:border-0 file:bg-transparent file:font-medium file:text-sm",
+  cn(
+    "flex w-full rounded-lg border bg-card px-4 py-2 text-sm placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50 file:border-0 file:bg-transparent file:font-medium file:text-sm",
+    focusField,
+  ),
   {
     variants: {
+      // `default` and `sandbox` render the same field; both names stay valid.
       variant: {
-        default: "border-input focus:ring-ring",
-        sandbox: "border-border focus:border-[var(--border-accent-hover)] focus:ring-[var(--border-accent)]",
-        error: "border-[var(--surface-danger-border)] focus:ring-[var(--surface-danger-border)]",
+        default: "",
+        sandbox: "",
+        error: focusFieldInvalid,
       },
       size: {
         default: "h-11",
@@ -75,6 +80,7 @@ Input.displayName = "Input";
 
 export interface TextareaProps
   extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+  /** Both values render the same field. */
   variant?: "default" | "sandbox";
   label?: string;
   error?: string;
@@ -83,26 +89,21 @@ export interface TextareaProps
 
 const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
   (
-    { className, variant = "default", label, error, hint, id, ...props },
+    // `variant` is taken out so it never reaches the DOM element.
+    { className, variant: _variant, label, error, hint, id, ...props },
     ref,
   ) => {
     const textareaId = id ?? label?.toLowerCase().replace(/\s+/g, "-");
 
-    const variants = {
-      default: "border-input focus:ring-ring",
-      sandbox:
-        "border-border focus:border-[var(--border-accent-hover)] focus:ring-[var(--border-accent)]",
-    };
-
     const textarea = (
       <textarea
         id={textareaId}
         className={cn(
-          "flex min-h-[120px] w-full resize-y rounded-lg border bg-card px-4 py-3 text-sm transition-all duration-200",
+          "flex min-h-[120px] w-full resize-y rounded-lg border bg-card px-4 py-3 text-sm",
           "placeholder:text-muted-foreground",
-          "focus:outline-none focus:ring-2 focus:ring-offset-0",
           "disabled:cursor-not-allowed disabled:opacity-50",
-          error ? "border-[var(--surface-danger-border)] focus:ring-[var(--surface-danger-border)]" : variants[variant],
+          focusField,
+          error && focusFieldInvalid,
           className,
         )}
         ref={ref}

package/src/primitives/segmented-control.tsx

@@ -3,6 +3,7 @@
 declare const process: { env: { NODE_ENV?: string } } | undefined
 
 import * as React from "react"
+import { focusRing, focusRingInset } from "../lib/focus"
 import { cn } from "../lib/utils"
 
 /**
@@ -120,9 +121,10 @@ export function SegmentedControl<T extends string = string>({
               if (!active) onValueChange(option.value)
             }}
             className={cn(
-              "relative inline-flex items-center gap-2 whitespace-nowrap text-sm transition-colors",
-              variant === "row" && "rounded-md px-3 py-1.5",
-              variant === "tabs" && "rounded-none border-b-2 -mb-px px-4 py-2",
+              "relative inline-flex items-center gap-2 whitespace-nowrap text-sm transition-[color,background-color,border-color,box-shadow]",
+              variant === "row" && ["rounded-md px-3 py-1.5", focusRing],
+              // The strip scrolls horizontally, which would clip an outer ring.
+              variant === "tabs" && ["rounded-none border-b-2 -mb-px px-4 py-2", focusRingInset],
               // Active styling is the ONLY styled state — unselected
               // segments stay transparent on purpose so they don't
               // compete visually with the selection.

package/src/primitives/select.tsx

@@ -3,6 +3,7 @@
 import * as SelectPrimitive from "@radix-ui/react-select";
 import { Check, ChevronDown, ChevronUp } from "lucide-react";
 import * as React from "react";
+import { focusField } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 const Select = SelectPrimitive.Root;
@@ -18,7 +19,8 @@ const SelectTrigger = React.forwardRef<
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      "flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border border-border bg-card px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-primary disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1",
+      "flex h-9 w-full items-center justify-between whitespace-nowrap rounded-md border bg-card px-3 py-2 text-sm shadow-sm placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1",
+      focusField,
       className,
     )}
     {...props}

package/src/primitives/switch.tsx

@@ -2,6 +2,7 @@
 
 import * as SwitchPrimitives from "@radix-ui/react-switch";
 import * as React from "react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 const Switch = React.forwardRef<
@@ -10,7 +11,8 @@ const Switch = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <SwitchPrimitives.Root
     className={cn(
-      "peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
+      "peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-[background-color,box-shadow] disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
+      focusRing,
       className,
     )}
     {...props}

package/src/primitives/tabs.tsx

@@ -1,5 +1,6 @@
 import * as TabsPrimitive from "@radix-ui/react-tabs";
 import * as React from "react";
+import { focusRing } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 const Tabs = TabsPrimitive.Root;
@@ -35,11 +36,11 @@ const TabsTrigger = React.forwardRef<
 >(({ className, variant = "default", ...props }, ref) => {
   const variants = {
     default:
-      "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm",
+      `inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium transition-all ${focusRing} disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm`,
     pills:
-      "inline-flex items-center justify-center whitespace-nowrap rounded-full px-4 py-2 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-primary data-[state=active]:text-primary-foreground data-[state=inactive]:text-muted-foreground data-[state=inactive]:hover:bg-muted",
+      `inline-flex items-center justify-center whitespace-nowrap rounded-full px-4 py-2 text-sm font-medium transition-all ${focusRing} disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-primary data-[state=active]:text-primary-foreground data-[state=inactive]:text-muted-foreground data-[state=inactive]:hover:bg-muted`,
     underline:
-      "inline-flex items-center justify-center whitespace-nowrap pb-3 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 border-b-2 border-transparent data-[state=active]:border-primary data-[state=active]:text-foreground data-[state=inactive]:text-muted-foreground",
+      `inline-flex items-center justify-center whitespace-nowrap rounded-t-md pb-3 text-sm font-medium transition-all ${focusRing} disabled:pointer-events-none disabled:opacity-50 border-b-2 border-transparent data-[state=active]:border-primary data-[state=active]:text-foreground data-[state=inactive]:text-muted-foreground`,
   };
 
   return (
@@ -59,7 +60,8 @@ const TabsContent = React.forwardRef<
   <TabsPrimitive.Content
     ref={ref}
     className={cn(
-      "mt-4 ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+      "mt-4",
+      focusRing,
       "data-[state=active]:fade-in-0 data-[state=active]:slide-in-from-bottom-2 data-[state=active]:animate-in",
       className,
     )}

package/src/primitives/terminal-display.tsx

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { useEffect, useRef } from "react";
+import { focusFieldWithin } from "../lib/focus";
 import { cn } from "../lib/utils";
 
 export interface TerminalDisplayProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -142,11 +143,13 @@ TerminalCursor.displayName = "TerminalCursor";
 export interface TerminalInputProps
   extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onSubmit"> {
   onSubmit?: (value: string) => void;
+  /** Both values render the same field. */
   variant?: "default" | "sandbox";
 }
 
 const TerminalInput = React.forwardRef<HTMLInputElement, TerminalInputProps>(
-  ({ className, onSubmit, variant = "default", ...props }, ref) => {
+  // `variant` is taken out so it never reaches the DOM element.
+  ({ className, onSubmit, variant: _variant, ...props }, ref) => {
     const [value, setValue] = React.useState("");
 
     const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
@@ -156,16 +159,11 @@ const TerminalInput = React.forwardRef<HTMLInputElement, TerminalInputProps>(
       }
     };
 
-    const variants = {
-      default: "border-border focus-within:border-border",
-      sandbox: "border-border focus-within:border-[var(--border-accent-hover)]",
-    };
-
     return (
       <div
         className={cn(
-          "flex items-center rounded-lg border bg-background px-4 py-2.5 font-mono text-sm transition-colors",
-          variants[variant],
+          "flex items-center rounded-lg border bg-background px-4 py-2.5 font-mono text-sm",
+          focusFieldWithin,
           className,
         )}
       >