@godxjp/ui 19.1.0 → 19.2.0

package/docs/COMPONENTS.md

@@ -0,0 +1,157 @@
+# Component Catalog
+
+All components consume prop types from `src/props/components/`. Preview: `pnpm preview`.
+
+---
+
+## Layout
+
+### AppShell / Sidebar / Topbar
+
+**Prop types:** `AppShellProp`, `SidebarProp`, `TopbarProp` **Import:** `@godxjp/ui/layout`
+
+Slot-based app chrome for admin products:
+
+```tsx
+<AppShell
+  sidebar={<Sidebar sections={sections} activeId="dashboard" />}
+  topbar={<Topbar start={<Logo mark="godx" label={product.name} />} />}
+>
+  <PageContainer title="Dashboard">...</PageContainer>
+</AppShell>
+```
+
+Do not rebuild sidebar or topbar chrome inside product previews or apps. Compose the shell slots, then put product content in the `children` slot.
+
+### PageContainer
+
+**Prop type:** `PageContainerProp` **Import:** `@godxjp/ui/layout`
+
+| Prop            | Vocabulary        | Required          |
+| --------------- | ----------------- | ----------------- |
+| `title`         | `TitleProp`       | ✅                |
+| `subtitle`      | `SubtitleProp`    |                   |
+| `extra`         | `ExtraProp`       |                   |
+| `footer`        | `FooterProp`      |                   |
+| `breadcrumb`    | `BreadcrumbProp`  |                   |
+| `headerLoading` | local (`boolean`) | default `false`   |
+| `density`       | `PageDensityProp` | default `default` |
+| `children`      | `ChildrenProp`    |                   |
+
+Every admin page **must** use PageContainer.
+
+## Mobile-first
+
+All UI is **mobile-first**: base layout targets ~320–428px viewport; `sm` (640px+) adds horizontal layouts. See `packages/ui/src/tokens/base.css` and `.ui-page-*` in `src/styles/index.css`. Preview defaults to mobile viewport.
+
+### Flex
+
+Default `direction="row"`; use `direction="col"` for vertical rhythm.
+
+| Component | Prop       | Key props                                                               |
+| --------- | ---------- | ----------------------------------------------------------------------- |
+| `Flex`    | `FlexProp` | `direction: "row" \| "col"`, `gap: GapProp`, `align`, `justify`, `wrap` |
+
+---
+
+## Foundation
+
+### Button
+
+**Prop type:** `ButtonProp` **Import:** `@godxjp/ui/general`
+
+| Prop       | Vocabulary          |
+| ---------- | ------------------- |
+| `variant`  | `ButtonVariantProp` |
+| `size`     | `ButtonSizeProp`    |
+| `asChild`  | `AsChildProp`       |
+| `disabled` | `DisabledProp`      |
+| `onClick`  | `OnClickProp`       |
+
+---
+
+## Data Entry
+
+| Component     | Prop type         | Key props                                          |
+| ------------- | ----------------- | -------------------------------------------------- |
+| `Input`       | `InputProp`       | extends native input                               |
+| `Textarea`    | `TextareaProp`    | extends native textarea                            |
+| `FormField`   | `FormFieldProp`   | `id`, `label`, `required`, `helper`, `error`       |
+| `SearchInput` | `SearchInputProp` | `onSearchChange: OnSearchChangeProp`               |
+| `Checkbox`    | `CheckboxProp`    | Radix checkbox; `Checkbox.Group` với `options`     |
+| `Radio`       | `RadioGroupProp`  | `Radio.Group` single-select; `Radio.Root` compound |
+
+---
+
+## Data Display
+
+| Component      | Prop type          | Key props                                |
+| -------------- | ------------------ | ---------------------------------------- |
+| `EmptyState`   | `EmptyStateProp`   | `icon`, `title`, `description`, `action` |
+| `DataTable`    | `DataTableProp<T>` | `columns`, `density: TableDensityProp`   |
+| `Descriptions` | `DescriptionsProp` | `items[]`                                |
+| `Badge`        | `BadgeProp`        | `status`, `tone: ToneProp`               |
+| `Badge`        | `BadgeProp`        | shadcn badge variants                    |
+| `Popover`      | Radix primitives   | floating content panel                   |
+| `ScrollArea`   | Radix primitives   | scrollable regions                       |
+| `Collapsible`  | Radix primitives   | expand/collapse sections                 |
+
+---
+
+## Feedback
+
+| Component   | Prop type           | Key props                                                                    |
+| ----------- | ------------------- | ---------------------------------------------------------------------------- |
+| `Alert`     | `AlertProp`         | `tone` (colour), `variant` (measure), slots, `onDismiss`, `Alert.QueryError` |
+| `Banner`    | `BannerProp`        | page-level `Alert` (`variant="banner"`); same tones/slots/dismiss            |
+| `Dialog`    | `DialogConfirmProp` | `mode: form \| confirm`, `Dialog.Confirm` preset                             |
+| `Sheet`     | Radix primitives    | slide-in panel (mobile filters, detail flyouts)                              |
+| `Skeleton*` | `SkeletonRowsProp`  | loading placeholders                                                         |
+
+---
+
+## Query
+
+Async data lifecycle helpers (TanStack Query). **Not visual components.**
+
+| Component               | Prop type                   | Key props                                                                               |
+| ----------------------- | --------------------------- | --------------------------------------------------------------------------------------- |
+| `DataState`             | `DataStateProp<T>`          | `query`, `skeleton`, `empty`, `isEmpty`, `showRetry`, `onRetry`, render-prop `children` |
+| `AlertMutationFeedback` | `AlertMutationFeedbackProp` | `mutation`, `onRetry`, `pending` — inline `useMutation` error                           |
+| `InfiniteQueryState`    | `InfiniteQueryStateProp`    | `flatten`, `loadMore`, `showLoadMore` — infinite scroll / timeline                      |
+| `PrefetchLink`          | `PrefetchLinkProp`          | `queryKey`, `queryFn`, `prefetchOn`, `staleTime`                                        |
+
+Import: `@godxjp/ui/query` (re-exported from `@godxjp/ui/admin`).
+
+**`DataState`** — one `useQuery` = one content block (list, detail). Not whole page when filters stay visible.
+
+**`InfiniteQueryState`** — `useInfiniteQuery` + Load more. CRM timeline, activity feeds. Offset pagination lists → `DataState` + `DataTable.Pagination`.
+
+**`PrefetchLink`** — hover/focus prefetch before navigate to detail.
+
+**`AlertMutationFeedback`** — blocking mutation errors (simulator). Small saves → toast.
+
+**`ButtonRefetch`** — `PageContainer extra` refresh pattern (MediaListPage).
+
+**`Alert.QueryError`** — manual error when not using DataState (audit results region).
+
+Auto retry: `useQuery({ retry, retryDelay })`. Manual retry: default `refetch()`.
+
+---
+
+## Navigation
+
+| Component        | Prop type          | Key props                                                                                                                      |
+| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `FilterBar`      | `ToolbarProp`      | typed model: `search`, `filters`, `chips`, `onChipRemove`, `resultCount`, `actions`, `loading`, `disabled`, `error`, `onClear` |
+| `FilterBarGroup` | `ToolbarGroupProp` | `label: LabelProp`, `controlId: IdProp`                                                                                        |
+| `Toolbar`        | `ToolbarProp`      | back-compat alias of `FilterBar`                                                                                               |
+| `ToolbarGroup`   | `ToolbarGroupProp` | back-compat alias of `FilterBarGroup`                                                                                          |
+| `Tabs`           | Radix primitives   | —                                                                                                                              |
+| `DropdownMenu`   | Radix primitives   | —                                                                                                                              |
+
+---
+
+## Adding a new component
+
+1. Check `PROPS-REGISTRY.md` — concept may already exist 2. Add vocabulary types if needed → `src/props/vocabulary/` 3.

