@godxjp/ui 28.8.0 → 28.10.0

package/agent/START-HERE.md

@@ -0,0 +1,193 @@
+# @godxjp/ui — for AI agents
+
+You are about to write code against a design system you did not author. This file is the whole
+contract. Read it before you write JSX.
+
+**This catalog describes `@godxjp/ui` 28.10.0.** If the project you are editing has a different
+version in its `package.json`, read the pinned catalog for THAT version instead
+(`…/v<their-version>/agent/…`). A catalog newer than the installed package describes props that do
+not exist yet; older, and it hides props that do. Neither failure announces itself.
+
+Pinned catalogs only exist for releases whose tag actually contains `agent/`. If `…/v<version>/agent/index.json` returns 404, that release predates this catalog: read `…/main/…` instead and compare `index.json` → `version` against the package you have, so you at least know which way it drifted.
+
+---
+
+## Which lane are you in
+
+## Where to read these files
+
+Three places carry this catalog, and they are not equivalent:
+
+| source | URL / path | use it when |
+| --- | --- | --- |
+| docs site | `https://godx-jp.github.io/godxjp-ui/agent/…` | you are an assistant in a browser and can only fetch a URL |
+| npm package | `node_modules/@godxjp/ui/agent/…` | the project is on disk — this copy is **version-locked to the installed package by construction** |
+| raw GitHub | `https://raw.githubusercontent.com/godx-jp/godxjp-ui/v<version>/agent/…` | you need a version the other two cannot give you |
+
+Prefer the package copy when a project is in front of you: it cannot drift from what is installed,
+which is exactly the failure the version note above describes. The docs-site copy always describes
+the LATEST release, so pair it with the raw `v<version>` URL if the project is pinned to an older
+one.
+
+**You can run a process** (Claude Code · Codex CLI · Cursor · any client with MCP)
+→ Do not use these files. Run the MCP server; it is searchable, version-locked to the package on
+disk, and costs far fewer tokens than fetching a 1 MB JSON.
+
+```jsonc
+// .mcp.json — or let `npx @godxjp/ui sync-rules` write it for you
+{ "mcpServers": { "godx-ui": { "command": "npx", "args": ["@godxjp/ui-mcp@<installed version>"] } } }
+```
+
+Then ask it: `search_components`, `get_component`, `get_tokens`, `get_rule`, `list_anti_ai_tells`.
+
+**You cannot run a process** (ChatGPT web · Claude.ai · anything fetching URLs)
+→ These files are for you. Fetch in this order:
+
+0. `patterns-index.json` — 19 whole-task patterns as name + tagline + tags. **If your
+   task is a task** — "build a settings page", "confirm a destructive delete", "a list page with
+   filters" — start HERE, not at the components. Then fetch `patterns/<name>.json` for complete,
+   copy-paste-ready code. A component index answers "does X exist"; it cannot answer "build Y".
+1. `components-index.json` — 45 KB, all 170 components as name + group +
+   tagline. Read this when you already know the SHAPE you need. Each entry may carry `absorbed`:
+   names that **do not exist** and map to it — `Combobox`, `Autocomplete`, `CountrySelect` and
+   `SearchSelect` are all `Select`. If you are about to hand-roll something, search this field
+   first; it exists because that is the mistake.
+2. `components/<Name>.json` — one file per component (1 KB–33 KB, median 6 KB), carrying its props,
+   its `importPath`, and its examples. Fetch only the handful you picked in step 1.
+3. `rules.json` — 47 cardinal rules. The ones about raw HTML and hardcoded colour are not
+   style advice.
+4. `tokens.json` — 1684 design tokens. Only when you need a specific knob's name.
+5. `anti-ai-tells.json` — 26 shapes that make generated UI look generated, each with the
+   fix. Read before you reach for a gradient hero or a wall of coloured chips.
+
+**Do not fetch `components.json`.** It is 1.1 MB, and most URL fetchers truncate a
+response that size and return the head without telling you. You get the first few entries, believe
+you read the catalog, and answer the rest from memory — which is the failure this file exists to
+prevent. The per-component files say the same thing without the cliff.
+
+---
+
+## The four rules that decide whether your output is usable
+
+Everything else is detail. These four are why generated code gets rejected here.
+
+### 1. Never a raw HTML control
+
+No `<button>`, `<input>`, `<select>`, `<textarea>`, hand-rolled `<table>`. Use `Button`, `Input`,
+`Select`, `Textarea`, `DataTable`. A raw control has no focus ring, no size ladder, no RTL, and no
+dark mode — it *looks* fine in a screenshot and fails every gate this package ships.
+
+### 2. Never a colour, size or spacing literal
+
+Not `#6400D4`, not `color: rgb(...)`, not `p-[13px]`, not `height: 36px`. Reference the **role**:
+
+```tsx
+<Alert tone="warning">      {/* not: style={{ borderColor: "#B45309" }} */}
+<Button size="sm">          {/* not: className="h-8" */}
+<CardContent>               {/* not: <Card className="p-4"> */}
+```
+
+In CSS, reference the token by NAME so it re-resolves per theme and per tenant:
+
+```css
+color: var(--code-block-token-keyword-color, hsl(var(--primary)));   /* yes */
+color: #6400D4;                                                       /* no  */
+```
+
+### 3. Compose primitives fully
+
+Padding comes from `CardContent`, not from `p-4` on a bare `Card`. An empty table state comes from
+`DataTable`'s own empty, not from a `<div>` you wrote. If you find yourself styling a `<div>` to
+look like a component, the component exists — search the index.
+
+### 4. It is one control, not a family
+
+There is no `Combobox`, `Autocomplete`, `CountrySelect`, `SearchSelect`. There is `Select`, with
+`showSearch` and `loadOptions`. The i18n pickers are one `AppSettingPicker kind=…`. Components were
+deleted for being duplicates; do not add another by hand-rolling.
+
+This is not advice you have to remember — it is **data**. Every one of those names is in the
+`absorbed` field of the component that replaced it, in `components-index.json`, and
+`check:absorbed-names` fails the build if any of them ever becomes real. Search the name you were
+about to invent.
+
+---
+
+## Tokens: how to stay flexible
+
+The common failure is treating tokens as a **closed menu of approved layouts**. They are not.
+Tokens carry VALUES; composition, responsive behaviour and interaction are still yours.
+
+What keeps a token-first page flexible is the **scoped override contract** — the same knob, settable
+at three levels, each beating the one above:
+
+| level | how | reaches |
+|---|---|---|
+| theme | `:root { --card-radius: 0; }` | every Card in the product |
+| region / tenant | `[data-tenant="acme"] { --card-radius: 0; }` | one tenant, one section |
+| instance | `<Card className="…">` or the documented prop | this one Card |
+
+So: **build any layout you like out of primitives, and express every visual decision as a token or
+a documented prop.** You keep full freedom of composition and lose none of the theming. The moment
+you write a literal, that pixel stops following the theme and the tenant override silently skips it.
+
+A knob you want to retheme globally is a **component token** (`--{component}-{part}-{property}`).
+Most are declared `initial` with the real default at the call site — that is deliberate, so a
+scoped override re-resolves instead of freezing at `:root`.
+
+---
+
+## A page that would pass review
+
+```tsx
+import { PageContainer, Flex } from "@godxjp/ui/layout";
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, DataTable } from "@godxjp/ui/data-display";
+import { Button } from "@godxjp/ui/general";
+import { Select } from "@godxjp/ui/data-entry";
+import { Alert, AlertTitle, AlertDescription } from "@godxjp/ui/feedback";
+
+export default function InvoicesPage() {
+  return (
+    <PageContainer title="請求一覧" subtitle="今月の未収を上から">
+      <Flex direction="col" gap="lg">
+        <Alert tone="warning">
+          <AlertTitle>お支払いが確認できていません</AlertTitle>
+          <AlertDescription>3 件の請求が期限を過ぎています。</AlertDescription>
+        </Alert>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>未収</CardTitle>
+            <CardDescription>期限順。金額は税込。</CardDescription>
+          </CardHeader>
+          {/* `flush` because DataTable draws its own edges — a padded body double-insets it */}
+          <CardContent flush>
+            <DataTable data={rows} columns={columns} getRowId={(r) => r.id} striped />
+          </CardContent>
+        </Card>
+
+        <Flex direction="row" gap="sm" wrap>
+          <Select width="auto" options={statuses} defaultValue="unpaid" aria-label="状態" />
+          <Button variant="outline" size="sm">CSV</Button>
+        </Flex>
+      </Flex>
+    </PageContainer>
+  );
+}
+```
+
+Note what is absent: no colour, no pixel, no raw control, no `<div className="flex gap-4">` where
+`Flex` exists.
+
+**Take the import path from the catalog, not from the group.** Every entry in
+`components/<Name>.json` carries an `importPath`; it is the only one guaranteed to resolve. The
+group is a docs heading and does not always match a subpath — `AppProvider` is in group
+`providers`, and `@godxjp/ui/providers` does not exist (it is `@godxjp/ui/app`).
+
+---
+
+## Before you answer
+
+Say which catalog version you read and which files you actually fetched. If you could not fetch
+one, say so rather than filling the gap from memory — a prop invented from another library is the
+single most common failure here, and it looks exactly like a correct answer.

