@godxjp/ui 19.4.2 → 19.6.0

package/dist/components/general/typography.js

@@ -3,16 +3,21 @@ import { cn } from "../../lib/utils.js";
 const Text = React.forwardRef(
   ({
     as = "span",
+    asChild = false,
     size = "sm",
-    tone = "default",
+    // `link` is an affordance, not a colour: it only moves the DEFAULT tone, so
+    // `link tone="destructive"` is a destructive link rather than an argument between two rules.
+    tone,
     weight = "regular",
     align,
     truncate,
     clamp,
     tabular,
     mono,
+    link,
     className,
     style,
+    children,
     ...props
   }, ref) => {
     const clampLines = typeof clamp === "number" && Number.isFinite(clamp) && clamp >= 1 ? Math.floor(clamp) : void 0;
@@ -28,11 +33,11 @@ const Text = React.forwardRef(
         );
       }
     }
-    return React.createElement(as, {
-      ref,
+    const typography = {
       "data-slot": "text",
       "data-size": size,
-      "data-tone": tone,
+      "data-tone": tone ?? (link ? "primary" : "default"),
+      "data-link": link ? "" : void 0,
       "data-weight": weight,
       "data-align": align,
       "data-truncate": truncate && clampLines === void 0 ? "" : void 0,
@@ -42,7 +47,17 @@ const Text = React.forwardRef(
       "data-mono": mono ? "" : void 0,
       className: cn("ui-text", className),
       ...props
-    });
+    };
+    if (asChild) {
+      const child = React.Children.only(children);
+      return React.cloneElement(child, {
+        ...typography,
+        ...child.props,
+        ref,
+        className: cn(typography.className, child.props.className)
+      });
+    }
+    return React.createElement(as, { ref, ...typography }, children);
   }
 );
 Text.displayName = "Text";

package/dist/components/layout/index.d.ts

