@godxjp/ui 18.4.0 → 18.6.0

package/dist/styles/shell-layout.css

@@ -6,24 +6,31 @@
 @layer components {
   .app-root {
     display: grid;
+    width: 100%;
+    max-width: 100vw;
+    min-width: 0;
     grid-template-areas:
       "sidebar topbar"
       "sidebar main"
       "sidebar footer";
-    grid-template-columns: 16rem minmax(0, 1fr);
+    /* Rail width is a knob, never a literal (rule #45) — a service on a different design grid sets
+     * --app-shell-sidebar-width once (e.g. 255px) instead of forking this rule. */
+    grid-template-columns: var(--app-shell-sidebar-width) minmax(0, 1fr);
     grid-template-rows: var(--app-shell-bar-height) minmax(0, 1fr) auto;
     height: 100vh;
     background: hsl(var(--background));
   }
 
   .app-root[data-collapsed="true"] {
-    grid-template-columns: 4rem minmax(0, 1fr);
+    grid-template-columns: var(--app-shell-rail-width) minmax(0, 1fr);
   }
 
   .app-sidebar {
     grid-area: sidebar;
     display: flex;
+    height: 100%;
     min-width: 0;
+    min-height: 0;
     flex-direction: column;
     overflow: hidden;
     border-inline-end: 1px solid hsl(var(--border));
@@ -40,9 +47,10 @@
      * set to baseline; --scaling:1 alone is not enough — see foundation.css). */
     display: flex;
     min-width: 0;
+    overflow: hidden;
     align-items: center;
-    gap: var(--space-3);
-    padding-inline: var(--space-4);
+    gap: var(--app-shell-bar-gap);
+    padding-inline: var(--app-shell-bar-inset);
     border-bottom: 1px solid hsl(var(--border));
     background: hsl(var(--card));
     /* Opt-in brand-chrome wash — invisible by default (--topbar-gradient: none). */
@@ -105,7 +113,7 @@
     flex: 1 1 auto;
     flex-direction: column;
     align-items: center;
-    justify-content: center;
+    justify-content: var(--auth-shell-main-align);
     padding: var(--auth-shell-main-padding);
   }
 
@@ -120,6 +128,271 @@
     color: hsl(var(--muted-foreground));
   }
 