package/agent/anti-ai-tells.json

@@ -0,0 +1,158 @@
+[
+  {
+    "body": "The default LLM color palette — purple → blue → cyan radial /\nlinear gradient as hero background. Looks like every AI-generated\nSaaS landing page from 2023.",
+    "category": "visual",
+    "fix": "Use the framework's accent palette (`data-accent=\"blue\"` /\n\"violet\" / \"cyan\" / \"green\" / \"orange\" / \"rose\"). Solid surface\ncolors with semantic meaning. If you want depth, use a SINGLE\nsubtle gradient that supports brand (not decoration).",
+    "name": "Purple-blue gradient hero"
+  },
+  {
+    "body": "Frosted-glass cards stacked on a colorful blurry background.\nLooked novel in 2020 — now a tell that the designer reached for\ntrend instead of solving a problem.",
+    "category": "visual",
+    "fix": "Solid surface tiers (Card on background, Popover on Card,\nDialog on backdrop). The framework's elevation system already\nencodes 3 surface tiers — use them.",
+    "name": "Glassmorphism without purpose"
+  },
+  {
+    "body": "Random gradient blobs floating behind content with no narrative\npurpose. The \"creative space-filler\" AI pattern. Reads as\ndistracting noise.",
+    "category": "visual",
+    "fix": "If the page needs visual interest, use a REAL image (product\nphoto, founder photo, branded illustration). If you need\n\"breathing room\", use whitespace. Never use shapes as filler.",
+    "name": "Ambient blobs / floating shapes"
+  },
+  {
+    "body": "Every Card / Button / Input with `border-radius: 24px`. Reads\nas \"I picked one radius and applied it globally\". Premium design\nuses ROLES — small radius on inputs (4-6px), medium on cards\n(8-12px), pill on chips (full).",
+    "category": "visual",
+    "fix": "Use the framework's radius scale (`--radius-sm | -md | -lg | -full`).\nEach primitive defaults to the right role; only override when the\ndesign canon specifically calls for it.",
+    "name": "Oversized border-radius on everything"
+  },
+  {
+    "body": "Row of Tags / Badges each in a different color (red, orange,\nyellow, green, blue, purple) — usually navigation or filter\ncategories. Reads as chaos; eye can't anchor.",
+    "category": "visual",
+    "fix": "Pick ONE accent for the tag row. Use `appearance` (\"soft\" vs\n\"solid\" vs \"outline\") for variety within the same hue. Reserve\nnon-neutral colors (success / warning / destructive) for tags\nthat genuinely carry that meaning.",
+    "name": "Rainbow chip wall"
+  },
+  {
+    "body": "Full-bleed, fully-saturated brand color on buttons, banners and\nnotification bars (the classic loud Slack/Linear/Notion blue) — the\naccent SCREAMS instead of signalling. A bright primary CTA bar across\nthe whole width, vivid send buttons, neon success. It reads as a\nverbatim copy of a SaaS chrome, not a restrained product surface.",
+    "category": "visual",
+    "fix": "渋み (restraint): keep --primary chroma ≤ 0.18 — desaturate so the\naccent BLENDS with the warm-neutral spine and is used sparingly for\nthe ONE primary action. Don't paint a full-width bar in raw blue;\nprefer a quiet Alert (icon + text + a normal-width action). Never\nhard-code a vivid hex — read `bg-primary`/`text-primary` tokens, and\nlet a service retheme via --primary only.",
+    "name": "Oversaturated brand accent"
+  },
+  {
+    "body": "Homepage with a 4x2 grid of \"stat cards\" — each with an icon, a\nnumber, a sparkline, a delta. None of them relate to a real\nbusiness question; they were chosen because \"more cards = more\ndata\". Classic AI dashboard slop.",
+    "category": "layout",
+    "fix": "Show 1-2 hero metrics (the ones executives ASK about), then the\ntop action list (orders waiting, tasks due, alerts). If the user\nneeds more analytics, link to a dedicated Reports page.",
+    "name": "8-card stat dashboard"
+  },
+  {
+    "body": "Mobile screen rendered as a vertical strip with the same density\n+ same layout as desktop — just narrower. Cramped tap targets,\nhorizontal scrolling for overflow, no system bar awareness.",
+    "category": "layout",
+    "fix": "Mobile is its OWN design. Use full-width inputs (`block` Button),\nstacked layout, larger tap targets, Sheet/Drawer for secondary\ncontent, system-bar safe area. The framework's `useBreakpoint`\n+ Tailwind `sm:` variants give you the canvas.",
+    "name": "Phone-shaped website"
+  },
+  {
+    "body": "10+ tabs at the top of a screen, no priority. User has to read all\nof them to find the right one. AI default: \"more tabs = more\nfeatures = better\".",
+    "category": "layout",
+    "fix": "2-4 tabs max. If you have more categories, use a sidebar (Sidebar),\nor a Cascader / Tree picker. Tabs are for switching between PEERS\n(2-4 mutually exclusive views of the same data).",
+    "name": "Wall-of-tabs navigation"
+  },
+  {
+    "body": "5 onboarding steps where every screen has the same headline +\nillustration + 2 buttons layout. Reads as \"I copy-pasted the\ntemplate\" — and devalues the user's time at each step.",
+    "category": "layout",
+    "fix": "Each step has a distinct visual + interactive feel. Step 1 might\nbe a centered question, step 2 a side-by-side comparison, step 3\na multi-field form, step 4 a single yes/no card. Same palette +\ntype system for coherence; different composition for engagement.",
+    "name": "Identical clone screens"
+  },
+  {
+    "body": "A notification / \"enable X\" bar where the pieces are stacked\nVERTICALLY and mis-placed: the icon floats centered ABOVE the text\n(often a SECOND redundant icon on the far left too), the primary\naction is a FULL-WIDTH colored bar UNDER the text, and the dismiss ×\nsits centered at the BOTTOM on its own line. It's a hand-rolled\nbanner that ignores the framework's Alert anatomy.",
+    "category": "layout",
+    "fix": "Use <Alert> and respect its fixed anatomy — ONE leading tone icon\nat the inline-start (top-aligned, auto by `tone`, never two), the\ntext body, an <Alert.Actions> with a NORMAL-WIDTH Button in the\ntrailing-right column, and `onDismiss` to render the × in the\nTOP-RIGHT corner. It is ONE horizontal row, never a vertical stack;\nnever hand-roll the ✕ or a full-bleed action bar.",
+    "name": "Stacked notification banner (misplaced alert controls)"
+  },
+  {
+    "body": "Emoji sprinkled through the product surface — ✅ / 🎉 / 🔥 in chat\nmessages, status lines, toasts, buttons, empty states or success\nbanners (\"All tests green 🎉\", \"done ✅\"). It reads as casual\nconsumer-app slop, breaks on Windows/Linux, and pollutes the\naccessible name. Celebrating with confetti/🎉 is the same tell.",
+    "category": "copy",
+    "fix": "No emoji anywhere in product UI. State the fact quietly in\ni18n-keyed copy (\"承認しました\" / \"All checks passed\"). Use a Lucide\nicon (1.5px) for an affordance and a semantic Badge `tone`\n(success/warning/destructive) for status — color + label carry the\nmeaning, not a glyph. Country names come from `Intl.DisplayNames`,\nnever emoji flags.",
+    "name": "Emoji in product UI"
+  },
+  {
+    "body": "\"Elevate your potential\", \"unlock seamless productivity\",\n\"transform your workflow\", \"next-generation experience\". Reads as\nnothing because it MEANS nothing.",
+    "category": "copy",
+    "fix": "Write what the feature DOES, specifically. \"Sync 1,000 rows in 2\nseconds\" beats \"Lightning-fast performance\". \"Replaces 3 manual\nsteps\" beats \"Streamline your workflow\".",
+    "name": "Filler corporate phrases"
+  },
+  {
+    "body": "Acme, NovaCore, Flowbit, Quantix, VeloPay, Lumen, Apex — the\ngo-to AI brand names that scream \"I couldn't think of one\".",
+    "category": "copy",
+    "fix": "Use believable real-sounding names: 株式会社ABC商事, Tanaka\nTrading, Yokohama Coffee Roasters, Mountain View Bakery. Or use\nyour actual project's brand if known.",
+    "name": "Generic brand placeholders"
+  },
+  {
+    "body": "\"Get started\", \"Begin your journey\", \"No items yet\" — without\nsaying WHAT to do or WHY there's nothing.",
+    "category": "copy",
+    "fix": "Be specific + actionable: \"まだ注文がありません。商品を追加して\n最初の注文を作成しましょう。\" + a clear next-action Button.\nEmpty states are TEACHING MOMENTS — use them to onboard.",
+    "name": "Vague empty-state copy"
+  },
+  {
+    "body": "\"Sorry, something went wrong\" / \"An error has occurred\" — no\ninformation about WHAT, no recovery action.",
+    "category": "copy",
+    "fix": "Specific + actionable: \"メールアドレスの形式が正しくありません\n(例: name@example.com)\". For server errors: \"通信エラー\n(再試行 ボタン)\". Never apologise if you can't say what failed\nor what to do.",
+    "name": "Apologetic / passive-voice error messages"
+  },
+  {
+    "body": "Action buttons that only appear on hover (table row actions\nhidden until mouseover). Breaks on mobile (no hover), inaccessible\n(keyboard users can't discover).",
+    "category": "interaction",
+    "fix": "Show actions inline or in a kebab menu (DropdownMenu) that's\nALWAYS visible. If you must hide on desktop for density, ensure\nthe same actions are reachable via keyboard (Tab to row, Enter to\nexpand a row-actions DropdownMenu).",
+    "name": "Hover-only affordances"
+  },
+  {
+    "body": "Hero carousel that rotates every 3 seconds. Users haven't\nfinished reading slide 1; now slide 2 is gone. Accessibility\nnightmare (cognitive load, motion-sensitive).",
+    "category": "interaction",
+    "fix": "Carousel ONLY rotates on explicit user action (arrow click,\ndot click, swipe). It has no autoplay prop and never rotates on its\nown — that is the default and there is nothing to turn off.",
+    "name": "Auto-advancing carousel"
+  },
+  {
+    "body": "Cards / list items reorderable by long-press anywhere — no\nvisual indicator that they ARE draggable. Users discover it by\naccident or never.",
+    "category": "interaction",
+    "fix": "Show a drag handle icon (`<GripVertical>`) on the left of the\nrow. Users see it, understand \"this row is draggable\", reach for\nit deliberately.",
+    "name": "Drag-without-handle"
+  },
+  {
+    "body": "`outline: none` on focus to \"look cleaner\". Keyboard users\ncan't see where they are; total navigation failure.",
+    "category": "interaction",
+    "fix": "Use `:focus-visible` (Radix primitives do automatically) so the\nring shows on keyboard focus, hides on mouse-click. Don't strip.",
+    "name": "Disappearing focus ring"
+  },
+  {
+    "body": "Empty state / About page with a photo of a \"diverse team in an\nopen office laughing at a laptop\". Reads as 2010 corporate stock.\nNo relationship to your product.",
+    "category": "imagery",
+    "fix": "Real photos of YOUR team / users (with consent), product\nscreenshots, branded illustrations. Avatar's INITIALS fallback is\nbetter than a generic stock person.",
+    "name": "Stock photo of generic smiling team"
+  },
+  {
+    "body": "Empty state with a chrome / pastel 3D icon (coin, key, shield)\nfloating in the center. Looks like every NFT marketplace from\n2021.",
+    "category": "imagery",
+    "fix": "Simple lucide-react line icon (`<Inbox size={48} />`) +\ndescriptive title. Or a flat illustration matching the brand\npalette. Skip the 3D entirely unless your brand IS 3D.",
+    "name": "Floating 3D crypto icon"
+  },
+  {
+    "body": "Page sections with a colorful gradient mesh (\"Stripe-style\")\nbehind text. Looks \"premium\" until you realize every AI design\nuses it. Often hurts text contrast.",
+    "category": "imagery",
+    "fix": "Solid background (`--background`). If you need depth, use a\nsubtle 1px border + `--card` background tint. Reserve high-effort\nbackgrounds for pages where they matter (marketing hero, product\nshowcase) — not every internal screen.",
+    "name": "Decorative gradient mesh background"
+  },
+  {
+    "body": "Settings page with 40 form fields in a single scroll. User\nloses their place, can't find the field they came for.",
+    "category": "structure",
+    "fix": "Section the form with `<Typography.Title size={5}>` subheaders\n+ `<Separator />`. Group by concern (基本情報 / 公開範囲 / 通知 /\nセキュリティ). If 40 fields is still too many, split into Tabs\nor a Sidebar-driven multi-page settings flow.",
+    "name": "Settings as one long form"
+  },
+  {
+    "body": "Click a Button → Dialog opens → click \"Edit\" → another Dialog\nopens → click \"Confirm\" → AlertDialog opens. Triple stack;\nuser loses context.",
+    "category": "structure",
+    "fix": "Use Sheet for the FIRST level (side panel), Dialog for the\nconfirm. Or, redesign the flow so the edit is INLINE in the\nfirst Dialog (no second Dialog needed). AlertDialog for confirm\nis correct — but ONE deep, not three.",
+    "name": "Modal-in-modal-in-modal"
+  },
+  {
+    "body": "Page-level spinner while data loads. User stares at an empty\nshell with a centered spinner. Layout shifts when content\narrives.",
+    "category": "structure",
+    "fix": "Use Skeleton placeholders matching the eventual content shape.\nRender `<Skeleton className=\"h-9 w-full\" />` in place of each control\n— inside the FormField that will hold it, so the labels and grid stay\nput. Height and fill are this screen's measurements; never add a\n`rounded-*`, because Skeleton already carries the radius token. Layout stays stable, perceived speed improves.",
+    "name": "Spinner-only loading state"
+  }
+]

