@godxjp/ui 0.2.0 → 2.2.0

package/BRAND.md

@@ -0,0 +1,286 @@
+# GoDX brand bible
+
+**Locked 2026-05-13.** Source: Claude Design handoff bundle —
+`design/source-2026-05-13/` (also kept verbatim as
+`design/godx-admin-2026-05-13.tar.gz`).
+
+## Drop-in / no customization
+
+`@godxjp/ui` is **turnkey**. A new service does ONE thing to be brand-compliant:
+
+```tsx
+// services/<svc>/frontend/src/main.tsx
+import "@godxjp/ui/tokens";   // <-- this is the entire brand contract
+import "./app.tsx";
+```
+
+That single import wires:
+- type scale, color palette, OKLCH dark mode, four tenants
+  (godx / kintai / tempo / betoya), density modes, spacing grid,
+  shadows, motion
+- all application-shell CSS classes (`.app-root`, `.sb-*`, `.tb-*`,
+  `.btn`, `.badge`, `.card`, `.kanban`, `.diff`, `.prose`,
+  `.auth-shell`, …)
+
+For React: also pull pre-built primitives + screens:
+
+```tsx
+import { AppShell, Sidebar, Topbar, TweaksPanel } from "@godxjp/ui/components/shell";
+import { DashboardScreen, PlansScreen, IssuesScreen, WikiScreen } from "@godxjp/ui/components/screens";
+import { useTweaks } from "@godxjp/ui/hooks";
+import { initI18n } from "@godxjp/ui/i18n";
+```
+
+**There is no theming step.** No per-service "wire up tokens" boilerplate. If a screen needs more than this provides, the answer is to add the primitive to `@godxjp/ui`, not fork.
+
+## Optional service-local overlay
+
+If — and only if — a service has a **brand-approved** deviation (e.g.
+a new tenant variant, a service-specific accent), the service ships
+a single overlay file:
+
+```css
+/* services/<svc>/frontend/src/theme.css */
+[data-tenant="my-svc"] {
+  --primary: oklch(56% 0.15 200);  /* still chroma ≤ 0.18 */
+  --ring: oklch(56% 0.15 200);
+}
+```
+
+Imported AFTER the base tokens:
+
+```tsx
+import "@godxjp/ui/tokens";
+import "./theme.css";   // overlay
+```
+
+The overlay can **only** redeclare brand-token CSS variables under a
+`[data-tenant]` or `[data-theme]` attribute selector. Editing
+foundational variables on `:root`, redefining the type scale, or
+overriding shell classes is forbidden and a review-block.
+
+> ⚠️ **Never lose the brand.** Every frontend in the GoDX ecosystem
+> (admin / forge / console / me / work / knowledge / agent / media /
+> chat / reporting / schema-studio / marketing) must:
+>
+> 1. import `@godxjp/ui/tokens` as the FIRST stylesheet
+> 2. consume the variables below as-is — never redefine `--primary`,
+>    `--foreground`, `--background`, spacing, type, density tokens
+> 3. live by the design philosophy (next section)
+>
+> A PR that hard-codes a color, custom font scale, or off-grid spacing
+> gets rejected at review.
+
+## Design philosophy (immutable)
+
+Three principles from the dxs-kintai brand foundation (Japanese
+enterprise aesthetics):
+
+| Term | Meaning | What it enforces |
+|---|---|---|
+| **渋み** (shibumi) | restrained elegance | Primary chroma ≤ 0.18 in OKLCH. No neon. No gradients on functional UI. |
+| **間** (ma) | vertical breathing room | Body `line-height: 1.7`. Generous spacing. Density toggle for compact data tables. |
+| **簡素** (kanso) | simplicity | Three font weights total: **400** (body), **500** (heading + emphasis default), **700** (loud emphasis only). No 600 in new code (kept as legacy alias). |
+
+These are NOT taste choices — they're brand contracts. Any visual
+direction that breaks them needs operator sign-off in advance.
+
+## Token surface (read from `src/tokens/tokens.css`)
+
+One file. Variables + application-shell classes mastered together so
+consumers do `import "@godxjp/ui/tokens"` once and get everything. The
+design handoff bundle split them into `tokens.css` + `tokens-ext.css`
+for portability to Figma / theme tools — that split is preserved
+verbatim under `design/source-2026-05-13/` as an audit trail; the
+consumable artefact in `src/tokens/` is intentionally merged.
+
+### Type
+
+```
+--font-sans-jp        "M PLUS 2" + JP fallback chain + system-ui
+--font-weight-normal  400 (body)
+--font-weight-medium  500 (headings, buttons, labels)
+--font-weight-bold    700 (loud emphasis only)
+
+--text-2xs            11px    fine print
+--text-xs             12px    caption / label
+--text-sm             13px    dense table rows
+--text-base           14px    DEFAULT body (JP density override)
+--text-md             16px    content-heavy body
+--text-lg             18px    subheading
+--text-xl             20px    h3 / page title
+--text-2xl            24px    h2
+--text-3xl            30px
+--text-4xl            32px    h1 cap
+
+--leading-tight       1.25    headings
+--leading-normal      1.5     dense / single-line UI
+--leading-body        1.7     JP body default (ma principle)
+```
+
+Semantic heading sizes are deliberately small — info-dense JP
+enterprise vibe: `--heading-h1 = 20px`, `--heading-h2 = 18px`,
+`--heading-h3 = 14px`, `--heading-h4 = 13px`.
+
+### Color — OKLCH only
+
+Primary palette mastered in OKLCH so dark mode + tenant overrides are
+mechanical. Never override `--primary` / `--foreground` /
+`--background` / `--card` / `--muted` in app code; switch via
+`[data-tenant]` or `[data-theme="dark"]` attributes.
+
+```
+--background     warm off-white  oklch(99% 0.002 60)
+--foreground     warm off-black  oklch(20% 0.006 60)   (SmartHR #23221e)
+--primary        SmartHR blue    oklch(56% 0.15 240)   (#0077c7)
+--destructive    茜 madder       oklch(52% 0.18 25)    (#b7282e, chroma capped)
+--success        若竹 bamboo     oklch(72% 0.13 155)   (#68be8d)
+--warning        山吹 mountain   oklch(80% 0.17 85)    (#f8b500)
+--info           群青 ultramarine oklch(55% 0.12 265)  (#4c6cb3)
+--attention      朱 vermilion    oklch(66% 0.19 45)    (#eb6101)
+```
+
+**和色 (wa-iro) decorative palette** is for charts, accent tags,
+illustrations — **never** for role-mapped UI (don't use `--wa-akane`
+as a button color; use `--destructive`). The palette:
+
+`--wa-ai` `--wa-gunjo` `--wa-ruri` `--wa-kon` `--wa-wakatake`
+`--wa-moegi` `--wa-yamabuki` `--wa-shu` `--wa-akane` `--wa-enji`
+`--wa-sakura` `--wa-sumi` `--wa-nezu`.
+
+### Tenant overrides
+
+Brand palette swaps via `[data-tenant="<slug>"]` at `<html>` or any
+ancestor. Defined slugs:
+
+- `godx` (default) — Famgia emerald accent + SmartHR blue primary
+- `kintai` — SmartHR blue primary
+- `tempo` — deeper indigo
+- `betoya` — Vietnamese green (Betoya restaurant brand)
+
+### Dark mode
+
+`[data-theme="dark"]` flips every surface + tenant. Already wired in
+`tokens-ext.css`.
+
+### Density
+
+`[data-density="compact|default|comfortable"]` rescales every UI
+element (button height, padding, row height). Default fits SmartHR /
+freee density (32px element). Compact for kintone-style dense tables
+(28px). Comfortable for public surfaces (44px — WCAG touch target).
+
+### Spacing — 4px grid
+
+```
+--spacing-0  0      --spacing-1 4px   --spacing-2 8px
+--spacing-3 12px    --spacing-4 16px  --spacing-5 20px
+--spacing-6 24px    --spacing-8 32px  --spacing-10 40px
+--spacing-12 48px   --spacing-16 64px --spacing-20 80px  --spacing-24 96px
+```
+
+Never invent off-grid values (`13px`, `7px`, etc).
+
+### Layout invariants
+
+```
+--header-height            48px
+--sidebar-width            256px
+--sidebar-collapsed-width  64px
+--container-max-width      1280px
+--touch-target-min         44px  (Digital Agency hard rule, never go below)
+```
+
+### Radius / motion
+
+```
+--radius      6px (base)
+--radius-md   4px, --radius-lg 6px, --radius-xl 10px, --radius-full ∞
+
+--transition-fast   150ms
+--transition-base   200ms
+--transition-slow   300ms
+--ease-in-out       cubic-bezier(0.4, 0, 0.2, 1)
+```
+
+`@media (prefers-reduced-motion: reduce)` honours user preference; the
+`.pulse` keyframe self-disables.
+
+## Component primitives (read from `src/tokens/tokens-ext.css`)
+
+Application-shell primitives are mastered as CSS classes (not React
+components — those layer on top per portal). Each frontend imports the
+tokens and gets these for free:
+
+| Class | Use |
+|---|---|
+| `.app-root / .app-sidebar / .app-topbar / .app-main` | three-pane app shell with collapse animation |
+| `.sb-product / .sb-section / .sb-nav-item` | sidebar primary nav |
+| `.tb-breadcrumb / .tb-chip / .tb-search / .tb-icon-btn` | topbar |
+| `.sw-pop` family | command-palette / switcher dropdown |
+| `.page / .page-header / .page-title / .page-actions` | page chrome |
+| `.card / .card-header / .card-title` | card surface |
+| `.btn / .btn-primary / .btn-secondary / .btn-ghost / .btn-danger / .btn-sm / .btn-lg` | buttons |
+| `.input / .label / .help` | form primitives |
+| `.badge / .badge-success / -warning / -info / -error / -attention / -neutral / -outline` | status badges |
+| `.chip` | tag |
+| `.table / .num / .mono` | tabular data |
+| `.tabs / .tab` | tab strip |
+| `.kpi / .kpi-label / .kpi-value / .kpi-delta` | dashboard metric |
+| `.log-line` | terminal-style activity feed |
+| `.diff / .diff-row.add / .diff-row.del / .diff-row.ctx` | code diff |
+| `.kanban / .kanban-col / .issue-card` | kanban board |
+| `.wiki-layout / .wiki-toc / .prose` | wiki / doc render |
+| `.auth-shell / .auth-card / .auth-art` | login screen |
+| `.avatar / .kbd / .dot / .pulse` | utilities |
+
+Use them directly when building plain HTML. When using React, wrap
+each in a small primitive component in your portal's `components/`
+directory; do NOT re-create the class names — import the existing CSS.
+
+## Reference HTML prototypes
+
+The bundle ships pixel-canonical HTML prototypes in
+`design/source-2026-05-13/project/`:
+
+| File | What it shows |
+|---|---|
+| `godx-unified.html` | full admin shell (sidebar + topbar + page) |
+| `signin.html` | sign-in flow (email → password → 2FA → done) |
+| `device.html` | device-code authorize flow |
+| `login.html` | 15-artboard canvas reviewing every login state |
+| `design-canvas.jsx` | React canvas showcasing every primitive |
+| `shell.jsx`, `ui-kit.jsx`, `tweaks-panel.jsx` | JSX primitives mirroring the CSS classes |
+| `screens-*.jsx` | per-screen reference layouts (product / project / detail) |
+
+When implementing a new screen, **open the closest reference** first
+and match its visual rhythm. Don't redesign solo without a precedent.
+
+## Forbidden patterns
+
+- ❌ Hard-coded hex colors in component code (use `var(--primary)` etc).
+- ❌ Custom font sizes outside the `--text-*` scale.
+- ❌ Spacing values off the 4px grid (`5px`, `7px`, `13px`…).
+- ❌ Font weight 300 / 600 / 800 / 900 in new code (only 400 / 500 / 700).
+- ❌ Tailwind utility classes that re-encode tokens (e.g. `text-blue-500`
+  instead of `text-[var(--primary)]`).
+- ❌ A new shadow / radius / motion curve "just for this card".
+- ❌ Logos, marketing copy, or product-specific imagery in the
+  `@godxjp/ui` package — those live in the consumer portal.
+
+## Updating the brand
+
+When the operator approves a brand change:
+
+1. Update `src/tokens/tokens.css` and/or `tokens-ext.css` here in
+   `packages/godxjp-ui`.
+2. Bump the package version.
+3. Bump the submodule pointer in `godx-admin` umbrella.
+4. Each portal pulls the new submodule SHA in a follow-up PR.
+5. **Refresh `BRAND.md` if the change moves a foundational rule.**
+
+Document the change in `design/CHANGELOG.md` (create on first change).
+
+The current locked snapshot is preserved at
+`design/source-2026-05-13/` + the original archive at
+`design/godx-admin-2026-05-13.tar.gz`.

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to `@godxjp/ui`. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.0] — 2026-05-13
+
+### Added
+- **Popover** primitive (`Popover`, `PopoverTrigger`, `PopoverContent`,
+  `PopoverAnchor`) wrapping `@radix-ui/react-popover`. Visual contract
+  in the new `.popover-content` class in `tokens.css` — brand-tokenised
+  surface (`--popover`), border, and elevation.
+- **DropdownMenu** primitive (`DropdownMenu`, `DropdownMenuTrigger`,
+  `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuSeparator`,
+  `DropdownMenuLabel`, `DropdownMenuShortcut`, `DropdownMenuGroup`,
+  `DropdownMenuPortal`, `DropdownMenuSub`, `DropdownMenuRadioGroup`)
+  wrapping `@radix-ui/react-dropdown-menu`. `<DropdownMenuItem>`
+  supports `variant="destructive"` + `inset` matching the public v0.2
+  surface so call sites migrate by dep bump only.
+- **Calendar** primitive — `react-day-picker` themed via the new
+  `.calendar` class in `tokens.css` (primary / surface / ring tokens).
+- **TimeInput** primitive — narrow `HH:mm` text input with on-blur
+  normalisation (accepts `HHmm`, `H:mm`, etc.). Surfaces
+  `aria-invalid` when the draft doesn't parse.
+- New CSS classes in `tokens.css`: `.popover-content`,
+  `.dropdown-menu-content`, `.dropdown-menu-item`,
+  `.dropdown-menu-separator`, `.dropdown-menu-label`,
+  `.dropdown-menu-shortcut`, `.calendar`, `.time-input`.
+- `react-day-picker` added as a dependency.
+
+### Notes
+- This release fills the gap that blocked
+  `services/forge-service/frontend/` from migrating off the public
+  TempoFast `@godxjp/ui@0.2.0`. After 2.1.0 every primitive forge
+  imports (`Badge`, `Button`, `Tabs*`, `Popover*`, `DropdownMenu*`,
+  `Calendar`, `TimeInput`) is brand-tokenised by default.
+
+## [2.0.0] — 2026-05-13
+
+**Major version bump.** `@godxjp/ui` (the npm package owned by godx-jp / TempoFast) is now the GoDX brand bible. The previous public 0.2.0 — TempoFast's existing component library — stays consumable for legacy callers until TempoFast itself migrates onto 2.0+. SemVer signals the breaking change so dependents pin explicitly.
+
+### Breaking
+
+- Package surface re-anchored on the Claude Design handoff 2026-05-13.
+  Color tokens use OKLCH (not hex literals), font scale tightened
+  (text-2xs..text-4xl), density modes added, four tenants pinned.
+  `<Badge>` / `<Button>` etc. now wrap canonical CSS classes from
+  `tokens.css` rather than shadcn-default Tailwind utilities.
+- Token files merged: `tokens.css` + `tokens-ext.css` →
+  single `tokens.css` (635 lines). Consumers do
+  `import "@godxjp/ui/tokens"` once.
+- `src/primitives/` moved to `src/components/primitives/` —
+  `@godxjp/ui/primitives` alias preserved in the exports map for
+  backwards compatibility, but new code should import from
+  `@godxjp/ui` (top-level barrel re-exports everything).
+
+### Added
+
+### Added
+- **BRAND.md** — the brand bible (locked 2026-05-13 from Claude Design
+  handoff bundle). Spells out the 渋み / 間 / 簡素 design philosophy
+  and lists the forbidden patterns reviewers reject.
+- **`design/source-2026-05-13/`** — full design handoff preserved
+  verbatim (README, chat transcripts, every JSX + HTML prototype).
+- **`design/godx-admin-2026-05-13.tar.gz`** — original archive from
+  `api.anthropic.com/v1/design/h/7Ya1OxEEfiaI2SWojzuP9A`. Kept so the
+  brand can be re-extracted on any fresh checkout.
+- **Atomic primitives**: `Badge`, `Button`, `Card` (+ `CardHeader`,
+  `CardTitle`, `CardSubtitle`, `CardContent`), `Input`, `Textarea`,
+  `Label`, `Tabs` (+ `TabsList`, `TabsTrigger`, `TabsContent`),
+  `Avatar`, `Separator`. Each maps onto a canonical CSS class from
+  `tokens.css` — no Tailwind utility re-encoding.
+- **`./components/primitives` export path** for explicit imports.
+
+### Changed
+- **`tokens.css` is now the single CSS entry point.** The handoff's
+  `tokens.css` + `tokens-ext.css` were merged so consumers do one
+  import (`@godxjp/ui/tokens`). The split is preserved verbatim under
+  `design/source-2026-05-13/` as an audit trail.
+- **`src/primitives/` → `src/components/primitives/`** for consistency
+  with international design-system conventions (atomic primitives
+  alongside shell + screens under `components/`). Top-level
+  `@godxjp/ui` import paths unchanged.
+- **`src/index.ts`** now re-exports primitives by default so
+  consumers can `import { Badge, Button } from "@godxjp/ui"`.
+
+### Removed
+- `src/tokens/tokens-ext.css` (merged into `tokens.css`).
+- `src/tokens/index.css` (no longer needed — `tokens.css` is the entry).
+
+## [0.1.0] — 2026-05-10
+
+Initial scaffold: tokens, hooks, i18n, data, shell components, screen
+components.