+  .ui-auth-shell[data-variant="canonical"] {
+    --control-height: var(--auth-shell-canonical-control-height);
+    --heading-h1: var(--auth-shell-canonical-heading-size);
+    --auth-shell-card-max-width: var(--auth-shell-canonical-card-max-width);
+    --auth-shell-main-padding: var(--auth-shell-canonical-main-padding);
+  }
+
+  /*
+   * NAMED FLOW PRESETS (gh#217 / gh#220) — orthogonal to `variant` and declared AFTER it (equal
+   * specificity, so source order wins) so a preset re-measures the page while `variant="canonical"`
+   * keeps owning control density and heading size. A preset owns the card measure + page gutters,
+   * so the consumer never overrides `--auth-shell-card-max-width` by hand.
+   */
+  .ui-auth-shell[data-preset] .ui-auth-shell-card {
+    display: flex;
+    flex-direction: column;
+    gap: var(--auth-shell-card-stack-gap);
+  }
+
+  /* Login is an anchored three-part composition: AuthIdentity · Card · AuthFooter. The fixed
+   * identity track absorbs absent, one-line and wrapped two-line requester states while its
+   * content remains visually adjacent to the Card. This keeps real requester data intact without
+   * allowing its line count to move the canonical SCR-001 card anchor (gh#237). */
+  .ui-auth-shell[data-preset="login"] {
+    --auth-shell-card-max-width: var(--auth-shell-login-card-max-width);
+    --auth-shell-main-align: flex-start;
+    --auth-shell-main-padding: var(--auth-shell-login-flow-offset-block)
+      var(--auth-shell-login-main-padding-inline) var(--auth-shell-login-main-padding-block-end);
+    --auth-shell-card-stack-gap: var(--auth-shell-login-card-stack-gap);
+    --auth-shell-card-padding-block-compact: var(--auth-shell-login-card-padding-block-compact);
+  }
+
+  .ui-auth-shell[data-preset="login"] .ui-auth-shell-card {
+    display: grid;
+    grid-template-rows: var(--auth-shell-login-identity-slot-block-size) auto auto;
+  }
+
+  .ui-auth-shell[data-preset="login"] .ui-auth-shell-card > .ui-auth-identity,
+  .ui-auth-shell[data-preset="login"] .ui-auth-shell-card > :has(> .ui-auth-identity) {
+    min-width: 0;
+    min-height: 0;
+    block-size: var(--auth-shell-login-identity-slot-block-size);
+  }
+
+  .ui-auth-shell[data-preset="login"] .ui-auth-shell-card > .ui-auth-identity,
+  .ui-auth-shell[data-preset="login"]
+    .ui-auth-shell-card
+    > :has(> .ui-auth-identity)
+    > .ui-auth-identity {
+    height: 100%;
+    justify-content: flex-end;
+  }
+
+  .ui-auth-shell[data-preset="login"] .ui-auth-requester {
+    max-width: 100%;
+    justify-content: center;
+  }
+
+  .ui-auth-shell[data-preset="login"] .ui-auth-requester > :last-child {
+    min-width: 0;
+    overflow-wrap: anywhere;
+    text-align: center;
+  }
+
+  .ui-auth-shell[data-preset="device-authorization"] {
+    --auth-shell-card-max-width: var(--auth-shell-device-card-max-width);
+    --auth-shell-main-padding: var(--auth-shell-device-main-padding);
+  }
+
+  .ui-auth-shell[data-preset="context-selection"] {
+    --auth-shell-card-max-width: var(--auth-shell-context-card-max-width);
+    --auth-shell-main-padding: var(--auth-shell-context-main-padding);
+    --auth-shell-card-stack-gap: var(--auth-shell-context-card-stack-gap);
+  }
+
+  /* Account-recovery preset (gh#233) — one 432px measure for BOTH SCR-008 panels (password
+   * recovery and the sign-in MFA challenge). Title + description live INSIDE the bordered surface
+   * here, so the panel is `Card > CardHeader(CardTitle + CardDescription)` with no `AuthIdentity`
+   * mark above it — the preset only re-measures the page, it never dictates content. */
+  .ui-auth-shell[data-preset="account-recovery"] {
+    --auth-shell-card-max-width: var(--auth-shell-recovery-card-max-width);
+    --auth-shell-main-padding: var(--auth-shell-recovery-main-padding);
+  }
+
+  .ui-auth-identity {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--auth-identity-gap);
+    text-align: center;
+  }
+
+  .ui-auth-requester {
+    display: flex;
+    align-items: center;
+    gap: var(--auth-requester-gap);
+  }
+
+  .ui-auth-requester-icon {
+    display: inline-flex;
+    width: var(--auth-requester-icon-size);
+    height: var(--auth-requester-icon-size);
+    align-items: center;
+    justify-content: center;
+    border-radius: var(--radius-sm);
+    background: hsl(var(--accent));
+    color: hsl(var(--primary));
+  }
+
+  .ui-auth-requester-icon > svg {
+    width: var(--auth-requester-glyph-size);
+    height: var(--auth-requester-glyph-size);
+  }
+
+  .ui-auth-account-summary {
+    display: flex;
+    min-height: var(--auth-account-summary-min-height);
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--auth-account-summary-gap);
+    padding: var(--auth-account-summary-padding);
+    border-radius: var(--radius-md);
+    background: hsl(var(--muted));
+  }
+
+  .ui-auth-account-identity {
+    display: flex;
+    min-width: min(100%, var(--auth-account-summary-identity-min-width));
+    flex: 1 1 var(--auth-account-summary-identity-min-width);
+    align-items: center;
+    gap: var(--auth-account-summary-gap);
+  }
+
+  .ui-auth-account-avatar {
+    width: var(--auth-account-summary-avatar-size);
+    height: var(--auth-account-summary-avatar-size);
+    flex: none;
+  }
+
+  .ui-auth-account-fallback-icon {
+    width: var(--auth-account-summary-avatar-glyph-size);
+    height: var(--auth-account-summary-avatar-glyph-size);
+  }
+
+  .ui-auth-account-email {
+    min-width: 0;
+    overflow: hidden;
+    color: hsl(var(--foreground));
+    font-size: var(--auth-account-summary-email-font-size);
+    /* Declares its own line box because it CLIPS — see gh#254. */
+    line-height: var(--auth-account-summary-email-line-height);
+    font-weight: var(--font-weight-medium);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .ui-auth-account-summary > [data-slot="button"] {
+    margin-inline-start: auto;
+  }
+
+  .ui-auth-legal-footer {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: center;
+    gap: var(--auth-footer-content-gap);
+    color: hsl(var(--muted-foreground));
+    font-family: var(--font-mono);
+    font-size: var(--auth-footer-text-font-size);
+  }
+
+  .ui-auth-legal-footer-item {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--auth-footer-content-gap);
+  }
+
+  .ui-auth-stack {
+    display: flex;
+    flex-direction: column;
+    gap: var(--auth-stack-gap);
+  }
+
+  .ui-auth-shell[data-variant="canonical"] .ui-form-field {
+    --field-label-gap: var(--auth-shell-field-label-gap);
+  }
+
+  .ui-auth-shell[data-variant="canonical"] [data-slot="form-field-label"] [data-slot="label"] {
+    font-size: var(--auth-shell-field-label-font-size);
+    line-height: var(--auth-shell-field-label-line-height);
+  }
+
+  /*
+   * Compact auth card density — the two card axes are wired to SEPARATE knobs (gh#232), so a
+   * service can shorten the canonical Login card without narrowing its column (or vice versa):
+   *   inline column  ← --auth-shell-compact-card-inset      → --card-space-inset
+   *   block padding  ← --auth-shell-card-padding-block-compact → --card-space-shell-y
+   *   header↔body    ← --auth-shell-card-body-gap-compact    → --card-space-body-y
+   *   solo body      ← --auth-shell-card-padding-block-compact → --card-space-solo-y
+   * The block knob is `initial` at :root, so its default resolves HERE against the live inset —
+   * canonical output is byte-identical to pre-gh#232 while the knob is now actually consumed.
+   * --card-space-solo-y is mapped EXPLICITLY as well as via the shell-y fallback: a solo body
+   * takes both block edges symmetrically, and naming it here keeps that contract legible at the
+   * one place a reader looks for the compact card's spacing.
+   */
+  .ui-auth-shell[data-density="compact"] .ui-auth-shell-card {
+    --card-space-inset: var(--auth-shell-compact-card-inset);
+    --card-space-shell-y: var(
+      --auth-shell-card-padding-block-compact,
+      var(--auth-shell-compact-card-inset)
+    );
+    --card-space-body-y: var(--auth-shell-card-body-gap-compact);
+    --card-space-solo-y: var(
+      --auth-shell-card-padding-block-compact,
+      var(--auth-shell-compact-card-inset)
+    );
+    --card-space-gap: var(--auth-shell-card-gap-compact);
+  }
+
+  .ui-auth-divider {
+    display: grid;
+    width: 100%;
+    grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr);
+    align-items: center;
+    gap: var(--auth-shell-divider-gap);
+    color: hsl(var(--auth-shell-divider-label-color));
+    font-size: var(--auth-shell-divider-label-font-size);
+    line-height: 1;
+  }
+
+  .ui-auth-divider-rule {
+    height: 1px;
+    background: hsl(var(--auth-shell-divider-rule-color));
+  }
+
+  @media (max-width: 30rem) {
+    .ui-auth-shell[data-variant="canonical"] {
+      --auth-shell-main-padding: var(--auth-shell-canonical-main-padding-mobile);
+    }
+
+    .ui-auth-shell[data-preset="login"] {
+      --auth-shell-main-padding: var(--auth-shell-login-flow-offset-block-mobile)
+        var(--auth-shell-login-main-padding-inline-mobile)
+        var(--auth-shell-login-main-padding-block-end);
+    }
+
+    /* Declared after the canonical mobile inset so a preset's mobile gutter wins at equal
+     * specificity: device-authorization = 5px inline (card x=5, width=380 at 390px);
+     * context-selection = edge-to-edge (0 inline). */
+    .ui-auth-shell[data-preset="device-authorization"] {
+      --auth-shell-main-padding: var(--auth-shell-device-main-padding-mobile);
+    }
+
+    .ui-auth-shell[data-preset="context-selection"] {
+      --auth-shell-main-padding: var(--auth-shell-context-main-padding-mobile);
+    }
+
+    /* account-recovery = 15px inline at 390 (panel x=15, width=360). This is a DECIDED mobile
+     * contract — the supplied 390 canonical reference is a desktop 2x2 composite that overflows
+     * horizontally and is not a valid source (gh#233). */
+    .ui-auth-shell[data-preset="account-recovery"] {
+      --auth-shell-main-padding: var(--auth-shell-recovery-main-padding-mobile);
+    }
+  }
+
   /*
    * CENTERED SHELL — authenticated, no-sidebar, centred-column page shell (hosted-ID "My Page",
    * account / self-service, standalone settings). A flex column over the same brand-wash surface as
@@ -165,9 +438,17 @@
   .ui-centered-shell-column {
     width: 100%;
     margin-inline: auto;
+    /* Block offset knob — `0` (top-aligned page, the default) or `auto` (viewport-centred system
+     * surface via `align="center"`). Auto margins absorb the free space of the flex `main`, and
+     * collapse to 0 when the content overflows, so tall content still scrolls from the top. */
+    margin-block: var(--centered-shell-column-offset-block);
     max-width: var(--centered-shell-width-md);
   }
 