@@ -3,6 +3,8 @@ export type { PageContainerProp, PageContainerProps, BreadcrumbItem, BreadcrumbI
 export { Flex } from "./flex.js";
 export type { FlexAlignProp, FlexDirectionProp, FlexJustifyProp, FlexProp, FlexProps, } from "./flex.js";
 export { ResizablePanel, ResizablePanelGroup, ResizableHandle } from "./resizable.js";
+export { NavList } from "./nav-list.js";
+export type { NavListProp, NavListProps } from "./nav-list.js";
 export { AppShell } from "./app-shell.js";
 export type { AppShellProps } from "./app-shell.js";
 export { OrgSwitcher } from "./org-switcher.js";
@@ -37,6 +39,8 @@ export { createSidebarLink, Sidebar, SidebarHeader, SidebarItem, SidebarSection
 export type { SidebarItemData, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, SidebarSectionProp, } from "../../props/components/layout.prop.js";
 export { Topbar } from "./topbar.js";
 export type { TopbarProp, TopbarProps } from "./topbar.js";
+export { TopbarItem } from "./topbar-item.js";
+export type { TopbarItemProp, TopbarItemProps } from "./topbar-item.js";
 export { ResponsiveGrid } from "./responsive-grid.js";
 export type { ResponsiveGridProps } from "./responsive-grid.js";
 export { MasterDetail } from "./master-detail.js";

package/dist/components/layout/index.js

@@ -1,6 +1,7 @@
 import { PageContainer } from "./page-container.js";
 import { Flex } from "./flex.js";
 import { ResizablePanel, ResizablePanelGroup, ResizableHandle } from "./resizable.js";
+import { NavList } from "./nav-list.js";
 import { AppShell } from "./app-shell.js";
 import { OrgSwitcher } from "./org-switcher.js";
 import { AuthShell } from "./auth-shell.js";
@@ -16,6 +17,7 @@ import { ErrorSurface } from "./error-surface.js";
 import { Breadcrumb } from "./breadcrumb.js";
 import { createSidebarLink, Sidebar, SidebarHeader, SidebarItem, SidebarSection } from "./sidebar.js";
 import { Topbar } from "./topbar.js";
+import { TopbarItem } from "./topbar-item.js";
 import { ResponsiveGrid } from "./responsive-grid.js";
 import { MasterDetail } from "./master-detail.js";
 import { SplitPane } from "./split-pane.js";
@@ -40,6 +42,7 @@ export {
   LegalDocumentShell,
   MasterDetail,
   MobileShell,
+  NavList,
   OrgSwitcher,
   PageContainer,
   ResizableHandle,
@@ -54,5 +57,6 @@ export {
   SidebarSection,
   SplitPane,
   Topbar,
+  TopbarItem,
   createSidebarLink
 };

package/dist/components/layout/nav-list.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+import type { NavListProp } from "../../props/components/layout.prop.js";
+export type { NavListProp };
+export type NavListProps = NavListProp;
+/**
+ * NavList — a vertical route navigation that is NOT shell furniture (gh#374).
+ *
+ * `Sidebar` owns the app's primary rail and renders into `AppShell`'s grid, so it cannot be nested
+ * in a page. The settings-nav shape — a column of links beside the pane they drive, one of them
+ * current — had no primitive, which left every consumer hand-rolling rows out of `Button`s with the
+ * current one encoded as a variant swap: no `aria-current`, no icon column, a different invention
+ * per app.
+ *
+ * This is the SAME row as the rail, deliberately: it composes `SidebarItem`, so icon slot, label,
+ * badge, active tokens and `aria-current="page"` are one implementation shared by both, and a
+ * consumer that already learnt `SidebarItemProp` / `linkComponent` for the rail knows this too.
+ * Only the container differs — a `<nav>` landmark instead of the shell's grid area, and no
+ * collapsed rail (a page-level nav has no rail to collapse into).
+ */
+export declare const NavList: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLElement>, "onSelect"> & {
+    items: import("../../props/index.js").SidebarItemProp[];
+    activeId?: string;
+    label: string;
+    linkComponent?: import("./sidebar.js").SidebarLinkComponentProp;
+    onSelect?: (id: string) => void;
+} & React.RefAttributes<HTMLElement>>;

package/dist/components/layout/nav-list.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+import { SidebarItem } from "./sidebar.js";
+const NavList = React.forwardRef(
+  ({ items, activeId, label, linkComponent, onSelect, className, ...props }, ref) => /* @__PURE__ */ jsx("nav", { ref, "aria-label": label, className: cn("ui-nav-list", className), ...props, children: items.map((item) => /* @__PURE__ */ jsx(
+    SidebarItem,
+    {
+      item,
+      active: item.id === activeId,
+      linkComponent,
+      onActivate: onSelect
+    },
+    item.id
+  )) })
+);
+NavList.displayName = "NavList";
+export {
+  NavList
+};

package/dist/components/layout/topbar-item.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+export type { TopbarItemProp, TopbarItemProp as TopbarItemProps, } from "../../props/components/layout.prop.js";
+/**
+ * TopbarItem — one interactive cell of a {@link Topbar} slot, shaped like part of the bar.
+ *
+ * Full bar height, the bar's own hover surface, and the focus mark hosted INSIDE the cell (a
+ * full-bleed cell has nothing outside itself to ring, and the bar clips its own overflow). All of
+ * that lives in `.ui-topbar-item`; this component only picks the element and the classes.
+ *
+ * `ui-focus-ring` is the ONE focus source (styles/focus-ring.css) — the cell hosts whatever that
+ * file resolves, including nothing at all while the `--focus-outline` switch ships off.
+ */
+export declare const TopbarItem: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    asChild?: boolean;
+    children?: React.ReactNode;
+    className?: import("../../props/index.js").ClassNameProp;
+} & React.RefAttributes<HTMLButtonElement>>;

package/dist/components/layout/topbar-item.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "../../lib/utils.js";
+const TopbarItem = React.forwardRef(function TopbarItem2({ asChild = false, className, type, ...props }, ref) {
+  const Comp = asChild ? Slot : "button";
+  return /* @__PURE__ */ jsx(
+    Comp,
+    {
+      ref,
+      "data-slot": "topbar-item",
+      className: cn("ui-topbar-item ui-focus-ring", className),
+      type: asChild ? void 0 : type ?? "button",
+      ...props
+    }
+  );
+});
+export {
+  TopbarItem
+};

package/dist/components/navigation/app-setting-picker.js

@@ -135,19 +135,36 @@ const AppSettingPicker = React.forwardRef(
                   // sits among ghost icon buttons (the topbar's sidebar-toggle/notifications/account
                   // triggers), so it drops controlTriggerClass's form-input chrome (border/bg/shadow)
                   // at rest and adopts the same ghost hover — a resting border here read as visually
-                  // inconsistent next to its borderless topbar siblings. The open-state ring
-                  // (`data-[state=open]:border-ring`, from controlTriggerClass) and the
-                  // focus-visible ring are untouched, so keyboard and "is this open" affordance
-                  // still hold.
+                  // inconsistent next to its borderless topbar siblings. The open-state and
+                  // focus-visible rings are untouched, so keyboard and "is this open" affordance
+                  // still hold: both come from styles/focus-ring.css, which also excludes this
+                  // variant from the bordered-field rebind precisely BECAUSE it has no resting
+                  // border to recolour, so it keeps the opaque ring form.
                   // Bề ngang phải là UTILITY, không phải luật class. SelectTrigger phát `w-full`,
                   // mà utility nằm sau components trong thứ tự layer nên `inline-size` khai trong
                   // .ui-app-setting-picker-icon luôn thua. Trong một khe co theo nội dung của
                   // topbar, `width: 100%` co lại bằng chính nội dung, tức 18px thay vì ô vuông
                   // --control-height. Nhánh có nhãn ngay dưới đã phải tự vệ đúng như vậy bằng
                   // `w-auto`. Giá trị vẫn đọc token chứ không phải một con số.
+                  // `justify-content` đi cùng lý do đó: SelectTrigger phát `justify-between`,
+                  // với một con duy nhất thì nó dồn glyph sát viền trái (khe 1px/15px trong ô
+                  // 32px). `justify-content: center` khai trong .ui-app-setting-picker-icon
+                  // cũng nằm ở @layer components nên cũng thua. Cả hai trục của cái hộp này
+                  // phải do lớp utility sở hữu, không được để sót nửa nào lại trong luật class.
+                  // `shrink-0` là NỬA CÒN LẠI của trục ngang, không phải trang trí. `w-*` chỉ khai
+                  // kích thước MONG MUỐN; trong một flex row chật, `flex-shrink: 1` mặc định vẫn
+                  // ép nó nhỏ hơn. Đo thật trong Chromium ở chính frame tài liệu của component:
+                  // `.ui-topbar-end` rộng 82px, gap 8px, hai trigger cùng co → ô vuông ra
+                  // 21,28 × 32px thay vì 32 × 32. Đây không phải gh#366 quay lại: `inline-size`
+                  // vẫn giải đúng --control-height; cái hỏng là co giãn. Một tap target vuông
+                  // biến thành hình chữ nhật 21px mỗi khi topbar chật là lỗi thật, và nó kéo
+                  // theo cả vùng chạm. Nhánh CÓ NHÃN cố tình KHÔNG nhận `shrink-0`: nó rộng theo
+                  // nội dung và mang sẵn `max-w-full` để được phép thu lại.
+                  // Vẫn phải là utility vì cùng lý do với `w-*`: luật trong @layer components
+                  // thua lớp utilities mà SelectTrigger phát ra.
                   cn(
                     "ui-app-setting-picker-icon hover:bg-accent hover:text-accent-foreground",
-                    "w-[length:var(--control-height)]"
+                    "w-[length:var(--control-height)] shrink-0 justify-center"
                   )
                 ) : (
                   // Labeled: sized to a per-kind width from `sm` up; below `sm` it hugs its content and

package/dist/components/navigation/context-menu.js

@@ -11,11 +11,11 @@ function ContextMenuTrigger(props) {
 }
 const ContextMenuPortal = ContextMenuPrimitive.Portal;
 const ContextMenuContent = React.forwardRef(({ className, ...props }, ref) => {
-  useInertHiddenBackground();
+  const contentRef = useInertHiddenBackground(ref);
   return /* @__PURE__ */ jsx(ContextMenuPrimitive.Portal, { children: /* @__PURE__ */ jsx(
     ContextMenuPrimitive.Content,
     {
-      ref,
+      ref: contentRef,
       "data-slot": "context-menu-content",
       className: cn("ui-context-menu-content", className),
       ...props

package/dist/components/navigation/dropdown-menu.js

@@ -24,11 +24,11 @@ function DropdownMenuSub(props) {
   return /* @__PURE__ */ jsx(DropdownMenuPrimitive.Sub, { "data-slot": "dropdown-menu-sub", ...props });
 }
 const DropdownMenuContent = React.forwardRef(({ className, sideOffset = 4, ...props }, ref) => {
-  useInertHiddenBackground();
+  const contentRef = useInertHiddenBackground(ref);
   return /* @__PURE__ */ jsx(DropdownMenuPortal, { children: /* @__PURE__ */ jsx(
     DropdownMenuPrimitive.Content,
     {
-      ref,
+      ref: contentRef,
       "data-slot": "dropdown-menu-content",
       sideOffset,
       className: cn(

package/dist/components/navigation/tabs.js

@@ -47,9 +47,28 @@ function Tabs({
             "data-slot": "tabs-list",
             variant: variant === "line" ? "line" : "default",
             className: cn(
-              // The padding override is an arbitrary value reading the knob (never `p-0`): it must
-              // stay a UTILITY so tailwind-merge still drops the strip's own padding step, and a
-              variant === "line" && "h-auto w-full justify-start border-b p-[var(--tabs-list-line-space-inset)]",
+              // The inset override is an arbitrary value reading the knob (never `p-0`): it must
+              // stay a UTILITY so tailwind-merge still drops the strip's own padding step.
+              //
+              // IT IS SPLIT INTO `px-`/`py-` FOR THE FOCUS RING (gh#376). The strip clips its
+              // block axis (`overflow-y: hidden` beside `overflow-x: auto`), and this variant's
+              // inset is 0px, so a focused trigger had NO block headroom at all — measured in
+              // Chromium, 0px top and bottom, i.e. the entire ring was shaved. The headroom has to
+              // come from layout: `overflow-y: visible` next to `overflow-x: auto` computes back
+              // to `auto` per spec (a second scroll container, not a ring), and Chromium honours
+              // `overflow-clip-margin` only when BOTH axes are `clip`. So the block padding carries
+              // the ring's outer reach and an equal negative block margin hands it straight back —
+              // the ring paints inside the scrollport and the strip's OUTER box is unchanged
+              // (measured: 38px before and after). Both values read the same token the ring is
+              // sized from, so the two can never drift apart.
+              //
+              // The cost, recorded rather than hidden: the rail hairline (`border-b`, drawn at the
+              // border box) now sits the ring's reach below the triggers instead of flush. That is
+              // where a hand-composed <TabsList variant="line"> already put it — its `p-1` gives
+              // the same block inset — so the two construction paths now agree. A service that
+              // wants the active bar parked back on the hairline raises `--tabs-indicator-offset`,
+              // which exists for exactly that.
+              variant === "line" && "my-[calc(-1_*_var(--tabs-list-focus-ring-space-inset,calc(var(--focus-ring-width)_+_var(--focus-ring-glow-width))))] h-auto w-full justify-start border-b px-[var(--tabs-list-line-space-inset)] py-[calc(var(--tabs-list-line-space-inset)_+_var(--tabs-list-focus-ring-space-inset,calc(var(--focus-ring-width)_+_var(--focus-ring-glow-width))))]",
               variant === "card" && "w-full justify-start",
               listClassName
             ),
@@ -134,12 +153,25 @@ const TabsTrigger = React.forwardRef(({ className, ...props }, ref) => /* @__PUR
     ref,
     "data-slot": "tabs-trigger",
     className: cn(
-      // The SELECTED-state ring (`ring-1 ring-primary/25`) is scoped to the default/card lists —
-      // it competes with (and at equal specificity overrides) the `:focus-visible` ring. The
-      // focus-visible ring/outline below is deliberately left unscoped: every variant keeps a
-      // visible keyboard focus indicator (WCAG 2.4.7). The line indicator itself lives in
-      // src/styles/navigation-layout.css so it reads the --tabs-indicator-* tokens.
-      "text-muted-foreground ring-offset-background hover:text-foreground ui-focus-ring data-[state=active]:bg-background data-[state=active]:text-foreground group-data-[variant=default]/tabs-list:data-[state=active]:ring-primary/25 relative inline-flex flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-3 py-1 text-sm font-medium whitespace-nowrap transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start group-data-[variant=line]/tabs-list:border-e-0 group-data-[variant=line]/tabs-list:border-b-0 focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=default]/tabs-list:data-[state=active]:ring-1 group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none",
+      // SELECTED IS A BORDER TINT, NOT A RING — and that is a WCAG fix, not a style preference.
+      // It used to be `ring-1 ring-primary/25`, which writes `--tw-ring-shadow` in the UTILITIES
+      // layer and therefore overwrote the focus ring that focus-ring.css feeds from `components`.
+      // Measured: a focused ACTIVE tab painted `oklab(… / 0.25) 0 0 0 1px` and nothing else — a
+      // 1px indicator at 25% alpha, failing both clauses of SC 2.4.13 (2px perimeter, ≥3:1),
+      // while every other control in the library carried a full 2px ring. The trigger already
+      // owns `border border-transparent`, so tinting that border reproduces the selected hairline
+      // at the same colour and width with no layout change, and leaves `--tw-ring-shadow` free for
+      // the focus ring. `shadow-sm` stays: its composite READS `--tw-ring-shadow`, so the lift and
+      // the ring coexist.
+      //
+      // No `focus-visible:outline-1` either. It was the fallback that survived the clobber — a 1px
+      // currentColor line squeezed between the border and the ring once both paint. The ring is
+      // the indicator now; two marks for one state is what this pass exists to remove.
+      //
+      // The line indicator lives in src/styles/navigation-layout.css so it reads --tabs-indicator-*.
+      // Selected and focused stay visually distinct (WCAG 2.4.7): selected is a 1px hairline in the
+      // border, focused is the 2px ring plus its halo outside it.
+      "text-muted-foreground ring-offset-background hover:text-foreground ui-focus-ring data-[state=active]:bg-background data-[state=active]:text-foreground group-data-[variant=default]/tabs-list:data-[state=active]:border-primary/25 relative inline-flex flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-3 py-1 text-sm font-medium whitespace-nowrap transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start group-data-[variant=line]/tabs-list:border-e-0 group-data-[variant=line]/tabs-list:border-b-0 disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none",
       className
     ),
     ...props
@@ -151,7 +183,7 @@ const TabsContent = React.forwardRef(({ className, ...props }, ref) => /* @__PUR
   {
     ref,
     "data-slot": "tabs-content",
-    className: cn("focus-visible:ring-ring flex-1 outline-none focus-visible:ring-2", className),
+    className: cn("ui-focus-ring flex-1 outline-none", className),
     ...props
   }
 ));

package/dist/components/ui/segmented.d.ts

@@ -0,0 +1,48 @@
+import * as React from "react";
+/** One choice in a {@link Segmented}. */
+export type SegmentedOption = {
+    /** Wire value — what `onValueChange` reports and what a form submits. */
+    value: string;
+    /** Visible label. It is also the item's accessible name, so it is required. */
+    label: React.ReactNode;
+    /** Optional leading glyph, rendered `aria-hidden` beside the label. */
+    icon?: React.ReactNode;
+    /** Disable this one choice; the rest of the group stays operable. */
+    disabled?: boolean;
+};
+export type SegmentedProp = {
+    /** The closed set of choices, in reading order. */
+    options: readonly SegmentedOption[];
+    /** Controlled selection. */
+    value?: string;
+    /** Uncontrolled initial selection. */
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    /** Disable the whole group. */
+    disabled?: boolean;
+    /** Form field name — submits the selected value with the form. */
+    name?: string;
+    id?: string;
+    className?: string;
+    /** Accessible name of the group. Required unless a visible label points at `id`. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+};
+export type SegmentedProps = SegmentedProp;
+/**
+ * Segmented — one-of-N from a small, closed, always-visible set. antd's `Segmented`
+ * (docs/DESIGN-AUTHORITY.md names Ant Design the taxonomy authority) drawn on Radix's RadioGroup,
+ * which is this repo's authority for behaviour primitives.
+ *
+ * WHY NOT `ToggleGroup`. A ToggleGroup is a row of PRESSED buttons: `aria-pressed`, independently
+ * togglable, and — even at `type="single"` — deselectable, so "no theme at all" is a state the
+ * markup permits. A segmented control is a radio group: exactly one member is always chosen, the
+ * arrow keys move between members rather than Tab, and a screen reader must say "Light, radio
+ * button, 1 of 3, selected" and not "Light, toggle button, pressed". WAI-ARIA APG owns that
+ * distinction and it is not a skin.
+ *
+ * The primitive gives roving tabindex, arrow-key traversal (RTL-aware), the radiogroup/radio roles
+ * and the hidden input a native form submit needs. This file adds the antd geometry and nothing
+ * else — the focus mark comes from `ui-focus-ring`, the ONE source in styles/focus-ring.css.
+ */
+export declare const Segmented: React.ForwardRefExoticComponent<SegmentedProp & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ui/segmented.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
+import { cn } from "../../lib/utils.js";
+const Segmented = React.forwardRef(function Segmented2({ options, value, defaultValue, onValueChange, disabled, name, id, className, ...props }, ref) {
+  return /* @__PURE__ */ jsx(
+    RadioGroupPrimitive.Root,
+    {
+      ref,
+      id,
+      "data-slot": "segmented",
+      className: cn("ui-segmented", className),
+      orientation: "horizontal",
+      value,
+      defaultValue,
+      onValueChange,
+      disabled,
+      name,
+      ...props,
+      children: options.map((option) => /* @__PURE__ */ jsxs(
+        RadioGroupPrimitive.Item,
+        {
+          value: option.value,
+          disabled: option.disabled,
+          "data-slot": "segmented-item",
+          className: "ui-segmented-item ui-focus-ring",
+          children: [
+            option.icon == null ? null : /* @__PURE__ */ jsx(
+              "span",
+              {
+                "data-slot": "segmented-item-icon",
+                className: "ui-segmented-item-icon",
+                "aria-hidden": "true",
+                children: option.icon
+              }
+            ),
+            /* @__PURE__ */ jsx("span", { "data-slot": "segmented-item-label", className: "ui-segmented-item-label", children: option.label })
+          ]
+        },
+        option.value
+      ))
+    }
+  );
+});
+export {
+  Segmented
+};

package/dist/email/tokens.generated.d.ts

@@ -44,8 +44,8 @@ export declare const EMAIL_COLOR_SOURCE: {
         readonly hsl: "60 33% 99%";
     };
     readonly focus: {
-        readonly cssVar: "--ring";
-        readonly hsl: "204 100% 39%";
+        readonly cssVar: "--primary";
+        readonly hsl: "204 100% 37%";
     };
     readonly brand: {
         readonly cssVar: "--brand";
@@ -103,7 +103,7 @@ export declare const EMAIL_COLOR_SOURCE_DARK: {
         readonly hsl: "48 9% 9%";
     };
     readonly focus: {
-        readonly cssVar: "--ring";
+        readonly cssVar: "--primary";
         readonly hsl: "204 90% 60%";
     };
     readonly brand: {

package/dist/email/tokens.generated.js

@@ -36,8 +36,8 @@ const EMAIL_COLOR_SOURCE = {
     "hsl": "60 33% 99%"
   },
   "focus": {
-    "cssVar": "--ring",
-    "hsl": "204 100% 39%"
+    "cssVar": "--primary",
+    "hsl": "204 100% 37%"
   },
   "brand": {
     "cssVar": "--brand",
@@ -94,7 +94,7 @@ const EMAIL_COLOR_SOURCE_DARK = {
     "hsl": "48 9% 9%"
   },
   "focus": {
-    "cssVar": "--ring",
+    "cssVar": "--primary",
     "hsl": "204 90% 60%"
   },
   "brand": {

package/dist/i18n/messages/en.json

@@ -336,7 +336,8 @@
     "themePicker": {
       "ariaLabel": "Theme",
       "light": "Light",
-      "dark": "Dark"
+      "dark": "Dark",
+      "system": "System"
     },
     "densityPicker": {
       "ariaLabel": "Density",

package/dist/i18n/messages/ja.json

@@ -324,7 +324,8 @@
     "themePicker": {
       "ariaLabel": "テーマ",
       "light": "ライト",
-      "dark": "ダーク"
+      "dark": "ダーク",
+      "system": "システム"
     },
     "densityPicker": {
       "ariaLabel": "密度",

package/dist/i18n/messages/vi.json

@@ -324,7 +324,8 @@
     "themePicker": {
       "ariaLabel": "Giao diện",
       "light": "Sáng",
-      "dark": "Tối"
+      "dark": "Tối",
+      "system": "Hệ thống"
     },
     "densityPicker": {
       "ariaLabel": "Mật độ",

package/dist/props/components/app.prop.d.ts

@@ -28,7 +28,11 @@ export type AppProviderProp = {
     storageKey?: string;
     /** Persist user choices. Default: true. */
     persist?: boolean;
-    /** Initial light/dark theme — written to `<html data-theme>`. Default: `"light"`. */
+    /**
+     * Initial theme choice. `"light"` / `"dark"` are written straight to `<html data-theme>`;
+     * `"system"` defers to `prefers-color-scheme` and is re-resolved whenever the OS changes.
+     * Default: `"light"`.
+     */
     theme?: AppTheme;
     /**
      * Initial brand palette preset — written to `<html data-brand>`. OPT-IN: omit
@@ -101,7 +105,10 @@ export type AppContextValue = {
     requestHeaders: AppRequestHeaders;
     /** Configured timezone list; `undefined` → full IANA in the timezone-picker recipe. */
     timezoneOptions?: readonly AppTimezone[];
-    /** Current theme axes (mirror `<html data-*>` / inline `--scaling`). */
+    /**
+     * Current theme axes (mirror `<html data-*>` / inline `--scaling`). `theme` is the user's
+     * CHOICE — it can be `"system"`, which `<html data-theme>` never is.
+     */
     theme: AppTheme;
     brand: AppBrand | null;
     density: AppDensity;

package/dist/props/components/general.prop.d.ts

@@ -4,7 +4,25 @@ import type { ActivityAnnounceProp, ActivityVariantProp, AsChildProp, ButtonSize
 /** @see Text — typographic primitive; replaces hand-rolled `<span className="text-[13px] …">`. */
 export type TextProp = Omit<React.HTMLAttributes<HTMLElement>, "color"> & {
     /** Render element. Default `span`. */
-    as?: "span" | "p" | "div" | "label" | "strong" | "em" | "small" | "code" | "kbd" | "dt" | "dd" | "caption" | "abbr";
+    as?: "span" | "p" | "div" | "a" | "label" | "strong" | "em" | "small" | "code" | "kbd" | "dt" | "dd" | "caption" | "abbr";
+    /**
+     * Render the typography onto the child element instead of emitting one — for a router link
+     * (`<Text asChild link><Link href=…>…</Link></Text>`). The child owns the element and its
+     * navigation; Text owns the type step, tone, weight and truncation.
+     */
+    asChild?: AsChildProp;
+    /**
+     * This text IS a link: underline on hover and on keyboard focus, at the token underline offset,
+     * and the focus mark every other interactive element draws.
+     *
+     * It is an AFFORDANCE, not a colour — `tone` still owns the colour and simply defaults to
+     * `primary` here, so a destructive link (`link tone="destructive"`) reads destructive and still
+     * underlines. Use this INSTEAD of `className="text-primary hover:underline"`, and instead of
+     * `Button variant="link"` whenever the link sits in running content: `.ui-button` is a control
+     * box (`white-space: nowrap`, `flex-shrink: 0`, a `--control-height` tier and inline padding),
+     * so in a table cell it cannot wrap and cannot share the cell's line height.
+     */
+    link?: boolean;
     /** Size from the type scale — never an arbitrary px. Default `sm` (base). */
     size?: TextSizeProp;
     /** Semantic colour intent. Default `default` (foreground). */
@@ -24,6 +42,18 @@ export type TextProp = Omit<React.HTMLAttributes<HTMLElement>, "color"> & {
     /** Monospace family (codes, ids). */
     mono?: boolean;
     htmlFor?: string;
+    /**
+     * Anchor attributes, for `as="a"` (and for the `<a>` a router link supplies under `asChild`).
+     *
+     * Declared explicitly rather than by widening the base to `AnchorHTMLAttributes`, and for the
+     * same reason `htmlFor` is declared explicitly for `as="label"`: the element union is the
+     * contract, so each polymorphic branch names the attributes it actually accepts instead of every
+     * span silently offering an `href` it will never render.
+     */
+    href?: string;
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    download?: React.AnchorHTMLAttributes<HTMLAnchorElement>["download"];
 };
 /** @see Heading — h1..h4 sized from the `--heading-h*` tokens. */
 export type HeadingProp = Omit<React.HTMLAttributes<HTMLHeadingElement>, "color"> & {