package/agent/components/Accordion.json

@@ -0,0 +1,60 @@
+{
+  "example": "import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from \"@godxjp/ui/data-display\";\n\n<Accordion type=\"single\" collapsible>\n  <AccordionItem value=\"ship\">\n    <AccordionTrigger>配送について</AccordionTrigger>\n    <AccordionContent>3〜5営業日でお届けします。</AccordionContent>\n  </AccordionItem>\n</Accordion>",
+  "group": "data-display",
+  "importPath": "@godxjp/ui/data-display",
+  "name": "Accordion",
+  "props": [
+    {
+      "description": "single = one open at a time; multiple = independent.",
+      "name": "type",
+      "required": true,
+      "type": "\"single\" | \"multiple\""
+    },
+    {
+      "description": "When type=single, allow closing the open item.",
+      "name": "collapsible",
+      "type": "boolean"
+    },
+    {
+      "description": "Controlled open item(s).",
+      "name": "value",
+      "type": "string | string[]"
+    },
+    {
+      "description": "Uncontrolled initial open item(s).",
+      "name": "defaultValue",
+      "type": "string | string[]"
+    },
+    {
+      "description": "Open-state callback.",
+      "name": "onValueChange",
+      "type": "(value: string | string[]) => void"
+    }
+  ],
+  "related": [
+    "Collapsible (single open/close region, no item set)",
+    "Tabs (mutually-exclusive views, always one visible)"
+  ],
+  "rules": [
+    3,
+    6
+  ],
+  "storyPath": "data-display/Accordion.stories.tsx",
+  "subParts": [
+    "AccordionContent",
+    "AccordionItem",
+    "AccordionTrigger"
+  ],
+  "tagline": "Radix accordion — vertically stacked, collapsible sections. Compose Accordion > AccordionItem > AccordionTrigger + AccordionContent.",
+  "usage": [
+    "DO compose the full set: <Accordion type=\"single\" collapsible><AccordionItem value=\"a\"><AccordionTrigger/><AccordionContent/></AccordionItem></Accordion>.",
+    "DO give each AccordionItem a unique `value`.",
+    "DON'T use it for primary navigation — that's Sidebar/Tabs. Accordion is for collapsible content/FAQ."
+  ],
+  "useCases": [
+    "FAQ lists",
+    "Grouped settings sections",
+    "Collapsible detail panels on a record page",
+    "Filter facet groups in a sidebar"
+  ]
+}