package/docs/COMPOSITION-VS-COMPONENT.md

@@ -0,0 +1,105 @@
+# Composition pattern vs Framework component — the decision contract
+
+> **Cardinal rule:** before ANY new thing is added to `src/components/`, it MUST pass the
+> **Framework-Component Test** below — _all_ criteria, no exceptions. If it fails even one, it is a
+> **composition pattern**: build it from existing primitives + tokens in the app/showcase, and do
+> **not** add it to the framework. **When in doubt, compose.** The framework stays lean; brand- and
+> screen-specific UI lives where it belongs — in the consumer app (or a `docs/` showcase), as a
+> composition of real primitives configured by tokens.
+
+This document defines the two concepts precisely, gives the mandatory test, and lists worked examples so the call is never a matter of taste.
+
+---
+
+## 1. The two concepts
+
+### Framework component (`src/components/**`)
+
+A **reusable, behavior-bearing primitive** that ships in the `@godxjp/ui` bundle and is imported by many consumer apps. It encapsulates interaction, state, accessibility and a controlled API that must NOT be re-implemented per app. Examples: `Button`, `Select`, `DataTable`, `Dialog`, `Calendar`, `Switch`, `Combobox` (= `Select showSearch`), `StatCard`.
+
+### Composition pattern (consumer app, or a `docs/` showcase)
+
+A **specific arrangement of existing primitives** for a specific screen, domain or brand — a dashboard layout, a marketing **Hero**, a **Navbar**, a **Footer**, a pricing section, a settings page. It has **no reusable behavior of its own**: it is layout + content + token configuration over real components. It is brand/design-specific and is **expressible today** by composing `Card`, `Button`, `Text`, `ResponsiveGrid`, `Flex`, `Badge`, `Avatar`, … + token overrides (incl. scoped `[data-tenant]` / per-region role scoping).
+
+> A Claude Design's marketing landing page (Hero / Services / CTA / Footer) is the canonical
+> composition case: it is reproduced 100% from **token configuration + real primitives**, with zero
+> new framework components. See `docs/showcase/acme-website.tsx`.
+
+---
+
+## 2. The Framework-Component Test (MANDATORY — all 7 must pass)
+
+Before creating OR proposing a framework component, evaluate **every** criterion and record the verdict. **Allowed only if ALL are `PASS`.** Any `FAIL` ⇒ it is a composition pattern; use existing components instead.
+
+| #                                                                 | Criterion                                                                                                                      | PASS means                                                            | FAIL means (→ compose)                                                   |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| **C1. Universal, not design-specific**                            | Needed by many apps across domains; not a recreation of one design's block.                                                    | A generic capability (a select, a table, a date picker).              | "ACME Hero", "AcmePricingTable", "this dashboard's header".              |
+| **C2. Encapsulates reusable BEHAVIOR**                            | Owns non-trivial state / keyboard / focus / ARIA that must not be re-implemented per app.                                      | Listbox navigation, dialog focus-trap, table sort/select, async load. | Pure static layout/visual arrangement (a hero, a footer, a banner).      |
+| **C3. Not expressible by composing existing primitives + tokens** | You genuinely cannot build it from `Card`/`Button`/`Text`/`Grid`/`Flex`/… + token overrides.                                   | A new interaction primitive with no existing equivalent.              | You _can_ build it today from primitives + tokens (then you must).       |
+| **C4. Single responsibility + controlled-vocabulary API**         | One job; maps to `value`/`defaultValue`/`onValueChange`, `size ∈ xs\|sm\|md\|lg`, `tone`, etc.; generalizes beyond one screen. | `Select`, `Switch`, `Pagination`.                                     | A grab-bag "Section"/"Block"/"Layout" with a bespoke, screen-shaped API. |
+| **C5. Fully token-themeable, zero baked brand**                   | Appearance is 100% token-driven; works for every brand with no code change.                                                    | Reads `hsl(var(--…))` / semantic tokens only.                         | Needs baked colors / raw hex / per-brand styling to look right.          |
+| **C6. Earns the international contract**                          | Broad reuse justifies the full i18n (`t()`/`Intl`) + WAI-ARIA APG + WCAG 2.2 AA + RTL + a11y-test + MCP-catalog cost.          | A control everyone uses and that needs correct ARIA.                  | A one-off where that cost is pure overhead.                              |
+| **C7. Earns its bundle cost**                                     | Broadly used ⇒ worth shipping to _every_ consumer.                                                                             | Used across most apps.                                                | Used by one app / one design ⇒ it belongs in that app.                   |
+
+> **Heuristic shortcuts** (a single one is usually enough to send it to composition):
+>
+> - "Could I build this **right now** from existing primitives + token overrides?" → **yes ⇒ compose** (C3).
+> - "Is the name a **proper noun / screen name / brand block** (Hero, Navbar, Footer, Pricing,
+>   DashboardHeader)?" → **yes ⇒ compose** (C1).
+> - "Does it own **any real behavior**, or is it just **layout + content + color**?" → layout only ⇒ **compose** (C2).
+
+### Decision flow
+
+```
+new UI need
+  │
+  ├─ Does an existing primitive already cover it? ───────────── yes → USE IT (no new code)
+  │        (Select = searchable/async; AppShell/PageContainer = chrome; DataTable = grids)
+  │
+  ├─ Run the Framework-Component Test (C1–C7).
+  │        ├─ ALL pass → it MAY be a framework component
+  │        │             → follow the full `godxjp-ui-component` contract (i18n/a11y/vocab/
+  │        │               tokens/test/MCP/registry) before merging into src/components/.
+  │        └─ ANY fail → it is a COMPOSITION PATTERN
+  │                      → build it from existing primitives + tokens in the app (or a docs/
+  │                        showcase). Resolve any visual gap with a TOKEN, never a baked value.
+  │                        NEVER add it to src/components/.
+  │
+  └─ If a token is missing to express it → ADD THE TOKEN (extensibility), not a component.
+```
+
+---
+
+## 3. Worked examples
+
+| Thing                                                   | C1  | C2  | C3  | C4  | C5  | C6  | C7  | Verdict                                                                  |
+| ------------------------------------------------------- | --- | --- | --- | --- | --- | --- | --- | ------------------------------------------------------------------------ |
+| `Select` (incl. search/async)                           | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | **Framework component**                                                  |
+| `DataTable`, `Dialog`, `Calendar`, `Switch`, `Combobox` | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | **Framework component**                                                  |
+| `StatCard` (+ `icon`)                                   | ✅  | ➖  | ✅  | ✅  | ✅  | ✅  | ✅  | **Framework component** (a reusable KPI tile with a stable API + tokens) |
+| Marketing **Hero**                                      | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | **Composition** — section, static, composable, brand-specific            |
+| **Navbar** / **Footer**                                 | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | **Composition** — layout of `Text`/`Button`/`Flex`                       |
+| **PricingTable** / feature grid                         | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | ❌  | **Composition** — `ResponsiveGrid` + `Card`                              |
+| Dashboard **page layout**                               | ❌  | ❌  | ❌  | ❌  | ➖  | ❌  | ❌  | **Composition** — `AppShell` + `PageContainer` + `ResponsiveGrid`        |
+| "Icon medallion"                                        | ❌  | ❌  | ❌  | ❌  | ✅  | ❌  | ❌  | **Composition** — `Avatar` (square) + a Lucide glyph                     |
+
+`✅ pass · ❌ fail · ➖ borderline`. **StatCard** is the instructive borderline: C2 is weak (it owns little behavior), but it is a universal KPI tile with a controlled API, fully tokenized, broadly reused — so it earns its place. A **Hero** fails six of seven; it is unambiguously a composition.
+
+---
+
+## 4. How to build a composition pattern correctly
+
+1. **Real primitives only.** Compose `Card`/`Button`/`Text`/`ResponsiveGrid`/`Flex`/`Avatar`/… — never hand-roll a control or fake a primitive with a styled `<div>`. 2. **Sections are layout, not components.** A `<section>`/`<header>`/`<footer>` wrapper that arranges primitives is allowed — it is plain layout, not a faked primitive. 3. **Resolve every visual gap with a TOKEN.** A navy hero, a glass card, a brand glow, display type → a token override (global `:root`, scoped `[data-tenant]`, or **per-region role scoping** `[data-tenant] .region { --card: navy; --foreground: white; … }`). If the token doesn't exist, **add the token to the framework** (extensibility), never bake a value into the composition. 4. **Live in the app, or a `docs/` showcase** — never `src/components/`.
+
+> The whole point of the token-extensibility work (scoped theming, glow / tint / gradient / focus,
+> display type, dual-font, role-scoping) is so that **a composition pattern can reach 100% design
+> fidelity from tokens alone** — which is exactly why almost nothing new needs to become a framework
+> component.
+
+---
+
+## 5. The mandatory gate (enforced)
+
+This contract is wired into the build/skill gates:
+
+- **`godxjp-ui-component` skill, Gate 0** — the FIRST gate before writing any component is the Framework-Component Test.

