@godxjp/ui-mcp 14.0.1 → 16.5.0

package/dist/index.js

@@ -275,7 +275,7 @@ import { StatCard } from "@godxjp/ui/data-display";
       {
         name: "logo",
         type: "ReactNode",
-        description: "Logo at the far-left of the auto-built topbar rail."
+        description: "Brand mark at the far-left of the auto-built topbar rail (e.g. an Avatar)."
       },
       {
         name: "sidebarCollapsed",
@@ -488,7 +488,7 @@ export default function Shell() {
         name: "start",
         type: "ReactNode",
         defaultValue: "undefined",
-        description: "Inline-start cluster \u2014 typically the sidebar toggle (a `Button` with a `PanelLeftClose` icon), the brand `Logo`, and primary nav."
+        description: "Inline-start cluster \u2014 typically the sidebar toggle (a `Button` with a `PanelLeftClose` icon), the brand mark (an `Avatar`), and primary nav."
       },
       {
         name: "center",
@@ -515,25 +515,26 @@ export default function Shell() {
       }
     ],
     usage: [
-      "DO compose the bar yourself: brand `Logo` + sidebar toggle in `start`, a search trigger in `center`, settings pickers + notifications + user menu in `end`. The shell only positions; it never decides WHICH controls exist.",
+      "DO compose the bar yourself: a brand mark (an `Avatar`) + sidebar toggle in `start`, a search trigger in `center`, settings pickers + notifications + user menu in `end`. The shell only positions; it never decides WHICH controls exist.",
       'DO build the sidebar toggle as a `Button variant="ghost" size="icon-sm"` with a `PanelLeftClose`/`PanelLeftOpen` icon and your own `t()` aria-label, wired to AppShell\'s `sidebarCollapsed`. There is no baked toggle.',
       "DO put a locale/theme switcher in `end` using `AppSettingPicker` (or your own control) \u2014 icon-only vs labelled, bordered vs not, is THAT component's prop, not Topbar's. Topbar does not ship or force a language picker.",
       "DON'T look for `product`/`project`/`onSearchOpen`/`onNotificationsOpen`/`collapsed` props \u2014 they were removed. A chrome control only exists if YOU put it in a slot, so there is never a dead dropdown / empty search with nothing behind it.",
       "DO render Topbar inside `AppShell`'s `topbar` slot (or any `<header>`). For a non-three-cluster layout, pass `children` and lay it out yourself."
     ],
     useCases: [
-      "Admin shell: `start` = sidebar toggle + Logo + an entity switcher (`DropdownMenu` around a `Button`); `center` = a `Button` search trigger; `end` = `AppSettingPicker` (locale) + a notifications `Button` + a user `DropdownMenu`.",
-      "Minimal shell (no search, no notifications): pass only `start` (Logo) and `end` (user menu). Nothing else renders \u2014 no empty chrome.",
+      "Admin shell: `start` = sidebar toggle + brand mark (`Avatar`) + an entity switcher (`DropdownMenu` around a `Button`); `center` = a `Button` search trigger; `end` = `AppSettingPicker` (locale) + a notifications `Button` + a user `DropdownMenu`.",
+      "Minimal shell (no search, no notifications): pass only `start` (brand mark) and `end` (user menu). Nothing else renders \u2014 no empty chrome.",
       "Marketing / docs header: pass `children` with a fully custom flex layout when the three-cluster model doesn't fit."
     ],
     related: [
       "AppShell \u2014 place Topbar in its `topbar` slot. AppShell also exposes its own `logo`/`topbarLeft`/`topbarRight` slots if you don't want a separate Topbar at all.",
-      "Logo \u2014 the brand mark for the `start` slot.",
+      'Avatar \u2014 the brand mark for the `start` slot (use `className="rounded-md"` for a square-ish product glyph).',
       "AppSettingPicker \u2014 locale/theme/timezone/currency picker; the consumer drops it into `end`. Its appearance (icon-only, labelled, bordered) is configured on IT, not on Topbar.",
       "DropdownMenu \u2014 wrap a `Button` to build an entity switcher or user menu yourself, then place it in a slot."
     ],
     example: `import { Topbar, AppShell } from "@godxjp/ui/layout";
-import { Logo, Button } from "@godxjp/ui/general";
+import { Button } from "@godxjp/ui/general";
+import { Avatar, AvatarFallback } from "@godxjp/ui/data-display";
 import { AppSettingPicker } from "@godxjp/ui/navigation";
 import { PanelLeftClose, Search } from "lucide-react";
 
@@ -547,7 +548,9 @@ import { PanelLeftClose, Search } from "lucide-react";
           <Button variant="ghost" size="icon-sm" aria-label={t("toggleSidebar")} onClick={toggle}>
             <PanelLeftClose />
           </Button>
-          <Logo label="CoreBooks" />
+          <Avatar className="rounded-md">
+            <AvatarFallback className="bg-primary text-primary-foreground font-bold">C</AvatarFallback>
+          </Avatar>
         </>
       }
       center={
@@ -864,68 +867,11 @@ import { Trash2 } from "lucide-react";
 <Heading level={2}>\u8ACB\u6C42\u66F8\u4E00\u89A7</Heading>
 <Heading level={3} tone="muted">\u88DC\u8DB3\u30BB\u30AF\u30B7\u30E7\u30F3</Heading>`
   },