package/agent/components/AccountChip.json

@@ -0,0 +1,59 @@
+{
+  "example": "import { AccountChip } from \"@godxjp/ui/layout\";\n\n<PageContainer title=\"Bug report\" extra={<><Button variant=\"outline\">History</Button><AccountChip name={user.name} email={user.email} actionLabel={t(\"auth.signOut\")} onAction={signOut} /><Button>Send</Button></>}>…</PageContainer>",
+  "group": "layout",
+  "importPath": "@godxjp/ui/layout",
+  "name": "AccountChip",
+  "props": [
+    {
+      "description": "Display name; its first character is the avatar fallback.",
+      "name": "name",
+      "required": true,
+      "type": "string"
+    },
+    {
+      "description": "Shown as the chip's title (hover / assistive tooltip).",
+      "name": "email",
+      "type": "string"
+    },
+    {
+      "description": "Optional avatar image URL.",
+      "name": "avatarSrc",
+      "type": "string"
+    },
+    {
+      "description": "Overrides the first-character fallback.",
+      "name": "avatarFallback",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Accessible name of the action button, e.g. a localized sign-out label.",
+      "name": "actionLabel",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Action handler; omit it to render no button.",
+      "name": "onAction",
+      "type": "() => void"
+    },
+    {
+      "description": "Disables the action button.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "description": "Optional structural class override.",
+      "name": "className",
+      "type": "string"
+    }
+  ],
+  "rules": [
+    40
+  ],
+  "storyPath": "layout/AccountChip.stories.tsx",
+  "tagline": "Signed-in user for a PageContainer extra slot, Topbar or footer row: avatar, name and one ghost action at the control tier height — never a hand-rolled rounded-full border div.",
+  "usage": [
+    "Put it in PageContainer `extra` beside Buttons and a Select width=\"auto\": every control in that row shares --control-height.",
+    "Pass a localized actionLabel with onAction; the component owns no route, session or permission behaviour.",
+    "DO compose from the package (it is Avatar + Text + Button in a Flex row); DON'T hand-roll <div className=\"inline-flex rounded-full border py-0.5\"> — it drifts from the control height and the audit flags it (no-hand-rolled-surface)."
+  ]
+}