package/docs/CONSUMER-RULES.md

@@ -0,0 +1,14 @@
+# @godxjp/ui — the ten consumer rules
+
+Read this once; the audit enforces it. Everything else in `docs/` is for contributors.
+
+1. Load styles with `@import "@godxjp/ui/styles"` (fonts bundled) or `@import "@godxjp/ui/styles/core"` (no fonts). Never cherry-pick `*-layout.css`.
+2. Every page is `<PageContainer title subtitle extra footer>`; its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
+3. No Tailwind layout on your own elements: no `flex`, `grid`, `gap-*`, `p-*`, `m-*`, `space-*`. Rows are `<Flex>` (default row), stacks are `<Flex direction="col">`, grids are `<ResponsiveGrid>`.
+4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`.
+5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`.
+6. Text is `<Text>` / `<Heading>` with `tone`, `size`, `weight`, `truncate`, `mono` — not `className="text-muted-foreground font-semibold"`.
+7. Colours are semantic tokens (`tone="destructive"`, `bg-primary`), never palette names, hex, or `bg-black` / `text-white`.
+8. Sizes come from props (`size`, `width`, `columns`), never `w-[240px]` / `max-h-[420px]`.
+9. Logical directions (`ms-`, `me-`, `start-`, `end-`) when a utility is unavoidable; never `ml-` / `left-`.
+10. Run `node node_modules/@godxjp/ui/scripts/ui-audit.mjs <dir>` before every review; then `visual-audit.mjs <url>` on the running app. Zero errors is the bar.

