@godxjp/ui 19.1.0 → 19.2.0

package/dist/tokens/semantic/layout.css

@@ -1,259 +1,85 @@
-/* Layout primitive tokens: page, section, stack, inline. */
+
 
 :root {
-  /* Semantic spacing — ONE coherent 4px grid (Tailwind/Material/Ant standard). All steps reference
-   * the linear `--space-*` scale (NOT the golden φ scale — golden ratio is for modular SIZE scales
-   * like type/radius, not the spacing grid; mixing the two left an incoherent density rhythm). The
-   * φ tokens remain available as an optional golden-layout utility, just not the spacing baseline. */
-  --space-page-x: var(--space-6); /* 24px — page gutter */
-  --space-page-y: var(--space-6); /* 24px */
-  --space-section: var(--space-4); /* 16px */
-  --space-stack-xs: var(--space-1); /* 4px */
-  --space-stack-sm: var(--space-2); /* 8px */
-  --space-stack-md: var(--space-4); /* 16px */
-  --space-stack-lg: var(--space-6); /* 24px */
-  --space-stack-xl: var(--space-10); /* 40px */
-  --space-inline-xs: var(--space-1); /* 4px */
-  --space-inline-sm: var(--space-2); /* 8px */
-  --space-inline-md: var(--space-3); /* 12px */
-  --space-inline-lg: var(--space-4); /* 16px */
 
-  /* OVERLAY STACKING — one system-level layer for every portaled surface (rule #44/#45).
-   * Tooltip, Popover, Select, DropdownMenu and Sheet all hard-coded `z-50` independently, so a
-   * host app that mounts @godxjp/ui under its own stacking context (a sticky masthead, a
-   * third-party chat widget) had to fight five separate literals. Stacking is a SYSTEM decision,
-   * not a per-primitive one: a service raises every overlay together by setting this once. */
+  --space-page-x: var(--space-6);
+  --space-page-y: var(--space-6);
+  --space-section: var(--space-4);
+  --space-stack-xs: var(--space-1);
+  --space-stack-sm: var(--space-2);
+  --space-stack-md: var(--space-4);
+  --space-stack-lg: var(--space-6);
+  --space-stack-xl: var(--space-10);
+  --space-inline-xs: var(--space-1);
+  --space-inline-sm: var(--space-2);
+  --space-inline-md: var(--space-3);
+  --space-inline-lg: var(--space-4);
+
   --overlay-z-index: 50;
 
-  /* Master-detail geometry. Consumers choose a semantic rail preset; they never author grid tracks. */
-  --master-detail-rail-compact: 18.75rem; /* 300px */
-  --master-detail-rail-standard: 20rem; /* 320px */
+  --master-detail-rail-compact: 18.75rem;
+  --master-detail-rail-standard: 20rem;
   --master-detail-gap: var(--space-stack-md);
-  /* The collapse threshold: MasterDetail keeps its two-track split while the composition's OWN
-   * inline size is at least this wide, and stacks (master then detail) below it. A service theme
-   * retunes it once globally; the `collapseBelow` prop overrides it per instance (rule #45).
-   * This is a real knob — the layout reads it through the flex-basis threshold, NOT a media
-   * query, precisely so a `var()` can drive it (see src/styles/layout.css · .ui-master-detail). */
-  --master-detail-collapse-below: 40rem; /* 640px — the `sm` step */
 
-  /* Bounded master viewport (gh#231). OPT-IN, chosen by the semantic `masterViewport` prop —
-   * `auto` (the default) applies NO bound, so every existing composition is unchanged. A real
-   * collection can be thousands of pixels tall; when the layout stacks, that pushes the detail
-   * far below the fold. The presets cap the collection's BLOCK size and scroll it inside the
-   * region instead. Sized as a whole number of nominal collection rows (2.5rem ≈ a compact list
-   * row) so a service theme retunes them in the same semantic unit the design grid uses. */
-  --master-detail-master-viewport-compact: 20rem; /* 320px — about 8 nominal rows */
-  --master-detail-master-viewport-standard: 28rem; /* 448px — about 11 nominal rows */
-  /* Focus-ring room INSIDE the bounded region: an overflow container clips both axes, so without
-   * an inset the ring of a row at the edge would be cut off (WCAG 2.4.11/2.4.13). Doubles as the
-   * scroll-padding so a row scrolled into view never sits flush against the clip edge. */
-  --master-detail-master-viewport-inset: var(--space-1); /* 4px */
+  --master-detail-collapse-below: 40rem;
+
+  --master-detail-master-viewport-compact: 20rem;
+  --master-detail-master-viewport-standard: 28rem;
+
+  --master-detail-master-viewport-inset: var(--space-1);
 
   --space-page-active-x: var(--space-page-x);
   --space-page-active-y: var(--space-page-y);
   --space-section-active: var(--space-section);
-  --space-page-compact-x: var(--space-4); /* 16px mobile page gutter */
+  --space-page-compact-x: var(--space-4);
   --space-page-compact-y: var(--space-4);
   --space-section-compact: var(--space-4);
 
-  /* Modal scrim — the single backdrop colour shared by EVERY overlay (Dialog, AlertDialog, Sheet,
-   * Drawer, AppShell mobile nav). Themeable (rule #44) so a service tints the wash to its brand
-   * once, e.g. a navy `--overlay-background: rgb(12 26 49 / .55)`, instead of forking each overlay.
-   *
-   * HOW IT REACHES AN OVERLAY (gh#215 — it previously reached NOTHING): each surface declares its
-   * own knob `initial` and resolves a SHARE of this colour at the call site,
-   * `var(--dialog-overlay-background, color-mix(in srgb, var(--overlay-background)
-   * var(--dialog-overlay-alpha), transparent))`. That keeps the calibrated per-surface depth — a
-   * slide-in Sheet washes the page more lightly (40%) than a modal Dialog (60%) — while ONE
-   * override here retints every backdrop. Per docs/TOKENS.md the knobs must stay `initial`: a
-   * `:root` binding would freeze and a scoped `[data-tenant]`/`.dark` override of this token would
-   * never reach the overlay. Overlays are portaled, so a tenant scope must also sit on the portal
-   * container (see docs/CUSTOMER-THEMING.md). */
   --overlay-background: rgb(0 0 0 / 0.5);
 
-  /* Full-bleed rule under the PageContainer header. OFF by default — the title/body
-   * gap already separates them; a divider is a service-theme opt-in:
-   * `--page-header-divider: 1px solid hsl(var(--border));` */
+  --page-footer-pad-block-end: var(--space-stack-md);
   --page-header-divider: none;
 
-  /* PageContainer `toolbar` — the fixed chrome band between the header and the (scrolling) body.
-   * ALL THREE knobs are quiet by default (rule #44):
-   *   background    — `transparent`, i.e. the band shows the page ground exactly as it did before
-   *                   the knob existed. It is bound at `:root` and NOT `initial`, unlike the
-   *                   divider below, because the default is a plain CSS keyword rather than
-   *                   another role token: there is nothing for a scoped [data-tenant]/.dark
-   *                   override to re-resolve, so the `initial` + call-site-fallback dance would
-   *                   buy nothing and only hide the default from anyone reading this file. A
-   *                   service that wants the band to read as its own surface — the design that
-   *                   asked for this knob puts a chat channel's workflow rail on the card ground —
-   *                   sets `--page-toolbar-background: hsl(var(--card));` ONCE in its theme. Never
-   *                   `className="bg-card"` at the call site: that is hand-laid page chrome, it
-   *                   paints only under `variant="flush"` gutters correctly by accident, and it
-   *                   cannot be re-themed per tenant.
-   *   pad-block 0   — the band's ONLY breathing room, and the only one it should ever have. The
-   *                   band is chrome, so it sits FLUSH against the header above and the body
-   *                   below (src/styles/layout.css cancels the container's --page-band-gap from
-   *                   the band itself); there is deliberately no outside space to tune, because a
-   *                   ruled, painted band floating in a void divides nothing. A service that opts
-   *                   into the background or the divider gives the band its inset HERE
-   *                   (`--page-toolbar-pad-block: var(--space-2)`) instead of padding the strip at
-   *                   the call site. Still 0 by default: a transparent band is not a surface and
-   *                   has no inside to breathe, and under `fill` every pixel of it comes straight
-   *                   off the scroll viewport the slot exists to protect.
-   *   divider       — declared `initial` so the CALL SITE can fall back to --page-header-divider
-   *                   (`var(--page-toolbar-divider, var(--page-header-divider))`). One theme
-   *                   declaration therefore rules the whole page chrome consistently, and a
-   *                   scoped [data-tenant]/.dark override of the header divider still reaches the
-   *                   band — a `:root` binding would freeze it at the :root value
-   *                   (docs/TOKENS.md · "Role-mirror knobs MUST be `initial`"). Set
-   *                   `--page-toolbar-divider: none` to silence just this band. */
   --page-toolbar-background: transparent;
   --page-toolbar-pad-block: 0px;
   --page-toolbar-divider: initial;
 
-  /* Top rule of the PageContainer `footer` — the third page chrome band, brought onto the same
-   * contract as the header and the toolbar (its rule used to be a hard literal in layout.css, so
-   * a page could not turn it off at all). Declared `initial` like the toolbar's, so the CALL SITE
-   * resolves it as `var(--page-footer-divider, 1px solid hsl(var(--border)))` and a scoped
-   * [data-tenant]/.dark override still reaches it (docs/TOKENS.md · "Role-mirror knobs MUST be
-   * `initial`").
-   *
-   * It is the ONE chrome knob whose default is a RULE rather than silence, and deliberately so:
-   * `footer` is the shared slot a form's Save/Cancel bar lands in, where the line separating the
-   * actions from the page content is the behaviour every existing page already depends on. The
-   * old literal is the fallback verbatim, so unset is byte-identical. A page whose footer content
-   * already carries its own frame — a chat composer is a bordered Card — silences the duplicate
-   * with `--page-footer-divider: none`. */
   --page-footer-divider: initial;
 
-  /* Bottom inset of the page header, sized so title→body distance (this pad + the
-   * --space-section-active container gap) EQUALS the page's top padding — the title
-   * band reads vertically balanced (24 above / 24 below by default), instead of the
-   * old fixed 16px pad that left 24 above vs 32 below. A page that passes a `toolbar`
-   * measures title→BAND instead (this pad alone, the gap being cancelled): the band is
-   * chrome attached to the header, not the next section down. */
   --page-header-pad-bottom: calc(var(--space-page-active-y) - var(--space-section-active));
 
-  /* Inline measure of the header `extra` region while the page header is in `responsive-inline`
-   * arrangement (gh#231). Below the 640px step the default arrangement drops `extra` onto its own
-   * full-width line under the subtitle; `headerLayout="responsive-inline"` keeps it beside the
-   * title band at this measure instead, so a single compact control (a search field, one primary
-   * action) stays on the title row at 390px. Unused by the default arrangement, so no existing
-   * page moves. 11rem = 176px, i.e. the control ends flush with the compact page gutter. */
-  --page-header-extra-measure: 11rem; /* 176px */
+  --page-header-extra-measure: 11rem;
 
-  /* Gap between the page title and its status/meta band (PageContainer `status`,
-   * godxjp-ui#255), and between the band's own items. One knob aligns the badge row
-   * to a service's grid; a page that never passes `status` reads neither the token
-   * nor the wrapping row. */
   --page-header-status-gap: var(--space-inline-sm);
 
-  /* PageContainer `headerLoading` placeholders (gh#255). The title/subtitle elements wear the
-   * shared `.ui-skeleton-block` skin, so they need only a MEASURE and a block size — a service
-   * retunes the pending band's proportions here instead of per page. */
-  --page-title-placeholder-measure: 14rem; /* 224px */
+  --page-title-placeholder-measure: 14rem;
   --page-title-placeholder-block-size: 1.5em;
-  --page-subtitle-placeholder-measure: 22rem; /* 352px */
+  --page-subtitle-placeholder-measure: 22rem;
   --page-subtitle-placeholder-block-size: 1.25em;
 
-  /* Bounded page MEASURE (gh#245 / gh#247) — the shared inline cap applied to the page HEADER and
-   * BODY together, so the header `extra` action ends on the same edge as the body surface (the
-   * `variant="narrow"` complaint: it caps only `.ui-page-body`, leaving the header action out at
-   * the page edge). Selected by the semantic `measure` prop; `measure="default"` reads NEITHER
-   * token, so an existing page is untouched.
-   *
-   * These are OUTER measures: the page gutters (--space-page-active-x, 24px each side by default)
-   * live INSIDE the cap, so the VISIBLE surface is the measure minus both gutters:
-   *   narrow  42rem = 672px → 624px visible surface (the historical variant="narrow" body width)
-   *   medium  48rem = 768px → 720px visible surface (the canonical readable/feed measure)
-   * Below the cap nothing binds, so a 390px viewport stays fluid at the 16px compact gutter
-   * (358px surface). A service theme retunes both in ONE place; never a page-local max-width. */
-  --page-measure-narrow: 42rem; /* 672px outer → 624px surface */
-  --page-measure-medium: 48rem; /* 768px outer → 720px surface */
+  --page-measure-narrow: 42rem;
+  --page-measure-medium: 48rem;
 
-  /* Responsive page typography is independent from density. Density changes information spacing;
-   * these tokens change only page chrome so mobile keeps readable body text and touch targets. */
   --page-title-font-size: var(--heading-h1);
   --page-title-font-size-compact: var(--heading-h2);
   --page-subtitle-font-size: var(--font-size-base);
   --page-subtitle-font-size-compact: var(--font-size-sm);
 
-  /* PageContainer `headerScale="chrome"` — the title step for a page whose top row IS CHROME
-   * rather than a document title: a chat channel name, a mail subject line, an IDE tab. It is a
-   * SEPARATE knob from the two above on purpose: those are ONE document title at two viewport
-   * sizes (a responsive step), while this is a different KIND of page and holds at every width.
-   * `--heading-h3` (= --font-size-base, 14px) is the body step, which is the point — the row
-   * reads as a label ON the surface, not as the page's headline, and the header band collapses
-   * from the measured 61px to ~40px once it stops carrying a 20px h1. Quiet by default: a page
-   * that never passes `headerScale` never reads this token (rule #44). */
   --page-title-font-size-chrome: var(--heading-h3);
 
-  /* The SUBTITLE step of the same fact. Measured against the reference chat screen, the chrome
-   * title and the chrome subtitle were rendering at the SAME step (both --font-size-base), which
-   * is not a hierarchy — a channel name and the channel's purpose line read as one undifferentiated
-   * block. The design puts the purpose line two steps down (`Text size="2xs"`), and the size is
-   * what carries the LINE BOX: at 14px/1.7 the subtitle line is 23.8px tall, at 11px/1.7 it is
-   * 18.9px, so the whole header band loses ~5px it was spending on a caption. `--font-size-2xs`
-   * (ratio⁻², ≈11px) is that step, and it is the same golden scale the title step reads — never a
-   * literal. Quiet by default: a page that never passes `headerScale` never resolves it (#44). */
   --page-subtitle-font-size-chrome: var(--font-size-2xs);
 
-  /* The page's TOP inset under `headerScale="chrome"`, the second half of the same fact: chrome
-   * sits on the frame's edge. A document page opens with --space-page-active-y (24px, 16px below
-   * the 720px step) because a title needs air above it; a chat channel head, a mail subject bar or
-   * an IDE tab strip is the frame itself, and 24px of margin above it reads as a page floating
-   * inside its own shell — measured on a consumer chat screen as 24px lost off the top of the
-   * transcript viewport, against a design whose channel head starts at y=0. 0 is therefore the
-   * quiet default (rule #44), and it is a knob rather than a literal so a service whose grid wants
-   * its chrome inset (`--page-pad-block-start-chrome: var(--space-2)`) retunes it once instead of
-   * forking the page shell. Read ONLY when the prop is passed, so no document page resolves it. */
   --page-pad-block-start-chrome: 0px;
 
-  /* The BAND HEIGHT of the same fact (gh#331). A document header is content-height by definition —
-   * a title is as tall as the title is. A chrome band is the opposite: it is furniture, and
-   * furniture has a height that things centre INTO. `AppShell` has had `--app-shell-bar-height`
-   * for exactly that since it shipped; `PageContainer` had no equivalent, so a `headerScale="chrome"`
-   * band's vertical centre drifted with its own copy — measured in Chromium on
-   * /isolate/layout-page-container, 42.02px with an `extra` control and 40.38px without, i.e. the
-   * centre moves 0.8px for a change of content and there is no value a service can aim at.
-   *
-   * WHO OWNS THE BAND-HEIGHT AXIS (the question gh#331 defers to gh#330). `--app-shell-bar-height`
-   * does: it is the system's one declared chrome-band height, and `--centered-shell-bar-height`
-   * already reads it. A service that wants its page chrome to sit on the shell bar's band writes
-   * ONE line — `--page-header-min-block-size-chrome: var(--app-shell-bar-height)` — and the two
-   * bands are on one axis for good.
-   *
-   * It is NOT that value by DEFAULT, and the reason is not timidity: a `PageContainer` with a
-   * chrome header is not necessarily inside an `AppShell` (the canonical chat composition renders
-   * one inside a bordered region, a SplitPane pane, a Card), and a band that is not trying to line
-   * up with a bar has no business inheriting that bar's height. `auto` is the quiet state (rule
-   * #44): no floor, content-height, byte-identical to every page rendered before this token
-   * existed — document AND chrome.
-   *
-   * A MIN, never a fixed height: a taller `extra` (an `lg` control, a wrapped JA/VI channel name)
-   * must still fit rather than overflow its own band. The header centres its content in whatever
-   * band it ends up with — see `justify-content` in styles/layout.css — so raising this knob
-   * centres, it does not top-pack. The header's own `--page-header-pad-bottom` lives INSIDE the
-   * band (border-box); under the canonical chrome composition (`variant="ghost"`) that pad is 0
-   * and the centring is exact. */
   --page-header-min-block-size-chrome: auto;
 
-  /* Section "chrome" padding — the SHARED inset for header / body / footer of every overlay-ish
-   * surface (Dialog · Sheet · Drawer · Card). One global knob: a service sets these once instead of
-   * per-component. Vertical is tightened (16 vs the old 24) and density-aware (see density.css);
-   * horizontal stays 24 (Ant standard). Per-component tokens (--sheet-pad-*, --dialog-space-inset…)
-   * default to these and only override when a surface genuinely needs to differ. */
-  --space-chrome-x: var(--space-6); /* 24px — horizontal inset */
-  --space-chrome-y: var(--space-4); /* 16px — vertical inset (header/footer/body) */
-  --space-chrome-gap: var(--space-stack-sm); /* gap between header ↔ body ↔ footer */
+  --space-chrome-x: var(--space-6);
+  --space-chrome-y: var(--space-4);
+  --space-chrome-gap: var(--space-stack-sm);
 
-  /* The ONE vertical gap between a field's LABEL and its CONTENT — same everywhere a label sits above
-   * a control or a value (FormField, Descriptions, Form, any label-above stack). Single source so the
-   * whole system stays in sync (gh feedback: Descriptions was ~0px while FormField was 8px). */
-  --field-label-gap: var(--space-2); /* 8px */
+  --field-label-gap: var(--space-2);
 }
 