package/agent/components/Actions.json

@@ -0,0 +1,78 @@
+{
+  "docPath": "general/actions.tsx",
+  "example": "import { Actions, ActionsCopy, ActionsFeedback } from \"@godxjp/ui/general\";\nimport { RefreshCw, Share2 } from \"lucide-react\";\n\n<Actions\n  label=\"回答の操作\"\n  items={[\n    { key: \"retry\", label: \"やり直す\", icon: <RefreshCw />, onItemClick: () => regenerate() },\n    {\n      key: \"more\",\n      label: \"その他\",\n      subItems: [{ key: \"share\", label: \"共有\", icon: <Share2 /> }],\n    },\n    { key: \"copy\", actionRender: <ActionsCopy text={answer} /> },\n    { key: \"feedback\", actionRender: <ActionsFeedback value={vote} onChange={setVote} /> },\n  ]}\n  onClick={({ key }) => run(key)}\n/>",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Actions",
+  "props": [
+    {
+      "description": "The actions: { key, label?, icon?, onItemClick?, danger?, subItems?, actionRender? }. `label` is the accessible name AND the tooltip. `subItems` folds the action into a menu; `actionRender` replaces it entirely.",
+      "name": "items",
+      "required": true,
+      "type": "ActionsItemsProp[]"
+    },
+    {
+      "description": "Fires for any action WITHOUT its own onItemClick — a per-item handler wins and this does not also fire, exactly as in Ant Design X. A sub-item reports keyPath [subKey, parentKey].",
+      "name": "onClick",
+      "type": "(info: { item, key, keyPath, domEvent }) => void"
+    },
+    {
+      "defaultValue": "\"borderless\"",
+      "description": "Chrome of the STRIP, not the intent of the buttons (that is `danger` per item).",
+      "name": "variant",
+      "type": "\"borderless\" | \"filled\" | \"outlined\""
+    },
+    {
+      "description": "The strip fades in on mount. Zeroed under prefers-reduced-motion.",
+      "name": "fadeIn",
+      "type": "boolean"
+    },
+    {
+      "description": "The same fade, arriving along the LOGICAL inline axis (so it mirrors under dir=rtl).",
+      "name": "fadeInLeft",
+      "type": "boolean"
+    },
+    {
+      "description": "Accessible name of the toolbar (a plain string). Localized default otherwise.",
+      "name": "label",
+      "type": "string"
+    },
+    {
+      "description": "DOM id of the strip.",
+      "name": "id",
+      "type": "string"
+    }
+  ],
+  "related": [
+    "Toolbar / FilterBar — the list-page filter strip. Actions is the per-message action cluster, not a page-level control bar.",
+    "DropdownMenu — what `subItems` renders; compose it directly when the menu is not one action in a strip.",
+    "ChatBubble — the message the strip belongs to.",
+    "CredentialReveal — a copy affordance for a SECRET field; ActionsCopy copies message text."
+  ],
+  "rules": [
+    2,
+    6,
+    23,
+    44,
+    45
+  ],
+  "storyPath": "general/Actions.stories.tsx",
+  "subParts": [
+    "ActionsItem",
+    "ActionsCopy",
+    "ActionsFeedback"
+  ],
+  "tagline": "The strip of actions under an assistant message (Ant Design X Actions): copy, retry, like, and a menu for the rest — a WAI-ARIA toolbar with ONE tab stop, where Ant X's own strip is <div onClick> with no role and no accessible name.",
+  "usage": [
+    "DO give every action a `label`. It becomes the accessible name and the tooltip; without one the key is used, which is better than nameless but worse than a sentence.",
+    "DO use `subItems` once the strip passes about five actions — it folds them behind one trigger instead of widening the row under every message.",
+    "DO reach for ActionsCopy and ActionsFeedback instead of hand-rolling copy and thumbs: ActionsCopy announces the copy through a live region (a tick alone is invisible to a screen reader), and ActionsFeedback keeps BOTH buttons on screen with aria-pressed rather than hiding the one you did not pick.",
+    "DON'T put a form control in the strip. It is a toolbar of buttons with one tab stop; a field inside would be unreachable by Tab.",
+    "DON'T expect `dropdownProps`, `triggerSubMenuAction`, `styles` or `classNames` from Ant Design X — they are not ported; the strip is retuned through the --actions-* tokens."
+  ],
+  "useCases": [
+    "Under an assistant answer: copy, regenerate, like/dislike, and a menu with share and report.",
+    "Under a streaming answer: an ActionsItem with status=\"running\" while the audio plays back, error when it fails.",
+    "In a message hover strip inside ChatBubbleList."
+  ]
+}