package/docs/CUSTOMER-THEMING.md

@@ -0,0 +1,162 @@
+# Theming `@godxjp/ui`
+
+The design system ships a complete, **zero-config default theme**. Two audiences:
+
+- **Internal apps** — just import the styles. No configuration needed. - **Customer apps** — override a handful of **anchor tokens** in your own `theme.css`; the whole system rescales/retints in proportion (golden-ratio type & radius, derived shadow ramp, etc.).
+
+---
+
+## Internal apps — zero config
+
+```ts
+import "@godxjp/ui/styles";
+```
+
+That single import ships everything: colors, the bundled fonts (**Noto Sans JP** as the default face — including the Vietnamese coverage — with **M PLUS 2** as the fallback, self-bundled & subsetted), the golden-ratio type scale, spacing grid, radius scale, shadow ramp, and all component CSS. Nothing else to configure. Pick density per surface with `<PageContainer density="compact | default | comfortable">`.
+
+---
+
+## CSS entries — `styles` or `styles/core`, nothing smaller
+
+`@godxjp/ui/styles` bundles every component's CSS plus the fonts. When you manage fonts yourself (next/font, a system stack, a browser extension that must not ship font files), load the same layers without the faces:
+
+```css
+@import "@godxjp/ui/styles/core"; /* every component layer, no @font-face */
+```
+
+The per-layer files (`control`, `card-layout`, `navigation-layout`, …) are the package's internal structure, **not a public menu**. Layers share rules — a Select's rows and a menu's surface, a form's rhythm, a card's header type — so a page that loads a subset renders naked menus and unsized rows with no error. The runtime `visual-audit` reports it as `css-layers-missing`.
+
+---
+
+## Fonts — token-driven, per-language
+
+The base ships **no hardcoded brand face** (`--font-sans-base` is a pure system stack). Supply your own faces (next/font, `@fontsource`, self-host) and set tokens — never edit the library. Two modes, both token-only:
+
+```css
+/* 1. One face everywhere */
+:root {
+  --font-sans-base: var(--my-face), system-ui, sans-serif;
+}
+
+/* 2. Per-language faces — no [lang] selectors to write. Each locale reads its
+      slot, falling back to --font-sans-base. */
+:root {
+  --font-sans-base: var(--brand-sans), system-ui, sans-serif;
+  --font-sans-ja: "Noto Sans JP", var(--font-sans-base); /* html lang="ja" */
+  --font-sans-vi: "Montserrat", var(--font-sans-base); /* html lang="vi" */
+  --font-sans-ko: var(--font-kr), var(--font-sans-base); /* html lang="ko" */
+  --font-sans-zh-hans: var(--font-sc), var(--font-sans-base); /* zh | zh-Hans | zh-CN */
+  --font-sans-zh-hant: var(--font-tc), var(--font-sans-base); /* zh-Hant | zh-TW */
+}
+```
+
+`styles/base.css` wires every `[lang]` to its slot; the opt-in `styles/fonts`
+overwrites `--font-sans-base` (and `--font-sans-vi`) with the bundled stack —
+**Noto Sans JP** primary, **M PLUS 2** fallback. (**Bundle change:** v16 bundled
+Noto Sans JP + Montserrat; v18.12.0–18.12.19 bundled M PLUS 2 + Noto Sans JP;
+v18.12.20+ bundles Noto Sans JP + M PLUS 2 (product override, direct
+instruction). If your design spec named an earlier bundle's faces, set the
+tokens yourself rather than relying on the bundle.) Headings read
+`--font-family-display` and body reads `--font-family-body`, both defaulting to
+`--font-family-sans` — override them for a dual-font (display + body) brand.
+
+> **Per-locale @font-face loading is the consumer's job.** The library only
+> exposes the tokens; deciding _which_ `@font-face` blocks ship on _which_ pages
+> (e.g. loading the heavy CJK face only on `lang="ja"` routes) is done in your
+> app's font pipeline, not the library.
+
+---
+
+## Customer apps — override anchor tokens
+
+Import the styles, then set anchor tokens in your app's `theme.css` (loaded after the import).
+**Never edit the package token files** — override from your app.
+
+````css
+@import "@godxjp/ui/styles";
+
+:root { /* ── Brand color (HSL components — no hsl() wrapper) ─────────────── */ --primary: 211 73% 15%; /* your brand hue → buttons, links, focus ring, brand chrome */ --primary-foreground: 0 0% 100%; /* text on --primary */ --ring: 24 99% 46%; /* focus ring (often a brand accent) */ --accent: 24 99% 95%; /* hover/active surface tint */ --accent-foreground: 24 99% 28%;
+
+/* ── Type scale — ONE knob, golden-ratio derived ────────────────── */ --font-size-base: 1rem; /* 16px (default 14px). Every step (xs…2xl) + headings rescale by ratio. */ --font-size-ratio: 1.1227; /* φ^¼ default — raise toward φ=1.618 for a more dramatic scale. */
+
+/* ── Radius — ONE knob, golden-ratio derived ───────────────────── */ --radius: 0.5rem; /* 8px (default 6px). xs…2xl rescale by --radius-ratio (φ). */
+
+/* ── Shadow tint — ONE knob ─────────────────────────────────────── */ --shadow-color: 12 26 49; /* RGB channels (default 0 0 0). Tints the WHOLE shadow ramp. */
+
+/* ── Brand depth — all opt-in, all quiet by default ─────────────── */ --shadow-glow: 0 8px 20px hsl(var(--primary) / 0.32); /* glow halo on the primary CTA */ --card-shadow: 0 1px 2px rgb(12 26 49 / 0.06), 0 10px 28px -14px rgb(12 26 49 / 0.2); /* lift every Card */ --focus-ring-color: var(--ring); /* hue of every focus ring */ --focus-ring-width: 2px; /* thickness of every focus ring — 0 turns it OFF */ --focus-ring-opacity: 1; /* alpha of every focus ring */ --focus-ring-offset: 0px; /* gap, outline-form rings only (star, dot, anchor) */ --gradient-hero: linear-gradient( 180deg, hsl(var(--accent)), transparent ); /* PageContainer header banner */ --gradient-glow: radial-gradient( 60% 70% at 90% -8%, hsl(var(--primary) / 0.1), transparent 70% ); /* AppShell ambient wash */ --overlay-background: rgb(12 26 49 / 0.55); /* modal scrim (Dialog / Sheet / Drawer) */ } ```
+
+### The anchor tokens (single knobs that propagate)
+
+| Anchor                                                                     | Default                 | Propagates to                                                                           |
+| -------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------- |
+| `--primary` (+ `-foreground`, `--ring`, `--accent`, `--accent-foreground`) | SmartHR blue            | every brand/action/focus surface                                                        |
+| `--font-size-base` (+ `--font-size-ratio`)                                 | `0.875rem` (14px) / φ^¼ | the whole type scale `--font-size-{2xs…2xl}` + `--heading-h{1…4}` (all `base × ratioⁿ`) |
+| `--radius` (+ `--radius-ratio`)                                            | `0.375rem` (6px) / φ    | `--radius-{xs…2xl}` (all `radius × φⁿ`)                                                 |
+| `--shadow-color`                                                           | `0 0 0`                 | every shadow step `--shadow-{xs…2xl}` (`rgb(color / α)`)                                |
+| `--shadow-glow`                                                            | invisible               | brand glow halo on the primary CTA (set the full shadow value)                          |
+| `--card-shadow`                                                            | `none`                  | resting elevation of every Card                                                         |
+| `--focus-ring-color` / `--focus-ring-width`                                | `var(--ring)` / `2px`   | hue & thickness of every keyboard-focus ring (`width: 0` turns every ring OFF)          |
+| `--focus-ring-opacity` / `--focus-ring-offset`                             | `1` / `0px`             | alpha of every ring · gap for outline-form rings (star, carousel dot, heading anchor)   |
+| `--gradient-{hero,glow,brand}`                                             | `none`                  | hero header banner / AppShell ambient wash / spare (set the full gradient)              |
+| `--overlay-background`                                                     | `rgb(0 0 0 / .5)`       | the scrim of every overlay (Dialog / AlertDialog / Sheet / Drawer)                      |
+
+### Focus ring — one definition, three levels of override
+
+Every keyboard-focus ring in the system is drawn by a single rule (`src/styles/focus-ring.css`) reading the four tokens above. Nothing else paints one; a test fails the build if a stylesheet tries.
+
+That means retuning is a one-liner and it reaches everything:
+
+```css
+:root {
+  --focus-ring-color: 24 99% 46%; /* every ring, brand orange */
+  --focus-ring-width: 3px; /* every ring, thicker */
+}
+````
+
+**Per component.** A component that genuinely needs a different ring publishes its own knob and the rule picks it up locally — Toggle and TimeInput ship a heavier, softer ring because they are filled surfaces where a hard 2px reads as a second border:
+
+```css
+:root {
+  --toggle-focus-ring-width: 3px;
+  --toggle-focus-ring-alpha: 0.35;
+  --sidebar-user-focus-ring-alpha: 0.45; /* tinted shell ground */
+  --rating-focus-ring-offset: 2px; /* outline form needs a gap */
+}
+```
+
+**Per instance.** Any subtree, no CSS file needed:
+
+```tsx
+<div style={{ "--focus-ring-color": "0 84% 60%" } as React.CSSProperties}>…</div>
+```
+
+**Turning it off** — `--focus-ring-width: 0`, at any of the three levels. It ships **on** (WCAG 2.4.7 / 2.4.11); switching it off is a deliberate act on your side, never a default of this package. Removing the visible focus indicator fails WCAG 2.4.7 — do it only where another indicator takes over.
+
+**Adding your own component to the system**: put `ui-focus-ring` (or `ui-focus-ring-outline` when the mark needs a gap) on the focusable element.
+
+### What does NOT need an anchor
+
+Density (`<PageContainer density>`) scales component sizes, not the grid. - **Pills / squared corners** use `--radius-pill` (9999px) / `--radius-sharp` (0) — full-round shapes stay round regardless of `--radius`.
+
+---
+
+## Multi-tenant (one app, many brands)
+
+Scope the overrides under a tenant attribute instead of `:root`. The colour utilities are declared with `@theme inline`, so a scoped `--primary` (and the other anchors) **re-resolve at the element** — `bg-primary`, `text-success`, every component surface, the focus ring, the brand glow, gradients and the modal scrim all retint inside the scope:
+
+```css
+[data-tenant="betoya"] {
+  /* Colours, focus, glow, gradient, scrim — all propagate scoped */
+  --primary: 146 60% 30%; /* VN green */
+  --primary-foreground: 0 0% 100%;
+  --ring: 146 60% 30%;
+  --focus-ring-color: 146 60% 30%;
+  --shadow-glow: 0 8px 20px hsl(var(--primary) / 0.3);
+  --gradient-glow: radial-gradient(60% 70% at 90% -8%, hsl(var(--primary) / 0.1), transparent 70%);
+  --overlay-background: rgb(10 40 25 / 0.55);
+}
+```
+
+Set `data-tenant` on the app root. Two CSS-inheritance caveats for the **scoped** case (a single `:root` brand theme is unaffected — there, overriding just `--radius` / `--shadow-color` cascades):
+
+- **Radius & shadow-tint don't cascade from a scoped anchor.** `--radius-{xs…2xl}`, `--card-radius`, `--control-radius` and the `--shadow-{xs…2xl}` ramp are computed at their declaring element, so a scoped `--radius` / `--shadow-color` override won't reach them. For a scoped re-theme, re-declare the derived tokens you need (e.g. `--card-radius: var(--radius)`, or set `--card-shadow` to a literal value).