package/README.md

@@ -1,50 +1,206 @@
-# @godxjp/ui
+# @godxjp/ui — GoDX Forge unified design system
 
-> GodX Design System — React UI components with i18n, translatable fields, and metadata-driven forms/tables.
+**Status:** core source of truth. **Every frontend in the GoDX
+ecosystem MUST consume this package.** No service may bring its own
+tokens, theme, color palette, i18n provider, or component primitives.
+This rule is review-blocking (see `MUST RULES` below).
 
-## Install
+The only thing a service is allowed to do differently from another is
+**layout**: route tree, page composition, screen-specific widgets that
+have no equivalent in another service. Everything visual — typography,
+color, spacing, density, dark mode, language switcher, sidebar shape,
+top-bar shape, buttons, badges, kanban, KPI tiles, modal pattern — comes
+from here.
+
+---
+
+## MUST RULES (review-blocking)
+
+> If a PR violates any of these the reviewer rejects, regardless of
+> deadline. Sync the visual layer first, ship the feature after.
+
+1. **Tokens.** Every frontend imports `@godxjp/ui/tokens.css` AND
+   `@godxjp/ui/tokens-ext.css` from its root entry (`main.tsx` /
+   `app.tsx`). Services do not define their own `--background`,
+   `--foreground`, `--primary`, font stack, density variables, or
+   shadow scale. Tenant overrides happen via `[data-tenant="<id>"]`
+   on `<html>`, never per-service.
+
+2. **Stack.** TypeScript + React 19 + Vite + Tailwind v4 + shadcn-style
+   primitives (Radix + cva + tailwind-merge). Components from this
+   package are the only UI atoms a service uses. No service may ship
+   `@mui/material`, `chakra-ui`, `antd`, native `styled-components`,
+   raw `<input>` with custom CSS, etc.
+
+3. **i18n.** All translation goes through `@godxjp/ui/i18n` — a single
+   pre-configured `i18next` instance with auto-detect + JA fallback +
+   localStorage persistence. The base dictionary (nav, shell, common,
+   tweaks, kpi, pdca, issue) lives in `src/i18n/locales/{ja,en,vi}.ts`
+   and is exported as `ForgeTranslations`. Services may register their
+   own namespace (e.g. `i18n.addResourceBundle("ja", "sandbox", {…})`)
+   but never replace the base.
+
+4. **Locale set.** Supported: `ja` (default), `en`, `vi`. Adding a
+   locale = PR to this package, never per-service.
+
+5. **Theme + density + tenant.** All toggled via the `useTweaks` hook
+   from `@godxjp/ui/hooks`. The hook mirrors selections onto `<html>`
+   data attributes — services rely on those, they do not maintain
+   their own theme state.
+
+6. **Fonts.** `M PLUS 2` (loaded by `tokens.css`) is the primary face;
+   fallbacks are Hiragino → Yu Gothic → Noto Sans JP → system. No
+   service may swap in `Inter`, `Roboto`, `Comic Sans`, etc.
+
+7. **Color literals.** No hex / rgb / oklch literals in service code.
+   Always reference a CSS variable: `var(--primary)`, `var(--wa-akane)`,
+   `text-foreground`, `bg-surface-2`. The 13 `--wa-*` 和色 colors are
+   for charts + decoration ONLY; never role-map them.
+
+8. **Density.** Three modes only: `compact` (28 px element), `default`
+   (32 px), `comfortable` (44 px, WCAG-friendly). No `medium`, no
+   intermediate sizes. Components honor `--density-element-*` tokens.
+
+9. **Signal palette.** 5 colors with fixed semantics — `--success`
+   (若竹 wakatake), `--warning` (山吹 yamabuki), `--info` (群青
+   gunjō), `--error/destructive` (茜 akane), `--attention` (朱 shu).
+   **Red (`--destructive`) is reserved for destructive actions only.**
+   Don't use `--destructive` for "wrong answer" badges, validation
+   chrome, or general emphasis.
+
+10. **No emojis in product UI.** Iconography uses `lucide-react`.
+    Emoji are acceptable in user-generated content (comments, chat,
+    notifications) but never in chrome.
+
+11. **Shell layout.** When a service needs a sidebar + topbar shell,
+    it imports `<AppShell>` from `@godxjp/ui/components/shell` and
+    plugs in its own nav config + screen routes. Services do not
+    hand-roll a CSS grid for the chrome.
+
+12. **Switchers (product/project) are universal.** The Linear-style
+    quick switcher is one component, used everywhere — same data
+    shape (`ForgeProduct` / `ForgeProject` from `@godxjp/ui/data`).
+    A service that doesn't have a project concept passes
+    `project={null}`; the chip auto-hides.
+
+---
+
+## Layout boundary — what a service CAN do without violating
+
+| Service-owned | Must come from `@godxjp/ui` |
+|---|---|
+| Route tree (`react-router-dom` config) | Visual atoms: button, badge, card, KPI, kanban col |
+| Page composition (what cards live on this screen) | Shell: sidebar + topbar + tweaks panel |
+| Screen-specific widgets (e.g. a domain-pool map view that no other service has) | Theme tokens, density, dark mode |
+| Domain data shapes (e.g. the sandbox's tmux pane object) | i18n provider, locale list, base dictionary |
+| Per-service API client | Color palette, font stack, spacing scale |
+
+If a screen requires a NEW primitive that another service might also
+need, add it to this package first, then consume it. Don't fork.
+
+---
+
+## Adoption tracker
+
+Each service must reach **100% token coverage** before it's allowed
+to claim "GoDX Forge compliant" in its README:
+
+| Service | Status | Owner | Notes |
+|---|---|---|---|
+| `forge-service/frontend` | adopting (phase 1) | platform | Reference implementation. |
+| `admin-platform/frontend` | partial (existing Omnify tokens overlap ~90%) | platform | Migrate before Plan #19 cut-over. |
+| `me-service/frontend` | not started | platform | Tracked under Plan #31 R6. |
+| `console-service/frontend` | not started | platform | Tracked under Plan #31 R6. |
+| `agent-service/frontend` | not started | platform | Plan #21 G17 finished embed; visual port pending. |
+| `knowledge-service/frontend` | not started | knowledge | Plan #18 K-phase polish. |
+
+Operator-side dashboards (Grafana, Mailpit, etc.) are external — they
+keep their own UI, not in scope.
+
+---
+
+## What lives here
 
-```sh
-npm install @godxjp/ui
 ```
+packages/godxjp-ui/src/
+├── tokens/                      Source of truth for CSS variables.
+│   ├── tokens.css               Base palette, type scale, density,
+│   │                            shadows, motion. Imports M PLUS 2.
+│   └── tokens-ext.css           Sidebar, topbar, page, card, badge,
+│                                kanban, dark mode, tenant overrides.
+│
+├── i18n/                        i18next bootstrap + base dictionary.
+│   ├── index.ts                 initI18n(); auto-detect + JA fallback.
+│   └── locales/{ja,en,vi}.ts    `ForgeTranslations` shape.
+│
+├── hooks/
+│   └── useTweaks.ts             density / theme / tenant / locale /
+│                                sidebar-collapsed state w/ persistence.
+│
+├── data/
+│   └── products.ts              ForgeProduct / ForgeProject types +
+│                                mock fixture (until forge-service
+│                                /api/v1/orgs/ wires real data).
+│
+├── primitives/                  shadcn-styled atoms (button, badge,
+│                                card, kbd, ...). One copy across the
+│                                org.
+│
+└── components/shell/            AppShell, Sidebar, Topbar,
+                                 ProductSwitcher, ProjectSwitcher,
+                                 TweaksPanel, CommandPalette.
+```
+
+---
 
-## Usage
+## How to consume from a service frontend
 
 ```tsx
-import { Button, Input, Card, UIProvider } from "@godxjp/ui";
-
-function App() {
-  return (
-    <UIProvider locales={{ ja: "日本語", en: "English" }} defaultLocale="ja">
-      <Card>
-        <Input placeholder="Enter text..." />
-        <Button>Submit</Button>
-      </Card>
-    </UIProvider>
-  );
-}
+// services/<svc>/frontend/src/main.tsx
+import "@godxjp/ui/tokens.css";
+import "@godxjp/ui/tokens-ext.css";
+import { initI18n } from "@godxjp/ui/i18n";
+import { AppShell, Sidebar, Topbar } from "@godxjp/ui/components/shell";
+
+initI18n();
+
+createRoot(document.getElementById("root")!).render(
+  <BrowserRouter>
+    <AppShell sidebar={<Sidebar nav={MY_NAV} />} topbar={<Topbar />}>
+      <Routes>{/* service-specific routes */}</Routes>
+    </AppShell>
+  </BrowserRouter>,
+);
 ```
 
-## Components
+That's the entire integration surface for a new service.
 
-60+ components including: Accordion, Alert, Avatar, Badge, Breadcrumb, Button, Calendar, Card, Checkbox, ColorPicker, Combobox, DatePicker, Dialog, Drawer, DropdownMenu, FileUpload (5 variants), Input, Label, Menubar, Pagination, PasswordInput, Popover, Progress, RadioGroup, Rating, SchemaField, SchemaTable, Select, Separator, Sheet, Skeleton, Slider, Switch, Table, Tabs, Textarea, TimePicker, Toggle, Tooltip, TranslatableField.
+---
 
-## Key Features
+## Versioning + change control
 
-- **Translatable fields** — locale tab switcher on Input/Textarea
-- **SchemaField** — metadata-driven form fields (15 input types)
-- **SchemaTable** — metadata-driven data table (sort, filter, paginate, actions)
-- **FileUpload** — 5 variants (dropzone, compact, avatar, gallery, inline)
-- **i18n** — UIProvider with locale context, all labels locale-aware
+The package follows semver. Breaking changes (renamed token, removed
+component prop, changed default tenant) require:
 
-## Build
+1. RFC issue in `godx-platform-sdk` repo (or local `docs/plans/` if
+   pre-extraction).
+2. Cross-service audit — which surfaces break, who fixes them.
+3. Major version bump.
 
-Source lives in `frontend/src/components/ui/` (sibling repo). This package builds from there:
+Additive changes (new component, new locale string, new wa-iro color,
+new tenant) are minor / patch — no RFC needed.
 
-```sh
-npm run build    # tsup → dist/
-```
+Issue / PR for changes: file under `godx-jp/godx-platform-sdk` repo
+once Plan #22 extraction completes; until then file under
+`godx-jp/godx-admin` with label `area:design-system`.
+
+---
 
-## License
+## See also
 
-Private — GodX Japan.
+- Design prototype the package is ported from: `chat1.md` + `chat2.md`
+  (Claude Design handoff, 2026-05-08 / 2026-05-09).
+- Plan #19 — forge-service extraction.
+- Plan #22 — multi-repo standalone services. `@godxjp/ui` is the
+  TypeScript counterpart to `godx-platform-sdk` (Go shared kernel).
+- Plan #31 R6 — per-portal UI alignment.