-  {
-    name: "Logo",
-    group: "general",
-    tagline: 'Product brand-mark \u2014 the lettermark (or custom SVG) in a tokenized box. Use instead of a hand-rolled `<span className="flex size-8 rounded-md bg-primary font-bold">g</span>` (typography-on-span, literal size/radius).',
-    props: [
-      {
-        name: "glyph",
-        type: "ReactNode",
-        defaultValue: '"G"',
-        description: "The mark \u2014 a short lettermark string or a custom SVG/image node."
-      },
-      {
-        name: "label",
-        type: "string",
-        description: 'Accessible product name. When set the mark exposes `role="img"` + `aria-label` (use when the Logo IS the accessible name, e.g. a home link). Omitted \u2192 the mark is `aria-hidden` (decorative; an adjacent wordmark names it).'
-      },
-      {
-        name: "size",
-        type: '"xs" | "sm" | "md" | "lg"',
-        defaultValue: '"md"',
-        description: "Square box size (24 / 28 / 32 / 40). Size comes from the prop, never a literal."
-      },
-      {
-        name: "shape",
-        type: '"default" | "pill" | "sharp"',
-        defaultValue: '"default"',
-        description: "Corner shape \u2014 `default` (--logo-radius, a service knob), `pill` (fully rounded), `sharp` (square)."
-      }
-    ],
-    usage: [
-      "DO use Logo for the product glyph in a topbar, sidebar header, or auth shell instead of hand-rolling a styled `<span>`/`<div>` with a literal size + radius + bg (cardinal rules #42/#46).",
-      "DO pass `label` when the mark is the only branding AND acts as the accessible name (e.g. wrapped in a home link); omit it when a wordmark sits beside it (then the mark is decorative `aria-hidden`).",
-      "DO retheme via tokens \u2014 brand fill follows `--primary`; a service squares/rounds the corner globally via `--logo-radius`. DON'T override size/radius with a raw className.",
-      "DON'T put body copy in Logo \u2014 it is a brand mark (bold lettermark / SVG), not a Text/Heading substitute."
-    ],
-    useCases: [
-      'Topbar / sidebar header brand mark next to a wordmark: `<Logo /> <Text weight="bold">GoDX</Text>`.',
-      'Auth shell (sign-in card) centered product mark with an accessible name: `<Logo size="lg" label="GoDX" />`.',
-      'A home link in an app shell where the logo IS the link label: `<a href="/"><Logo label="GoDX \u30DB\u30FC\u30E0" /></a>`.'
-    ],
-    related: [
-      "Avatar \u2014 for a USER/person image or initials; Logo is for the PRODUCT/brand mark.",
-      "Text / Heading \u2014 for the wordmark or any real copy beside the mark; Logo never holds prose."
-    ],
-    example: `import { Logo, Text } from "@godxjp/ui/general";
-
-// Topbar lettermark + wordmark
-<span className="inline-flex items-center gap-2">
-  <Logo />
-  <Text weight="bold">GoDX</Text>
-</span>
-
-// Auth shell, the mark is the accessible name
-<Logo size="lg" label="GoDX" />`,
-    storyPath: "general/Logo.stories.tsx",
-    rules: [42, 46]
-  },
   // ─── data-display ───────────────────────────────────────────────────────
   {
     name: "DataTable",
     group: "data-display",
-    tagline: "Compound admin list component with sticky header, sorting, bulk selection, cursor pagination, and built-in empty/loading states \u2014 never hand-roll a data.length===0 guard around it.",
+    tagline: "The one TanStack-powered compound admin list \u2014 sticky header, sorting, global search, column visibility ('set view'), bulk selection, BOTH cursor and numbered pagination, density, and built-in empty/loading states. Keep the SIMPLE `data` + lean `columns` (ColumnDef) API for the common case; opt into the full grid chrome via the compound parts. Internally driven by @tanstack/react-table (a real dependency). Lives on @godxjp/ui/data-display only (it is NOT on the runtime-neutral root/admin barrel because it pulls TanStack). This is the single table component \u2014 the former DataGrid has been merged in and removed. Never hand-roll a data.length===0 guard around it.",
     props: [
       {
         name: "data",
@@ -937,7 +883,7 @@ import { Trash2 } from "lucide-react";
         name: "columns",
         type: "ColumnDef<T>[]",
         required: true,
-        description: "Column definitions. Each column: { key: string; header: ReactNode; render?: (row: T) => ReactNode; sortable?: boolean; width?: string; align?: 'left'|'center'|'right'; hiddenOnMobile?: boolean; pin?: 'end' }. If render is omitted, the raw value at row[key] is rendered as a string. pin:'end' sticks the column (typically row actions) to the inline-end edge on horizontal scroll with a separating shadow \u2014 pin at most one column."
+        description: "Lean column definitions (adapted to TanStack internally). Each column: { key: string; header: ReactNode; render?: (row: T) => ReactNode; sortable?: boolean; width?: string; align?: 'left'|'center'|'right'; hiddenOnMobile?: boolean; enableHiding?: boolean; pin?: 'end' }. If render is omitted, the raw value at row[key] is rendered as a string. sortable opts the column into the sort cycle (client-side by default, or server-side via sort+onSortChange). enableHiding (default true) lists the column in DataTable.ViewOptions; set false to keep a key/actions column always visible. pin:'end' sticks the column (typically row actions) to the inline-end edge on horizontal scroll with a separating shadow \u2014 pin at most one column."
       },
       {
         name: "getRowId",
@@ -997,13 +943,34 @@ import { Trash2 } from "lucide-react";
       },
       {
         name: "sort",
-        type: "{ value: string; direction: 'asc' | 'desc' }",
-        description: "Active sort state. When provided alongside onSortChange, sortable columns show directional arrow icons and are clickable. Clicking the active column twice clears sort (calls onSortChange(undefined))."
+        type: "{ key: string; direction: 'asc' | 'desc' }",
+        description: "Active sort state (controlled/server surface). When provided alongside onSortChange, sortable columns show directional arrow icons and clicking the active column twice clears sort (calls onSortChange(undefined)). Omit both sort and onSortChange to sort client-side via TanStack."
       },
       {
         name: "onSortChange",
-        type: "(sort: { value: string; direction: 'asc' | 'desc' } | undefined) => void",
-        description: "Called when a sortable column header is clicked. Receives undefined when sort is cleared (third click on same column)."
+        type: "(sort: { key: string; direction: 'asc' | 'desc' } | undefined) => void",
+        description: "Called when a sortable column header is clicked. Receives undefined when sort is cleared (third click on same column). Providing sort or onSortChange opts into the controlled (server) sort surface; omit both and the table sorts client-side via TanStack."
+      },
+      {
+        name: "globalFilter / onGlobalFilterChange",
+        type: "string / (next: string) => void",
+        description: "Global search term surfaced by DataTable.Search. Omit both for client-side filtering; pass them to drive a server query (with manualFiltering)."
+      },
+      {
+        name: "pagination / onPaginationChange / rowCount",
+        type: "{ pageIndex: number; pageSize: number } / OnChangeFn / number",
+        description: "Numbered-pagination state surfaced by DataTable.Pagination (page-size form). For server pagination pass all three (rowCount = total) with manualPagination; omit for client pagination."
+      },
+      {
+        name: "columnVisibility / onColumnVisibilityChange",
+        type: "VisibilityState / OnChangeFn<VisibilityState>",
+        description: "Column show/hide state surfaced by DataTable.ViewOptions ('set view'). Internal if omitted."
+      },
+      {
+        name: "manualSorting / manualFiltering / manualPagination",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Default false so the simple data+columns case sorts/filters/paginates in-browser. Set the relevant flag true and drive the matching state from your query for server-side behaviour."
       },
       {
         name: "loading",
@@ -1024,14 +991,15 @@ import { Trash2 } from "lucide-react";
       {
         name: "children",
         type: "ReactNode",
-        description: "Compound sub-parts: DataTable.Toolbar, DataTable.BulkActions, DataTable.DensityToggle, DataTable.Pagination, DataTable.Content. If no DataTable.Content is present in children, one is auto-rendered."
+        description: "Compound sub-parts: DataTable.Toolbar, DataTable.Search (global filter), DataTable.ViewOptions (column show/hide), DataTable.SelectAll, DataTable.BulkActions (ReactNode children OR a (count)=>node render-prop), DataTable.DensityToggle, DataTable.Pagination (cursor first/next when given cursor+hasMore+onChange, else numbered page-size form), DataTable.RowActions (kebab trigger), DataTable.Content. If no DataTable.Content is present in children, one is auto-rendered."
       }
     ],
     usage: [
       "DO pass loading={isFetching} during data fetches \u2014 it renders a loading row in the table body and suppresses the empty state. Never show a spinner outside DataTable while the table is visible.",
       "DO NOT add a data.length===0 conditional around DataTable. When data is empty and loading is false, the built-in EmptyState renders automatically. Pass empty={<EmptyState title='...'/>} only when you need a custom message.",
       "DO provide getRowId when selectable is true or when rows do not have a string/number 'id' field \u2014 the default falls back to row.id and silently returns '' for missing IDs, which breaks selection.",
-      "DO use DataTable.Toolbar as the immediate child that wraps search/filter controls on the left and DataTable.DensityToggle/action buttons on the right. DataTable.BulkActions inside the toolbar auto-hides when selection count is 0.",
+      "DO use DataTable.Toolbar as the immediate child that wraps search/filter controls on the left and DataTable.DensityToggle/action buttons on the right. DataTable.BulkActions inside the toolbar auto-hides when selection count is 0; it accepts either plain ReactNode children (built-in 'N selected' status bar) or a (count)=>node render-prop (you own the whole bar).",
+      "DO reach for the grid chrome (DataTable.Search, DataTable.ViewOptions, DataTable.Pagination pageSizeOptions) when you need global search, a column 'set view' picker, or numbered pagination \u2014 these are the merged former-DataGrid features, now on the one DataTable. Drive them client-side by default; pass the matching state + manual* flag for a server query.",
       "DO use ColumnDef.render for custom cell content (Badge, Link, RowActions). For plain string/number fields render can be omitted \u2014 DataTable falls back to String(row[key]).",
       "DO NOT nest DataTable.Content in a conditional \u2014 it is already guarded internally. If you need to override the table body slot, drop exactly one <DataTable.Content /> in children; DataTable auto-detects it by displayName and skips the default."
     ],
@@ -1039,7 +1007,8 @@ import { Trash2 } from "lucide-react";
       "Admin list pages (invoices, customers, orders, accounts) where rows are clickable for detail navigation via onRowClick.",
       "Bulk-action workflows (e.g. mark invoices paid, export selected rows) \u2014 use selectable + DataTable.BulkActions to show contextual action buttons only when something is selected.",
       "Server-side sorted tables: pass sort + onSortChange and update the data prop after the API call; DataTable renders asc/desc/neutral icons on the header automatically.",
-      "Cursor-paginated lists: add DataTable.Pagination with cursor + hasMore + onChange inside children to get First/Next navigation without offset arithmetic.",
+      "Cursor-paginated lists: add DataTable.Pagination with cursor + hasMore + onChange inside children to get First/Next navigation without offset arithmetic. For page-size + numbered prev/next instead, use DataTable.Pagination with pageSizeOptions (no cursor/onChange) driven by the internal TanStack pagination.",
+      "Full grid screens (global search + column 'set view' + numbered pagination): compose DataTable.Search, DataTable.ViewOptions, DataTable.DensityToggle in the toolbar and DataTable.Pagination pageSizeOptions={[\u2026]} \u2014 client-side by default, or server-side by passing globalFilter/pagination/sort state with the matching manual* flag.",
       "Responsive admin tables where lower-priority columns (e.g. internal IDs, dates) should collapse below mobile breakpoints \u2014 set hiddenOnMobile: true on those ColumnDef entries.",
       "Loading skeletons during initial page load or filter change: set loading={true} alongside an empty data={[]} to show the loading row without flashing an empty state."
     ],
@@ -1062,10 +1031,10 @@ type Invoice = {
 };
 
 const columns: ColumnDef<Invoice>[] = [
-  { value: "id", header: "Invoice #", width: "w-32" },
-  { value: "customer", header: "Customer" },
+  { key: "id", header: "Invoice #", width: "w-32" },
+  { key: "customer", header: "Customer" },
   {
-    value: "status",
+    key: "status",
     header: "Status",
     render: (row) => (
       <Badge
@@ -1077,7 +1046,7 @@ const columns: ColumnDef<Invoice>[] = [
       </Badge>
     ),
   },
-  { value: "amount", header: "Amount", align: "right", sortable: true },
+  { key: "amount", header: "Amount", align: "right", sortable: true },
 ];
 
 export default function InvoiceList({
@@ -1088,7 +1057,7 @@ export default function InvoiceList({
   loading: boolean;
 }) {
   const [selected, setSelected] = useState<Set<string>>(new Set());
-  const [sort, setSort] = useState<{ value: string; direction: "asc" | "desc" } | undefined>();
+  const [sort, setSort] = useState<{ key: string; direction: "asc" | "desc" } | undefined>();
 
   return (
     <DataTable
@@ -1122,106 +1091,6 @@ export default function InvoiceList({
     storyPath: "data-display/DataTable.stories.tsx",
     rules: [24, 31, 35, 37]
   },
-  {
-    name: "DataGrid",
-    group: "data-display",
-    tagline: "Full-feature data grid \u2014 the TanStack Table adapter on `@godxjp/ui/data-grid` (NOT the data-display barrel). Adds column sort, global search, column visibility ('set view'), per-page + numbered pagination, row selection + bulk actions, and density over the styled Table* primitives. Defaults to SERVER/manual mode: wire sorting/columnFilters/globalFilter/pagination to your AJAX query (pass rowCount). Use DataTable instead for a lean server-driven list that must NOT pull TanStack. Requires the `@tanstack/react-table` peer dependency.",
-    props: [
-      {
-        name: "columns",
-        type: "ColumnDef<T, unknown>[]",
-        required: true,
-        description: "TanStack column definitions ({ accessorKey, header, cell, enableSorting, enableHiding, meta:{label} }). Set enableHiding:false to keep a column out of the ViewOptions menu; meta.label gives a human label there when header is JSX."
-      },
-      {
-        name: "data",
-        type: "T[]",
-        required: true,
-        description: "Row data. Empty + loading=false renders a built-in EmptyState in the body."
-      },
-      {
-        name: "getRowId",
-        type: "(row: T) => string",
-        description: "Stable row id (defaults to row[rowIdKey], rowIdKey defaults to 'id')."
-      },
-      {
-        name: "enableRowSelection",
-        type: "boolean",
-        defaultValue: "false",
-        description: "Adds a checkbox column + header select-all; pair with DataGrid.BulkActions."
-      },
-      {
-        name: "sorting / onSortingChange",
-        type: "SortingState / OnChangeFn<SortingState>",
-        description: "Server sort: pass both and sort in your query (manualSorting defaults true). Omit both for client sort."
-      },
-      {
-        name: "globalFilter / onGlobalFilterChange",
-        type: "string / OnChangeFn<string>",
-        description: "Global search term, surfaced by DataGrid.Search. Server or client like sorting."
-      },
-      {
-        name: "pagination / onPaginationChange / rowCount",
-        type: "PaginationState / OnChangeFn / number",
-        description: "Server pagination: pass pagination + onPaginationChange + rowCount (total). Omit for client pagination."
-      },
-      {
-        name: "columnVisibility / onColumnVisibilityChange",
-        type: "VisibilityState / OnChangeFn<VisibilityState>",
-        description: "Column show/hide state surfaced by DataGrid.ViewOptions ('set view'). Internal if omitted."
-      },
-      {
-        name: "manualSorting / manualFiltering / manualPagination",
-        type: "boolean",
-        defaultValue: "true",
-        description: "Default true (server/AJAX). Set false to let TanStack sort/filter/paginate in-browser."
-      },
-      {
-        name: "loading / density / onRowClick / empty",
-        type: "boolean / 'compact'|'comfortable' / (row:T)=>void / ReactNode",
-        description: "Loading row, controlled density, clickable rows, custom empty content."
-      }
-    ],
-    usage: [
-      "Import from `@godxjp/ui/data-grid` \u2014 it lives on its own subpath because it pulls @tanstack/react-table; it is NOT in the runtime-neutral root or the data-display barrel.",
-      "Compose the compound parts as children: <DataGrid.Toolbar> (holds <DataGrid.BulkActions>, <DataGrid.Search>, <DataGrid.ViewOptions>, <DataGrid.DensityToggle>), then <DataGrid.Content> (auto-included if omitted) and <DataGrid.Pagination pageSizeOptions=[...]>.",
-      "Server mode (default): drive sorting/globalFilter/pagination from useQuery and pass rowCount. Client mode: set manualSorting/manualFiltering/manualPagination={false} and the grid handles it on the data array."
-    ],
-    useCases: [
-      "Server-paginated \u4ED5\u8A33 (journal entry) or \u8ACB\u6C42 (invoice) admin list backed by an AJAX/useQuery endpoint: drive sorting + globalFilter + pagination from the query and pass rowCount \u2014 the grid never loads the whole table into the browser. (Prefer DataTable here if the screen must NOT pull @tanstack/react-table.)",
-      "Member / employee directory with a user-toggled 'set view' column picker (DataGrid.ViewOptions) \u2014 let admins hide columns like \u5165\u793E\u65E5 or \u90E8\u7F72 they don't need, persisting the columnVisibility state per user.",
-      "Bulk-operation worklist (e.g. approve/export selected \u7D4C\u8CBB\u7CBE\u7B97 rows): enableRowSelection + DataGrid.BulkActions to show a 'N\u4EF6\u9078\u629E\u4E2D' action bar with \u4E00\u62EC\u627F\u8A8D / CSV\u51FA\u529B buttons only when rows are checked.",
-      "Dense reconciliation or ledger table where operators flip between compact and comfortable row height via DataGrid.DensityToggle to fit more rows on screen during data-entry-heavy sessions.",
-      "Client-side grid for a fully-loaded small dataset (e.g. a fixed master list of \u52D8\u5B9A\u79D1\u76EE): set manualSorting/manualFiltering/manualPagination={false} so TanStack sorts, searches, and paginates in-browser without any server round-trip."
-    ],
-    related: ["DataTable", "Table", "DataState", "Select", "DropdownMenu"],
-    example: `import { DataGrid, type ColumnDef } from "@godxjp/ui/data-grid";
-import { Flex } from "@godxjp/ui/layout";
-
-type Row = { id: string; name: string; amount: number };
-const columns: ColumnDef<Row, unknown>[] = [
-  { accessorKey: "name", header: "Name", meta: { label: "Name" } },
-  { accessorKey: "amount", header: "Amount", meta: { label: "Amount" } },
-];
-
-export function Grid({ rows }: { rows: Row[] }) {
-  return (
-    <DataGrid columns={columns} data={rows} getRowId={(r) => r.id} enableRowSelection manualSorting={false} manualFiltering={false} manualPagination={false}>
-      <DataGrid.Toolbar>
-        <Flex direction="row" align="center" gap="sm" className="ms-auto">
-          <DataGrid.Search />
-          <DataGrid.ViewOptions />
-          <DataGrid.DensityToggle />
-        </Flex>
-      </DataGrid.Toolbar>
-      <DataGrid.Content />
-      <DataGrid.Pagination pageSizeOptions={[10, 20, 50]} />
-    </DataGrid>
-  );
-}`,
-    storyPath: "data-display/DataGrid.stories.tsx",
-    rules: [24, 31, 35, 37]
-  },
   {
     name: "Card",
     group: "data-display",
@@ -1256,7 +1125,8 @@ export function Grid({ rows }: { rows: Row[] }) {
       "DO use <CardContent flush> for edge-to-edge children such as DataTable, Table, or a Tabs list \u2014 this removes horizontal padding. Combine with <CardContent tight> when there is no visual gap needed after the header, and <CardContent solo> when there is no CardHeader above (top padding matches the card shell).",
       "DO use <CardFooter separated> to render a top-bordered action band (Save/Cancel buttons, table summary row). Use <CardFooter flush> for a full-bleed footer bar.",
       "DO use <CardCover> as the first child for full-bleed cover media \u2014 the header below it uses card-section top spacing, not the card shell.",
-      "DON'T hand-roll a stat/KPI tile with <Card> + raw divs \u2014 use <StatCard> (label, value, hint, delta, layout, inverse props) which is already a Card internally with correct token-driven layout."
+      "DON'T hand-roll a stat/KPI tile with <Card> + raw divs \u2014 use <StatCard> (label, value, hint, delta, layout, inverse props) which is already a Card internally with correct token-driven layout.",
+      "SPACING IS BORDER-AWARE & token-driven (theme via src/tokens/components/card.css, never hard-code padding on slots): `--card-space-inset` is the shared horizontal column every slot (header/content/footer) aligns to. A DIVIDED section \u2014 a `banded` header or a `separated` footer, i.e. one carrying a divider border \u2014 pads SYMMETRICALLY top+bottom from `--card-space-divided-y` (a band reads as its own region). A PLAIN header flows into the body instead: top `--card-space-inset`, no bottom, and the body supplies the gap via `--card-space-body-y`. Special case: a header above `<CardContent flush>` with a <Table> gets its own `--card-space-body-y` bottom gap (the flush table zeroes its top), so the title never butts the table. `--card-space-gap` is the in-slot stack gap (title\u2195description). Tune the band rhythm once at `--card-space-divided-y`; tune the accent stripe width at `--card-accent-rail-width` (default 6px)."
     ],
     useCases: [
       'Dashboard KPI summary row: wrap each metric in <StatCard> (or a plain <Card size="compact"> with <CardContent>) to render a uniform grid of labeled value tiles with optional trend deltas.',
@@ -1347,6 +1217,11 @@ export function Grid({ rows }: { rows: Row[] }) {
         description: "Metric value (string/number/ReactNode)."
       },
       { name: "hint", type: "ReactNode", description: "Secondary context below the value." },
+      {
+        name: "icon",
+        type: "LucideIcon",
+        description: "Optional leading icon rendered as a tinted medallion above the metric. Decorative (aria-hidden) \u2014 the label carries the meaning. Tint via the --stat-card-icon-{background,foreground} tokens (default a soft brand-primary wash)."
+      },
       {
         name: "delta",
         type: "ReactNode",
@@ -1565,6 +1440,12 @@ import { Smartphone } from "lucide-react";
         defaultValue: "2",
         description: "Column count; collapses to 1 on mobile."
       },
+      {
+        name: "layout",
+        type: '"vertical" | "horizontal"',
+        defaultValue: '"vertical"',
+        description: "Label placement within each item \u2014 `vertical` stacks the label over the value (default); `horizontal` puts the label BESIDE the value in a token-aligned column (mirrors `<Form layout>`). Tune the horizontal label-column width via `--descriptions-label-width`."
+      },
       {
         name: "children",
         type: "ReactNode",
@@ -2092,6 +1973,11 @@ import { Smartphone } from "lucide-react";
         name: "onClear",
         type: "() => void",
         description: "Called after the field is cleared via the inline \u2715 (requires `allowClear`)."
+      },
+      {
+        name: "trailingIcon",
+        type: "React.ReactNode",
+        description: "A trailing affordance pinned inside the field (e.g. a calendar / clock popover trigger). ONE trailing icon shows at a time: when `allowClear` and the field holds a value the clear \u2715 REPLACES this icon; otherwise this icon shows. Never both \u2014 this is how DatePicker/TimePicker render their open trigger."
       }
     ],
     usage: [
@@ -2218,7 +2104,7 @@ import { Smartphone } from "lucide-react";
       "Input \u2014 the plain single-line field NumberInput composes; use Input directly only for free numeric text with no stepper/clamp need.",
       "Slider \u2014 use instead when the user picks an approximate value within a range by dragging; NumberInput is for exact keyed entry.",
       "FormField \u2014 compose NumberInput inside FormField (matching id) for label/helper/error a11y wiring.",
-      "TimeInput \u2014 the HH:mm sibling spinbutton; NumberInput is for plain numbers, TimeInput for clock times."
+      "TimePicker \u2014 the HH:mm time sibling; NumberInput is for plain numbers, TimePicker for clock times."
     ],
     storyPath: "data-entry/NumberInput.stories.tsx",
     rules: [3, 6],
@@ -6857,7 +6743,7 @@ export default function PasswordBlock() {
       "DON'T hand-roll a positioned `<div>` + `onContextMenu={e => e.preventDefault()}` \u2014 the primitive already gives you keyboard navigation, focus trapping, typeahead, and WAI-ARIA menu semantics for free."
     ],
     useCases: [
-      "Right-click actions on a DataTable/DataGrid row (\u8A73\u7D30 / \u8907\u88FD / \u524A\u9664) as a power-user accelerator alongside the visible row action button.",
+      "Right-click actions on a DataTable row (\u8A73\u7D30 / \u8907\u88FD / \u524A\u9664) as a power-user accelerator alongside the visible row action button.",
       "Contextual menu on a file or document tile in an upload/asset manager (\u30C0\u30A6\u30F3\u30ED\u30FC\u30C9 / \u540D\u524D\u5909\u66F4 / \u524A\u9664).",
       "Nested action menu with submenus and shortcuts (e.g. '\u30A8\u30AF\u30B9\u30DD\u30FC\u30C8 \u25B8 CSV / PDF') on a report card.",
       "Stateful toggles on a board/kanban card via ContextMenuCheckboxItem (e.g. \u30D4\u30F3\u7559\u3081, \u5B8C\u4E86\u3068\u3057\u3066\u30DE\u30FC\u30AF)."
@@ -7002,15 +6888,19 @@ export default function PasswordBlock() {
       },
       {
         name: "defaultSize",
-        type: "number",
-        description: "ResizablePanel initial size as a percentage (0\u2013100) of the group."
+        type: "string | number",
+        description: 'ResizablePanel initial size. react-resizable-panels v4: a STRING is a unit ("35%", "20rem", "240px"); a bare NUMBER is PIXELS. For a percentage of the group pass a string like "35%" \u2014 `defaultSize={35}` means 35px (a sliver), not 35%.'
       },
       {
         name: "minSize",
-        type: "number",
-        description: "ResizablePanel minimum size (%) \u2014 drag can't shrink below this."
+        type: "string | number",
+        description: `ResizablePanel minimum size \u2014 drag can't shrink below this. Same unit rule: "20%" for percent, bare number = px.`
+      },
+      {
+        name: "maxSize",
+        type: "string | number",
+        description: 'ResizablePanel maximum size. "60%" for percent, bare number = px.'
       },
-      { name: "maxSize", type: "number", description: "ResizablePanel maximum size (%)." },
       {
         name: "collapsible",
         type: "boolean",
@@ -7025,7 +6915,7 @@ export default function PasswordBlock() {
     ],
     usage: [
       'DO put the layout on `<ResizablePanelGroup orientation="horizontal|vertical">`, the resizable regions in `<ResizablePanel>`, and a `<ResizableHandle>` BETWEEN every adjacent pair \u2014 a group of N panels needs N-1 handles or there is nothing to drag.',
-      "DO size panels with `defaultSize`/`minSize`/`maxSize` as PERCENTAGES (the group totals 100), not pixels \u2014 don't fight this with a fixed `w-[280px]` className on the panel.",
+      'DO express `defaultSize`/`minSize`/`maxSize` as PERCENTAGE STRINGS like `defaultSize="35%"` (react-resizable-panels v4: a bare number is PIXELS, so `defaultSize={35}` renders a 35px sliver, NOT 35% \u2014 pass the string). Don\'t fight sizing with a fixed `w-[280px]` className on the panel.',
       "DON'T reach for ResizablePanel when the split is fixed and never user-adjustable \u2014 use a plain `Flex`/`ResponsiveGrid`, or `SplitPane` for a simple two-pane layout. Resizable is for *user-draggable* boundaries only.",
       "DO give each panel a stable `id` and use `collapsible` + `collapsedSize` for a side panel the user can fully tuck away (e.g. a filters rail), reacting via `onResize`.",
       "DON'T hand-roll a draggable divider with mouse-move listeners \u2014 the primitive handles pointer + keyboard resizing, ARIA separator semantics, and min/max clamping. Always render `<ResizableHandle>`, never a bare styled `<div>`."
@@ -7040,10 +6930,10 @@ export default function PasswordBlock() {
     rules: [3, 6],
     example: `import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from "@godxjp/ui/layout";
 
-<ResizablePanelGroup>
-  <ResizablePanel>Panel A</ResizablePanel>
+<ResizablePanelGroup orientation="horizontal">
+  <ResizablePanel id="list" defaultSize="35%" minSize="20%">Panel A</ResizablePanel>
   <ResizableHandle />
-  <ResizablePanel>Panel B</ResizablePanel>
+  <ResizablePanel id="detail" defaultSize="65%" minSize="40%">Panel B</ResizablePanel>
 </ResizablePanelGroup>`
   },
   {
@@ -7095,50 +6985,6 @@ export default function PasswordBlock() {
   <CarouselNext />
   <CarouselDots />
 </Carousel>`
-  },
-  {
-    name: "TimeInput",
-    group: "data-entry",
-    tagline: "Masking HH:mm input with validation and optional minute step quantization.",
-    props: [
-      { name: "value", type: "string", description: "Controlled HH:mm value." },
-      {
-        name: "defaultValue",
-        type: "string",
-        description: "Uncontrolled initial HH:mm value."
-      },
-      {
-        name: "onValueChange",
-        type: "(value: string) => void",
-        description: "Validated value callback."
-      },
-      {
-        name: "step",
-        type: "number",
-        defaultValue: "1",
-        description: "Minute step (clamped 1\u201359). Snaps the committed minute to the nearest lower multiple and sets the ArrowUp/ArrowDown increment."
-      },
-      { name: "name", type: "string", description: "Form field name." }
-    ],
-    usage: [
-      "DO treat the value as a plain `HH:mm` string (24-hour, zero-padded) \u2014 TimeInput is calendar-free. For a date, or a date+time, use `DatePicker`/`Calendar`; for a richer dropdown time selector use `TimePicker`.",
-      "DO drive it controlled with `value` + `onValueChange` (it follows the vocabulary \u2014 NOT `onChange`/`defaultValue` pairing for control). `onValueChange` fires only with a VALID, step-snapped `HH:mm`, so your state never holds a half-typed value.",
-      "DON'T pass `value` without `onValueChange` \u2014 like every controlled @godxjp/ui input that freezes the field. Omit both for uncontrolled (use `defaultValue`).",
-      "DO set `step` to your scheduling granularity (e.g. `15` or `30`) \u2014 the user can still type freely, but blur/Enter snaps the minute down to the nearest multiple, and ArrowUp/ArrowDown step by that amount (wrapping across midnight).",
-      "DO let the built-in masking + validation work: digits auto-format to `HH:mm`, invalid input sets `aria-invalid` and is reverted on blur. Don't add your own regex/onChange masking on top.",
-      "DON'T use it for a duration/elapsed time that can exceed 23:59 \u2014 it's a clock time-of-day input (00:00\u201323:59). Use a numeric Input for durations."
-    ],
-    useCases: [
-      "\u52E4\u6020 (attendance) start/end time fields \u2014 \u51FA\u52E4 / \u9000\u52E4 HH:mm entry with step={1} or a rounding step for shift schedules.",
-      "Business-hours / reservation slot editor where times snap to a 15- or 30-minute grid (step={15}).",
-      "A from\u2013to time range filter on a report or log screen (two TimeInputs) with no date component.",
-      "Any calendar-free HH:mm-only form field (e.g. a recurring daily batch time, a \u7DE0\u3081\u6642\u523B)."
-    ],
-    storyPath: "data-entry/TimeInput.stories.tsx",
-    rules: [3, 6],
-    example: `import { TimeInput } from "@godxjp/ui/data-entry";
-
-<TimeInput value="09:00" step={15} onValueChange={(time) => console.log(time)} />`
   },
   {
     name: "AppSettingPicker",
@@ -7795,6 +7641,36 @@ var TOKENS = [
     tier: "primitive",
     role: "Distance (10px) a revealed element travels on enter (translateY/-X). Read instead of a literal `translateY(10px)` for staggered reveals."
   },
+  {
+    name: "--shadow-color",
+    category: "primitive",
+    tier: "primitive",
+    role: "RGB channels (space-separated, e.g. `12 26 49`) that tint the WHOLE elevation ramp (--shadow-xs..2xl) at once. Default `0 0 0`. Single-brand :root only \u2014 a scoped override does not re-resolve the ramp (the steps compute at :root); for a scoped/multi-tenant card lift set --card-shadow to a literal value."
+  },
+  {
+    name: "--shadow-glow",
+    category: "primitive",
+    tier: "primitive",
+    role: "Opt-in brand GLOW halo layered on the primary CTA's resting shadow. Default invisible (`0 0 0 0 transparent`, valid inside a comma shadow list). A service sets the whole value, e.g. `--shadow-glow: 0 8px 20px hsl(var(--primary) / .32)` \u2014 works scoped under [data-tenant] because the service declares it inside the scope."
+  },
+  {
+    name: "--focus-ring-color",
+    category: "primitive",
+    tier: "primitive",
+    role: "Themeable hue of EVERY keyboard-focus ring (HSL components, default var(--ring)). A leaf token, so it re-resolves at the element that paints the ring \u2014 override it once, even scoped under [data-tenant], to retint all focus rings. Pair with --focus-ring-width."
+  },
+  {
+    name: "--focus-ring-width",
+    category: "primitive",
+    tier: "primitive",
+    role: "Thickness (2px) of the solid keyboard-focus ring. Leaf token \u2014 :focus-visible rules read it directly as `0 0 0 var(--focus-ring-width) hsl(var(--focus-ring-color))`, never via an intermediate composite (which would freeze at :root). Propagates scoped."
+  },
+  {
+    name: "--gradient-{brand,hero,glow}",
+    category: "primitive",
+    tier: "primitive",
+    role: "Opt-in decorative gradient fills, default `none`. --gradient-hero paints the PageContainer header (hero banner); --gradient-glow paints the AppShell .app-main (ambient brand wash); --gradient-brand is a spare. A service sets the full gradient, e.g. `--gradient-glow: radial-gradient(60% 80% at 50% 0%, hsl(var(--primary) / .25), transparent)`."
+  },
   { name: "--primary", category: "semantic", tier: "semantic", role: "Brand/action color role." },
   { name: "--success", category: "semantic", tier: "semantic", role: "Success status role." },
   { name: "--warning", category: "semantic", tier: "semantic", role: "Warning status role." },
@@ -7812,6 +7688,12 @@ var TOKENS = [
     tier: "semantic",
     role: "PageContainer header bottom divider. Default none; a service theme opts in with `1px solid hsl(var(--border))`."
   },
+  {
+    name: "--overlay-background",
+    category: "semantic",
+    tier: "semantic",
+    role: "Modal scrim \u2014 the single backdrop colour shared by every overlay (Dialog, AlertDialog, Sheet, Drawer). Default `rgb(0 0 0 / 0.5)`. A service tints it once, e.g. a navy `rgb(12 26 49 / .55)`. NOTE: portaled overlays render outside a [data-tenant] subtree, so for multi-tenant scoping put the tenant attribute on the portal container too."
+  },
   {
     name: "--page-header-pad-bottom",
     category: "semantic",
@@ -7880,72 +7762,77 @@ var COMPONENT_TOKENS = [
   {
     "name": "--card-space-inset",
     "value": "var(--space-section-active)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Horizontal inset of every slot (header / content / footer) + the resting top/bottom * shell padding. This is the column the title, body and footer all align to."
   },
   {
     "name": "--card-space-header-y",
     "value": "var(--space-stack-sm)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical padding of a BANDED header band (top = bottom). Drives --card-space-divided-y."
   },
   {
     "name": "--card-space-body-y",
     "value": "var(--space-section-active)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Gap between the header and the body, and the body's own top padding \u2014 the breathing * room under a title before content begins."
   },
   {
     "name": "--card-space-footer-y",
     "value": "var(--space-stack-sm)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical padding of a SEPARATED footer band (top = bottom). Drives --card-space-divided-y."
+  },
+  {
+    "name": "--card-space-divided-y",
+    "value": "var(--card-space-header-y)",
+    "description": "DIVIDED-section vertical padding (rule #44/#45). A header/footer that carries a divider * border (banded header, separated footer) reads as its own band, so it pads SYMMETRICALLY * top+bottom \u2014 distinct from a plain header that flows into the body (top inset, no bottom). * One themeable knob keeps the header- and footer-band rhythm in sync; a service theme tunes * the band density here instead of forking per-slot CSS."
   },
   {
     "name": "--card-space-gap",
     "value": "var(--space-stack-xs)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical gap between stacked items WITHIN a slot (e.g. title \u2195 description in the header)."
   },
   {
     "name": "--card-title-font-size",
     "value": "var(--font-size-base)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical gap between stacked items WITHIN a slot (e.g. title \u2195 description in the header)."
   },
   {
     "name": "--card-title-line-height",
     "value": "var(--line-height-tight)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical gap between stacked items WITHIN a slot (e.g. title \u2195 description in the header)."
   },
   {
     "name": "--card-title-font-weight",
     "value": "var(--font-weight-semibold)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical gap between stacked items WITHIN a slot (e.g. title \u2195 description in the header)."
   },
   {
     "name": "--card-description-font-size",
     "value": "var(--font-size-sm)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical gap between stacked items WITHIN a slot (e.g. title \u2195 description in the header)."
   },
   {
     "name": "--card-description-line-height",
     "value": "var(--line-height-normal)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical gap between stacked items WITHIN a slot (e.g. title \u2195 description in the header)."
   },
   {
     "name": "--card-background",
     "value": "var(--card)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical gap between stacked items WITHIN a slot (e.g. title \u2195 description in the header)."
   },
   {
     "name": "--card-border",
     "value": "var(--border)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Vertical gap between stacked items WITHIN a slot (e.g. title \u2195 description in the header)."
   },
   {
     "name": "--card-header-background",
     "value": "var(--muted)",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Banded-header fill \u2014 already role-tintable (rule #45): a service points this at any role, * e.g. --card-header-background: var(--primary), and tunes --card-header-background-alpha for * the wash strength. No separate tint token needed."
   },
   {
     "name": "--card-header-background-alpha",
     "value": "0.55",
-    "description": "Card component tokens: card chrome derives from semantic layout tokens."
+    "description": "Banded-header fill \u2014 already role-tintable (rule #45): a service points this at any role, * e.g. --card-header-background: var(--primary), and tunes --card-header-background-alpha for * the wash strength. No separate tint token needed."
   },
   {
     "name": "--card-header-border-bottom",
@@ -7957,6 +7844,21 @@ var COMPONENT_TOKENS = [
     "value": "var(--radius)",
     "description": "Banded-header divider \u2014 tokenised (rule #44) so a service theme can make it * dashed / heavier / none without forking CSS. Pair with * --card-header-background-alpha: 0 for a quiet borderless-band header."
   },
+  {
+    "name": "--card-shadow",
+    "value": "0 0 0 0 transparent",
+    "description": "Resting elevation \u2014 quiet by default (rule #44): cards are flat (1px border, no shadow) in the * dxs-kintai baseline. A service that wants lifted cards sets this to an elevation token once, * e.g. --card-shadow: var(--shadow-sm), and every Card picks up the shadow with no markup change."
+  },
+  {
+    "name": "--card-glow",
+    "value": "0 0 0 0 transparent",
+    "description": "Brand glow layer \u2014 invisible no-op at rest (rule #44). Paired AFTER --card-shadow in the * surface box-shadow so a service can wash every card with the global glow, e.g. * --card-glow: var(--shadow-glow), with no markup change."
+  },
+  {
+    "name": "--card-tint",
+    "value": "transparent",
+    "description": "Fill tint \u2014 subtle role wash over the card background (default transparent = invisible). * Painted as an overlay so a service sets --card-tint: hsl(var(--primary) / 0.04) once."
+  },
   {
     "name": "--card-accent-rail-width",
     "value": "6px",
@@ -8007,10 +7909,30 @@ var COMPONENT_TOKENS = [
     "value": "2.25rem",
     "description": "Accent edge \u2014 width of the semantic leading-edge stripe (data-accent). * Tokenised (rule #44) so a service theme can re-tune it without forking CSS. * The slot padding compensation in card-layout.css subtracts the same token, * so content stays aligned on the shell whatever the rail width."
   },
+  {
+    "name": "--stat-card-icon-glyph-size",
+    "value": "1.25rem",
+    "description": "Accent edge \u2014 width of the semantic leading-edge stripe (data-accent). * Tokenised (rule #44) so a service theme can re-tune it without forking CSS. * The slot padding compensation in card-layout.css subtracts the same token, * so content stays aligned on the shell whatever the rail width."
+  },
+  {
+    "name": "--stat-card-icon-radius",
+    "value": "var(--radius-md)",
+    "description": "Accent edge \u2014 width of the semantic leading-edge stripe (data-accent). * Tokenised (rule #44) so a service theme can re-tune it without forking CSS. * The slot padding compensation in card-layout.css subtracts the same token, * so content stays aligned on the shell whatever the rail width."
+  },
+  {
+    "name": "--stat-card-icon-background",
+    "value": "hsl(var(--primary) / 0.1)",
+    "description": "Medallion tint \u2014 soft brand wash + brand glyph by default; a service retints by overriding * --primary or these tokens directly (rule #44/#45)."
+  },
+  {
+    "name": "--stat-card-icon-foreground",
+    "value": "hsl(var(--primary))",
+    "description": "Medallion tint \u2014 soft brand wash + brand glyph by default; a service retints by overriding * --primary or these tokens directly (rule #44/#45)."
+  },
   {
     "name": "--stat-card-delta-font-size",
     "value": "var(--font-size-xs)",
-    "description": "Accent edge \u2014 width of the semantic leading-edge stripe (data-accent). * Tokenised (rule #44) so a service theme can re-tune it without forking CSS. * The slot padding compensation in card-layout.css subtracts the same token, * so content stays aligned on the shell whatever the rail width."
+    "description": "Medallion tint \u2014 soft brand wash + brand glyph by default; a service retints by overriding * --primary or these tokens directly (rule #44/#45)."
   },
   {
     "name": "--control-height-compact",
@@ -8094,7 +8016,7 @@ var COMPONENT_TOKENS = [
   },
   {
     "name": "--control-focus-ring-width",
-    "value": "2px",
+    "value": "var(--focus-ring-width)",
     "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
   },
   {
@@ -8207,85 +8129,110 @@ var COMPONENT_TOKENS = [
     "value": "1rem",
     "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
   },
+  {
+    "name": "--checkbox-checked-background",
+    "value": "hsl(var(--primary))",
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
+  },
+  {
+    "name": "--switch-checked-background",
+    "value": "hsl(var(--primary))",
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
+  },
+  {
+    "name": "--toggle-on-background",
+    "value": "hsl(var(--primary))",
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
+  },
+  {
+    "name": "--slider-track-background",
+    "value": "hsl(var(--primary) / 0.2)",
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
+  },
+  {
+    "name": "--slider-range-background",
+    "value": "hsl(var(--primary))",
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
+  },
   {
     "name": "--color-picker-input-width",
     "value": "6.5rem",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--command-list-max-height",
     "value": "min(300px, 50vh)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--command-input-padding-x",
     "value": "var(--space-3)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--command-group-padding",
     "value": "var(--space-1)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--command-item-padding-y",
     "value": "var(--space-2)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--command-item-padding-x",
     "value": "var(--space-2)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--search-input-edge-inset",
     "value": "var(--space-3)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--search-input-start-padding",
     "value": "calc( var(--search-input-edge-inset) + var(--control-icon-size) + var(--control-gap) )",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--search-input-end-padding",
     "value": "calc( var(--search-input-edge-inset) + var(--control-icon-size) + var(--control-gap) )",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--choice-description-font-size",
     "value": "var(--font-size-xs)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--color-picker-hex-font-size",
     "value": "var(--font-size-xs)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--command-group-heading-font-size",
     "value": "var(--font-size-xs)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--search-input-label-font-size",
     "value": "var(--font-size-xs)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--tag-input-chip-font-size",
     "value": "var(--font-size-xs)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--toggle-sm-font-size",
     "value": "var(--font-size-xs)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--button-sm-font-size",
     "value": "var(--font-size-xs)",
-    "description": "Adjacent control sizes, derived from the active --control-height. The \xB1step * is scaled too so the whole control ladder stays proportional under --scaling."
+    "description": 'Checked/on/active fills \u2014 themeable role expression, defaults equal the current literal * (quiet: no visual change). A service retints the "selected" state by overriding these.'
   },
   {
     "name": "--control-height-compact",
@@ -8317,6 +8264,51 @@ var COMPONENT_TOKENS = [
     "value": "var(--font-size-xs)",
     "description": "Data-display component tokens \u2014 small-by-design text knobs (rule #45/#46)."
   },
+  {
+    "name": "--avatar-background",
+    "value": "hsl(var(--muted))",
+    "description": "Avatar surface \u2014 reads the muted role by default. A service can re-tint the placeholder fill once (e.g. --avatar-background: hsl(var(--accent)))."
+  },
+  {
+    "name": "--avatar-tint",
+    "value": "transparent",
+    "description": "Optional role wash over the avatar (default transparent = invisible, rule #44). Painted as an overlay so a service sets --avatar-tint: hsl(var(--primary) / 0.08)."
+  },
+  {
+    "name": "--progress-track-background",
+    "value": "hsl(var(--secondary))",
+    "description": "Progress track + fill \u2014 quiet defaults equal the current literals (rule #44). Track reads secondary, fill reads success; a service re-tones once."
+  },
+  {
+    "name": "--progress-fill-background",
+    "value": "hsl(var(--success))",
+    "description": "Progress track + fill \u2014 quiet defaults equal the current literals (rule #44). Track reads secondary, fill reads success; a service re-tones once."
+  },
+  {
+    "name": "--timeline-dot-done-background",
+    "value": "hsl(var(--success))",
+    "description": "Timeline accents \u2014 dot/line roles, defaults unchanged (rule #44)."
+  },
+  {
+    "name": "--timeline-dot-current-background",
+    "value": "hsl(var(--primary))",
+    "description": "Timeline accents \u2014 dot/line roles, defaults unchanged (rule #44)."
+  },
+  {
+    "name": "--timeline-line-completed-background",
+    "value": "hsl(var(--primary))",
+    "description": "Timeline accents \u2014 dot/line roles, defaults unchanged (rule #44)."
+  },
+  {
+    "name": "--tree-item-active-border",
+    "value": "hsl(var(--primary) / 0.3)",
+    "description": "Tree active item \u2014 border + soft bg tint over the primary role. Defaults equal the current literals (rule #44)."
+  },
+  {
+    "name": "--tree-item-active-background",
+    "value": "hsl(var(--primary) / 0.05)",
+    "description": "Tree active item \u2014 border + soft bg tint over the primary role. Defaults equal the current literals (rule #44)."
+  },
   {
     "name": "--password-strength-score-font-size",
     "value": "var(--font-size-xs)",
@@ -8327,6 +8319,11 @@ var COMPONENT_TOKENS = [
     "value": "var(--font-size-xs)",
     "description": "Data-entry component tokens \u2014 small-by-design text knobs (rule #45/#46)."
   },
+  {
+    "name": "--descriptions-label-width",
+    "value": "8rem",
+    "description": 'Width of the label column when <Descriptions layout="horizontal">. Labels align to this * shared column so the values line up (the horizontal-detail look, mirroring <Form layout>). * A rem value gives a fixed aligned column; set `max-content` to size each label to its text. * (rule #44/#45 \u2014 a service theme tunes it here instead of forking CSS.)'
+  },
   {
     "name": "--dialog-space-x",
     "value": "var(--space-chrome-x)",
@@ -8382,35 +8379,55 @@ var COMPONENT_TOKENS = [
     "value": "0.3",
     "description": "Soft (subtle) semantic tint ratios \u2014 themeable so a service can hit its exact spec * (a brand's success-bg/-border are often more present than the faint 5%/30% default)."
   },
+  {
+    "name": "--dialog-content-glow",
+    "value": "0 0 0 0 transparent",
+    "description": "Brand glow layer for the raised dialog/sheet panel \u2014 invisible no-op at rest (rule #44). * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change."
+  },
   {
     "name": "--empty-state-space-y",
     "value": "var(--space-10)",
-    "description": "Soft (subtle) semantic tint ratios \u2014 themeable so a service can hit its exact spec * (a brand's success-bg/-border are often more present than the faint 5%/30% default)."
+    "description": "Brand glow layer for the raised dialog/sheet panel \u2014 invisible no-op at rest (rule #44). * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change."
   },
   {
     "name": "--empty-state-space-x",
     "value": "var(--space-6)",
-    "description": "Soft (subtle) semantic tint ratios \u2014 themeable so a service can hit its exact spec * (a brand's success-bg/-border are often more present than the faint 5%/30% default)."
+    "description": "Brand glow layer for the raised dialog/sheet panel \u2014 invisible no-op at rest (rule #44). * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change."
+  },
+  {
+    "name": "--empty-state-icon-foreground",
+    "value": "hsl(var(--muted-foreground))",
+    "description": "EmptyState icon medallion colour \u2014 defaults to the current literal (rule #44), so a service can * recolour the glyph (--icon-foreground) or wash the medallion fill (--icon-tint) without forking."
+  },
+  {
+    "name": "--empty-state-icon-tint",
+    "value": "hsl(var(--muted))",
+    "description": "EmptyState icon medallion colour \u2014 defaults to the current literal (rule #44), so a service can * recolour the glyph (--icon-foreground) or wash the medallion fill (--icon-tint) without forking."
   },
   {
     "name": "--skeleton-row-gap",
     "value": "var(--space-stack-sm)",
-    "description": "Soft (subtle) semantic tint ratios \u2014 themeable so a service can hit its exact spec * (a brand's success-bg/-border are often more present than the faint 5%/30% default)."
+    "description": "EmptyState icon medallion colour \u2014 defaults to the current literal (rule #44), so a service can * recolour the glyph (--icon-foreground) or wash the medallion fill (--icon-tint) without forking."
   },
   {
     "name": "--skeleton-cell-gap",
     "value": "var(--space-inline-lg)",
-    "description": "Soft (subtle) semantic tint ratios \u2014 themeable so a service can hit its exact spec * (a brand's success-bg/-border are often more present than the faint 5%/30% default)."
+    "description": "EmptyState icon medallion colour \u2014 defaults to the current literal (rule #44), so a service can * recolour the glyph (--icon-foreground) or wash the medallion fill (--icon-tint) without forking."
   },
   {
     "name": "--skeleton-card-inset",
     "value": "var(--space-section-active)",
-    "description": "Soft (subtle) semantic tint ratios \u2014 themeable so a service can hit its exact spec * (a brand's success-bg/-border are often more present than the faint 5%/30% default)."
+    "description": "EmptyState icon medallion colour \u2014 defaults to the current literal (rule #44), so a service can * recolour the glyph (--icon-foreground) or wash the medallion fill (--icon-tint) without forking."
   },
   {
     "name": "--skeleton-radius",
     "value": "var(--radius)",
-    "description": "Soft (subtle) semantic tint ratios \u2014 themeable so a service can hit its exact spec * (a brand's success-bg/-border are often more present than the faint 5%/30% default)."
+    "description": "EmptyState icon medallion colour \u2014 defaults to the current literal (rule #44), so a service can * recolour the glyph (--icon-foreground) or wash the medallion fill (--icon-tint) without forking."
+  },
+  {
+    "name": "--skeleton-background",
+    "value": "hsl(var(--muted))",
+    "description": "Skeleton placeholder fill \u2014 defaults to the current literal hsl(var(--muted)); themeable so a * service can tint the shimmer to its surface (rule #44) without forking the keyframes."
   },
   {
     "name": "--form-label-width",
@@ -8442,31 +8459,6 @@ var COMPONENT_TOKENS = [
     "value": "1px solid hsl(var(--border))",
     "description": "ListRow component tokens \u2014 a single-line entity row for short lists inside a Card * (sessions / API tokens / linked accounts / passkeys \u2026). Sits in a flush CardContent; * rows separate with a quiet divider (#44 \u2014 chrome defaults to the calm semantic border)."
   },
-  {
-    "name": "--logo-size",
-    "value": "2rem",
-    "description": "Logo (brand mark) component tokens. Box size and corner radius are knobs (#45) so a service can * match its own grid without forking the mark; brand fill follows --primary. The `size` prop picks * the step; a service retunes the steps globally here. (Not a --control-height tier \u2014 the mark is * decorative, not a density-aware interactive control.)"
-  },
-  {
-    "name": "--logo-size-xs",
-    "value": "1.5rem",
-    "description": "md"
-  },
-  {
-    "name": "--logo-size-sm",
-    "value": "1.75rem",
-    "description": "md"
-  },
-  {
-    "name": "--logo-size-lg",
-    "value": "2.5rem",
-    "description": "md"
-  },
-  {
-    "name": "--logo-radius",
-    "value": "var(--radius)",
-    "description": "md"
-  },
   {
     "name": "--pagination-gap",
     "value": "var(--space-inline-sm)",
@@ -8522,6 +8514,16 @@ var COMPONENT_TOKENS = [
     "value": "var(--font-size-xs)",
     "description": "Navigation primitive tokens: pagination, filters, compact pickers."
   },
+  {
+    "name": "--menubar-item-hover-background",
+    "value": "hsl(var(--accent))",
+    "description": "Menu item hover/highlight tint \u2014 reads the accent role; default unchanged."
+  },
+  {
+    "name": "--menubar-item-hover-foreground",
+    "value": "hsl(var(--accent-foreground))",
+    "description": "Menu item hover/highlight tint \u2014 reads the accent role; default unchanged."
+  },
   {
     "name": "--sidebar-section-label-font-size",
     "value": "var(--font-size-2xs)",
@@ -8577,6 +8579,36 @@ var COMPONENT_TOKENS = [
     "value": "var(--font-size-xs)",
     "description": "Shell (sidebar / topbar / kbd) component tokens \u2014 small-by-design text * knobs (rule #45/#46). A service re-tunes chrome text without moving the * global scale."
   },
+  {
+    "name": "--sidebar-gradient",
+    "value": "none",
+    "description": "Brand-chrome gradient hooks \u2014 opt-in, invisible by default. A service paints * the sidebar/topbar surface by setting these to a gradient (no-op = none)."
+  },
+  {
+    "name": "--topbar-gradient",
+    "value": "none",
+    "description": "Brand-chrome gradient hooks \u2014 opt-in, invisible by default. A service paints * the sidebar/topbar surface by setting these to a gradient (no-op = none)."
+  },
+  {
+    "name": "--sidebar-item-active-color",
+    "value": "hsl(var(--primary))",
+    "description": "Sidebar active-item tint/marker \u2014 tokenised from the literal hsl(var(--primary)) * usages; defaults are byte-identical to the prior hard-coded values. A service * can re-tune the active sub-item accent without forking CSS."
+  },
+  {
+    "name": "--sidebar-item-active-tint",
+    "value": "hsl(var(--primary))",
+    "description": "Sidebar active-item tint/marker \u2014 tokenised from the literal hsl(var(--primary)) * usages; defaults are byte-identical to the prior hard-coded values. A service * can re-tune the active sub-item accent without forking CSS."
+  },
+  {
+    "name": "--sidebar-item-active-background",
+    "value": "hsl(var(--accent))",
+    "description": "Main nav-item active row \u2014 defaults are byte-identical to the hover state (accent bg, * foreground text). A service overrides these to brand the selected row (e.g. a gold tint + * gold text on a navy sidebar)."
+  },
+  {
+    "name": "--sidebar-item-active-foreground",
+    "value": "hsl(var(--foreground))",
+    "description": "Main nav-item active row \u2014 defaults are byte-identical to the hover state (accent bg, * foreground text). A service overrides these to brand the selected row (e.g. a gold tint + * gold text on a navy sidebar)."
+  },
   {
     "name": "--table-row-height-compact",
     "value": "1.75rem",
@@ -8612,10 +8644,35 @@ var COMPONENT_TOKENS = [
     "value": "var(--font-size-xs)",
     "description": "Table component tokens: row height, cell padding."
   },
+  {
+    "name": "--table-header-background",
+    "value": "hsl(var(--muted))",
+    "description": "Header band \u2014 its OWN bg + fg tokens (decoupled from --secondary, which == --muted by default so * this is byte-identical). A brand whose --secondary is dark (navy buttons) no longer bleeds a * dark band under the dark header text; it sets both header tokens together to keep contrast."
+  },
+  {
+    "name": "--table-header-foreground",
+    "value": "hsl(var(--muted-foreground))",
+    "description": "Header band \u2014 its OWN bg + fg tokens (decoupled from --secondary, which == --muted by default so * this is byte-identical). A brand whose --secondary is dark (navy buttons) no longer bleeds a * dark band under the dark header text; it sets both header tokens together to keep contrast."
+  },
   {
     "name": "--table-pin-shadow",
     "value": "-6px 0 6px -5px hsl(var(--foreground) / 0.12)",
     "description": "Inline-end shadow that lifts a pinned (sticky) action column off the body it scrolls over."
+  },
+  {
+    "name": "--table-row-striped-background",
+    "value": "hsl(var(--muted) / 0.4)",
+    "description": "Row-state tint washes \u2014 translucent muted over the opaque base. Defaults equal * the prior literals; a service retints by reading another role (e.g. --primary)."
+  },
+  {
+    "name": "--table-row-hover-background",
+    "value": "hsl(var(--muted) / 0.5)",
+    "description": "Row-state tint washes \u2014 translucent muted over the opaque base. Defaults equal * the prior literals; a service retints by reading another role (e.g. --primary)."
+  },
+  {
+    "name": "--table-row-selected-background",
+    "value": "hsl(var(--muted) / 0.3)",
+    "description": "Row-state tint washes \u2014 translucent muted over the opaque base. Defaults equal * the prior literals; a service retints by reading another role (e.g. --primary)."
   }
 ];
 
@@ -12674,7 +12731,7 @@ ${c.example}
 // package.json
 var package_default = {
   name: "@godxjp/ui-mcp",
-  version: "14.0.1",
+  version: "16.5.0",
   description: "Model Context Protocol server for @godxjp/ui \u2014 gives Claude Code / Codex CLI / Cursor / any MCP-aware agent live access to the component catalog, prop vocabulary, design tokens, 45 cardinal rules, copy-paste-ready patterns, 12 design / taste skills synthesised from Leonxlnx/taste-skill, 20+ anti-AI-tell patterns, and a 50-check redesign audit \u2014 token-efficient (list \u2192 drill-down).",
   type: "module",
   main: "./dist/index.js",