package/docs/DATETIME.md

@@ -0,0 +1,69 @@
+# formatDate — mandatory datetime display
+
+Package: `@godxjp/ui/datetime`
+
+## Import
+
+```tsx
+import { formatDate } from "@godxjp/ui/datetime";
+import { useDateTime } from "@godxjp/ui/app";
+```
+
+## Rules
+
+1. **Never** use `date-fns/format`, `toLocaleString`, or raw ISO slices for UI.
+2. **Always** wrap apps in `<AppProvider>` so defaults apply.
+3. **Optional** per-call `timezone` override — global prefs unchanged.
+
+## Defaults
+
+Omit `locale`, `timezone`, `timeFormat`, `dateFormat` → synced from AppProvider.
+
+## dateFormat presets
+
+| value | Pattern      | Default locale |
+| ----- | ------------ | -------------- |
+| `iso` | `yyyy-MM-dd` | ja             |
+| `dmy` | `dd/MM/yyyy` | vi             |
+| `mdy` | `MM/dd/yyyy` | en             |
+
+Sent to backend as `x-date-format`. Pick with `<DateFormatPicker />`.
+
+## kind presets
+
+| kind       | Use                                      |
+| ---------- | ---------------------------------------- |
+| `auto`     | Default — detects date / time / datetime |
+| `datetime` | Audit logs, `created_at`                 |
+| `date`     | `"2026-05-01"` fields                    |
+| `calendar` | `Date` from DatePicker                   |
+| `time`     | `"14:30"` HH:mm                          |
+| `long`     | Detail headings (PPP)                    |
+| `relative` | Activity feeds                           |
+
+## ISO 8601 patterns
+
+Date order follows `dateFormat` from AppProvider (`iso` | `dmy` | `mdy`):
+
+- `iso`: `yyyy-MM-dd` + `yyyy-MM-dd HH:mm`
+- `dmy`: `dd/MM/yyyy` + `dd/MM/yyyy HH:mm`
+- `mdy`: `MM/dd/yyyy` + `MM/dd/yyyy HH:mm`
+
+Time portion still follows `timeFormat` (24h vs 12h).
+
+## Examples
+
+```tsx
+formatDate("2026-05-01T14:30:00Z");
+formatDate("2026-05-01");
+formatDate("17:30", { kind: "time" });
+formatDate(pickedDate, { kind: "calendar" });
+formatDate(iso, { timezone: "Asia/Tokyo" });
+```
+
+## React
+
+```tsx
+const { format } = useDateTime();
+return <td>{format(row.createdAt)}</td>;
+```