-/* Canonical admin collection composition. Services may retune these semantic knobs once. */
 :root {
   --admin-collection-control-height: var(--control-height-default);
   --admin-collection-section-gap: var(--space-stack-md);

package/docs/CANONICAL-CONTRACTS.md

@@ -0,0 +1,206 @@
+# Canonical contracts — the answer to "does @godxjp/ui have an X?"
+
+A consumer design spec names a component (`PageHeader`, `Banner`, `SocialLinks`, `OrganizationChoiceList`, `ServiceRolePanel`, `BranchScopePicker`, `PermissionMatrix`, `FilterBar`).
+
+---
+
+## 1. `PageHeader` — **`PageContainer`'s embedded header IS the DXS PageHeader** (gh#255)
+
+```ts
+import { PageContainer, type PageContainerProps } from "@godxjp/ui/layout";
+```
+
+There is **no standalone `PageHeader` export**. The canonical page title band — breadcrumbs · `<h1>` · subtitle · status/meta (`status`) · actions (`extra`) — lives on **one renderer**: `PageContainer`'s embedded header, with `headerLayout` (`stack` | `responsive-inline`), `breadcrumbLabel` (the landmark-unique override), `measure` and `headerLoading` (skeleton title band + `aria-busy`, keeping the `<h1>` in the document with an sr-only name so the heading outline never disappears mid-load).
+
+**Why one renderer rather than a lifted export.** The band's geometry is token-owned (`.ui-page-header`, `--page-header-status-gap`, the placeholder measures) and every page mounts it through `PageContainer`, so a second mount point would be a second `<h1>` waiting to happen. A title band outside a full page shell (a Sheet detail, a `MasterDetail` pane, a tab body) is a COMPOSITION of `Breadcrumb` + heading text + `Flex` at section level — it should NOT be an `<h1>`.
+
+| Situation                                    | Use                                                                       |
+| -------------------------------------------- | ------------------------------------------------------------------------- |
+| The surface **is a page**                    | `PageContainer` (`title`/`subtitle`/`status`/`extra`/`breadcrumb`)        |
+| A title band **inside** a pane/sheet/tab     | Compose at section level — never a second `<h1>` / `PageContainer` header |
+| The user **may not see the resource at all** | `ErrorSurface` — never a header that leaks the resource's name            |
+
+`denied` / `error` are deliberately **not** states of the band — see the table above.
+
+---
+
+## 2. `Banner` — **EXPORTED** as the page-level `Alert` (gh#255)
+
+```ts
+import { Banner, type BannerProps } from "@godxjp/ui/feedback";
+```
+
+Same tones, same icon defaults, same assertive/polite role split, same actions grid, same dismiss control. `Banner.Title` **is** `AlertTitle` — the same element, not a parallel family.
+
+It is an alias, not a second implementation, for the same reason `FilterBar` is an alias of `Toolbar`: a banner and an inline alert are one object at two measures, and duplicating the tone mapping and dismiss behaviour is exactly what the no-duplication rule forbids.
+
+| Scope of the message                                                  | Use                                         |
+| --------------------------------------------------------------------- | ------------------------------------------- |
+| The page or the whole app (maintenance, trial expiry, read-only mode) | `Banner` above the header, or in `AppShell` |
+| One section / card / form                                             | `Alert` inside that section                 |
+| One field                                                             | `FormField` `error`                         |
+| Transient ("saved")                                                   | `toast()`                                   |
+| The user may not see the page at all                                  | `ErrorSurface`                              |
+
+Retheme through tokens, never a wrapper class: `--banner-radius`, `--banner-border-width`, `--banner-border-block-end-width`, `--banner-space-block`, `--banner-space-inline`, `--banner-dismiss-space-offset`. Never stack two banners.
+
+---
+
+## 3. `AuthShell preset="registration"` — **EXPORTED** (gh#256)
+
+```tsx
+<AuthShell variant="canonical" preset="registration" brand={…} footer={…}>
+```
+
+The 360px sign-up measure with a 15px inline gutter at 390px — the same page rhythm as `preset="login"`, so sign-in → sign-up never jumps on a phone. It carries the full password form **and** the pending-email confirmation state with no consumer geometry CSS.
+
+Two things make it structurally distinct from every other preset, and both are load-bearing:
+
+1. **It is the only START-aligned preset.** A sign-up card is the tallest surface in the hosted-identity set (name · email · password · confirm · strength · consent · submit · providers). A vertically _centred_ tall card overflows **above the scroll origin** on a short viewport, putting its first field permanently out of reach. 2. **It is the only preset with its own footer-clearance knob**, so the legal/consent footer never sits flush against the submit button at the end of a long scroll.
+
+Geometry knobs: `--auth-shell-registration-{card-max-width, main-padding-block-start, main-padding-block-start-mobile, main-padding-inline, main-padding-inline-mobile, main-padding-block-end, main-padding-block-end-mobile, card-stack-gap}`.
+
+Worked screen: `docs/layout/auth-shell-registration.tsx`.
+
+---
+
+## 4. `SocialLinks` — **COMPOSE** (gh#256)
+
+There is no `SocialLinks` component, and none is planned.
+
+```tsx
+<AuthDivider label="または" />
+<Flex direction="col" gap="sm">
+  {providers.map((p) => (
+    <Button key={p.id} variant="outline" disabled={submitting} onClick={p.start}>
+      <p.Icon aria-hidden="true" />
+      {p.label}
+    </Button>
+  ))}
+</Flex>
+```
+
+**Why.** It owns no behaviour: each provider is a plain action the app points at its own OAuth start URL. A framework component would have to invent _which_ providers a product offers, in what order, and what consent they imply — product decisions the package must not make. `disabled` and `loading` are the `Button`'s own props; there is no provider-specific API to learn.
+
+---
+
+## 5. `OrganizationChoiceList` — **COMPOSE** (gh#256)
+
+```tsx
+<Card>
+  <CardHeader>…</CardHeader>
+  <CardContent flush>
+    <ul>
+      {orgs.map((org) => (
+        <ListRow
+          as="li"
+          key={org.id}
+          leading={<Avatar>…</Avatar>}
+          title={org.name}
+          description={org.role}
+          trailing={
+            <Button variant="ghost" size="sm">
+              選択
+            </Button>
+          }
+        />
+      ))}
+    </ul>
+  </CardContent>
+</Card>
+```
+
+`CardContent flush` is what produces shared row dividers instead of a card outline per row.
+
+States — all existing exports, no bespoke markup:
+
+| State             | Use                                                      |
+| ----------------- | -------------------------------------------------------- |
+| loading           | `Skeleton` rows at the settled row height                |
+| empty             | `EmptyState`                                             |
+| error             | `Alert tone="destructive"` + a retry action              |
+| permission-denied | `Alert tone="warning"` (section) / `ErrorSurface` (page) |
+| disabled row      | the row's own `Button disabled`                          |
+
+Worked screens: `docs/layout/auth-shell-context.tsx`, `docs/layout/auth-shell-registration.tsx`.
+
+---
+
+## 6. `ServiceRolePanel` · `BranchScopePicker` · `PermissionMatrix` — **EXPORTED** (gh#257)
+
+All three compositions were promoted to public exports — the composition-first Gate 0 verdict was revisited when consumers kept re-authoring the same states and geometry:
+
+```ts
+import { ServiceRolePanel } from "@godxjp/ui/layout";
+import { BranchScopePicker } from "@godxjp/ui/data-entry";
+import { PermissionMatrix } from "@godxjp/ui/data-display";
+```
+
+```ts
+import {
+  grantKey,
+  hasGrant,
+  rolesDifferOnPermission,
+  visibleRows,
+  countGrants,
+  countDifferences,
+} from "@godxjp/ui/lib/permission-grid";
+```
+
+Layout the role list beside the editor with `MasterDetail` — it owns the tracks, the gap and the stacking threshold as tokens, so the page carries no `grid-template-columns` and no media query at 1440 / 1024 / 390. Destructive changes go through `AlertDialog variant="destructive"` (add `challenge` for type-to-confirm).
+
+Worked screens: `docs/layout/service-role-panel.tsx`, `docs/data-entry/branch-scope-picker.tsx`, `docs/data-display/permission-matrix.tsx`, `docs/showcase/permission-matrix.tsx`.
+
+---
+
+## 7. `FilterBar` — **EXPORTED, and now typed** (gh#258)
+
+`FilterBar` / `FilterBarGroup` remain the public domain-neutral names for the `Toolbar` primitives.
+
+```tsx
+<FilterBar
+  search={{ value: q, onValueChange: setQ, placeholder: "Search records" }}
+  filters={[
+    {
+      value: "status",
+      label: "状態",
+      options: STATUS_OPTIONS,
+      selected: status,
+      onSelectedChange: setStatus,
+    },
+  ]}
+  chips={applied.map((f) => ({ value: f.value, label: f.label }))}
+  onChipRemove={lift}
+  resultCount={rows.length}
+  onClear={clearAll}
+  hasActiveFilters={applied.length > 0}
+  actions={
+    <Button variant="outline" size="sm">
+      エクスポート
+    </Button>
+  }
+/>
+```
+
+**Order is the contract.** DOM order is tab order, and the **bar** decides it, not each page:
+
+```
+search → typed filters → children (custom composition filters) → reset → actions
+  → applied-chips row → result-count / error line
+```
+
+Reset sits before `actions` deliberately, so "clear filters" never lands at the end of the row beside an unrelated primary action.
+
+What each prop buys that a plain child did not:
+
+- **`search`** — the canonical `SearchInput` at one token-owned measure (`--filter-bar-search-width`) across every list page, full-width below the 640px step. Controlled through the `value`/`defaultValue`/`onValueChange` triad; `onSearch` mirrors the debounced-term callback. - **`filters`** — labelled, domain-neutral `Select` filters whose visible `label` is the control's real `<label htmlFor>` (WCAG 2.5.3 / 1.3.1), at the `--filter-bar-filter-width` measure. - **`chips`** — the chip lifecycle: a labelled row, a remove control named after _that specific_ filter (a row of buttons all called "Remove" is unusable from a screen-reader's control list), and no row at all when nothing is applied. Remove = `onChipRemove(value)`; clear-all = `onClear`. - **`resultCount`** — a polite live region formatted with `Intl.NumberFormat` + CLDR plurals.
+
+The bar still owns **no filter state**. `search`/`filters`/`chips` are rendered consumer data, `resultCount` is a number you computed. It owns placement, measure, ordering, keyboard order and announcement — nothing else.
+
+Worked screen: `docs/navigation/filter-bar.tsx`.
+
+---
+
+## Adding to this document
+
+Any future "does the package have an X?" answer belongs here, with: the Gate 0 verdict, the public-route question, and — for a composition — the exact primitives, the token knobs, and the state table. If the honest answer is "the consumer cannot reach it publicly", that is a package gap: fix the library, never patch the consumer app.