@godxjp/ui-mcp 0.19.1 → 0.21.0

package/dist/index.js

@@ -712,9 +712,9 @@ function MyShell({ children }: { content: React.ReactNode }) {
     props: [
       {
         name: "variant",
-        type: '"default" | "destructive" | "outline" | "secondary" | "ghost" | "link"',
+        type: '"default" | "destructive" | "outline" | "dashed" | "secondary" | "ghost" | "link"',
         defaultValue: '"default"',
-        description: "Visual style."
+        description: "Visual style. `dashed` = outline with a dashed border (Ant-style add-row / placeholder action)."
       },
       {
         name: "size",
@@ -722,6 +722,12 @@ function MyShell({ children }: { content: React.ReactNode }) {
         defaultValue: '"default"',
         description: "Size preset (height, padding, icon dims)."
       },
+      {
+        name: "shape",
+        type: '"default" | "pill" | "sharp"',
+        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: "asChild",
         type: "boolean",
@@ -729,10 +735,21 @@ function MyShell({ children }: { content: React.ReactNode }) {
         description: "Render as Radix Slot \u2014 merge props onto the child (<a>/<Link>)."
       },
       { name: "disabled", type: "boolean", description: "Disable the button." },
+      {
+        name: "loading",
+        type: "boolean",
+        defaultValue: "false",
+        description: 'In-flight state \u2014 shows a leading `Loader2` spinner (replaces a leading icon if present), sets `aria-busy="true"`, and blocks activation (non-interactive, pointer-events disabled) while keeping the label visible so the width doesn\'t jump. Prefer this over a hand-rolled `<Loader2 className="animate-spin">` inside the button. Ignored when `asChild` (Slot requires a single child).'
+      },
+      {
+        name: "loadingText",
+        type: "string",
+        description: "Optional label to swap in while `loading` (pass the `t()`-translated string, e.g. `loadingText={t('saving')}`). When omitted the original children stay beside the spinner."
+      },
       {
         name: "onClick",
         type: "React.MouseEventHandler<HTMLButtonElement>",
-        description: "Click handler."
+        description: "Click handler. Does not fire while `loading` or `disabled`."
       }
     ],
     usage: [
@@ -741,7 +758,8 @@ function MyShell({ children }: { content: React.ReactNode }) {
       "DO use `asChild` to render the button as a React Router/Inertia `<Link>` or native `<a>` while keeping all button styling and a11y: `<Button asChild variant=\"outline\"><Link href={route('invoices.show', id)}>\u8A73\u7D30</Link></Button>`. Never wrap a `<button>` around an `<a>` \u2014 that is invalid HTML.",
       "DON'T use raw `<button>` elements anywhere in the UI \u2014 always use this `Button`. The only exception is an `aria-hidden` native control used as an e2e/a11y hook paired with a visible godx-ui control.",
       'DO set `type="submit"` explicitly on form submit buttons (the default HTML button type inside `<form>` is already `submit`, but being explicit prevents accidental double-submissions when a `type="button"` sibling exists). For cancel/reset actions set `type="button"` to avoid accidental form submission.',
-      "DON'T apply raw padding, height, or `rounded-*` overrides to `Button` via `className` \u2014 the size variants encode the full box model. If a custom size is truly needed, use `buttonVariants` from `@godxjp/ui/general` to compose a new cva class rather than fighting the existing ones."
+      "DON'T apply raw padding, height, or `rounded-*` overrides to `Button` via `className` \u2014 the size variants encode the full box model. If a custom size is truly needed, use `buttonVariants` from `@godxjp/ui/general` to compose a new cva class rather than fighting the existing ones.",
+      "DO use the `loading` prop for async/pending actions instead of hand-rolling `<Loader2 className=\"animate-spin\">` inside the button \u2014 `loading` renders the spinner, sets `aria-busy`, and blocks activation for you; pair with `loadingText={t('saving')}` to swap the label. For a TanStack Query refetch use `ButtonRefetch` (it owns its own loading lifecycle) rather than wiring `loading` manually."
     ],
     useCases: [
       'Primary form submission in a Dialog or Sheet (e.g. `<Button type="submit" disabled={form.processing}>\u4FDD\u5B58</Button>`) \u2014 the `disabled` prop greys it out and blocks pointer events, preventing double-submit during async operations.',
@@ -768,6 +786,98 @@ import { Trash2 } from "lucide-react";
     storyPath: "general/Button.stories.tsx",
     rules: [23]
   },
+  {
+    name: "Text",
+    group: "general",
+    tagline: 'Typographic primitive \u2014 use INSTEAD of a hand-rolled `<span className="text-[13px] font-medium text-muted-foreground">`. Size is a type-scale step (never px); tone/weight are tokens.',
+    props: [
+      {
+        name: "size",
+        type: '"2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"',
+        defaultValue: '"sm"',
+        description: "Golden-ratio type-scale step (2xs\u20262xl). NEVER an arbitrary px (`text-[13px]` is banned) \u2014 pick the nearest step."
+      },
+      {
+        name: "tone",
+        type: '"default" | "muted" | "primary" | "success" | "warning" | "destructive" | "info"',
+        defaultValue: '"default"',
+        description: "Semantic foreground colour. Replaces `text-muted-foreground` etc. on a raw span."
+      },
+      {
+        name: "weight",
+        type: '"regular" | "medium" | "bold"',
+        defaultValue: '"regular"',
+        description: "Font weight \u2014 the 3-weight canon: regular 400 (body), medium 500 (label), bold 700 (emphasis). 600/semibold is forbidden."
+      },
+      { name: "align", type: '"start" | "center" | "end"', description: "Logical text alignment." },
+      { name: "truncate", type: "boolean", description: "Single-line ellipsis." },
+      { name: "tabular", type: "boolean", description: "Tabular figures for aligned numbers." },
+      { name: "mono", type: "boolean", description: "Monospace family for codes / ids." },
+      {
+        name: "as",
+        type: '"span" | "p" | "div" | "label" | "strong" | "em" | "small" | "code" | "kbd" | "dt" | "dd" | "caption" | "abbr"',
+        defaultValue: '"span"',
+        description: "Rendered element. `code`/`kbd` are monospace by default."
+      }
+    ],
+    usage: [
+      "DO use `<Text>` for ALL body / inline / caption text instead of a styled `<span>`/`<p>`. Pick `size` from the scale; never write `text-[13px]`/`text-[11px]` or `font-semibold` by hand.",
+      'DO use `tone` for colour (`muted`/`primary`/semantic), `tabular` for numbers, `mono` for codes \u2014 not `className="text-muted-foreground font-mono tabular-nums"`.',
+      "For a heading, use `<Heading level>` instead of a large-size `<Text>`."
+    ],
+    useCases: [
+      'A muted caption under a value: `<Text size="xs" tone="muted">2026\u5E745\u6708\u5EA6</Text>`.',
+      'A monospace id in a list row: `<Text size="xs" mono tone="muted">RC-204881</Text>`.',
+      'An emphasized inline figure: `<Text weight="medium" tabular>\xA51,240,000</Text>`.'
+    ],
+    storyPath: "general/typography.tsx",
+    rules: [2, 23],
+    example: `import { Text } from "@godxjp/ui/general";
+
+<Text size="xs" tone="muted">\u88DC\u52A9\u30C6\u30AD\u30B9\u30C8</Text>
+<Text weight="medium" tabular>\xA51,240,000</Text>
+<Text size="xs" mono tone="muted">RC-204881</Text>`
+  },
+  {
+    name: "Heading",
+    group: "general",
+    tagline: "Section heading sized from the --heading-h* tokens. `level` sets the size AND the semantic <h1..h4>.",
+    props: [
+      {
+        name: "level",
+        type: "1 | 2 | 3 | 4",
+        defaultValue: "2",
+        description: "Heading level \u2014 sizes from --heading-h{1..4} and renders the matching <h*>."
+      },
+      {
+        name: "as",
+        type: '"h1" | "h2" | "h3" | "h4" | "div"',
+        description: "Override the rendered element (e.g. a visual h2 that is a real <h1>)."
+      },
+      {
+        name: "tone",
+        type: '"default" | "muted" | "primary" | "success" | "warning" | "destructive" | "info"',
+        defaultValue: '"default"',
+        description: "Semantic foreground colour."
+      },
+      { name: "align", type: '"start" | "center" | "end"', description: "Logical text alignment." },
+      { name: "truncate", type: "boolean", description: "Single-line ellipsis." }
+    ],
+    usage: [
+      'DO use `<Heading level>` for section titles instead of a raw `<h2 className="text-lg font-semibold">`. The level drives both the token size and the semantic element.',
+      "Inside a Card use `<CardTitle>`; use `<Heading>` for free-standing page/section headings not covered by a component slot."
+    ],
+    useCases: [
+      "A section heading on a dashboard: `<Heading level={3}>\u4ECA\u6708\u306EKPI</Heading>`.",
+      'A visually-smaller heading that must stay an <h1> for a11y: `<Heading level={1} as="h1">\u2026</Heading>`.'
+    ],
+    storyPath: "general/typography.tsx",
+    rules: [6, 23],
+    example: `import { Heading } from "@godxjp/ui/general";
+
+<Heading level={2}>\u8ACB\u6C42\u66F8\u4E00\u89A7</Heading>
+<Heading level={3} tone="muted">\u88DC\u8DB3\u30BB\u30AF\u30B7\u30E7\u30F3</Heading>`
+  },
   // ─── data-display ───────────────────────────────────────────────────────
   {
     name: "DataTable",
@@ -1015,6 +1125,13 @@ export default function InvoiceList({
       "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";
@@ -1225,14 +1342,25 @@ import { ResponsiveGrid } from "@godxjp/ui/layout";
     props: [
       {
         name: "variant",
-        type: '"default" | "secondary" | "outline" | "success" | "warning" | "destructive" | "info" | "neutral"',
+        type: '"default" | "secondary" | "outline" | "dashed"',
         defaultValue: '"default"',
-        description: "Visual variant. Overrides the auto-mapped status tone when status is provided."
+        description: "STRUCTURAL emphasis only (fill/border style) \u2014 NOT colour. Use `tone` for semantic colour. `dashed` = dashed border."
+      },
+      {
+        name: "tone",
+        type: '"default" | "success" | "warning" | "destructive" | "info" | "muted" | "neutral"',
+        description: "SEMANTIC colour intent (ToneProp). This is the colour knob \u2014 success/warning/destructive/info/etc. Keep variant for structure, tone for meaning."
+      },
+      {
+        name: "shape",
+        type: '"default" | "pill" | "sharp"',
+        defaultValue: '"default"',
+        description: "Corner radius from the tokens \u2014 `default` (badge radius), `pill` (fully rounded), `sharp` (square). Use the prop instead of a `rounded-*` className."
       },
       {
         name: "status",
         type: "string",
-        description: "Lifecycle key. Known keys auto-map to variant + icon + i18n label; unknown keys fall back to neutral."
+        description: "Lifecycle key. Known keys auto-map to tone + icon + i18n label; unknown keys fall back to neutral."
       },
       {
         name: "icon",
@@ -1801,6 +1929,119 @@ import { ResponsiveGrid } from "@godxjp/ui/layout";
     storyPath: "data-entry/Input.stories.tsx",
     rules: []
   },
+  {
+    name: "NumberInput",
+    group: "data-entry",
+    tagline: "WAI-ARIA spinbutton for localized numeric entry \u2014 composes the real Input (role=spinbutton, inputMode=decimal) with stacked increment/decrement step Buttons. Type freely, Arrow/Shift-Arrow step, value commits clamped to min/max + rounded to precision.",
+    props: [
+      {
+        name: "value",
+        type: "number | null",
+        description: "Controlled value. `null` = empty field. Pair with `onValueChange`."
+      },
+      {
+        name: "defaultValue",
+        type: "number | null",
+        defaultValue: "null",
+        description: "Uncontrolled initial value."
+      },
+      {
+        name: "onValueChange",
+        type: "(value: number | null) => void",
+        description: "Value change callback (vocabulary triad \u2014 NOT onChange). Receives `null` when the field is empty."
+      },
+      {
+        name: "min",
+        type: "number",
+        description: "Lower bound \u2014 clamps on commit and disables the decrement stepper at the floor."
+      },
+      {
+        name: "max",
+        type: "number",
+        description: "Upper bound \u2014 clamps on commit and disables the increment stepper at the ceiling."
+      },
+      {
+        name: "step",
+        type: "number",
+        defaultValue: "1",
+        description: "Increment for the steppers + ArrowUp/ArrowDown (Shift = \xD710)."
+      },
+      {
+        name: "precision",
+        type: "number",
+        description: "Committed decimal places. Inferred from `step` when omitted."
+      },
+      { name: "disabled", type: "boolean", description: "Disables typing and stepping." },
+      {
+        name: "readOnly",
+        type: "boolean",
+        description: "Value is shown and selectable but not typeable or steppable."
+      },
+      {
+        name: "size",
+        type: '"xs" | "sm" | "md" | "lg"',
+        defaultValue: '"md"',
+        description: "Control height tier (--control-height). Aligns with sibling controls on a row."
+      },
+      { name: "placeholder", type: "string", description: "Placeholder shown when empty." },
+      {
+        name: "prefix",
+        type: "React.ReactNode",
+        description: "Leading decorative affix inside the field (e.g. `\xA5`). aria-hidden."
+      },
+      {
+        name: "suffix",
+        type: "React.ReactNode",
+        description: "Trailing decorative affix inside the field (e.g. `%`). aria-hidden."
+      },
+      {
+        name: "name",
+        type: "string",
+        description: "Form field name \u2014 submits its value natively."
+      },
+      { name: "id", type: "string", description: "Associates with a <label htmlFor> / FormField." },
+      {
+        name: "aria-label",
+        type: "string",
+        description: "Accessible name for the spinbutton when no visible FormField label is present."
+      }
+    ],
+    usage: [
+      "DO use NumberInput (not `<Input type='number'>`) whenever numeric entry wants steppers, min/max clamping, precision rounding, or a \xA5/% affix \u2014 it is the canonical numeric primitive. Plain Input has no stepper and no clamp.",
+      "DO drive it controlled with `value` + `onValueChange` carrying `number | null` (the vocabulary triad \u2014 NOT `onChange`). `null` means the field is empty; never substitute 0 for empty.",
+      "DON'T pass `value` without `onValueChange` \u2014 like every controlled @godxjp/ui input it would freeze. Omit both for uncontrolled (use `defaultValue`).",
+      "DO set `step` to your increment and let `precision` (or the decimals of `step`) round the committed value: `step={0.25} precision={2}` gives quarter-step entry rounded to 2 places on blur/Enter.",
+      "DO set `min`/`max` for bounded quantities \u2014 the value clamps on commit and the matching stepper Button auto-disables at the bound. The steppers are tabIndex=-1 so they never pollute the keyboard tab order (Arrow keys cover keyboard stepping).",
+      "DON'T wrap it in a hand-rolled label/error markup \u2014 compose it inside FormField (matching `id`) for the aria wiring, exactly like Input.",
+      "DON'T format the value yourself for display \u2014 NumberInput formats at rest via Intl.NumberFormat in the active locale while keeping the raw value typeable on focus."
+    ],
+    useCases: [
+      "Quantity / line-item steppers in order, invoice, or cart forms (min={1}, step={1}) where \xB1 buttons and a floor are expected.",
+      "Price / amount fields with a currency affix (prefix='\xA5', step={10}) \u2014 the affix is decorative and the committed value stays a plain number.",
+      "Percentage / rate inputs bounded 0\u2013100 (suffix='%', min={0} max={100}).",
+      "Decimal measurements \u2014 weight, dimensions, exchange rates (step={0.25}, precision={2}) needing rounded commit.",
+      "Any bounded numeric setting (timeouts, retry counts, page sizes) where a slider is too coarse and a free Input lacks clamping."
+    ],
+    related: [
+      "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."
+    ],
+    storyPath: "data-entry/NumberInput.stories.tsx",
+    rules: [3, 6],
+    example: `import { NumberInput } from "@godxjp/ui/data-entry";
+
+<NumberInput
+  value={qty}
+  onValueChange={setQty}
+  min={1}
+  max={99}
+  step={1}
+  prefix="\xA5"
+  aria-label="\u6570\u91CF"
+/>`
+  },
   {
     name: "SearchInput",
     group: "data-entry",
@@ -3316,7 +3557,7 @@ export function InvoicePeriodFilter() {
         description: "Initial value for uncontrolled mode. Same shape as value."
       },
       {
-        name: "onChange",
+        name: "onValueChange",
         type: "(value: string[] | string[][], selectedOptions?: TreeOptionProp[] | TreeOptionProp[][]) => void",
         description: "Fires when selection changes. First arg is the selected path(s); second is the matching node objects. On clear, called with []."
       },
@@ -3500,7 +3741,7 @@ function MultiRegionPicker() {
         description: "Initial value for uncontrolled usage. Ignored once `value` is provided."
       },
       {
-        name: "onChange",
+        name: "onValueChange",
         type: "(value: string | string[] | undefined) => void",
         description: "Called on selection change. Returns `string` in single mode, `string[]` in multi/checkable mode, or `undefined` when cleared."
       },
@@ -6024,18 +6265,35 @@ export default function PasswordBlock() {
     group: "navigation",
     tagline: "Context menu primitives with keyboard support and compound parts for command-style action surfaces.",
     props: [
-      { name: "open", type: "boolean", description: "Controlled open state." },
       {
         name: "onOpenChange",
         type: "(open: boolean) => void",
         description: "Open-state callback."
       },
-      { name: "value", type: "string", description: "Selected value (for controlled patterns)." }
+      {
+        name: "modal",
+        type: "boolean",
+        defaultValue: "true",
+        description: "Modal mode \u2014 locks scroll + outside interaction while open. Set false to keep the rest of the page interactive."
+      },
+      {
+        name: "dir",
+        type: '"ltr" | "rtl"',
+        description: "Reading direction for arrow-key navigation (inherits from the document if omitted)."
+      }
+    ],
+    usage: [
+      "DO trigger this on `onContextMenu` (right-click / long-press), NOT on left-click \u2014 for a button that opens a list of actions on left-click use `DropdownMenu` instead. The two are not interchangeable.",
+      "DO wrap exactly the right-clickable surface in `<ContextMenuTrigger>` (a table row, a card, a file tile) \u2014 the menu anchors to the pointer position, so the trigger should be the whole interactive region the menu acts on.",
+      "DON'T put primary, always-visible actions only behind a context menu \u2014 right-click is a discoverability dead-end on touch and for new users. Mirror critical actions in a visible `Button`/`DropdownMenu` and use ContextMenu as an accelerator.",
+      'DO mark irreversible items with `variant="destructive"` (\u524A\u9664 / \u53D6\u308A\u6D88\u3057) and group them under a `<ContextMenuSeparator>`; use `<ContextMenuShortcut>` to show the keyboard accelerator, `<ContextMenuSub>`/`<ContextMenuSubTrigger>` for nested submenus, and `<ContextMenuCheckboxItem>`/`<ContextMenuRadioItem>` for stateful toggles.',
+      "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 action menu",
-      "Contextual menus for rows and cards",
-      "Nested action rows with shortcuts"
+      "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.",
+      "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)."
     ],
     storyPath: "navigation/ContextMenu.stories.tsx",
     rules: [3, 6],
@@ -6059,21 +6317,34 @@ export default function PasswordBlock() {
     group: "navigation",
     tagline: "Application menubar primitives (menus, sub-menus, and check/radio items).",
     props: [
+      {
+        name: "value",
+        type: "string",
+        description: "Controlled value of the currently-open menu (pair with onValueChange)."
+      },
       {
         name: "defaultValue",
         type: "string",
-        description: "Uncontrolled initial selected value."
+        description: "Uncontrolled initial open menu."
       },
       {
         name: "onValueChange",
         type: "(value: string) => void",
-        description: "Selection callback."
+        description: "Fires with the id of the menu that opened (or '' when all close)."
       }
     ],
+    usage: [
+      "DO reserve Menubar for a persistent, desktop-app-style command bar (\u30D5\u30A1\u30A4\u30EB / \u7DE8\u96C6 / \u8868\u793A \u2026) where multiple top-level menus sit side by side \u2014 moving the pointer across triggers opens the adjacent menu without an extra click.",
+      "DON'T use Menubar for primary site/page navigation (links between pages) \u2014 that is `NavigationMenu`. Menubar items run *commands*; NavigationMenu items *navigate*.",
+      "DON'T use Menubar when there is only one menu button \u2014 a single trigger that drops a list of actions is a `DropdownMenu`. Menubar earns its weight only with several coordinated menus.",
+      "DO compose the full structure: `<Menubar>` \u203A `<MenubarMenu>` \u203A `<MenubarTrigger>` + `<MenubarContent>` with `<MenubarItem>`; use `<MenubarSeparator>` to group, `<MenubarShortcut>` for accelerators, `<MenubarSub>` for nested menus, and `<MenubarCheckboxItem>`/`<MenubarRadioItem>` for view toggles.",
+      'DO mark destructive commands with `variant="destructive"` and give every item an `onSelect` handler \u2014 items are commands, so they should *do* something, not just close.'
+    ],
     useCases: [
-      "Top-bar application command menus",
-      "Workspace menus with nested items",
-      "Desktop-like navigation shells"
+      "Top-bar command menu for a back-office editor (\u30D5\u30A1\u30A4\u30EB / \u7DE8\u96C6 / \u8868\u793A / \u30D8\u30EB\u30D7) with shortcuts and submenus.",
+      "Workspace tool menus in an admin console where each menu groups a category of actions (\u30C7\u30FC\u30BF / \u30EC\u30DD\u30FC\u30C8 / \u8A2D\u5B9A).",
+      "Desktop-like application shell (e.g. an internal POS or accounting workstation) that mirrors native menubar conventions.",
+      "View-state toggles via MenubarCheckboxItem/MenubarRadioItem (e.g. \u8868\u793A \u203A \u30B0\u30EA\u30C3\u30C9\u7DDA\u3092\u8868\u793A, \u901A\u8CA8\u8868\u793A \u25B8 \xA5 / $)."
     ],
     storyPath: "navigation/Menubar.stories.tsx",
     rules: [3, 6],
@@ -6099,18 +6370,41 @@ export default function PasswordBlock() {
         defaultValue: '"horizontal"',
         description: "Main-axis arrangement for the nav menu."
       },
+      {
+        name: "value",
+        type: "string",
+        description: "Controlled value of the currently-open item (pair with onValueChange)."
+      },
       {
         name: "defaultValue",
         type: "string",
-        description: "Uncontrolled initial selected value."
+        description: "Uncontrolled initial open item."
       },
       {
         name: "onValueChange",
         type: "(value: string) => void",
-        description: "Selection callback."
+        description: "Fires with the id of the item whose dropdown opened (or '' when all close)."
+      },
+      {
+        name: "delayDuration",
+        type: "number",
+        defaultValue: "200",
+        description: "Hover delay (ms) before a trigger's content opens."
       }
     ],
-    useCases: ["Primary app navigation", "Sectioned marketing navigation", "Nested link groups"],
+    usage: [
+      "DO use NavigationMenu for primary *navigation* between pages/sections \u2014 items wrap `<NavigationMenuLink>` (an `<a>`), not command buttons. For command bars (\u30D5\u30A1\u30A4\u30EB/\u7DE8\u96C6 \u2026) use `Menubar`; for a single action drop-down use `DropdownMenu`.",
+      "DO render real links inside `<NavigationMenuLink asChild>` so SPA routers work: `<NavigationMenuLink asChild><Link href={route('reports.index')}>\u30EC\u30DD\u30FC\u30C8</Link></NavigationMenuLink>` \u2014 never nest a raw `<a>` directly with its own onClick navigation.",
+      "DO use `<NavigationMenuTrigger>` + `<NavigationMenuContent>` only when an item needs a rich dropdown panel (link groups, featured cards). Top-level items that go straight to a page should be a bare `<NavigationMenuLink>` with NO trigger.",
+      "DON'T use it as the app's left sidebar \u2014 for a persistent vertical app sidebar use `Sidebar`/`AppShell`. Set `orientation=\"vertical\"` only for an in-content vertical link menu, not the global shell.",
+      "DON'T hand-roll the hover/focus dropdown timing \u2014 the primitive manages open-on-hover with `delayDuration`, keyboard navigation, and the animated viewport for you."
+    ],
+    useCases: [
+      "Primary top navigation for an admin/portal app with dropdown panels grouping related pages (e.g. \u30EC\u30DD\u30FC\u30C8 \u25BE \u2192 \u58F2\u4E0A / \u7D4C\u8CBB / \u5165\u91D1).",
+      "Sectioned marketing or docs navigation with featured link cards inside NavigationMenuContent.",
+      "Nested link groups where one trigger reveals a multi-column panel of related destinations.",
+      "Vertical in-content navigation (orientation='vertical') for a settings or documentation area \u2014 distinct from the global Sidebar shell."
+    ],
     storyPath: "navigation/NavigationMenu.stories.tsx",
     rules: [3, 6],
     example: `import { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger } from "@godxjp/ui/navigation";
@@ -6128,12 +6422,53 @@ export default function PasswordBlock() {
     group: "layout",
     tagline: "Resizable panel group/child/handle primitives from react-resizable-panels.",
     props: [
-      { name: "id", type: "string", description: "Panel identifier for persistence." },
-      { name: "defaultSize", type: "number", description: "Initial panel size (percent/units)." },
-      { name: "minSize", type: "number", description: "Minimum size constraint." },
-      { name: "maxSize", type: "number", description: "Maximum size constraint." }
+      {
+        name: "orientation",
+        type: '"horizontal" | "vertical"',
+        defaultValue: '"horizontal"',
+        description: "ResizablePanelGroup prop \u2014 axis the panels are laid out / resized along (horizontal = side-by-side)."
+      },
+      {
+        name: "id",
+        type: "string",
+        description: "ResizablePanel identifier \u2014 required for collapse/expand control and for layout persistence."
+      },
+      {
+        name: "defaultSize",
+        type: "number",
+        description: "ResizablePanel initial size as a percentage (0\u2013100) of the group."
+      },
+      {
+        name: "minSize",
+        type: "number",
+        description: "ResizablePanel minimum size (%) \u2014 drag can't shrink below this."
+      },
+      { name: "maxSize", type: "number", description: "ResizablePanel maximum size (%)." },
+      {
+        name: "collapsible",
+        type: "boolean",
+        defaultValue: "false",
+        description: "ResizablePanel \u2014 allow the panel to collapse to collapsedSize when dragged below minSize. Pair with onResize to react to collapse."
+      },
+      {
+        name: "onResize",
+        type: "(size: PanelSize, id, prevSize) => void",
+        description: "ResizablePanel \u2014 fires while/after the panel is resized (e.g. to persist layout)."
+      }
+    ],
+    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.",
+      "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>`."
+    ],
+    useCases: [
+      "Master\u2013detail admin layout: a draggable list pane on the left and a detail/preview pane on the right (e.g. \u4ED5\u8A33\u4E00\u89A7 | \u4ED5\u8A33\u8A73\u7D30).",
+      "Collapsible filters or navigation rail beside a data table that operators can widen for long labels or tuck away to maximize the table.",
+      "Stacked vertical split (orientation='vertical') such as a results table over a live JSON/log preview in a data-import tool.",
+      "Three-pane workbench (nav | content | inspector) where each boundary is independently draggable and layout is persisted via id + onResize."
     ],
-    useCases: ["Split-pane layouts", "Resizable sidebars", "Code editors with adjustable zones"],
     storyPath: "layout/ResizablePanel.stories.tsx",
     rules: [3, 6],
     example: `import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from "@godxjp/ui/layout";
@@ -6162,10 +6497,23 @@ export default function PasswordBlock() {
       {
         name: "setApi",
         type: "(api: CarouselApi) => void",
-        description: "Receive carousel API for custom logic."
+        description: "Receive the Embla api for custom logic (autoplay, external prev/next). NOT needed for dots \u2014 CarouselDots reads the api from context itself."
       }
     ],
-    useCases: ["Feature cards", "Image galleries", "Horizontal stepping lists"],
+    usage: [
+      "DO compose the full set: `<Carousel>` \u203A `<CarouselContent>` \u203A many `<CarouselItem>`, with `<CarouselPrevious>`/`<CarouselNext>` for arrows and `<CarouselDots>` for the indicator row. Don't render items outside `<CarouselContent>` \u2014 the track is the scroll container.",
+      "DO use `<CarouselDots>` for the active-slide indicator instead of wiring `setApi` by hand \u2014 it reads `selectedIndex`/`scrollSnaps` from the Carousel context, renders one `aria-current` dot per snap, and auto-hides when there is \u22641 slide.",
+      "DON'T use a Carousel where ALL items must be seen/compared at once or be keyboard-reachable in reading order (e.g. a list of selectable options, a data table, primary navigation) \u2014 hiding content behind a swipe is an anti-pattern there; use a Grid/`ResponsiveGrid`, `ScrollArea`, or `Tabs`.",
+      "DON'T autoplay without a pause-on-hover/focus control and reduced-motion respect \u2014 pass the Embla autoplay plugin via `plugins` only for non-essential decorative content, never for content the user must read.",
+      "DO set `opts={{ loop: true }}` for galleries that wrap, and rely on the built-in disabling: `CarouselPrevious`/`CarouselNext` auto-disable at the ends (via `canScrollPrev`/`canScrollNext`) \u2014 don't hide them, let them grey out.",
+      "DO give each `<CarouselItem>` real, meaningful content; the component already injects an 'N of M' slide label for screen readers, so don't add a redundant one (a consumer `aria-label` on the item overrides the default)."
+    ],
+    useCases: [
+      "Feature / onboarding highlight cards on a dashboard or landing surface, with CarouselDots showing position.",
+      "Image or document thumbnail gallery (e.g. uploaded receipts / \u7269\u4EF6\u5199\u771F) with looping and prev/next arrows.",
+      "Horizontal stepping list of compact KPI or announcement cards that overflow the viewport width.",
+      "Product/plan comparison cards on a marketing page where swiping between a few options is acceptable (not the primary action)."
+    ],
     storyPath: "data-display/Carousel.stories.tsx",
     rules: [3, 6],
     example: `import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, CarouselDots } from "@godxjp/ui/data-display";
@@ -6197,10 +6545,28 @@ export default function PasswordBlock() {
         type: "(value: string) => void",
         description: "Validated value callback."
       },
-      { name: "step", type: "number", defaultValue: "1", description: "Minute step." },
+      {
+        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." }
     ],
-    useCases: ["Time filters", "Schedule pickers (calendar-free)", "HH:mm-only forms"],
+    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";
@@ -6671,6 +7037,11 @@ var CARDINAL_RULES = [
     number: 41,
     title: "Drawer & dialog footer layout",
     body: 'Sheet/Dialog/AlertDialog footers are a pinned action bar (Ant Design Drawer footer): the footer sticks to the bottom, SheetFooter draws a full-bleed top border, and actions are RIGHT-aligned with the PRIMARY button rightmost (Cancel/secondary to its left). A destructive / clear / reset action goes far-LEFT \u2014 give that button `className="mr-auto"`. NEVER stack footer buttons full-width or center them.'
+  },
+  {
+    number: 42,
+    title: "Props & Tokens Before Customization",
+    body: "Before reaching for a Tailwind class, inline `style`, or extra CSS, you MUST first check whether the component already supports the need via a PROP, a design TOKEN, or a layout/typography PRIMITIVE. godx-ui is meant to be enough on its own (Ant-Design-style): `className` is for genuine one-offs only \u2014 never to redo what an API already does. Specifically: (1) NEVER hand-roll typography \u2014 no `text-[13px]`/`text-[11px]` arbitrary px (bypasses the golden type scale), no `font-medium`/`font-semibold`/`text-muted-foreground` on a raw `<span>`; use `<Text size tone weight tabular mono>` / `<Heading level>`. (2) NEVER hand-roll a trivial flex/grid wrapper; use `<Flex>` / `<ResponsiveGrid>` / `<PageContainer>`. (3) NEVER set a control's radius/height/colour with a utility when a `shape`/`size`/`tone`/token exists. If a real need has NO prop/token/primitive, that is a library GAP \u2014 file it (draft_bug_report), don't paper over it with ad-hoc Tailwind."
   }
 ];
 function findRule(num) {
@@ -9633,7 +10004,10 @@ function lintJsx(jsx) {
   check(/<input[\s>]/, "Use `<Input>` instead of raw `<input>` (rule 29).");
   check(/<select[\s>]/, "Use `<Select>` instead of raw `<select>` (rule 29).");
   check(/<textarea[\s>]/, "Use `<Textarea>` instead of raw `<textarea>` (rule 29).");
-  check(/<(table|thead|tbody)[\s>]/, "Use `<DataTable>` instead of a hand-rolled `<table>` (rule 29).");
+  check(
+    /<(table|thead|tbody)[\s>]/,
+    "Use `<DataTable>` instead of a hand-rolled `<table>` (rule 29)."
+  );
   check(
     /bg-(red|blue|green|yellow|gray|slate|zinc|neutral|stone|orange|amber|lime|emerald|teal|cyan|sky|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}\b/,
     "Use semantic token utilities (`bg-primary`/`bg-destructive`) not raw color scales (rule 2)."
@@ -9646,6 +10020,10 @@ function lintJsx(jsx) {
     /size=["']default["']/,
     '`size="default"` is not in the controlled vocabulary \u2014 use `size` \u2208 xs|sm|md|lg.'
   );
+  check(
+    /\btext-\[[0-9.]+px\]/,
+    "Arbitrary text size `text-[Npx]` bypasses the golden type scale \u2014 use `<Text size>` / `<Heading level>` (rule 42)."
+  );
   check(
     /<Tag[\s\S]*?color=["']error["']/i,
     'Tag `color="error"` \u2192 `"destructive"` (v5.0, PR #60).'
@@ -9844,7 +10222,7 @@ ${c.example}
 // package.json
 var package_default = {
   name: "@godxjp/ui-mcp",
-  version: "0.19.1",
+  version: "0.21.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, 34 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",