+  .ui-centered-shell-column[data-align="center"] {
+    --centered-shell-column-offset-block: auto;
+  }
+
   .ui-centered-shell-column[data-width="sm"] {
     max-width: var(--centered-shell-width-sm);
   }
@@ -211,11 +492,36 @@
     margin-inline-end: var(--space-1);
   }
 
+  /* Drawer scrim = a SHARE of the ONE shared semantic scrim (--overlay-background), resolved at the
+   * call site so a scoped [data-tenant]/.dark override of --overlay-background reaches the portaled
+   * drawer (docs/TOKENS.md · "Role-mirror knobs MUST be `initial`"). Default resolves to the same
+   * rgb(0 0 0 / 0.2) it has always been; setting --app-shell-mobile-nav-background still wins. */
+  [data-slot="sheet-overlay"].app-mobile-nav-overlay {
+    background-color: var(
+      --app-shell-mobile-nav-background,
+      color-mix(in srgb, var(--overlay-background) var(--app-shell-mobile-nav-alpha), transparent)
+    );
+  }
+
+  .app-mobile-nav-drawer {
+    padding-block-start: max(var(--sheet-pad-y), env(safe-area-inset-top));
+    padding-block-end: max(var(--sheet-pad-y), env(safe-area-inset-bottom));
+    padding-inline-start: max(var(--sheet-pad-x), env(safe-area-inset-left));
+    padding-inline-end: max(var(--sheet-pad-x), env(safe-area-inset-right));
+    overscroll-behavior: contain;
+  }
+
   /* The drawer nav reuses the docked Sidebar node; its `.sb-root { display: contents }` flattens
-   * into the scrollable SheetBody so sections/footer flow naturally in the panel. */
+   * into the scrollable SheetBody so sections/footer flow naturally in the panel.
+   * The body's INLINE inset is tokenized on the component itself
+   * (`px-[var(--app-shell-mobile-nav-inset)]` in AppShell, which wins over SheetBody's generic
+   * `px-[var(--sheet-pad-x)]` because both are utilities) — the nav owns its edge instead of being
+   * double-padded (gh#211). Do NOT set `padding-inline` here: this file is `@layer components`, so
+   * a Tailwind utility on the element always wins. */
   .app-mobile-nav-body {
     display: flex;
     flex-direction: column;
+    overscroll-behavior: contain;
   }
 
   .app-topbar-spacer {
@@ -229,6 +535,21 @@
     font-size: var(--font-size-base);
   }
 
+  /*
+   * THE ONE AppShell breakpoint — 900px (56.25rem), the DXS canonical value. It is stated in exactly
+   * two places and they must agree: this rule and `max-[900px]:inline-flex` on the hamburger in
+   * `app-shell.tsx` (a CSS @media cannot read a custom property, so the trigger's visibility has to
+   * repeat the number; making it a public knob needs a `data-shell-mode` attribute — tracked in the
+   * #213 audit, out of scope here).
+   *
+   * There used to be a SECOND, conflicting `@media (max-width: 768px)` block further down that also
+   * restructured `.app-root`. It (a) dropped the `"footer"` grid area and set `.app-footer{display:
+   * none}`, silently deleting whatever a consumer passed to AppShell's `footer` slot on a phone, and
+   * (b) re-declared the grid ROW template with a 3rem literal, overriding --app-shell-bar-height so
+   * a themed bar height was ignored below 768px only. Between 768 and 900 the sidebar was hidden by
+   * THIS rule while the grid still reserved a sidebar track — incoherent. Both are gone; the
+   * footer row and the bar-height token now hold at every width.
+   */
   @media (width <= 56.25rem) {
     .app-root,
     .app-root[data-collapsed="true"] {
@@ -243,6 +564,11 @@
       display: none;
     }
 
+    /* The docked rail is gone, so the bar tightens against the viewport edge (knob, not a literal). */
+    .app-topbar {
+      padding-inline: var(--app-shell-bar-inset-compact);
+    }
+
     .app-topbar-left:has(.app-mobile-sidebar-trigger) {
       display: flex;
     }
@@ -250,16 +576,165 @@
     .app-mobile-nav-trigger {
       display: inline-flex;
     }
+
+    /* Some approved application contracts retain their navigation rail at narrow widths. This is
+     * an explicit AppShell mode, never a consumer media-query fork: the same sidebar node, footer,
+     * active items and token-owned rail width remain in the canonical two-track grid. */
+    .app-root[data-responsive-navigation="docked"] {
+      grid-template-areas:
+        "sidebar topbar"
+        "sidebar main"
+        "sidebar footer";
+      grid-template-columns: var(--app-shell-sidebar-width) minmax(0, 1fr);
+    }
+
+    .app-root[data-responsive-navigation="docked"][data-collapsed="true"] {
+      grid-template-columns: var(--app-shell-rail-width) minmax(0, 1fr);
+    }
+
+    .app-root[data-responsive-navigation="docked"] > .app-sidebar {
+      display: flex;
+    }
+
+    .app-root[data-responsive-navigation="docked"] > .app-topbar {
+      padding-inline: var(--app-shell-bar-inset);
+    }
+
+    .app-root[data-responsive-navigation="docked"] .app-mobile-nav-trigger {
+      display: none;
+    }
   }
 
   .sb-root {
     display: contents;
   }
 
+  /*
+   * ORG SWITCHER — shared Console/Admin tenant control. Widths, insets and state geometry stay
+   * inside the library so a consumer never needs `w-64` or descendant-selector overrides.
+   */
+  .ui-org-switcher {
+    width: 100%;
+    min-width: 0;
+  }
+
+  .ui-org-switcher[data-collapsed="true"] {
+    display: flex;
+    justify-content: center;
+  }
+
+  .ui-org-switcher-trigger {
+    width: 100%;
+    height: var(--org-switcher-trigger-height);
+    min-width: 0;
+    justify-content: flex-start;
+    padding-inline: var(--org-switcher-trigger-padding-x);
+  }
+
+  .ui-org-switcher-trigger[data-collapsed="true"] {
+    width: var(--org-switcher-trigger-height);
+    padding: 0;
+  }
+
+  .ui-org-switcher-avatar {
+    display: grid;
+    width: var(--org-switcher-avatar-size);
+    height: var(--org-switcher-avatar-size);
+    flex: 0 0 auto;
+    place-items: center;
+    overflow: hidden;
+    border-radius: var(--radius);
+    background: hsl(var(--secondary));
+    color: hsl(var(--secondary-foreground));
+    font-size: var(--sidebar-avatar-font-size);
+    font-weight: var(--font-weight-semibold);
+  }
+
+  .ui-org-switcher-avatar > * {
+    width: 100%;
+    height: 100%;
+  }
+
+  .ui-org-switcher-current,
+  .ui-org-switcher-option {
+    display: grid;
+    min-width: 0;
+    flex: 1;
+    text-align: start;
+  }
+
+  .ui-org-switcher-name,
+  .ui-org-switcher-meta {
+    overflow: hidden;
+    line-height: 1.25;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .ui-org-switcher-name {
+    font-size: var(--sidebar-user-name-font-size);
+    font-weight: var(--font-weight-medium);
+  }
+
+  .ui-org-switcher-meta {
+    color: hsl(var(--org-switcher-meta-foreground));
+    font-size: var(--sidebar-user-role-font-size);
+  }
+
+  .ui-org-switcher-chevron,
+  .ui-org-switcher-check,
+  .ui-org-switcher-spinner {
+    width: 1rem;
+    height: 1rem;
+    flex: 0 0 auto;
+  }
+
+  .ui-org-switcher-chevron {
+    margin-inline-start: auto;
+    color: hsl(var(--muted-foreground));
+  }
+
+  .ui-org-switcher-check {
+    margin-inline-start: auto;
+  }
+
+  .ui-org-switcher-popover {
+    width: min(var(--org-switcher-menu-width), calc(100vw - var(--space-4)));
+    padding: 0;
+  }
+
+  .ui-org-switcher-sheet {
+    max-height: var(--org-switcher-sheet-max-height);
+    border-start-start-radius: var(--radius-lg);
+    border-start-end-radius: var(--radius-lg);
+  }
+
+  .ui-org-switcher-command {
+    width: 100%;
+  }
+
+  .ui-org-switcher-state {
+    display: flex;
+    min-height: var(--org-switcher-state-min-height);
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-3);
+    padding: var(--space-5);
+    color: hsl(var(--muted-foreground));
+    text-align: center;
+  }
+
+  .ui-org-switcher-spinner {
+    animation: spin 1s linear infinite;
+  }
+
   .sb-product,
   .sb-brand {
     display: flex;
+    min-width: 0;
     min-height: var(--app-shell-bar-height);
+    flex: 0 0 auto;
     align-items: center;
     gap: var(--space-2);
     padding-inline: var(--space-4);
@@ -337,8 +812,10 @@
 
   .sb-nav-scroll {
     flex: 1;
+    min-height: 0;
+    overscroll-behavior: contain;
     overflow-y: auto;
-    padding: var(--space-3) var(--space-2);
+    padding: var(--sidebar-nav-scroll-padding);
   }
 
   .sb-section {
@@ -346,11 +823,11 @@
   }
 
   .sb-section + .sb-section {
-    margin-top: var(--space-4);
+    margin-top: var(--sidebar-section-gap);
   }
 
   .sb-section-label {
-    padding: 0 var(--space-2) var(--space-1);
+    padding: 0 var(--sidebar-section-label-padding-x) var(--sidebar-section-label-padding-bottom);
     color: hsl(var(--muted-foreground));
     font-size: var(--sidebar-section-label-font-size);
     font-weight: 700;
@@ -362,7 +839,7 @@
   .sb-nav {
     display: flex;
     flex-direction: column;
-    gap: 2px;
+    gap: var(--sidebar-nav-gap);
   }
 
   .sb-nav-item {
@@ -370,22 +847,27 @@
     width: 100%;
     height: var(--sidebar-nav-item-height);
     min-width: 0;
+    flex: 0 0 auto;
     align-items: center;
-    gap: 0.625rem;
-    padding-inline: 0.625rem;
+    gap: var(--sidebar-nav-item-gap);
+    padding-inline: var(--sidebar-nav-item-padding-x);
     border: 0;
     border-radius: calc(var(--radius) - 1px);
     background: transparent;
-    color: hsl(var(--muted-foreground));
+    /* gh#228 — the row/label foreground is its own knob (default = the muted role, unchanged). The
+     * icon reads a SEPARATE knob on `.sb-icon` below, so a service can darken 16px nav icons
+     * without re-tinting every muted text. */
+    color: var(--sidebar-nav-item-foreground, hsl(var(--muted-foreground)));
     cursor: pointer;
     font-family: inherit;
     font-size: var(--sidebar-nav-item-font-size);
+    line-height: 1;
     text-align: start;
   }
 
   .sb-nav-item:hover {
     background: hsl(var(--accent));
-    color: hsl(var(--foreground));
+    color: var(--sidebar-nav-item-hover-foreground, hsl(var(--foreground)));
   }
 
   /* Active item reads its own bg/fg tokens (defaults = the hover look) so a service can give the
@@ -399,21 +881,34 @@
 
   .sb-icon {
     display: grid;
-    width: 1rem;
-    height: 1rem;
+    width: var(--sidebar-nav-icon-size);
+    height: var(--sidebar-nav-icon-size);
     flex: 0 0 auto;
+    line-height: 0;
     place-items: center;
+    /* gh#228 — the nav ICON owns its own foreground knob; the default `currentColor` resolves to the
+     * row colour, so the resting look is byte-identical to before. A service sets
+     * `--sidebar-nav-icon-foreground` alone to get canonical darker icons beside muted labels — no
+     * page-local selector, no global `--muted-foreground` re-tint. Colour only: size/geometry stay
+     * on --sidebar-nav-icon-size. */
+    color: var(--sidebar-nav-icon-foreground, currentColor);
   }
 
   .sb-icon svg {
-    width: 1rem;
-    height: 1rem;
+    display: block;
+    width: var(--sidebar-nav-icon-size);
+    height: var(--sidebar-nav-icon-size);
+    flex: 0 0 auto;
   }
 
   .sb-label {
     min-width: 0;
     flex: 1;
     overflow: hidden;
+    /* gh#254 — MUST NOT inherit the row's `line-height: 1`. This element clips, so its line box is
+     * its clip box, and a 1em box is shorter than the font's ascent+descent: every descender and
+     * Vietnamese tone mark below the baseline gets sheared off. Knob, not constant (rule #45). */
+    line-height: var(--sidebar-nav-item-line-height);
     text-overflow: ellipsis;
     white-space: nowrap;
   }
@@ -464,7 +959,9 @@
   .sb-nav-item--sub {
     height: 1.75rem;
     font-size: var(--sidebar-nav-sub-font-size);
-    color: hsl(var(--muted-foreground));
+    /* Same row knob as a top-level row (gh#228) — one override themes the whole nav, sub rows
+     * included. Default unchanged. */
+    color: var(--sidebar-nav-item-foreground, hsl(var(--muted-foreground)));
   }
 
   .sb-nav-item--sub::before {
@@ -479,7 +976,7 @@
 
   .sb-nav-item--sub:hover {
     background: transparent;
-    color: hsl(var(--foreground));
+    color: var(--sidebar-nav-item-hover-foreground, hsl(var(--foreground)));
   }
 
   .sb-nav-item--sub[data-active="true"] {
@@ -493,6 +990,42 @@
     opacity: 1;
   }
 
+  /* gh#228 — nav ICON state knobs. Declared AFTER the row-state rules so they win at equal
+   * specificity, in the same order the row states resolve (hover → active → disabled). Each falls
+   * back to the base icon knob and finally to `currentColor` (= the row colour for that state), so
+   * the defaults are byte-identical to the pre-gh#228 rendering and setting only
+   * `--sidebar-nav-icon-foreground` themes every state at once. Colour only — no geometry. */
+  .sb-nav-item:hover .sb-icon {
+    color: var(
+      --sidebar-nav-icon-hover-foreground,
+      var(--sidebar-nav-icon-foreground, currentColor)
+    );
+  }
+
+  .sb-nav-item[data-active="true"] .sb-icon {
+    color: var(
+      --sidebar-nav-icon-active-foreground,
+      var(--sidebar-nav-icon-foreground, currentColor)
+    );
+  }
+
+  /* Disabled rows (`aria-disabled="true"`, set by SidebarItem for item.disabled). Defaults resolve
+   * to the RESTING row/icon colour, so a disabled row reads as inert in every state; a service dims
+   * it further with the two disabled knobs. */
+  .sb-nav-item[aria-disabled="true"] {
+    color: var(
+      --sidebar-nav-item-disabled-foreground,
+      var(--sidebar-nav-item-foreground, hsl(var(--muted-foreground)))
+    );
+  }
+
+  .sb-nav-item[aria-disabled="true"] .sb-icon {
+    color: var(
+      --sidebar-nav-icon-disabled-foreground,
+      var(--sidebar-nav-icon-foreground, currentColor)
+    );
+  }
+
   /* Collapsed-rail flyout — PORTALED (Radix Popover) so it escapes the sidebar's overflow and is
    * never clipped: names a leaf item (tooltip) or reveals a group's submenu on hover/focus. */
   .sb-flyout-pop {
@@ -640,12 +1173,40 @@
   }
 
   /* Topbar — a pure slot bar. start (inline-start) · center (grows, centered) · end (inline-end).
-   * The library owns ONLY this positioning; every control inside is the consumer's to compose. */
+   * The library owns ONLY this positioning; every control inside is the consumer's to compose.
+   *
+   * SHRINK CONTRACT (gh#226) — a hosted console packs an intrinsically wide brand/tenant string
+   * into `start` and a fixed-width search trigger into `center`; at a compact desktop width
+   * (1024px minus a 16rem sidebar) that content used to push `end` (locale picker, user menu) past
+   * the bar and out of the viewport, and leak a horizontal document scroll. The contract is:
+   *   root      — never wider than its AppShell grid/flex allocation (`max-width:100%` +
+   *               `min-width:0`, so it shrinks whether the parent is a grid track or a flex line);
+   *   start     — shrinks first, its content clipped INSIDE the slot (never spills over center/end);
+   *   center    — `flex-basis:0`, so it yields all of its box before `start` gives up a pixel;
+   *   end       — `flex:0 0 auto`, so it keeps its natural width and stays anchored inline-end.
+   * Slots clip with `clip`, NOT `hidden`: a `hidden` box is still a scroll container, so focusing a
+   * clipped control would scroll the slot and shove its leading content out of view. The clip
+   * margin keeps the focus ring of an edge control paintable (WCAG 2.4.11 / 2.4.13).
+   *
+   * BOX KNOBS (rule #45) — --topbar-height / --topbar-inset / --topbar-gap. Their defaults are the
+   * QUIET ones (`auto` / `0` / the previous 8px), i.e. byte-identical rendering to before they
+   * existed: inside AppShell the `.app-topbar` grid row still owns the height and inset. A service
+   * that mounts <Topbar> DIRECTLY on a page (no AppShell) now sizes it from the theme —
+   * `--topbar-height: 3.5rem; --topbar-inset: var(--space-4)` — instead of an app-local class.
+   * `--topbar-gap` re-rhythms the whole bar at once: it is both the gap BETWEEN the three clusters
+   * and the gap INSIDE each of them, so a denser bar stays internally consistent.
+   * The shrink contract above is unaffected — none of these touch flex/overflow. */
   .ui-topbar {
     display: flex;
-    width: 100%;
+    height: var(--topbar-height);
+    width: auto;
+    max-width: 100%;
+    min-width: 0;
+    flex: 1 1 0%;
     align-items: center;
-    gap: var(--space-2);
+    gap: var(--topbar-gap);
+    padding-inline: var(--topbar-inset);
+    overflow: hidden;
   }
   .ui-topbar-start,
   .ui-topbar-center,
@@ -653,16 +1214,44 @@
     display: flex;
     min-width: 0;
     align-items: center;
-    gap: var(--space-2);
+    gap: var(--topbar-gap);
+    overflow: clip;
+    overflow-clip-margin: var(--focus-ring-width);
+  }
+  .ui-topbar-start {
+    flex: 0 1 auto;
+  }
+  .ui-topbar-start > :last-child {
+    max-width: 100%;
+    min-width: 0;
+    flex: 0 1 auto;
+    overflow: hidden;
+    /* Declares its own line box because it CLIPS — see gh#254. */
+    line-height: var(--topbar-start-truncate-line-height);
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
   .ui-topbar-center {
-    flex: 1 1 auto;
+    flex: 1 1 0%;
     justify-content: center;
   }
   .ui-topbar-end {
+    max-width: 100%;
+    flex: 0 0 auto;
     margin-inline-start: auto;
   }
 
+  /* COLLISION CONTRACT (gh#244) — with a docked 16rem sidebar, 901–1100px viewports do not have
+   * enough room for a breadcrumb/title, full search trigger and end utilities. The center slot is
+   * optional by definition, so remove it before it can cover either owned edge. This also gives
+   * phones the same deterministic allocation. A consumer with a real compact center presentation
+   * can opt it back in through the public token instead of a page-local media query. */
+  @media (width <= 68.75rem) {
+    .ui-topbar-center {
+      display: var(--topbar-center-compact-display);
+    }
+  }
+
   .tb-chip {
     display: inline-flex;
     max-width: 15rem;
@@ -716,6 +1305,10 @@
     min-width: 0;
     overflow: hidden;
     font-weight: 500;
+    /* gh#254 — same trap as `.sb-label`: this clips, so it must own a line box tall enough for the
+     * font's descenders. `.tb-chip` uses `font: inherit`, so without this the chip would shear its
+     * glyphs the moment a service set a tight line-height on the bar. */
+    line-height: 1.5;
     text-overflow: ellipsis;
     white-space: nowrap;
   }
@@ -807,27 +1400,18 @@
     background: hsl(var(--attention));
   }
 
+  /* TOPBAR CHIP/SEARCH DENSITY ONLY — this is NOT a second shell breakpoint. The `.app-root`
+   * restructure that used to live here (a 768px duplicate of the 900px rule that also deleted the
+   * footer row and re-declared the grid rows with a 3rem literal) is gone; see the note on the one
+   * `@media (width <= 56.25rem)` block above. What remains is purely the optional `.tb-*` console
+   * chrome collapsing to icon-only on a phone, which is independent of where the shell switches to
+   * its drawer. */
   @media (max-width: 768px) {
-    .app-root,
-    .app-root[data-collapsed="true"] {
-      grid-template-areas:
-        "topbar"
-        "main";
-      grid-template-columns: minmax(0, 1fr);
-      grid-template-rows: 3rem minmax(0, 1fr);
-    }
-
-    .app-sidebar,
-    .app-footer,
     .tb-chip-sep,
     .tb-search .kbd {
       display: none;
     }
 
-    .app-topbar {
-      padding-inline: var(--space-3);
-    }
-
     .tb-search {
       width: auto;
       min-width: var(--control-height);
@@ -838,3 +1422,169 @@
     }
   }
 }
+
+/*
+ * REDUCED MOTION for the AppShell mobile drawer (WCAG 2.3.3 / 2.2.2). The drawer is a Sheet, so it
+ * animates via Tailwind `data-[state]:animate-in|animate-out` + `slide-in-from-*` utilities.
+ * DELIBERATELY UNLAYERED: Tailwind v4 emits those into `@layer utilities`, which beats any rule in
+ * `@layer components` regardless of specificity — this gate was previously written inside the
+ * components layer above and could never win. Same reasoning as the overlay gate in
+ * dialog-layout.css (which also covers this drawer via [data-slot="sheet-*"]); kept here as well so
+ * a consumer importing only `styles/shell-layout` still gets it.
+ */
+@media (prefers-reduced-motion: reduce) {
+  .app-mobile-nav-overlay,
+  .app-mobile-nav-drawer {
+    animation: none;
+    transition: none;
+  }
+}
+
+/*
+ * ERROR SURFACE — the 403 / 404 / 500 / 503 exception surface (gh#221, gh#251).
+ *
+ * Geometry is PACKAGE-OWNED at 1440 / 1024 / 390: a consumer never writes `min-h-dvh`, a
+ * flex-centring class or a media query for an error page. In `system` mode the viewport centring
+ * comes from `CenteredShell align="center"` (which the component renders itself); this block owns
+ * the surface block that is identical in BOTH modes — measure, rhythm, metadata list.
+ *
+ * The narrow step is a CONTAINER query, not a viewport one (the SplitPane precedent, gh#165): the
+ * surface reads its OWN width, so it compacts correctly whether the shrinking came from a 390px
+ * phone or from an application shell whose sidebar is expanded on a laptop.
+ */
+@layer components {
+  .ui-error-surface {
+    container: error-surface / inline-size;
+    display: flex;
+    width: 100%;
+    max-width: var(--error-surface-max-width);
+    flex-direction: column;
+    align-items: center;
+    /* Logical, so the surface stays centred and its text start-aligns correctly under `dir="rtl"`. */
+    margin-inline: auto;
+    gap: var(--error-surface-gap);
+    padding-block: var(--error-surface-padding-block);
+    text-align: center;
+  }
+
+  .ui-error-surface-brand {
+    display: flex;
+    justify-content: center;
+    padding-block-end: var(--error-surface-brand-gap);
+  }
+
+  /* The EmptyState body already owns its own vertical rhythm and description measure
+   * (--empty-state-*); the surface only removes the duplicated block padding so the two spacing
+   * systems do not stack into a hole between the status code and the icon. */
+  .ui-error-surface .ui-error-surface-body {
+    width: 100%;
+    padding-block: 0;
+  }
+
+  .ui-error-surface-status {
+    margin: 0;
+  }
+
+  .ui-error-surface-meta {
+    display: flex;
+    width: 100%;
+    flex-direction: column;
+    gap: var(--error-surface-meta-gap);
+    /* Chrome is a token, default quiet (rule #44) — `none` unless a service opts in. */
+    border-block-start: var(--error-surface-meta-border);
+    padding-block-start: var(--error-surface-meta-padding-block);
+    margin: 0;
+  }
+
+  .ui-error-surface-meta-row {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: var(--error-surface-meta-row-gap);
+  }
+
+  .ui-error-surface-meta-row > dd {
+    margin-inline-start: 0;
+  }
+
+  .ui-error-surface-progress {
+    width: 100%;
+    max-width: var(--error-surface-progress-max-width);
+  }
+
+  /*
+   * NARROW STEP (the 390 case). Reclaim vertical space and stop a long ja / vi metadata row from
+   * wrapping into a ragged two-column shape: each label stacks over its value, centred.
+   */
+  @container error-surface (width < 30rem) {
+    .ui-error-surface {
+      padding-block: var(--error-surface-padding-block-compact);
+    }
+
+    .ui-error-surface-meta-row {
+      flex-direction: column;
+      gap: 0;
+    }
+  }
+}
+
+@layer components {
+  /* ── CenteredShell · `preset="public-landing"` (gh#252) ──────────────────────────────────────
+   * A PUBLIC landing page (marketing header · hero · sections · legal footer) is a COMPOSITION,
+   * not a framework component (docs/COMPOSITION-VS-COMPONENT.md: Hero / Navbar / Footer / Pricing
+   * all FAIL the Framework-Component Test). What the consumer must NOT own is the SHELL geometry —
+   * the content measure, the header/footer measure alignment, the section rhythm and the flat
+   * public-surface chrome. This preset owns all of it through `--centered-shell-landing-*` knobs,
+   * so a landing composes real primitives with ZERO page-local CSS and zero descendant selectors.
+   *
+   * `preset="default"` emits NO `data-preset` attribute at all, so none of this can match and every
+   * existing CenteredShell keeps its exact box (the gh#231 inert-default contract). */
+  .ui-centered-shell[data-preset="public-landing"] {
+    --centered-shell-main-padding: var(--centered-shell-landing-main-padding-block)
+      var(--centered-shell-landing-inset-inline);
+    /* The hero title is a real `Heading level={1}`; the preset re-points the h1 tier the same way
+     * `.ui-auth-shell` re-points it — never a consumer font-size. */
+    --heading-h1: var(--centered-shell-landing-heading-size);
+    /* Flat public surface: every Card in the subtree loses its elevation from ONE knob instead of
+     * a consumer `.landing .card { box-shadow: none }` descendant selector. */
+    --card-shadow: var(--centered-shell-landing-card-shadow);
+    background: hsl(var(--centered-shell-landing-background, var(--background)));
+  }
+
+  .ui-centered-shell[data-preset="public-landing"] .ui-centered-shell-column {
+    display: flex;
+    max-width: var(--centered-shell-landing-max-width);
+    flex-direction: column;
+    /* Section rhythm — the consumer stacks plain `<section>` layout elements and never sets a gap. */
+    gap: var(--centered-shell-landing-section-gap);
+  }
+
+  /* Header and footer share the column's measure WITHOUT a consumer max-width wrapper: the inline
+   * padding is the page gutter until the viewport is wider than the measure, then it grows so the
+   * bar content starts on exactly the same inline edge as the centred column. */
+  .ui-centered-shell[data-preset="public-landing"] .ui-centered-shell-bar,
+  .ui-centered-shell[data-preset="public-landing"] .ui-centered-shell-footer {
+    padding-inline: max(
+      var(--centered-shell-landing-inset-inline),
+      calc((100% - var(--centered-shell-landing-max-width)) / 2)
+    );
+  }
+
+  .ui-centered-shell[data-preset="public-landing"] .ui-centered-shell-footer {
+    padding-block: var(--centered-shell-landing-footer-padding-block);
+    text-align: start;
+  }
+
+  /* Compact step (the 390px acceptance width sits here): the gutter, the section rhythm and the
+   * hero tier switch to their compact knobs. One media query, owned by the package. */
+  @media (width < 40rem) {
+    .ui-centered-shell[data-preset="public-landing"] {
+      --centered-shell-landing-inset-inline: var(--centered-shell-landing-inset-inline-compact);
+      --centered-shell-landing-main-padding-block: var(
+        --centered-shell-landing-main-padding-block-compact
+      );
+      --centered-shell-landing-section-gap: var(--centered-shell-landing-section-gap-compact);
+      --centered-shell-landing-heading-size: var(--centered-shell-landing-heading-size-compact);
+    }
+  }
+}