@godxjp/ui-mcp 13.17.4 → 14.0.1

package/dist/index.js

@@ -482,164 +482,91 @@ export default function Shell() {
   {
     name: "Topbar",
     group: "layout",
-    tagline: "App-shell top bar with product/project chip switchers, search, notifications, and sidebar toggle \u2014 pass DropdownMenuContent to productMenu/projectMenu to turn any chip into a real dropdown switcher; the project chip is hidden entirely when neither project nor projectSidebar is set.",
+    tagline: "A PURE SLOT bar for the app shell \u2014 positions three clusters (start / center / end) and owns ONLY the bar layout. It bakes NO chrome: no product switcher, no search box, no notification bell, no language picker. The CONSUMER composes those from real primitives and drops them into a slot; whether a control is icon-only / labelled / bordered is that control's own config, never the shell's.",
     props: [
       {
-        name: "product",
-        type: "TopbarProductProp",
-        required: true,
-        description: "The active product identity shown in the left chip. Shape: `{ name: string; color?: string }`. `color` sets the chip icon background (defaults to `hsl(var(--attention))`); the first letter of `name` is used as the icon glyph."
-      },
-      {
-        name: "project",
-        type: "TopbarProjectProp | null",
-        defaultValue: "undefined",
-        description: "Optional active project shown after the product chip as `/ ProjectName`. Shape: `{ name: string }`. When both `project` and `projectMenu` are omitted the project chip is not rendered at all."
-      },
-      {
-        name: "productMenu",
+        name: "start",
         type: "ReactNode",
         defaultValue: "undefined",
-        description: "A `DropdownMenuContent` node. When provided, wraps the product chip in a `DropdownMenu` and renders this content as the dropdown body \u2014 turning the chip into an interactive switcher (e.g. an active-entity picker). When omitted, clicking the chip fires `onProductOpen` instead."
+        description: "Inline-start cluster \u2014 typically the sidebar toggle (a `Button` with a `PanelLeftClose` icon), the brand `Logo`, and primary nav."
       },
       {
-        name: "projectMenu",
+        name: "center",
         type: "ReactNode",
         defaultValue: "undefined",
-        description: "A `DropdownMenuContent` node. When provided, wraps the project chip in a `DropdownMenu`. Also causes the project chip to be rendered even when `project` is null \u2014 useful for a 'Pick project' state with a real dropdown. When omitted, clicking the chip fires `onProjectOpen`."
-      },
-      {
-        name: "onProductOpen",
-        type: "() => void",
-        defaultValue: "undefined",
-        description: "Called when the product chip is clicked and `productMenu` is NOT set. Use for custom modals / sheet-based switchers."
-      },
-      {
-        name: "onProjectOpen",
-        type: "() => void",
-        defaultValue: "undefined",
-        description: "Called when the project chip is clicked and `projectMenu` is NOT set."
-      },
-      {
-        name: "onSearchOpen",
-        type: "() => void",
-        defaultValue: "undefined",
-        description: "Called when the search bar button (\u2318K) is clicked. Wire this to your command-palette or search dialog."
-      },
-      {
-        name: "searchPlaceholder",
-        type: "string",
-        defaultValue: 'i18n "layout.topbar.searchPlaceholder" ("\u691C\u7D22\u2026")',
-        description: "Search-bar placeholder text \u2014 set a domain-specific hint (e.g. \u6848\u4EF6\u30FB\u53D7\u6CE8\u30FB\u9867\u5BA2\u3092\u691C\u7D22\u2026) instead of the generic default."
-      },
-      {
-        name: "onTweaksOpen",
-        type: "() => void",
-        defaultValue: "undefined",
-        description: "Called when the tweaks/settings icon button is clicked. The button is not rendered when this prop is omitted."
-      },
-      {
-        name: "collapsed",
-        type: "boolean",
-        defaultValue: "false",
-        description: "Whether the sidebar is currently collapsed. Controls which icon (`PanelLeftOpen` vs `PanelLeftClose`) is shown on the toggle button and sets its `aria-pressed` state."
-      },
-      {
-        name: "onToggleCollapsed",
-        type: "() => void",
-        defaultValue: "undefined",
-        description: "Called when the sidebar-toggle icon button is clicked. The button is not rendered when this prop is omitted."
+        description: "Center cluster (grows + centers) \u2014 optional. e.g. a search trigger (`Button` + `Search` icon opening your command palette) or a page/entity switcher (`DropdownMenu`)."
       },
       {
-        name: "rightSlot",
+        name: "end",
         type: "ReactNode",
         defaultValue: "undefined",
-        description: "Arbitrary content injected between the search bar and the notifications bell. Use for custom action buttons, locale switchers, or env badges."
-      },
-      {
-        name: "unread",
-        type: "boolean",
-        defaultValue: "false",
-        description: "When `true`, renders a red dot badge on the notifications bell to indicate unread notifications."
+        description: 'Inline-end cluster \u2014 settings pickers (`AppSettingPicker kind="locale"|"theme"`), a notifications `Button`, the user-menu `DropdownMenu`.'
       },
       {
-        name: "onNotificationsOpen",
-        type: "() => void",
+        name: "children",
+        type: "ReactNode",
         defaultValue: "undefined",
-        description: "Called when the notifications bell button is clicked. The bell button is not rendered when this prop is omitted."
+        description: "Escape hatch \u2014 render fully custom bar content instead of the three slots. When set, `start`/`center`/`end` are ignored."
       },
       {
-        name: "user",
-        type: "ReactNode",
-        defaultValue: "undefined",
-        description: "User avatar / profile menu node rendered at the far right of the topbar, after the notifications bell and before the tweaks button."
+        name: "className",
+        type: "string",
+        description: "Merged onto the bar element; arbitrary props (aria-*, etc.) are forwarded."
       }
     ],
     usage: [
-      "DO pass a `DropdownMenuContent` to `productMenu` or `projectMenu` to make a chip a real inline dropdown switcher (e.g. an entity/tenant picker). DO NOT combine both `productMenu` and `onProductOpen` \u2014 when `productMenu` is present, `onProductOpen` is ignored.",
-      "DO omit both `project` and `projectMenu` when the app has no project concept \u2014 the project chip is hidden entirely. If you want a 'Pick project' placeholder with a real dropdown, pass only `projectMenu` (leave `project` null/undefined) so the chip renders in its empty state with the dropdown attached.",
-      "DO render `Topbar` inside `AppShell`'s `topbar` prop \u2014 Topbar renders as a fragment of buttons/slots and relies on `AppShell`'s `app-topbar` CSS grid for layout. NEVER render it standalone outside of an `AppShell` or equivalent `<header>` container.",
-      "DO wire `onSearchOpen` to your command-palette/dialog \u2014 the search bar button always renders (it is not conditional on this prop), so omitting the handler leaves users with a non-functional control.",
-      "DO use `rightSlot` for extra topbar actions (e.g. locale switcher, environment badge, custom toolbar buttons) rather than adding children or extending the component.",
-      "DON'T hand-roll a topbar from scratch \u2014 Topbar ships the sidebar toggle, product/project switcher, search, notifications bell, user slot, and tweaks button with correct `aria-label`/`aria-pressed` attributes already."
+      "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 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 / SaaS shell where the header shows the active legal entity (product chip) and users switch between entities via a `DropdownMenuContent` passed to `productMenu`.",
-      "Multi-project app where the project chip shows the current project and `projectMenu` provides a `DropdownMenuContent` to switch projects inline without opening a modal.",
-      "App-shell with a collapsible sidebar: pass `collapsed` + `onToggleCollapsed` to let users toggle the sidebar from the topbar without building a custom toggle button.",
-      "Notification-aware shell: pass `onNotificationsOpen` + `unread={hasUnread}` to render a bell icon with a red-dot badge that opens a notifications panel.",
-      "Apps needing a locale switcher or environment badge in the header: put it in `rightSlot` to slot it between the search bar and the notifications bell without modifying the component.",
-      "Read-only / minimal shell where sidebar toggling, tweaks, and notifications are not needed \u2014 simply omit `onToggleCollapsed`, `onTweaksOpen`, and `onNotificationsOpen`; their buttons are not rendered."
+      "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.",
+      "Marketing / docs header: pass `children` with a fully custom flex layout when the three-cluster model doesn't fit."
     ],
     related: [
-      "AppShell \u2014 the parent shell component that places Topbar inside its `app-topbar` header region via the `topbar` prop. Always use Topbar inside AppShell, not standalone.",
-      "Sidebar \u2014 the companion left-rail nav; pair with Topbar's `collapsed`/`onToggleCollapsed` to keep sidebar and topbar toggle state in sync.",
-      "DropdownMenu / DropdownMenuContent \u2014 pass a `DropdownMenuContent` as `productMenu` or `projectMenu` to turn a chip into an inline switcher. Topbar handles the `DropdownMenuTrigger` wrapping internally; only the Content node is needed.",
-      "AppShell \u2014 a higher-level opinionated shell that already composes AppShell + Topbar with hardcoded product/project chips; use it for prototypes but use AppShell + Topbar directly for production apps that need real switcher props."
+      "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.",
+      "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 } from "@godxjp/ui/layout";
-import { AppShell } from "@godxjp/ui/layout";
-import {
-  DropdownMenuContent,
-  DropdownMenuItem,
-} from "@godxjp/ui/navigation";
-
-// Entity-switcher example: product chip opens an entity dropdown,
-// project chip is hidden (no project concept in this app).
-function MyShell({ children }: { content: React.ReactNode }) {
-  const [collapsed, setCollapsed] = React.useState(false);
-  const [unread, setUnread] = React.useState(true);
-
-  return (
-    <AppShell
-      sidebar={<MySidebar />}
-      sidebarCollapsed={collapsed}
-      topbar={
-        <Topbar
-          product={{ name: "CoreBooks", color: "hsl(220 70% 50%)" }}
-          productMenu={
-            <DropdownMenuContent align="start">
-              <DropdownMenuItem onSelect={() => switchEntity("acme")}>
-                Acme Corp
-              </DropdownMenuItem>
-              <DropdownMenuItem onSelect={() => switchEntity("globex")}>
-                Globex Ltd
-              </DropdownMenuItem>
-            </DropdownMenuContent>
-          }
-          collapsed={collapsed}
-          onToggleCollapsed={() => setCollapsed((c) => !c)}
-          onSearchOpen={() => openCommandPalette()}
-          unread={unread}
-          onNotificationsOpen={() => openNotificationsPanel()}
-          user={<UserAvatar />}
-        />
+    example: `import { Topbar, AppShell } from "@godxjp/ui/layout";
+import { Logo, Button } from "@godxjp/ui/general";
+import { AppSettingPicker } from "@godxjp/ui/navigation";
+import { PanelLeftClose, Search } from "lucide-react";
+
+// The shell gives you slots; YOU decide what goes in them.
+<AppShell
+  sidebar={<MySidebar />}
+  topbar={
+    <Topbar
+      start={
+        <>
+          <Button variant="ghost" size="icon-sm" aria-label={t("toggleSidebar")} onClick={toggle}>
+            <PanelLeftClose />
+          </Button>
+          <Logo label="CoreBooks" />
+        </>
       }
-    >
-      {children}
-    </AppShell>
-  );
-}`,
+      center={
+        <Button variant="outline" size="sm" onClick={openSearch}>
+          <Search />
+          {t("search")}
+        </Button>
+      }
+      end={
+        <>
+          <AppSettingPicker kind="locale" />
+          <UserMenu />
+        </>
+      }
+    />
+  }
+>
+  {children}
+</AppShell>`,
     storyPath: "layout/Topbar.stories.tsx",
     rules: [2, 3, 5, 6]
   },
@@ -759,6 +686,12 @@ function MyShell({ children }: { content: React.ReactNode }) {
         defaultValue: '"default"',
         description: "Corner radius from the tokens \u2014 `default` (control radius), `pill` (fully rounded, --radius-pill), `sharp` (square, --radius-sharp). Use the prop instead of a `rounded-*` className."
       },
+      {
+        name: "fullWidth",
+        type: "boolean",
+        defaultValue: "false",
+        description: 'Span the full container width (`width:100%`) instead of sizing to content. Use the prop instead of `className="w-full"` for stacked / auth-form / dialog-footer actions (rule #42).'
+      },
       {
         name: "asChild",
         type: "boolean",
@@ -931,6 +864,63 @@ 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",
@@ -1057,6 +1047,7 @@ import { Trash2 } from "lucide-react";
       "Table \u2014 raw primitive (TableHeader/TableBody/TableRow/TableCell). Use DataTable instead; only reach for Table directly when you need a non-standard layout that DataTable cannot express.",
       "SkeletonTable \u2014 standalone skeleton placeholder rendered before any DataTable mounts (e.g. in a Suspense fallback or deferred-prop skeleton slot). DataTable.loading covers in-table loading; SkeletonTable covers pre-mount skeletons.",
       "EmptyState \u2014 standalone empty state for non-table lists. DataTable already embeds EmptyState in its body; only use bare EmptyState for card content, non-tabular lists, or zero-state pages outside a DataTable.",
+      "LineChart / BarChart / AreaChart / PieChart (@godxjp/ui/charts) \u2014 when the SHAPE or trend of aggregated data matters more than exact per-row figures, visualize it with a chart instead of (or alongside) the table; keep DataTable when users need to read, sort, or act on individual rows.",
       "DataState / InfiniteQueryState \u2014 TanStack Query lifecycle widgets from @godxjp/ui/query. Prefer these over DataTable when your list is driven by useQuery/useInfiniteQuery and you want automatic skeleton/empty/error handling at the query level rather than at the table level."
     ],
     example: `import { useState } from "react";
@@ -1400,7 +1391,8 @@ export function Grid({ rows }: { rows: Row[] }) {
       "ResponsiveGrid \u2014 required layout wrapper for StatCard grids; controls column count and responsive breakpoints. Always pair them together.",
       "SkeletonStat \u2014 exact loading placeholder shaped like a StatCard tile; swap in while KPI data is fetching, then replace with the real StatCard.",
       "Descriptions \u2014 use instead when displaying multiple label/value metadata pairs on a detail page (not headline KPIs); Descriptions is not card-bordered and does not show delta/hint slots.",
-      "Card + CardContent \u2014 use when you need a general-purpose content container with a header, footer, or arbitrary body; do NOT wrap StatCard inside these."
+      "Card + CardContent \u2014 use when you need a general-purpose content container with a header, footer, or arbitrary body; do NOT wrap StatCard inside these.",
+      "LineChart / BarChart / PieChart (@godxjp/ui/charts) \u2014 when the trend or composition BEHIND a KPI matters, pair the StatCard headline number with a chart in the same dashboard grid: StatCard states the figure, the chart shows its shape over time or its breakdown."
     ],
     example: `import { StatCard } from "@godxjp/ui/data-display";
 import { ResponsiveGrid } from "@godxjp/ui/layout";
@@ -1481,6 +1473,87 @@ import { ResponsiveGrid } from "@godxjp/ui/layout";
     storyPath: "data-display/Badge.stories.tsx",
     rules: [35]
   },
+  {
+    name: "ListRow",
+    group: "data-display",
+    tagline: "Single-line entity row (leading \xB7 title/description \xB7 trailing action) for SHORT lists inside a Card \u2014 sessions, API tokens, linked accounts, passkeys, MFA factors, invitations.",
+    props: [
+      {
+        name: "title",
+        type: "ReactNode",
+        required: true,
+        description: "Primary line \u2014 rendered in medium weight; truncates to one line."
+      },
+      {
+        name: "description",
+        type: "ReactNode",
+        description: "Secondary line under the title (muted, xs); truncates to one line."
+      },
+      {
+        name: "leading",
+        type: "ReactNode",
+        description: "Leading slot \u2014 a decorative icon or an Avatar. Mark a purely decorative icon `aria-hidden`."
+      },
+      {
+        name: "trailing",
+        type: "ReactNode",
+        description: "Trailing slot \u2014 the row action(s): a Button / DropdownMenu trigger, a Badge, or a Switch."
+      },
+      {
+        name: "align",
+        type: '"center" | "start"',
+        defaultValue: '"center"',
+        description: "Cross-axis alignment of the columns; `start` for multi-line content."
+      },
+      {
+        name: "as",
+        type: '"div" | "li"',
+        defaultValue: '"div"',
+        description: "Render element \u2014 `li` when the parent is a semantic `<ul>`/`<ol>`."
+      }
+    ],
+    usage: [
+      "DO use ListRow for a SHORT (\u22482\u20138 item) list of entities inside a Card where each row is one line with an action \u2014 account sessions, API keys, linked identities, passkeys. Stack rows in a `<Card><CardContent flush>` so the rows draw their own quiet dividers edge-to-edge.",
+      "DON'T reach for DataTable here \u2014 it carries sorting/selection/pagination chrome that a 3-item list doesn't need. DON'T nest a Card per row either (card-in-card). ListRow is the in-between surface.",
+      'DON\'T hand-roll `<div className="flex items-center justify-between border-b py-3">` \u2014 that is exactly the repeated pattern ListRow replaces (border/radius/padding are tokenized via `--list-row-*`).',
+      'DO put the row\'s action in `trailing` (a `ghost`/`outline` Button, a DropdownMenu trigger, a Switch, or a status Badge). DO pass `as="li"` when the rows live inside a semantic `<ul>`.'
+    ],
+    useCases: [
+      "Account security page \u2014 a list of active sessions (device + last-seen as title/description, a destructive 'Revoke' Button in trailing).",
+      "Developer settings \u2014 API tokens or passkeys, each row showing the name + created date and a DropdownMenu of actions.",
+      "Linked accounts / SSO \u2014 an IdP icon in leading, the provider name + connected email, and a Switch or 'Disconnect' Button trailing."
+    ],
+    related: [
+      "DataTable \u2014 use instead when the list is long or needs sorting/selection/pagination; ListRow is for short, chrome-light lists.",
+      "Card \u2014 ListRow is designed to live inside `<CardContent flush>`; the Card supplies the outer surface and the closing border.",
+      "Descriptions \u2014 for a key/value metadata grid on a detail page (no per-row action); ListRow is for actionable entity rows."
+    ],
+    example: `import { Card, CardContent, CardHeader, CardTitle, ListRow, Badge } from "@godxjp/ui/data-display";
+import { Button } from "@godxjp/ui/general";
+import { Smartphone } from "lucide-react";
+
+<Card>
+  <CardHeader>
+    <CardTitle>\u30A2\u30AF\u30C6\u30A3\u30D6\u306A\u30BB\u30C3\u30B7\u30E7\u30F3</CardTitle>
+  </CardHeader>
+  <CardContent flush>
+    <ListRow
+      leading={<Smartphone aria-hidden="true" className="size-4" />}
+      title="iPhone 15 \xB7 Tokyo"
+      description="\u6700\u7D42\u30A2\u30AF\u30BB\u30B9 2\u5206\u524D"
+      trailing={<Badge status="active" />}
+    />
+    <ListRow
+      leading={<Smartphone aria-hidden="true" className="size-4" />}
+      title="MacBook Pro \xB7 Osaka"
+      description="\u6700\u7D42\u30A2\u30AF\u30BB\u30B9 3\u65E5\u524D"
+      trailing={<Button size="xs" variant="outline">\u30ED\u30B0\u30A2\u30A6\u30C8</Button>}
+    />
+  </CardContent>
+</Card>`,
+    storyPath: "data-display/ListRow.stories.tsx",
+    rules: [42, 44]
+  },
   {
     name: "Descriptions",
     group: "data-display",
@@ -1613,7 +1686,8 @@ import { ResponsiveGrid } from "@godxjp/ui/layout";
       "Slider \u2014 use Slider when the user must drag or set a bounded numeric value (volume, priority, price range); use Progress when the value is read-only and must not be interacted with.",
       "Steps \u2014 use Steps for a discrete, named sequence of phases (onboarding wizard, checkout flow) where each step has a label and a clear current/done/pending state; use Progress for a continuous 0\u2013100 fill.",
       'Badge / Badge \u2014 use Badge or Badge to communicate a categorical status label (e.g. "Paid", "Overdue") without a fill metaphor; use Progress when the numeric proportion itself is the information.',
-      "StatCard \u2014 use StatCard to headline a single KPI metric with a title; compose Progress inside or alongside StatCard when a visual fill adds meaning to the number."
+      "StatCard \u2014 use StatCard to headline a single KPI metric with a title; compose Progress inside or alongside StatCard when a visual fill adds meaning to the number.",
+      "BarChart / PieChart / LineChart (@godxjp/ui/charts) \u2014 Progress shows ONE ratio against a target; the moment you have several series, categories, or a part-to-whole split (or a value changing over time), move up to a chart instead of stacking many Progress bars."
     ],
     example: `import { Progress } from "@godxjp/ui/data-display";
 
@@ -3263,6 +3337,7 @@ import { Button } from "@godxjp/ui/general";
       }
     ],
     usage: [
+      "ANATOMY (positions are fixed \u2014 never re-lay-them-out): Alert is ONE horizontal row \u2014 a SINGLE leading tone icon at the inline-start (top-aligned to the first text line, auto-selected by `tone`, never two icons), then the text body (Title/Description), then `<Alert.Actions>` in a trailing-RIGHT column (\u2265sm), and the dismiss \xD7 pinned to the TOP-RIGHT corner (rendered by `onDismiss`). DON'T stack these vertically, DON'T make the action a full-width bar under the text, DON'T center the \xD7 at the bottom, DON'T add a second icon \u2014 that hand-rolled vertical banner is the #1 Alert mistake.",
       'DO compose text as `<Alert.Title>` + `<Alert.Description>` \u2014 they stack vertically inside the body (the Example below is canonical). When you add `<Alert.Actions>`, the body becomes a two-column grid (text | actions) at \u2265sm; group multi-part text in `<Alert.Content>` so it occupies the text column as one block: `<Alert tone="destructive"><Alert.Content><Alert.Title>Error</Alert.Title><Alert.Description>{msg}</Alert.Description></Alert.Content><Alert.Actions><Button \u2026/></Alert.Actions></Alert>`.',
       "DO use `Alert.QueryError` (alias `AlertQueryError`) for TanStack Query / API failure surfaces \u2014 it already renders humanError(error), an i18n title, and an optional Retry button. Never hand-roll that pattern.",
       'DON\'T pass raw action elements directly as top-level children of `<Alert>` without wrapping them in `<Alert.Actions>` \u2014 the layout slot only activates correctly via the `data-slot="alert-actions"` wrapper.',
@@ -7189,60 +7264,475 @@ export function NotifyRow() {
 }\`}`,
     storyPath: "data-entry/Field.stories.tsx",
     rules: [23]
-  }
-];
-function findComponent(name) {
-  const normalized = name.trim().toLowerCase();
-  return COMPONENTS.find((c) => c.name.toLowerCase() === normalized);
-}
-function componentsByGroup(group) {
-  return COMPONENTS.filter((c) => c.group === group);
-}
-
-// src/data/prop-vocabulary.ts
-var PROP_VOCABULARY = [
-  {
-    name: "ValueProp<T = string>",
-    concept: "Abstract controlled value.",
-    values: ["generic"],
-    usedBy: ["CheckboxGroup", "Upload", "Cascader", "TreeSelect", "Tabs", "SearchSelect"]
-  },
-  {
-    name: "DefaultValueProp<T = string>",
-    concept: "Abstract uncontrolled initial value.",
-    values: ["generic"],
-    usedBy: ["CheckboxGroup", "Upload", "Cascader", "TreeSelect", "Tabs"]
-  },
-  {
-    name: "OnValueChangeProp<T = string>",
-    concept: "Callback for abstract value changes. DOM events continue to use onChange.",
-    values: ["(value: T) => void"],
-    usedBy: ["CheckboxGroup", "Upload", "Cascader", "TreeSelect", "Transfer", "settings pickers"]
-  },
-  {
-    name: "OpenProp / DefaultOpenProp / OnOpenChangeProp",
-    concept: "Disclosure state.",
-    values: ["boolean", "(open: boolean) => void"],
-    usedBy: ["Dialog", "Sheet", "Popover"]
   },
+  // ─── charts (tree-shaken `@godxjp/ui/charts`; needs the `recharts` optional peer) ───
   {
-    name: "SizeProp",
-    concept: "Shared public size names.",
-    values: ["xs", "sm", "md", "lg"],
-    usedBy: ["Button", "Steps", "Switch"],
-    notes: "Component-specific subsets must be documented. Old alias small is sm."
-  },
-  {
-    name: "ToneProp",
-    concept: "Semantic status/color intent.",
-    values: ["default", "success", "warning", "destructive", "info", "muted", "neutral"],
-    usedBy: ["Badge", "Alert"],
-    notes: "Status values belong in tone, not variant."
+    name: "LineChart",
+    group: "data-display",
+    importPath: "@godxjp/ui/charts",
+    tagline: "Trends over an ordered category axis \u2014 one or more series, locale-formatted ticks/tooltips, screen-reader text alternative built in. Data-visualization graph / plot.",
+    props: [
+      {
+        name: "data",
+        type: "ChartDatum[]",
+        required: true,
+        description: "Row data: one category per row with a numeric value per series."
+      },
+      {
+        name: "series",
+        type: "ChartSeriesProp[]",
+        required: true,
+        description: "Plotted series: { dataKey, label?, color? }. Colour defaults to the --chart-1..6 palette."
+      },
+      {
+        name: "categoryKey",
+        type: "string",
+        required: true,
+        description: "Key into each datum holding the x-axis category label."
+      },
+      {
+        name: "label",
+        type: "string",
+        required: true,
+        description: "Accessible name + visible caption (role=img needs a name)."
+      },
+      {
+        name: "description",
+        type: "string",
+        description: "Extra context appended to the screen-reader description."
+      },
+      {
+        name: "size",
+        type: '"xs" | "sm" | "md" | "lg"',
+        defaultValue: '"md"',
+        description: "Canvas height preset. Ignored when `height` is set."
+      },
+      {
+        name: "height",
+        type: "number",
+        description: "Explicit canvas height in px (overrides `size`)."
+      },
+      {
+        name: "showLegend",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Show the series legend."
+      },
+      {
+        name: "showGrid",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Show the cartesian background grid."
+      },
+      {
+        name: "numberFormat",
+        type: "Intl.NumberFormatOptions",
+        description: "Locale-aware formatting for axis ticks + tooltip values."
+      },
+      {
+        name: "curved",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Render smooth (monotone) lines instead of straight segments."
+      },
+      {
+        name: "emptyMessage",
+        type: "string",
+        description: "Message shown when `data` is empty (defaults to a localized 'no data')."
+      }
+    ],
+    usage: [
+      'DO import from the tree-shaken charts entry: `import { LineChart } from "@godxjp/ui/charts";`. Importing any other subpath never pulls in recharts.',
+      "DO install the `recharts` optional peer dependency in the consuming app \u2014 charts are the only part of @godxjp/ui that needs it, so apps without charts never pay for it.",
+      "DO pass an i18n'd `label` \u2014 it is both the visible caption and the accessible name; the component also emits a screen-reader list of the plotted values (WCAG 1.1.1).",
+      "DO pre-translate each series' `label`; pass `numberFormat` (e.g. { style: 'currency', currency: 'JPY' }) and the axis/tooltip numbers localize automatically via Intl.",
+      "DON'T hand-roll an SVG/canvas chart or drop raw recharts into a page \u2014 LineChart owns the colour tokens, locale formatting, empty state, and accessibility wiring."
+    ],
+    useCases: [
+      "Revenue / KPI trend over months in a dashboard.",
+      "Multi-series comparison (e.g. plan vs actual) across a time axis.",
+      "Any continuous metric where the shape of the trend is the message."
+    ],
+    related: [
+      "AreaChart \u2014 use when the filled magnitude under the line matters (cumulative/stacked volume).",
+      "BarChart \u2014 use for discrete category comparison rather than a continuous trend.",
+      "DataTable \u2014 use when exact per-row figures matter more than the trend shape."
+    ],
+    example: `import { LineChart } from "@godxjp/ui/charts";
+
+<LineChart
+  label={t("dashboard.revenueTrend")}
+  data={data}
+  categoryKey="month"
+  series={[
+    { dataKey: "plan", label: t("metric.plan") },
+    { dataKey: "actual", label: t("metric.actual") },
+  ]}
+  numberFormat={{ style: "currency", currency: "JPY" }}
+/>`,
+    storyPath: "charts/LineChart.stories.tsx",
+    rules: []
   },
   {
-    name: "GapProp",
-    concept: "Shared layout gap scale.",
-    values: ["xs", "sm", "md", "lg", "xl"],
+    name: "BarChart",
+    group: "data-display",
+    importPath: "@godxjp/ui/charts",
+    tagline: "Compare a value across categories \u2014 grouped or `stacked`, vertical or `horizontal`, with localized ticks/tooltips and a built-in text alternative. Data-visualization graph / plot / diagram.",
+    props: [
+      {
+        name: "data",
+        type: "ChartDatum[]",
+        required: true,
+        description: "Row data: one category per row with a numeric value per series."
+      },
+      {
+        name: "series",
+        type: "ChartSeriesProp[]",
+        required: true,
+        description: "Plotted series: { dataKey, label?, color? }."
+      },
+      {
+        name: "categoryKey",
+        type: "string",
+        required: true,
+        description: "Key into each datum holding the category label."
+      },
+      {
+        name: "label",
+        type: "string",
+        required: true,
+        description: "Accessible name + visible caption."
+      },
+      {
+        name: "description",
+        type: "string",
+        description: "Extra context appended to the screen-reader description."
+      },
+      {
+        name: "size",
+        type: '"xs" | "sm" | "md" | "lg"',
+        defaultValue: '"md"',
+        description: "Canvas height preset. Ignored when `height` is set."
+      },
+      {
+        name: "height",
+        type: "number",
+        description: "Explicit canvas height in px (overrides `size`)."
+      },
+      {
+        name: "showLegend",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Show the series legend."
+      },
+      {
+        name: "showGrid",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Show the cartesian background grid."
+      },
+      {
+        name: "numberFormat",
+        type: "Intl.NumberFormatOptions",
+        description: "Locale-aware formatting for ticks + tooltip values."
+      },
+      {
+        name: "stacked",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Stack series into one bar instead of grouping side by side."
+      },
+      {
+        name: "horizontal",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Lay bars out horizontally (category on the y-axis)."
+      },
+      { name: "emptyMessage", type: "string", description: "Message shown when `data` is empty." }
+    ],
+    usage: [
+      'DO import from the charts entry: `import { BarChart } from "@godxjp/ui/charts";` (recharts optional peer required).',
+      "DO use `horizontal` when category labels are long (they read better on the y-axis).",
+      "DO use `stacked` for part-to-whole-per-category; keep grouped (default) for direct side-by-side comparison.",
+      "DON'T use BarChart for a single part-to-whole total \u2014 that is PieChart. DON'T fake bars with styled divs."
+    ],
+    useCases: [
+      "Sales by region / category comparison.",
+      "Stacked composition per period (e.g. expense breakdown by month).",
+      "Ranking with long labels (horizontal)."
+    ],
+    related: [
+      "LineChart \u2014 continuous trend rather than discrete comparison.",
+      "PieChart \u2014 single part-to-whole composition.",
+      "DataTable \u2014 exact tabular figures."
+    ],
+    example: `import { BarChart } from "@godxjp/ui/charts";
+
+<BarChart
+  label={t("report.salesByRegion")}
+  data={data}
+  categoryKey="region"
+  series={[{ dataKey: "sales", label: t("metric.sales") }]}
+  numberFormat={{ notation: "compact" }}
+/>`,
+    storyPath: "charts/BarChart.stories.tsx",
+    rules: []
+  },
+  {
+    name: "AreaChart",
+    group: "data-display",
+    importPath: "@godxjp/ui/charts",
+    tagline: "Magnitude over an ordered category axis \u2014 overlay or `stacked` areas, optional `curved` smoothing, localized formatting + text alternative. Data-visualization graph / plot.",
+    props: [
+      {
+        name: "data",
+        type: "ChartDatum[]",
+        required: true,
+        description: "Row data: one category per row with a numeric value per series."
+      },
+      {
+        name: "series",
+        type: "ChartSeriesProp[]",
+        required: true,
+        description: "Plotted series: { dataKey, label?, color? }."
+      },
+      {
+        name: "categoryKey",
+        type: "string",
+        required: true,
+        description: "Key into each datum holding the x-axis category label."
+      },
+      {
+        name: "label",
+        type: "string",
+        required: true,
+        description: "Accessible name + visible caption."
+      },
+      {
+        name: "description",
+        type: "string",
+        description: "Extra context appended to the screen-reader description."
+      },
+      {
+        name: "size",
+        type: '"xs" | "sm" | "md" | "lg"',
+        defaultValue: '"md"',
+        description: "Canvas height preset. Ignored when `height` is set."
+      },
+      {
+        name: "height",
+        type: "number",
+        description: "Explicit canvas height in px (overrides `size`)."
+      },
+      {
+        name: "showLegend",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Show the series legend."
+      },
+      {
+        name: "showGrid",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Show the cartesian background grid."
+      },
+      {
+        name: "numberFormat",
+        type: "Intl.NumberFormatOptions",
+        description: "Locale-aware formatting for ticks + tooltip values."
+      },
+      {
+        name: "stacked",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Stack series areas instead of overlaying them."
+      },
+      {
+        name: "curved",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Render smooth (monotone) areas instead of straight segments."
+      },
+      { name: "emptyMessage", type: "string", description: "Message shown when `data` is empty." }
+    ],
+    usage: [
+      'DO import from the charts entry: `import { AreaChart } from "@godxjp/ui/charts";` (recharts optional peer required).',
+      "DO use `stacked` to show how parts accumulate into a total over time.",
+      "DON'T overlay more than 2-3 unstacked areas \u2014 fill opacity makes dense overlays unreadable; switch to LineChart."
+    ],
+    useCases: [
+      "Cumulative volume over time (e.g. total transactions per day).",
+      "Stacked composition trend (traffic sources, revenue streams)."
+    ],
+    related: [
+      "LineChart \u2014 when only the trend line matters, not the filled magnitude.",
+      "BarChart \u2014 discrete category comparison."
+    ],
+    example: `import { AreaChart } from "@godxjp/ui/charts";
+
+<AreaChart
+  label={t("dashboard.trafficByChannel")}
+  data={data}
+  categoryKey="day"
+  series={[
+    { dataKey: "organic", label: t("channel.organic") },
+    { dataKey: "paid", label: t("channel.paid") },
+  ]}
+  stacked
+/>`,
+    storyPath: "charts/AreaChart.stories.tsx",
+    rules: []
+  },
+  {
+    name: "PieChart",
+    group: "data-display",
+    importPath: "@godxjp/ui/charts",
+    tagline: "Part-to-whole composition across a small set of slices \u2014 `donut` option, localized tooltips, and a screen-reader breakdown of every slice. Data-visualization graph / diagram.",
+    props: [
+      {
+        name: "data",
+        type: "ChartDatum[]",
+        required: true,
+        description: "Row data: one slice per row."
+      },
+      {
+        name: "dataKey",
+        type: "string",
+        required: true,
+        description: "Key into each datum holding the slice's numeric value."
+      },
+      {
+        name: "nameKey",
+        type: "string",
+        required: true,
+        description: "Key into each datum holding the slice's category label."
+      },
+      {
+        name: "label",
+        type: "string",
+        required: true,
+        description: "Accessible name + visible caption."
+      },
+      {
+        name: "colors",
+        type: "string[]",
+        description: "Per-slice colours by index (defaults to the --chart-1..6 palette)."
+      },
+      {
+        name: "description",
+        type: "string",
+        description: "Extra context appended to the screen-reader description."
+      },
+      {
+        name: "size",
+        type: '"xs" | "sm" | "md" | "lg"',
+        defaultValue: '"md"',
+        description: "Canvas height preset. Ignored when `height` is set."
+      },
+      {
+        name: "height",
+        type: "number",
+        description: "Explicit canvas height in px (overrides `size`)."
+      },
+      {
+        name: "showLegend",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Show the slice legend."
+      },
+      {
+        name: "numberFormat",
+        type: "Intl.NumberFormatOptions",
+        description: "Locale-aware formatting for tooltip values."
+      },
+      {
+        name: "donut",
+        type: "boolean",
+        defaultValue: "false",
+        description: "Render a donut (hollow centre) instead of a full pie."
+      },
+      { name: "emptyMessage", type: "string", description: "Message shown when `data` is empty." }
+    ],
+    usage: [
+      'DO import from the charts entry: `import { PieChart } from "@godxjp/ui/charts";` (recharts optional peer required).',
+      "DO keep slices few (\u22482\u20136) \u2014 pies are unreadable past a handful; use BarChart for many categories.",
+      "DO pass `numberFormat` (e.g. percent or currency) so tooltip values localize.",
+      "DON'T use a pie for trends over time (LineChart/AreaChart) or precise comparison (BarChart)."
+    ],
+    useCases: [
+      "Budget / expense split across a few categories.",
+      "Market or status share (e.g. paid vs overdue vs draft)."
+    ],
+    related: [
+      "BarChart \u2014 when there are many categories or precise comparison matters.",
+      "Progress \u2014 single ratio against a target rather than a multi-slice split."
+    ],
+    example: `import { PieChart } from "@godxjp/ui/charts";
+
+<PieChart
+  label={t("dashboard.expenseSplit")}
+  data={data}
+  dataKey="amount"
+  nameKey="category"
+  numberFormat={{ style: "currency", currency: "JPY" }}
+  donut
+/>`,
+    storyPath: "charts/PieChart.stories.tsx",
+    rules: []
+  }
+];
+function findComponent(name) {
+  const normalized = name.trim().toLowerCase();
+  return COMPONENTS.find((c) => c.name.toLowerCase() === normalized);
+}
+function componentsByGroup(group) {
+  return COMPONENTS.filter((c) => c.group === group);
+}
+
+// src/data/prop-vocabulary.ts
+var PROP_VOCABULARY = [
+  {
+    name: "ValueProp<T = string>",
+    concept: "Abstract controlled value.",
+    values: ["generic"],
+    usedBy: ["CheckboxGroup", "Upload", "Cascader", "TreeSelect", "Tabs", "SearchSelect"]
+  },
+  {
+    name: "DefaultValueProp<T = string>",
+    concept: "Abstract uncontrolled initial value.",
+    values: ["generic"],
+    usedBy: ["CheckboxGroup", "Upload", "Cascader", "TreeSelect", "Tabs"]
+  },
+  {
+    name: "OnValueChangeProp<T = string>",
+    concept: "Callback for abstract value changes. DOM events continue to use onChange.",
+    values: ["(value: T) => void"],
+    usedBy: ["CheckboxGroup", "Upload", "Cascader", "TreeSelect", "Transfer", "settings pickers"]
+  },
+  {
+    name: "OpenProp / DefaultOpenProp / OnOpenChangeProp",
+    concept: "Disclosure state.",
+    values: ["boolean", "(open: boolean) => void"],
+    usedBy: ["Dialog", "Sheet", "Popover"]
+  },
+  {
+    name: "SizeProp",
+    concept: "Shared public size names.",
+    values: ["xs", "sm", "md", "lg"],
+    usedBy: ["Button", "Steps", "Switch"],
+    notes: "Component-specific subsets must be documented. Old alias small is sm."
+  },
+  {
+    name: "ToneProp",
+    concept: "Semantic status/color intent.",
+    values: ["default", "success", "warning", "destructive", "info", "muted", "neutral"],
+    usedBy: ["Badge", "Alert"],
+    notes: "Status values belong in tone, not variant."
+  },
+  {
+    name: "GapProp",
+    concept: "Shared layout gap scale.",
+    values: ["xs", "sm", "md", "lg", "xl"],
     usedBy: ["Stack", "Inline"],
     notes: "Inline uses an Exclude<GapProp, 'xl'> subset."
   },
@@ -7278,7 +7768,7 @@ var TOKENS = [
     name: "--chart-1..6",
     category: "primitive",
     tier: "primitive",
-    role: "Neutral decorative chart primitives; @theme chart colors reference these tokens."
+    role: "Neutral decorative chart series palette. The @godxjp/ui/charts components (LineChart/BarChart/AreaChart/PieChart) read these by series index automatically \u2014 a service rethemes every chart at once by overriding --chart-1..6; per-series/per-slice overrides go through the component's series.color / colors props."
   },
   { name: "--space-0..12", category: "primitive", tier: "primitive", role: "Raw spacing scale." },
   {
@@ -7287,6 +7777,24 @@ var TOKENS = [
     tier: "primitive",
     role: "Raw typography scale."
   },
+  {
+    name: "--duration-{fast,base,slow}",
+    category: "primitive",
+    tier: "primitive",
+    role: "Motion durations (150 / 250 / 500ms). Read these instead of a literal `0.5s` for enter/transition timing (rule #2). dxs-kintai keeps motion short; honour `prefers-reduced-motion` at the call site."
+  },
+  {
+    name: "--ease-{standard,emphasized,decelerate,accelerate}",
+    category: "primitive",
+    tier: "primitive",
+    role: "Motion easing curves. `standard` for most transitions, `emphasized` for entrances/overlays (the vaul drawer curve), `decelerate` for settling in, `accelerate` for exits. Read instead of a literal `cubic-bezier(\u2026)`."
+  },
+  {
+    name: "--reveal-distance",
+    category: "primitive",
+    tier: "primitive",
+    role: "Distance (10px) a revealed element travels on enter (translateY/-X). Read instead of a literal `translateY(10px)` for staggered reveals."
+  },
   { 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." },
@@ -7914,6 +8422,51 @@ var COMPONENT_TOKENS = [
     "value": "var(--space-4)",
     "description": "Column gap between the label and its control in horizontal/inline layout."
   },
+  {
+    "name": "--list-row-padding-y",
+    "value": "var(--space-3)",
+    "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": "--list-row-padding-x",
+    "value": "var(--space-4)",
+    "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": "--list-row-gap",
+    "value": "var(--space-3)",
+    "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": "--list-row-border",
+    "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)",
@@ -10018,6 +10571,21 @@ categories. Reads as chaos; eye can't anchor.`,
 "solid" vs "outline") for variety within the same hue. Reserve
 non-neutral colors (success / warning / destructive) for tags
 that genuinely carry that meaning.`
+  },
+  {
+    category: "visual",
+    name: "Oversaturated brand accent",
+    body: `Full-bleed, fully-saturated brand color on buttons, banners and
+notification bars (the classic loud Slack/Linear/Notion blue) \u2014 the
+accent SCREAMS instead of signalling. A bright primary CTA bar across
+the whole width, vivid send buttons, neon success. It reads as a
+verbatim copy of a SaaS chrome, not a restrained product surface.`,
+    fix: `\u6E0B\u307F (restraint): keep --primary chroma \u2264 0.18 \u2014 desaturate so the
+accent BLENDS with the warm-neutral spine and is used sparingly for
+the ONE primary action. Don't paint a full-width bar in raw blue;
+prefer a quiet Alert (icon + text + a normal-width action). Never
+hard-code a vivid hex \u2014 read \`bg-primary\`/\`text-primary\` tokens, and
+let a service retheme via --primary only.`
   },
   // ── layout ─────────────────────────────────────────────────────
   {
@@ -10062,8 +10630,39 @@ template" \u2014 and devalues the user's time at each step.`,
 be a centered question, step 2 a side-by-side comparison, step 3
 a multi-field form, step 4 a single yes/no card. Same palette +
 type system for coherence; different composition for engagement.`
+  },
+  {
+    category: "layout",
+    name: "Stacked notification banner (misplaced alert controls)",
+    body: `A notification / "enable X" bar where the pieces are stacked
+VERTICALLY and mis-placed: the icon floats centered ABOVE the text
+(often a SECOND redundant icon on the far left too), the primary
+action is a FULL-WIDTH colored bar UNDER the text, and the dismiss \xD7
+sits centered at the BOTTOM on its own line. It's a hand-rolled
+banner that ignores the framework's Alert anatomy.`,
+    fix: `Use <Alert> and respect its fixed anatomy \u2014 ONE leading tone icon
+at the inline-start (top-aligned, auto by \`tone\`, never two), the
+text body, an <Alert.Actions> with a NORMAL-WIDTH Button in the
+trailing-right column, and \`onDismiss\` to render the \xD7 in the
+TOP-RIGHT corner. It is ONE horizontal row, never a vertical stack;
+never hand-roll the \u2715 or a full-bleed action bar.`
   },
   // ── copy ───────────────────────────────────────────────────────
+  {
+    category: "copy",
+    name: "Emoji in product UI",
+    body: `Emoji sprinkled through the product surface \u2014 \u2705 / \u{1F389} / \u{1F525} in chat
+messages, status lines, toasts, buttons, empty states or success
+banners ("All tests green \u{1F389}", "done \u2705"). It reads as casual
+consumer-app slop, breaks on Windows/Linux, and pollutes the
+accessible name. Celebrating with confetti/\u{1F389} is the same tell.`,
+    fix: `No emoji anywhere in product UI. State the fact quietly in
+i18n-keyed copy ("\u627F\u8A8D\u3057\u307E\u3057\u305F" / "All checks passed"). Use a Lucide
+icon (1.5px) for an affordance and a semantic Badge \`tone\`
+(success/warning/destructive) for status \u2014 color + label carry the
+meaning, not a glyph. Country names come from \`Intl.DisplayNames\`,
+never emoji flags.`
+  },
   {
     category: "copy",
     name: "Filler corporate phrases",
@@ -10539,6 +11138,288 @@ function checksByCategory(cat) {
   return REDESIGN_CHECKS.filter((c) => c.category === cat);
 }
 
+// src/data/audit-rules.ts
+var AUDIT_COMMAND = "node node_modules/@godxjp/ui/scripts/ui-audit.mjs  (add --format json for machine output, --rules to print this catalog)";
+var AUDIT_RULES = [
+  // ── tokens (house design-system: semantic tokens only) ──────────────────
+  {
+    id: "no-raw-palette-color",
+    severity: "error",
+    category: "tokens",
+    standard: null,
+    fix: "Use semantic tokens (bg-primary, text-muted-foreground), never raw palette (bg-blue-500)."
+  },
+  {
+    id: "no-arbitrary-hex",
+    severity: "error",
+    category: "tokens",
+    standard: null,
+    fix: "No hardcoded hex in className; read design-system color tokens."
+  },
+  {
+    id: "no-arbitrary-spacing",
+    severity: "error",
+    category: "tokens",
+    standard: null,
+    fix: "No p-[13px]/gap-[7px]; use the token scale / <Flex gap> / <PageContainer>."
+  },
+  {
+    id: "no-arbitrary-size",
+    severity: "error",
+    category: "tokens",
+    standard: null,
+    fix: "No w-[37px]/h-[260px]; use token sizes or a sizing prop (min-w-[\u2026] allowed)."
+  },
+  {
+    id: "no-arbitrary-typography",
+    severity: "error",
+    category: "tokens",
+    standard: null,
+    fix: "No text-[20px]/leading-[1.7]; use the golden-ratio type-scale tokens."
+  },
+  {
+    id: "no-arbitrary-radius",
+    severity: "error",
+    category: "tokens",
+    standard: null,
+    fix: "No rounded-[6px]; use rounded-sm/md/lg radius tokens."
+  },
+  {
+    id: "no-dark-color-override",
+    severity: "warn",
+    category: "tokens",
+    standard: null,
+    fix: "Drop dark: color overrides \u2014 semantic tokens already adapt."
+  },
+  {
+    id: "raw-white-black",
+    severity: "warn",
+    category: "tokens",
+    standard: null,
+    fix: "Prefer semantic tokens (text-primary-foreground, bg-background) over raw white/black."
+  },
+  {
+    id: "no-domain-tracking-token",
+    severity: "error",
+    category: "tokens",
+    standard: null,
+    fix: "No package-tracking/domain tokens; use semantic tokens or app theme overrides."
+  },
+  {
+    id: "no-space-xy",
+    severity: "error",
+    category: "tokens",
+    standard: null,
+    fix: "Use <Flex gap> instead of space-x/y-*."
+  },
+  // ── composition (real primitives, no raw HTML / hand-rolled) ─────────────
+  {
+    id: "no-raw-select",
+    severity: "error",
+    category: "composition",
+    standard: "HTML Living Standard (WHATWG)",
+    fix: "Use <Select> from @godxjp/ui, not a raw <select>."
+  },
+  {
+    id: "no-raw-table",
+    severity: "error",
+    category: "composition",
+    standard: "HTML Living Standard (WHATWG)",
+    fix: "Use the <Table>/<DataTable> family, not a raw <table>."
+  },
+  {
+    id: "no-raw-input",
+    severity: "error",
+    category: "composition",
+    standard: "HTML Living Standard (WHATWG)",
+    fix: "Use <Input> from @godxjp/ui, not a raw <input>."
+  },
+  {
+    id: "no-raw-textarea",
+    severity: "warn",
+    category: "composition",
+    standard: "HTML Living Standard (WHATWG)",
+    fix: "Use <Textarea> from @godxjp/ui, not a raw <textarea>."
+  },
+  {
+    id: "no-raw-button",
+    severity: "error",
+    category: "composition",
+    standard: "HTML Living Standard (WHATWG)",
+    fix: "Use <Button> from @godxjp/ui, not a raw <button>."
+  },
+  {
+    id: "card-manual-padding",
+    severity: "error",
+    category: "composition",
+    standard: null,
+    fix: "Wrap the body in <CardContent>; don't hand-roll padding on <Card>."
+  },
+  {
+    id: "card-needs-content",
+    severity: "error",
+    category: "composition",
+    standard: null,
+    fix: "<Card> body must be in <CardContent> (no padding otherwise); flush only for a full-bleed table."
+  },
+  {
+    id: "bare-control-needs-formfield",
+    severity: "warn",
+    category: "composition",
+    standard: "WCAG 2.2 SC 1.3.1 \xB7 3.3.2 \xB7 @godxjp/ui FormField (cardinal rule 227)",
+    fix: "Wrap a labelled control in <FormField label=\u2026> \u2014 it owns label\u2194control id wiring, aria/error, AND the field rhythm; never pair a bare <Label> with an <Input>."
+  },
+  {
+    id: "manual-field-error",
+    severity: "warn",
+    category: "composition",
+    standard: "WCAG 2.2 SC 3.3.1",
+    fix: "Use <FormField error=\u2026>, not a hand-rolled <p class='text-destructive'>."
+  },
+  {
+    id: "manual-field-helper",
+    severity: "warn",
+    category: "composition",
+    standard: null,
+    fix: "Use <FormField helper=\u2026>, not a hand-rolled helper <p>."
+  },
+  // ── api (controlled-vocabulary props) ────────────────────────────────────
+  {
+    id: "status-tone-not-variant",
+    severity: "error",
+    category: "api",
+    standard: null,
+    fix: "Badge/Tag/StatCard status uses tone, not variant (variant is structural)."
+  },
+  {
+    id: "value-callback-on-value-change",
+    severity: "error",
+    category: "api",
+    standard: null,
+    fix: "Abstract value components use onValueChange, not onChange."
+  },
+  // ── a11y (WCAG 2.2 + WAI-ARIA APG) ───────────────────────────────────────
+  {
+    id: "icon-button-needs-name",
+    severity: "warn",
+    category: "a11y",
+    standard: "WCAG 2.2 SC 4.1.2 \xB7 1.1.1 \xB7 WAI-ARIA 1.2",
+    fix: "Add aria-label={t('\u2026')} to <Button size='icon'>; the glyph is aria-hidden."
+  },
+  {
+    id: "img-needs-alt",
+    severity: "warn",
+    category: "a11y",
+    standard: "WCAG 2.2 SC 1.1.1 \xB7 HTML Living Standard",
+    fix: "Add alt to every <img> (alt='' if decorative); prefer <Avatar>/<AspectRatio>."
+  },
+  {
+    id: "no-positive-tabindex",
+    severity: "warn",
+    category: "a11y",
+    standard: "WCAG 2.2 SC 2.4.3 \xB7 WAI-ARIA APG",
+    fix: "Use tabIndex 0 or -1 only; never positive \u2014 it breaks focus order."
+  },
+  {
+    id: "hand-rolled-close-glyph",
+    severity: "warn",
+    category: "a11y",
+    standard: "WAI-ARIA 1.2 (dialog) \xB7 WCAG 2.2 SC 4.1.2",
+    fix: "Pass onDismiss to <Alert>, or use <Dialog>/<Sheet>'s built-in labelled close \u2014 not a bare \u2715."
+  },
+  // ── i18n (ECMA-402 Intl + ISO + IANA) ────────────────────────────────────
+  {
+    id: "no-emoji-in-ui",
+    severity: "warn",
+    category: "i18n",
+    standard: "Unicode UTS #51 \xB7 WCAG 2.2 SC 1.1.1",
+    fix: "No emoji in product UI; quiet i18n copy + Lucide icon + Badge tone."
+  },
+  {
+    id: "no-emoji-flag",
+    severity: "warn",
+    category: "i18n",
+    standard: "ISO 3166-1 \xB7 ECMA-402 Intl.DisplayNames \xB7 Unicode UTS #51",
+    fix: "Derive country names from Intl.DisplayNames; no emoji flags."
+  },
+  {
+    id: "hardcoded-currency",
+    severity: "warn",
+    category: "i18n",
+    standard: "ISO 4217 \xB7 ECMA-402 Intl.NumberFormat",
+    fix: "Format money with Intl.NumberFormat({ style: 'currency', currency }), not \xA5{amount}."
+  },
+  {
+    id: "raw-intl-date",
+    severity: "warn",
+    category: "i18n",
+    standard: "ISO 8601 \xB7 IANA tz \xB7 ECMA-402 Intl.DateTimeFormat",
+    fix: "Use formatDate from @godxjp/ui/datetime, not hand-built or locale-default dates."
+  },
+  // ── rtl (CSS Logical Properties) ─────────────────────────────────────────
+  {
+    id: "no-physical-direction",
+    severity: "warn",
+    category: "rtl",
+    standard: "W3C CSS Logical Properties L1 \xB7 WCAG 2.2 (1.3.2)",
+    fix: "Use logical utilities (ms-/me-/ps-/pe-, start-/end-, text-start/end, border-s/e, rounded-s/e)."
+  },
+  // ── copy (dxs-kintai DNA) ────────────────────────────────────────────────
+  {
+    id: "no-em-dash-in-copy",
+    severity: "warn",
+    category: "copy",
+    standard: "@godxjp/ui dxs-kintai typography",
+    fix: "No em-dash (\u2014) in copy; use a middot \xB7 or two calm sentences."
+  }
+];
+function auditRulesByCategory(category) {
+  return category ? AUDIT_RULES.filter((r) => r.category === category) : AUDIT_RULES;
+}
+
+// src/data/visual-rules.ts
+var VISUAL_AUDIT_COMMAND = "node node_modules/@godxjp/ui/scripts/visual-audit.mjs <baseUrl> [route \u2026]  (needs optional peers: playwright + @axe-core/playwright + a chromium; --strict for a CI gate, --format json, --rules to print this catalog)";
+var VISUAL_RULES = [
+  {
+    id: "axe-violations",
+    severity: "warn",
+    category: "a11y",
+    standard: "WCAG 2.2 A/AA \xB7 WAI-ARIA 1.2 (axe-core engine)",
+    fix: "Fix each axe node \u2014 contrast (1.4.3), name/role/value (4.1.2), ARIA, landmarks. Runs on the REAL DOM, catching what static analysis cannot."
+  },
+  {
+    id: "target-size-min",
+    severity: "warn",
+    category: "a11y",
+    standard: "WCAG 2.2 SC 2.5.8 (24\xD724 AA) \xB7 2.5.5 (44\xD744 AAA)",
+    fix: "Interactive targets must be \u226524\xD724 CSS px; size from the --control-height tier."
+  },
+  {
+    id: "oversaturated-accent",
+    severity: "warn",
+    category: "color",
+    standard: "@godxjp/ui dxs-kintai \u6E0B\u307F (OKLCH chroma \u2264 0.18)",
+    fix: "Desaturate brand/primary surfaces (OKLCH chroma \u2264 0.18); read --primary tokens, no raw vivid bars."
+  },
+  {
+    id: "emoji-rendered",
+    severity: "warn",
+    category: "i18n",
+    standard: "Unicode UTS #51 \xB7 WCAG 2.2 SC 1.1.1",
+    fix: "Remove emoji from rendered product text; quiet i18n copy + Lucide icon + Badge tone."
+  },
+  {
+    id: "alert-controls-misplaced",
+    severity: "warn",
+    category: "layout",
+    standard: "@godxjp/ui Alert anatomy \xB7 WAI-ARIA 1.2 \xB7 WCAG 2.2 SC 4.1.2",
+    fix: "Use <Alert>: one leading tone icon, <Alert.Actions> trailing-right normal width, onDismiss \xD7 top-right, one horizontal row."
+  }
+];
+function visualRulesByCategory(category) {
+  return category ? VISUAL_RULES.filter((r) => r.category === category) : VISUAL_RULES;
+}
+
 // src/tools/registry.ts
 var TOOL_DEFINITIONS = [
   // ── DISCOVERY (small responses) ────────────────────────────────
@@ -10611,6 +11492,29 @@ var TOOL_DEFINITIONS = [
       }
     }
   },
+  {
+    name: "list_audit_rules",
+    description: "List the LOCAL ui-audit rules (scripts/ui-audit.mjs) an agent should run BEFORE any visual review. Each rule cites the international standard it enforces (WCAG 2.2 / WAI-ARIA / ECMA-402 Intl / ISO 4217\xB73166\xB78601 / IANA / CSS Logical Properties / HTML LS) + a concrete fix. Optionally filter by category. Includes the run command. ~3KB.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          enum: ["tokens", "composition", "api", "a11y", "i18n", "rtl", "copy"]
+        }
+      }
+    }
+  },
+  {
+    name: "list_visual_checks",
+    description: "List the RUNTIME visual-audit checks (scripts/visual-audit.mjs \u2014 Playwright + axe-core) to run against the RUNNING app BEFORE a visual review. Catches what source/static checks can't: colour contrast + ARIA (axe), target size (WCAG 2.5.8), OKLCH chroma of rendered accents (\u6E0B\u307F), emoji that reached the DOM, and a mis-laid-out notification banner. Separate from list_audit_rules (static, zero-dep) because it needs a browser. ~2KB.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: { type: "string", enum: ["a11y", "color", "i18n", "layout"] }
+      }
+    }
+  },
   // ── DRILL-DOWN (medium responses) ──────────────────────────────
   {
     name: "get_anti_ai_tell",
@@ -10806,6 +11710,10 @@ async function dispatchTool(name, args) {
       return listAntiAiTells(args.category);
     case "list_redesign_checks":
       return listRedesignChecks(args.category);
+    case "list_audit_rules":
+      return listAuditRules(args.category);
+    case "list_visual_checks":
+      return listVisualChecks(args.category);
     case "get_anti_ai_tell":
       return getAntiAiTell(String(args.name ?? ""));
     case "get_redesign_check":
@@ -11021,6 +11929,56 @@ function listPatterns() {
   }
   return out;
 }
+function listVisualChecks(cat) {
+  const list = visualRulesByCategory(cat);
+  let out = `# Runtime visual-audit checks${cat ? ` \u2014 ${cat}` : ""} (${list.length})
+
+`;
+  out += `_Run against the RUNNING app BEFORE a visual review (warnings, non-blocking). Needs a browser._
+`;
+  out += `\`\`\`
+${VISUAL_AUDIT_COMMAND}
+\`\`\`
+
+`;
+  out += `_Static \`list_audit_rules\` first (cheap, every save) \u2192 THIS (before review) \u2192 human eyes for taste._
+
+`;
+  for (const r of list) {
+    out += `- **${r.id}** (${r.severity}, ${r.category}) \u2014 _${r.standard}_
+  ${r.fix}
+`;
+  }
+  return out;
+}
+function listAuditRules(cat) {
+  const list = auditRulesByCategory(cat);
+  let out = `# Local UI-audit rules${cat ? ` \u2014 ${cat}` : ""} (${list.length})
+
+`;
+  out += `_Run BEFORE any visual review (warnings are agent guidance, non-blocking):_
+`;
+  out += `\`\`\`
+${AUDIT_COMMAND}
+\`\`\`
+
+`;
+  const grouped = list.reduce((acc, r) => {
+    (acc[r.category] ??= []).push(r);
+    return acc;
+  }, {});
+  for (const [c, items] of Object.entries(grouped)) {
+    out += `## ${c}
+`;
+    for (const r of items) {
+      out += `- **${r.id}** (${r.severity})${r.standard ? ` \u2014 _${r.standard}_` : ""}
+  ${r.fix}
+`;
+    }
+    out += "\n";
+  }
+  return out;
+}
 function listAntiAiTells(cat) {
   const list = cat ? aiTellsByCategory(cat) : ANTI_AI_TELLS;
   let out = `# AI tells to AVOID${cat ? ` \u2014 ${cat}` : ""} (${list.length})
@@ -11204,9 +12162,7 @@ function componentTokensFor(name) {
   const prefixes = TOKEN_PREFIXES[name] ?? [
     name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
   ];
-  return COMPONENT_TOKENS.filter(
-    (t) => prefixes.some((p) => t.name.startsWith(`--${p}-`))
-  );
+  return COMPONENT_TOKENS.filter((t) => prefixes.some((p) => t.name.startsWith(`--${p}-`)));
 }
 function getComponent(name) {
   const c = findComponent(name);
@@ -11718,7 +12674,7 @@ ${c.example}
 // package.json
 var package_default = {
   name: "@godxjp/ui-mcp",
-  version: "13.17.4",
+  version: "14.0.1",
   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",