@godxjp/ui 28.4.0 → 28.6.0

package/README.md

@@ -12,6 +12,64 @@ npm i @godxjp/ui
 
 ---
 
+## Using this from an AI agent
+
+The catalog — 165 components, 1616 tokens, 47 cardinal rules — is published in two forms from one
+source. **Entry point for either: [`AGENTS.md`](AGENTS.md).**
+
+### If your agent can run a process
+
+Claude Code · Codex CLI · Cursor · any MCP client:
+
+```bash
+npx @godxjp/ui sync-rules
+```
+
+Writes `.mcp.json`, `CLAUDE.md` and `.ai/rules/` into the consumer repo and wires
+`@godxjp/ui-mcp`. Prefer this: it is searchable, it drills down instead of dumping, and it is
+**locked to the version on disk** — the failure it prevents is an agent being told a prop does not
+exist because the catalog was two minors behind (gh#789).
+
+### If your agent can only fetch URLs
+
+ChatGPT on the web, Claude.ai, or any client without a local process. The same data is served as
+static files straight from this public repo — no hosting, no deploy step:
+
+| file                                                                                                                    | size    | what it is                                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| [`agent/START-HERE.md`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md)                   | 6 KB    | **read first** — self-contained: the four rules, the token override model, a page that passes review   |
+| [`agent/llms.txt`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/llms.txt)                             | 2 KB    | the [llms.txt](https://llmstxt.org/) entry point                                                       |
+| [`agent/index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/index.json)                         | 2 KB    | manifest: version, counts, every file's URL                                                            |
+| [`agent/components-index.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components-index.json)   | 42 KB   | all 165 as name + group + tagline — **fetch this first**                                               |
+| [`agent/components/<Name>.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components/Select.json) | 1–32 KB | one file per component, each with its `importPath` — **this is the route to take**                     |
+| [`agent/components.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/components.json)               | 1.1 MB  | all 165 entries in one file — most URL fetchers truncate this silently; prefer the per-component files |
+| [`agent/tokens.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/tokens.json)                       | 0.6 MB  | every design token, its value and why it exists                                                        |
+| [`agent/vocabulary.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/vocabulary.json)               | 7 KB    | the controlled prop vocabulary                                                                         |
+| [`agent/rules.json`](https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/rules.json)                         | 17 KB   | the 47 cardinal rules                                                                                  |
+
+Pasteable bootstrap:
+
+> Read https://raw.githubusercontent.com/godx-jp/godxjp-ui/main/agent/START-HERE.md and follow it.
+> Then fetch .../agent/components-index.json to choose components, and
+> .../agent/components/<Name>.json for the props of each one you chose. Tell me which catalog
+> version you read.
+
+**Pin to the version you installed.** Every URL above tracks `main`. Swap `main` for the matching
+tag — `https://raw.githubusercontent.com/godx-jp/godxjp-ui/v28.4.0/agent/...` — because a catalog
+newer than your package describes props you do not have, an older one hides props you do, and
+neither failure announces itself. Pinned URLs only resolve for releases whose tag contains
+`agent/`; on a 404 the release predates this catalog, so read `main` and compare
+`index.json` → `version` against what you installed.
+
+### Why static files and not a hosted MCP endpoint
+
+GitHub serves files; it does not run servers. MCP over the network needs a process handling POST
+requests, which no amount of Pages or raw hosting provides. A hosted HTTP MCP would work and would
+need real hosting, ops and an auth decision — so the static lane ships first, carrying the same
+data at no operational cost. Regenerate both from the one source with `pnpm gen:agent-catalog`.
+
+---
+
 ## Role & boundary — read this first
 
 This package is **the single source of UI truth**. It is shared, versioned infrastructure, which means two things are non-negotiable:

package/dist/app/theme-axes.js

@@ -68,6 +68,12 @@ function applyPrimaryColor(root, color, foreground) {
     "--primary-active": "initial",
     "--primary-border": "initial",
     "--control-outline": "initial",
+    /* The brand TEXT roles derive from the seed too (gh#664), so they are reset for the same
+     * reason: an ancestor theme that pinned a link colour for the previous brand would otherwise
+     * outrank the seed just set, and a re-tinted product would keep the old brand's links. */
+    "--text-link": "initial",
+    "--text-brand": "initial",
+    "--text-primary": "initial",
     "--primary-hover-channels": `var(--primary-hover-${polarity}-channels)`,
     "--primary-active-channels": `var(--primary-active-${polarity}-channels)`,
     "--ring": hsl(rgb)

package/dist/components/data-entry/field.d.ts

@@ -2,4 +2,4 @@ import * as React from "react";
 import type { FieldProp } from "../../props/components/data-entry.prop.js";
 export type { FieldProp, FieldProp as FieldProps } from "../../props/components/data-entry.prop.js";
 /** Label + optional description beside a checkbox/radio/switch control. */
-export declare function Field({ id, label, description, className, children }: FieldProp): React.JSX.Element;
+export declare function Field({ id, label, labelAddon, description, error, className, children, }: FieldProp): React.JSX.Element;

package/dist/components/data-entry/field.js

@@ -1,12 +1,43 @@
+"use client";
 import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
 import { cn } from "../../lib/utils.js";
+import { mergeAriaIds } from "../../lib/field-a11y.js";
 import { Label } from "./label.js";
-function Field({ id, label, description, className, children }) {
+function Field({
+  id,
+  label,
+  labelAddon,
+  description,
+  error,
+  className,
+  children
+}) {
+  const descriptionId = description ? `${id}-description` : void 0;
+  const errorId = error ? `${id}-error` : void 0;
+  const childProps = React.isValidElement(children) ? children.props : void 0;
+  const control = React.isValidElement(children) ? React.cloneElement(children, {
+    "aria-describedby": mergeAriaIds(
+      childProps?.["aria-describedby"],
+      descriptionId,
+      errorId
+    ),
+    "aria-errormessage": mergeAriaIds(
+      childProps?.["aria-errormessage"],
+      errorId
+    ),
+    "aria-invalid": error ? true : childProps?.["aria-invalid"]
+  }) : children;
+  const labelNode = /* @__PURE__ */ jsx(Label, { htmlFor: id, className: "ui-choice-label", children: label });
   return /* @__PURE__ */ jsxs("div", { className: cn("ui-choice-field", className), children: [
-    /* @__PURE__ */ jsx("div", { className: "ui-choice-control", children }),
+    /* @__PURE__ */ jsx("div", { className: "ui-choice-control", children: control }),
     /* @__PURE__ */ jsxs("div", { className: "ui-choice-content", children: [
-      /* @__PURE__ */ jsx(Label, { htmlFor: id, className: "ui-choice-label", children: label }),
-      description ? /* @__PURE__ */ jsx("p", { className: "ui-choice-description", children: description }) : null
+      labelAddon != null ? /* @__PURE__ */ jsxs("div", { className: "ui-choice-label-row", children: [
+        labelNode,
+        labelAddon
+      ] }) : labelNode,
+      description ? /* @__PURE__ */ jsx("p", { id: descriptionId, className: "ui-choice-description", children: description }) : null,
+      error ? /* @__PURE__ */ jsx("p", { id: errorId, role: "alert", className: "ui-choice-error", children: error }) : null
     ] })
   ] });
 }

package/dist/components/data-entry/index.d.ts

@@ -42,6 +42,7 @@ export type { SelectProp, SelectProp as SelectProps } from "./select.js";
 export type { SearchSelectOptionProp as SelectOption, SearchSelectLoadParamsProp as SelectLoadParams, SearchSelectLoadResultProp as SelectLoadResult, } from "./search-select.js";
 export { UPLOAD_LIST_IGNORE, Upload, collectUploadCommitActions, createUploadItem, useUploadDraft, } from "./upload.js";
 export type { UploadProps, UploadFileItem, UploadVariant, UploadCommitAction } from "./upload.js";
+export { UploadCropDialog } from "./upload-crop-dialog.js";
 export { Cascader } from "./cascader.js";
 export type { CascaderProps, TreeOption, TreeFieldNames } from "./cascader.js";
 export { TreeSelect, SHOW_CHILD, SHOW_PARENT, SHOW_ALL } from "./tree-select.js";

package/dist/components/data-entry/index.js

@@ -39,6 +39,7 @@ import {
   createUploadItem,
   useUploadDraft
 } from "./upload.js";
+import { UploadCropDialog } from "./upload-crop-dialog.js";
 import { Cascader } from "./cascader.js";
 import { TreeSelect, SHOW_CHILD, SHOW_PARENT, SHOW_ALL } from "./tree-select.js";
 import { Transfer } from "./transfer.js";
@@ -127,6 +128,7 @@ export {
   TreeSelect,
   UPLOAD_LIST_IGNORE,
   Upload,
+  UploadCropDialog,
   collectUploadCommitActions,
   createUploadItem,
   dateMatchModifiers,

package/dist/components/data-entry/input.d.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 export type { InputProp, InputProp as InputProps } from "../../props/components/data-entry.prop.js";
 export declare const Input: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "prefix" | "size"> & {
     onValueChange?: (value: string) => void;
-    size?: "sm" | "md" | "lg";
+    size?: "xs" | "sm" | "md" | "lg";
     status?: import("../../props/index.js").ControlStatusProp;
     variant?: import("../../props/index.js").ControlVariantProp;
     allowClear?: import("../../props/index.js").AllowClearProp;

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

@@ -38,7 +38,7 @@ export type { ErrorSurfaceModeProp, ErrorSurfaceStatusProp } from "../../props/v
 export { Breadcrumb } from "./breadcrumb.js";
 export type { BreadcrumbProps } from "./breadcrumb.js";
 export { createSidebarLink, Sidebar, SidebarHeader, SidebarItem, SidebarSection } from "./sidebar.js";
-export type { SidebarItemData, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, SidebarSectionProp, } from "../../props/components/layout.prop.js";
+export type { SidebarItemData, SidebarItemProp, 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";

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

@@ -16,9 +16,17 @@ export type NavListProps = NavListProp;
  * 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).
+ *
+ * `item.children` is part of that shared row shape, and it is rendered through the rail's OWN
+ * `NavGroup` (gh#815). It used to be dropped: `items` mapped straight to `SidebarItem`, so a
+ * nested group type-checked, rendered as a single flat row, and its children vanished with no
+ * error and no warning. A grouped settings nav — アカウント / セキュリティ / 通知 / 請求 — is the
+ * canonical use of this component, and it took one `NavList` per group wrapped in
+ * `SidebarSection`, i.e. N `<nav>` landmarks where the page has one navigation. Now it is one
+ * `NavList`, one landmark, and the group opens itself whenever the route lands on a descendant.
  */
 export declare const NavList: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLElement>, "onSelect"> & {
-    items: import("../../props/index.js").SidebarItemProp[];
+    items: import("./sidebar.js").SidebarItemProp[];
     activeId?: string;
     label: string;
     linkComponent?: import("./sidebar.js").SidebarLinkComponentProp;

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

@@ -2,18 +2,29 @@
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
-import { SidebarItem } from "./sidebar.js";
+import { NavGroup, 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
-  )) })
+  ({ 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) => item.children && item.children.length > 0 ? /* @__PURE__ */ jsx(
+      NavGroup,
+      {
+        item,
+        activeId: activeId ?? "",
+        linkComponent,
+        onSelect
+      },
+      item.id
+    ) : /* @__PURE__ */ jsx(
+      SidebarItem,
+      {
+        item,
+        active: item.id === activeId,
+        linkComponent,
+        onActivate: onSelect
+      },
+      item.id
+    )
+  ) })
 );
 NavList.displayName = "NavList";
 export {

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

@@ -1,6 +1,6 @@
 import * as React from "react";
-import type { SidebarItemData, SidebarLinkComponentProp, SidebarProp, SidebarRenderItemProp } from "../../props/components/layout.prop.js";
-export type { SidebarItemData, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, } from "../../props/components/layout.prop.js";
+import type { SidebarItemData, SidebarItemProp, SidebarLinkComponentProp, SidebarProp, SidebarRenderItemProp } from "../../props/components/layout.prop.js";
+export type { SidebarItemData, SidebarItemProp, SidebarLinkComponentProp, SidebarLinkProp, SidebarProductProp as SidebarProduct, SidebarProp, SidebarProp as SidebarProps, SidebarRenderItemProp, } from "../../props/components/layout.prop.js";
 type RenderItem = (item: SidebarItemData, rowProps: SidebarRenderItemProp) => React.ReactNode;
 type SidebarHeaderProps = React.HTMLAttributes<HTMLDivElement>;
 type SidebarSectionProps = {
@@ -28,6 +28,20 @@ type SidebarItemProps = {
 export declare function SidebarHeader({ children, className, ...props }: SidebarHeaderProps): React.JSX.Element;
 export declare function SidebarSection({ label, collapsed, children, className, ...props }: SidebarSectionProps & React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 export declare function SidebarItem({ item, active, sub, onActivate, linkComponent: LinkComponent, asChild, renderItem, children, ...props }: SidebarItemProps & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick">): React.JSX.Element;
+type RowProps = {
+    item: SidebarItemProp;
+    activeId: string;
+    onSelect?: (id: string) => void;
+    sub?: boolean;
+    linkComponent?: SidebarLinkComponentProp;
+    renderItem?: RenderItem;
+};
+/**
+ * The collapsible submenu group of a nested `SidebarItemProp`. Exported (not from the package —
+ * only within `src/components/layout`) so `NavList` renders nested items through the SAME group as
+ * the rail instead of dropping `item.children` on the floor (gh#815).
+ */
+export declare function NavGroup({ item, activeId, onSelect, linkComponent, renderItem }: RowProps): React.JSX.Element;
 export { createSidebarLink } from "./sidebar-link.js";
 /**
  * Sidebar — data-driven vertical nav rail. Use {@link createSidebarLink} to adapt a router `Link`,

package/dist/components/layout/sidebar.js

@@ -396,6 +396,7 @@ function Sidebar({
   ] });
 }
 export {
+  NavGroup,
   Sidebar,
   SidebarHeader,
   SidebarItem,

package/dist/components/ui/password-input.d.ts

@@ -18,7 +18,7 @@ export type PasswordInputProps = Omit<React.ComponentPropsWithoutRef<typeof Inpu
 };
 export declare const PasswordInput: React.ForwardRefExoticComponent<Omit<Omit<Omit<React.InputHTMLAttributes<HTMLInputElement>, "prefix" | "size"> & {
     onValueChange?: (value: string) => void;
-    size?: "sm" | "md" | "lg";
+    size?: "xs" | "sm" | "md" | "lg";
     status?: import("../../props/index.js").ControlStatusProp;
     variant?: import("../../props/index.js").ControlVariantProp;
     allowClear?: import("../../props/index.js").AllowClearProp;

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "28.4.0",
+  "version": "28.6.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/lib/control-styles.d.ts

@@ -30,11 +30,26 @@ export declare const controlOpenRingClass = "ui-control-trigger";
  * `--control-bounded-width` in gh#375). A control that wants the antd `variant` × `status` matrix
  * therefore composes THIS class plus `ui-control-surface`, which supplies the identical resting
  * border and fill from `--control-surface-*`.
+ *
+ * TRUNCATION HAS TO READ AS TRUNCATION (gh#813). `line-clamp-1` clips the value and — inside the
+ * trigger's `whitespace-nowrap` — never reaches a second line, so its own ellipsis never engages:
+ * `YYYY-MM-DD（年-月-日）` in a 101px value box showed `YYYY-MM-DD（全`, a format string cut through
+ * the middle of a glyph, with nothing to say it had been cut. Two declarations because the two
+ * engines ellipsize by different mechanisms, both measured on
+ * `/isolate/navigation-app-setting-picker` (dateFormat, ja, 1280×1000, value box 101px / text
+ * 160px):
+ *
+ *   text-ellipsis      Blink honours `text-overflow` on the clamped box → `YYYY-MM-DD…`.
+ *                      Gecko ignores it there (still `YYYY-MM-DD（全`).
+ *   whitespace-normal  lets `-webkit-line-clamp` clamp a real line, which is the ellipsis Gecko
+ *                      DOES paint → `YYYY-MM-D…` in Firefox, `YYYY-MM-DD…` in Chromium.
+ *
+ * The clamp keeps it to one line, so a wrappable value cannot grow the control.
  */
-export declare const controlTriggerBaseClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1";
-export declare const controlTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1 border-input bg-background";
+export declare const controlTriggerBaseClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1 [&>[data-slot=select-value]]:whitespace-normal [&>[data-slot=select-value]]:text-ellipsis";
+export declare const controlTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1 [&>[data-slot=select-value]]:whitespace-normal [&>[data-slot=select-value]]:text-ellipsis border-input bg-background";
 /** `controlTriggerBaseClass` + the token-driven surface — the select-family trigger. */
-export declare const controlSurfaceTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1 ui-control-surface";
+export declare const controlSurfaceTriggerClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1 [&>[data-slot=select-value]]:whitespace-normal [&>[data-slot=select-value]]:text-ellipsis ui-control-surface";
 export declare const controlIconClass = "size-[length:var(--control-height)] shrink-0";
 export declare const controlIconSmClass = "size-[calc(var(--control-height)-0.5rem)] shrink-0";
 /** Leading/affix icon inside an input row (search, command) — sized to `--control-icon-size`. */

package/dist/lib/control-styles.js

@@ -2,7 +2,7 @@ const controlMultilineClass = "ui-control-multiline aria-invalid:border-destruct
 const controlMultilineGhostClass = "ui-control-multiline data-[status=error]:border-destructive data-[status=warning]:border-warning w-full min-h-0 border-0 bg-transparent shadow-none placeholder:text-muted-foreground focus-visible:ring-0";
 const controlMultilineFilledClass = "ui-control-multiline ui-control--filled aria-invalid:border-destructive data-[status=error]:border-destructive data-[status=warning]:border-warning w-full rounded-[var(--control-radius)] ring-offset-background placeholder:text-muted-foreground";
 const controlOpenRingClass = "ui-control-trigger";
-const controlTriggerBaseClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1";
+const controlTriggerBaseClass = "ui-control ui-control-trigger flex items-center justify-between gap-2 whitespace-nowrap rounded-[var(--control-radius)] transition-[color,box-shadow] [&>[data-slot=select-value]]:line-clamp-1 [&>[data-slot=select-value]]:whitespace-normal [&>[data-slot=select-value]]:text-ellipsis";
 const controlTriggerClass = `${controlTriggerBaseClass} border-input bg-background`;
 const controlSurfaceTriggerClass = `${controlTriggerBaseClass} ui-control-surface`;
 const controlIconClass = "size-[length:var(--control-height)] shrink-0";

package/dist/props/components/data-entry.prop.d.ts

@@ -126,8 +126,18 @@ export type CommandProp = {
 };
 export type InputProp = Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "prefix"> & {
     onValueChange?: (value: string) => void;
-    /** Control height tier: `md` (default), `sm` or `lg` — the same tiers as SelectTrigger. */
-    size?: "sm" | "md" | "lg";
+    /**
+     * Control height tier: `md` (default), plus `xs`, `sm` and `lg` — the same tiers as
+     * SelectTrigger and NumberInput.
+     *
+     * `xs` was missing from this union alone. Everything underneath it already worked: `Input`
+     * renders `ui-control` and emits `data-size={size}`, and `.ui-control[data-size="xs"]`
+     * (src/styles/control.css:1674) binds `--control-height-xs`. That rule was added for the
+     * select family — its comment says the token "existed with nothing reading it" — and this
+     * union was never widened to match, so the most-used control in the package was the one
+     * control missing the bottom rung, for a reason no user could have guessed from behaviour.
+     */
+    size?: "xs" | "sm" | "md" | "lg";
     /** Validation state the field paints — antd `status`. `error` also reports `aria-invalid`. */
     status?: ControlStatusProp;
     /** Chrome level — antd `variant`. Default `outlined`. */
@@ -547,7 +557,31 @@ export type SwitchProp = Omit<React.ComponentPropsWithoutRef<"button">, "checked
 export type FieldProp = {
     id: IdProp;
     label: LabelProp;
+    /**
+     * Optional content rendered BESIDE the label and OUTSIDE the `<label>` element — a help
+     * button, a Tooltip trigger, a status chip, a short text action. `FormField.labelAddon` with
+     * the same semantics, and it has to live outside the label for a reason this row has that a
+     * stacked field does not: `Field`'s label is a real `<label htmlFor>` pointing at a
+     * checkbox / radio / switch, so a browser forwards a click anywhere inside it to that
+     * control. An interactive addon passed through `label` therefore TOGGLES the control when
+     * pressed (gh#812). A non-interactive mark (a `Badge as="span"`) is still fine inside
+     * `label`; anything pressable belongs here.
+     */
+    labelAddon?: React.ReactNode;
+    /**
+     * Muted hint under the label. Announced with the control (`aria-describedby`) rather than
+     * left as decoration, and it COMPOSES with `error` — `.ui-choice-content` is already a
+     * vertical stack, so the two lines sit under each other exactly as they do on `FormField`.
+     */
     description?: React.ReactNode;
+    /**
+     * Validation message under the description (`role="alert"`). Presence of a message IS the
+     * invalid state: the control is cloned with `aria-invalid`, and the message id reaches it
+     * through `aria-errormessage` AND `aria-describedby` (see field.tsx — react-aria's hidden
+     * input drops the former). This is the slot that lets a validated boolean stay in `Field`:
+     * `FormField` must not wrap a bare `Switch`, so before this there was nowhere to put it.
+     */
+    error?: ErrorProp;
     className?: ClassNameProp;
     children: React.ReactNode;
 };

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

@@ -932,11 +932,14 @@ export type SidebarItemProp = {
     id: string;
     label: string;
     /**
-     * Leading 16px glyph — REQUIRED: the collapsed rail is icon-only and the expanded rail aligns
-     * every label to the icon column. Its colour is themeable separately from the label via
+     * Leading 16px glyph. STRONGLY RECOMMENDED on the rail — the collapsed rail is icon-only, so a
+     * row without one reads as a hole there — but OPTIONAL at the type level (gh#815): the runtime
+     * has always rendered an empty `.sb-icon` box for a row whose data carries no glyph, precisely
+     * so the label column still aligns, and `NavList` (which has no collapsed rail) routinely mixes
+     * rows with and without one. Its colour is themeable separately from the label via
      * `--sidebar-nav-icon-foreground` (see {@link SidebarProp}).
      */
-    icon: ComponentType<SVGProps<SVGSVGElement>>;
+    icon?: ComponentType<SVGProps<SVGSVGElement>>;
     /**
      * Count/status affix rendered in the row's `.sb-badge` pill. Pass the CONTENT ONLY — a number, a
      * string, `"9+"`.
@@ -968,7 +971,11 @@ export type SidebarItemProp = {
      * right-click / open-in-new-tab / middle-click all work.
      */
     href?: string;
-    /** Nested rows — renders a collapsible submenu group (the parent reads active when any child is). */
+    /**
+     * Nested rows — renders a collapsible submenu group (the parent reads active when any child is).
+     * Honoured by BOTH `Sidebar` and `NavList` (gh#815): `NavList` used to map `items` straight to a
+     * row, so a nested group type-checked, rendered as one flat row and lost its children silently.
+     */
     children?: SidebarItemProp[];
 };
 /**
@@ -979,7 +986,11 @@ export type SidebarItemProp = {
  * learn a second one, and a fix to the row reaches both.
  */
 export type NavListProp = Omit<React.HTMLAttributes<HTMLElement>, "onSelect"> & {
-    /** Rows, in reading order. `icon` is required by `SidebarItemProp` — the label aligns to it. */
+    /**
+     * Rows, in reading order. An item carrying `children` renders as a collapsible GROUP — the same
+     * `.sb-nav-group` the rail draws, opened by the route whenever a descendant is active — so a
+     * grouped settings nav is one `NavList` and one `<nav>` landmark, not one per group (gh#815).
+     */
     items: SidebarItemProp[];
     /** `SidebarItemProp.id` of the current route; that row gets `aria-current="page"`. */
     activeId?: string;

package/dist/props/registry.d.ts

@@ -1470,7 +1470,7 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly FieldProp: {
         readonly group: "data-entry";
         readonly file: "components/data-entry.prop.ts";
-        readonly vocabulary: readonly ["IdProp", "LabelProp", "DescriptionProp", "ClassNameProp", "ChildrenProp"];
+        readonly vocabulary: readonly ["IdProp", "LabelProp", "DescriptionProp", "ErrorProp", "ClassNameProp", "ChildrenProp"];
     };
     readonly SliderProp: {
         readonly group: "data-entry";

package/dist/props/registry.js

@@ -1689,7 +1689,14 @@ const COMPONENT_PROP_REGISTRY = {
   FieldProp: {
     group: "data-entry",
     file: "components/data-entry.prop.ts",
-    vocabulary: ["IdProp", "LabelProp", "DescriptionProp", "ClassNameProp", "ChildrenProp"]
+    vocabulary: [
+      "IdProp",
+      "LabelProp",
+      "DescriptionProp",
+      "ErrorProp",
+      "ClassNameProp",
+      "ChildrenProp"
+    ]
   },
   SliderProp: {
     group: "data-entry",

package/dist/styles/base.css

@@ -74,7 +74,9 @@
   --color-attention: hsl(var(--attention));
   --color-attention-foreground: hsl(var(--attention-foreground));
 
-  --color-primary-strong: hsl(var(--text-primary));
+  --color-primary-strong: hsl(
+    var(--text-primary, from hsl(var(--primary)) var(--text-primary-channels))
+  );
   --color-success-strong: hsl(var(--text-success));
   --color-warning-strong: hsl(var(--text-warning));
   --color-info-strong: hsl(var(--text-info));
@@ -97,8 +99,8 @@
 
   --color-foreground-tertiary: hsl(var(--text-tertiary));
   --color-foreground-disabled: hsl(var(--text-disabled));
-  --color-link: hsl(var(--text-link));
-  --color-brand: hsl(var(--text-brand));
+  --color-link: hsl(var(--text-link, from hsl(var(--primary)) var(--text-link-channels)));
+  --color-brand: hsl(var(--text-brand, from hsl(var(--primary)) var(--text-brand-channels)));
 
   --color-primary-hover: hsl(
     var(--primary-hover, from hsl(var(--primary)) var(--primary-hover-channels))

package/dist/styles/card-layout.css

@@ -55,27 +55,32 @@
   }
 
   [data-slot="card"][data-accent="primary"] {
-    --card-accent-color: hsl(var(--mark-primary));
+    --card-accent-color: hsl(
+      var(
+        --mark-primary,
+        var(--text-primary, from hsl(var(--primary)) var(--text-primary-channels))
+      )
+    );
   }
 
   [data-slot="card"][data-accent="success"] {
-    --card-accent-color: hsl(var(--mark-success));
+    --card-accent-color: hsl(var(--mark-success, var(--text-success)));
   }
 
   [data-slot="card"][data-accent="warning"] {
-    --card-accent-color: hsl(var(--mark-warning));
+    --card-accent-color: hsl(var(--mark-warning, var(--text-warning)));
   }
 
   [data-slot="card"][data-accent="info"] {
-    --card-accent-color: hsl(var(--mark-info));
+    --card-accent-color: hsl(var(--mark-info, var(--text-info)));
   }
 
   [data-slot="card"][data-accent="attention"] {
-    --card-accent-color: hsl(var(--mark-attention));
+    --card-accent-color: hsl(var(--mark-attention, var(--attention)));
   }
 
   [data-slot="card"][data-accent="destructive"] {
-    --card-accent-color: hsl(var(--mark-destructive));
+    --card-accent-color: hsl(var(--mark-destructive, var(--text-error)));
   }
 
   [data-slot="card"][data-accent] {

package/dist/styles/control.css

@@ -435,11 +435,23 @@
     font-weight: var(--font-weight-normal);
   }
 
+  .ui-choice-label-row {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--control-label-space-gap);
+  }
+
   .ui-choice-description {
     color: hsl(var(--muted-foreground));
     font-size: var(--choice-description-font-size);
   }
 
+  .ui-choice-error {
+    color: hsl(var(--text-error));
+    font-size: var(--choice-description-font-size);
+  }
+
   .ui-label {
     display: flex;
     align-items: center;
@@ -999,7 +1011,7 @@
   .ui-otp-container:has(.ui-otp-input[data-status="warning"]) .ui-otp-slot,
   .ui-otp-container:has(.ui-otp-input[data-status="warning"])
     .ui-otp-group[data-appearance="grouped"] {
-    border-color: var(--control-status-warning-border-color);
+    border-color: var(--control-status-warning-border-color, hsl(var(--text-warning)));
   }
 
   .ui-otp-container:has(.ui-otp-input[readonly]) .ui-otp-slot {
@@ -1371,10 +1383,10 @@
   }
 
   .ui-control-surface[data-status="warning"] {
-    border-color: var(--control-status-warning-border-color);
+    border-color: var(--control-status-warning-border-color, hsl(var(--text-warning)));
     --focus-ring-color: var(--warning);
     --focus-outline-color: var(--warning);
-    --focus-ring-glow-color: var(--control-status-warning-outline-color);
+    --focus-ring-glow-color: var(--control-status-warning-outline-color, var(--text-warning));
   }
 
   .ui-number-input[data-size="sm"] {
@@ -2442,7 +2454,7 @@
 
   .ui-calendar .ui-calendar-day.day-today:not(.day-selected) .ui-calendar-day-button {
     box-shadow: inset 0 0 0 1px hsl(var(--primary));
-    color: hsl(var(--text-primary));
+    color: hsl(var(--text-primary, from hsl(var(--primary)) var(--text-primary-channels)));
     font-weight: var(--font-weight-medium);
   }
 
@@ -2471,7 +2483,7 @@
 
   .ui-calendar .ui-calendar-day.day-today:not(:has(button)) {
     box-shadow: inset 0 0 0 1px hsl(var(--primary));
-    color: hsl(var(--text-primary));
+    color: hsl(var(--text-primary, from hsl(var(--primary)) var(--text-primary-channels)));
     font-weight: var(--font-weight-medium);
     border-radius: var(--calendar-day-radius);
   }
@@ -2806,8 +2818,8 @@
 
   .ui-control[data-status="warning"],
   .ui-control-multiline[data-status="warning"] {
-    --focus-ring-color: var(--control-status-warning-outline-color);
-    --focus-outline-color: var(--control-status-warning-outline-color);
+    --focus-ring-color: var(--control-status-warning-outline-color, var(--text-warning));
+    --focus-outline-color: var(--control-status-warning-outline-color, var(--text-warning));
     --focus-ring-glow-color: var(--control-status-warning-glow-color);
     --focus-ring-glow-alpha: var(--control-status-warning-glow-alpha);
   }
@@ -2833,7 +2845,7 @@
   }
 
   .ui-control-count[data-exceeded="true"] {
-    color: hsl(var(--control-count-exceeded-color));
+    color: hsl(var(--control-count-exceeded-color, var(--text-error)));
   }
 
   .ui-textarea-count {