package/agent/components/Activity.json

@@ -0,0 +1,80 @@
+{
+  "absorbed": [
+    "Spin",
+    "Spinner",
+    "Loading",
+    "LoadingIndicator"
+  ],
+  "example": "import { Activity } from \"@godxjp/ui/general\";\n\n// a channel typing indicator — no live region by default (it flickers with every socket event)\n<Activity label={t(\"channel.typing\", { name: \"佐藤\" })} />\n\n// an ambient sync mark in a header\n<Activity variant=\"bar\" tone=\"info\" label={t(\"sync.running\")} />\n\n// a reconnect notice that must actually be heard, announced once and politely\n<Activity announce=\"polite\" tone=\"warning\" label={t(\"realtime.reconnecting\")} />",
+  "group": "general",
+  "importPath": "@godxjp/ui/general",
+  "name": "Activity",
+  "props": [
+    {
+      "defaultValue": "\"dots\"",
+      "description": "The mark. `dots` = three dots rising in sequence, the ellipsis convention (someone is typing). `pulse` = a single breathing mark (live / recording). `bar` = an indeterminate sweep (syncing / streaming).",
+      "name": "variant",
+      "type": "\"dots\" | \"pulse\" | \"bar\""
+    },
+    {
+      "defaultValue": "\"sm\"",
+      "description": "Size step. Default `sm` — an ambient mark is never the loudest thing on screen. Scales the mark AND the label together (the mark is em-based off `--activity-font-size-*`).",
+      "name": "size",
+      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\""
+    },
+    {
+      "defaultValue": "\"muted\"",
+      "description": "Semantic colour intent for the mark and the label.",
+      "name": "tone",
+      "type": "\"default\" | \"muted\" | \"primary\" | \"success\" | \"warning\" | \"destructive\" | \"info\" | \"inherit\""
+    },
+    {
+      "description": "Localized description of WHAT is happening ('佐藤さんが入力しています…', 'Hưng đang nhập…'). Rendered as visible Text beside the mark when `children` are absent; when `children` ARE present it becomes an sr-only description instead. Consumer-owned copy — the library never invents it, and 'N people are typing' must be pluralized with the consumer's Intl.PluralRules.",
+      "name": "label",
+      "type": "ReactNode"
+    },
+    {
+      "description": "Richer visible content in place of `label` (a name in a <strong>, a Badge…). The mark stays aria-hidden; pass `label` alongside for the sr-only description.",
+      "name": "children",
+      "type": "ReactNode"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Announce the label to assistive technology. Default `false` and then NO live region is emitted at all — the DELIBERATE default, because an ambient indicator that fires a live region on every socket event is a screen-reader flood. `'polite'` wraps ONLY the label in one aria-live='polite' aria-atomic='true' region; the mark stays outside it and aria-hidden.",
+      "name": "announce",
+      "type": "false | \"polite\""
+    }
+  ],
+  "related": [
+    "Reveal — the one-shot ENTRANCE counterpart. Reveal runs once on mount; Activity runs forever. Both live in styles/motion.css and both drop their animation under prefers-reduced-motion.",
+    "Skeleton — content is LOADING (aria-busy + a shaped placeholder). Use Skeleton when the content itself has not arrived; use Activity when content is present and something is happening elsewhere.",
+    "Button (loading) — THIS action is in flight, on a control. Not an ambient state.",
+    "Progress — a DETERMINATE amount is done. Activity's `bar` variant is the indeterminate case, where no percentage exists.",
+    "DataState — antd `Spin`'s wrapper form (`<Spin spinning>{children}</Spin>`) over a query: skeleton → prerequisite → empty → error, with cause-aware retry. This is what to reach for when the REGION is loading.",
+    "antd `Spin` — no such component here, by a ruling recorded twice in docs/roadmap/parity-backlog.md and docs/roadmap/parity-audit-data-display-feedback.md §2.20. Its four jobs are Activity / Skeleton / DataState / Button `loading`. Its `delay` (flicker guard) is tracked separately against Button as `loadingDelay`; its `fullscreen` is a Dialog/app-shell concern, not an indicator one."
+  ],
+  "rules": [],
+  "storyPath": "general/Activity.stories.tsx",
+  "tagline": "The official AMBIENT-motion primitive and the standalone indeterminate indicator (antd `Spin`) — a continuous, unbounded 'something is happening right now, elsewhere' mark (someone typing, a sync running, a response streaming, a recording live). Loading a REGION is Skeleton; an in-flight ACTION is Button loading; a known percentage is Progress.",
+  "usage": [
+    "DO read this first if you came looking for a Spin/Spinner (gh#830). antd's `Spin` is ONE component with a `spinning` boolean covering four different situations; here those are four components, because the accessible semantics of each are genuinely different: (1) something is happening ELSEWHERE, indefinitely → Activity, no live region by default; (2) the CONTENT of this region is loading → Skeleton (aria-busy + aria-live, shaped placeholders) or DataState (the whole skeleton → prerequisite → empty → error lifecycle); (3) THIS action is in flight → Button `loading` (aria-busy + activation blocked on the control itself); (4) a percentage is known → Progress. Picking by shape ('I want the round one') is how a persistent indicator ends up telling a screen reader the page is busy forever.",
+    "DO use `variant='bar'` for the indeterminate case — that IS this library's indeterminate indicator, and the mark being a sweeping bar rather than a rotating circle is a system-level decision, not a gap. antd's `Spin percent='auto'` (a synthesized percentage that never reaches 100) is deliberately NOT ported: a fabricated number over an unknown wait is a determinate-looking lie, and Progress is there for when the number is real.",
+    "DO use <Activity> INSTEAD of hand-rolling `@keyframes typing-bounce` in a consumer app CSS. That re-derives interval/amplitude/stagger the DS owns as tokens (`--duration-loop`, `--activity-interval`, `--activity-stagger-step`, `--activity-mark-offset`) and needs its own prefers-reduced-motion guard — the guard consumers forget.",
+    "DO NOT reuse Skeleton for an ambient indicator. Skeleton hard-codes `aria-busy='true'` + `aria-live='polite'` because it means CONTENT IS LOADING; a persistent typing indicator built on it tells every screen reader the region is busy for as long as anyone is typing, and re-announces. Activity emits neither by default.",
+    "DO NOT reuse Button `loading`. That is a spinner bound to an in-flight action, on a control. Activity means something is happening indefinitely, ELSEWHERE.",
+    "DO leave `announce` at its default `false` for a flickering affordance (typing, presence). Opt into `announce='polite'` only when the change genuinely must be heard (a reconnect banner, a recording that just started) — and never on a value that changes on every socket event.",
+    "DO always pass a localized `label` (or `children`) when the indicator carries meaning: the mark alone announces nothing and communicates nothing under reduced motion. Route the string through your app's t()/Intl.PluralRules — the library ships no copy for it.",
+    "DO rely on the built-in reduced-motion behaviour — under `prefers-reduced-motion: reduce` the loop is dropped and each mark falls back to a DESIGNED resting state (three solid dots / a solid pulse mark / a bar segment parked at the reading-start), never to nothing, with no layout shift (WCAG 2.2 SC 2.3.3 and SC 2.2.2).",
+    "DO retune the ambient feel from a service theme, not per call site: `--activity-interval` (rhythm), `--activity-stagger-step` (dot offset), `--activity-mark-size` / `--activity-mark-offset` (mark and travel), `--activity-mark-rest-alpha`, `--activity-pulse-mark-size`, `--activity-gap`, `--activity-font-size-{xs,sm,md,lg}`, `--activity-bar-{width,height,radius,segment-width,track-alpha}`, `--activity-color`.",
+    "DO reserve the indicator's row height in the surrounding layout (it sits above a composer): Activity itself never changes size, but the row appearing and disappearing is the consumer's layout to keep stable.",
+    "DO NOT add `role='status'` yourself — that implies an unconditional polite live region, which is exactly what the `announce` default exists to keep off. Activity is not focusable and is not a tab stop."
+  ],
+  "useCases": [
+    "A chat channel's typing affordance under the composer: `<Activity label={t('channel.typing', { name })} />` — appears and disappears on socket events without ever announcing.",
+    "A live-sync pulse in a page header: `<Activity variant='bar' tone='info' label='同期中…' />`.",
+    "A streaming assistant response: `<Activity variant='dots' label='生成しています…' />` under the partial answer.",
+    "A recording / live mark: `<Activity variant='pulse' tone='destructive' label='録画中' />`.",
+    "A live-updating dashboard tile: `<Activity variant='pulse' size='xs' label='リアルタイム更新中' />` beside the metric.",
+    "A reconnect notice that MUST be heard once: `<Activity announce='polite' tone='warning' label='接続を再試行しています…' />`."
+  ]
+}