@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Accordion/AccordionItem.tsx

@@ -0,0 +1,66 @@
+import { forwardRef, useId, useMemo, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import {
+  AccordionItemContext,
+  useAccordionContext,
+  type AccordionItemContextValue,
+} from './context';
+import type { AccordionHeaderLevel } from './Accordion';
+import styles from './Accordion.module.scss';
+
+export interface AccordionItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'value'> {
+  /** Unique value used to identify the item in the root's `value`/`onValueChange`. */
+  value: string;
+  /** When true, the trigger is non-interactive and keyboard nav skips this item. */
+  disabled?: boolean;
+  /**
+   * Heading level wrapping the trigger. WAI-ARIA APG requires triggers to live
+   * inside a heading element. Defaults to `'h3'`.
+   */
+  headerLevel?: AccordionHeaderLevel;
+  children: ReactNode;
+}
+
+/**
+ * Item wrapper providing the item context to its Trigger and Content.
+ * @see docs/components/Accordion.md
+ */
+export const AccordionItem = forwardRef<HTMLDivElement, AccordionItemProps>(function AccordionItem(
+  { value, disabled = false, headerLevel = 'h3', children, className, ...props },
+  ref,
+) {
+  const { isOpen } = useAccordionContext('Item');
+  const open = isOpen(value);
+  const reactId = useId();
+  const triggerId = `accordion-trigger-${reactId}`;
+  const contentId = `accordion-content-${reactId}`;
+
+  const ctx = useMemo<AccordionItemContextValue & { headerLevel: AccordionHeaderLevel }>(
+    () => ({
+      value,
+      disabled,
+      isOpen: open,
+      triggerId,
+      contentId,
+      headerLevel,
+    }),
+    [value, disabled, open, triggerId, contentId, headerLevel],
+  );
+
+  return (
+    <AccordionItemContext.Provider value={ctx}>
+      {/* Pattern A — {...props} after ref so consumer attrs reach the div,
+            but data-state/data-disabled/className are set AFTER the spread
+            so the component wins on those three. */}
+      <div
+        ref={ref}
+        {...props}
+        data-state={open ? 'open' : 'closed'}
+        data-disabled={disabled ? 'true' : undefined}
+        className={clsx(styles.item, className)}
+      >
+        {children}
+      </div>
+    </AccordionItemContext.Provider>
+  );
+});

package/src/components/Accordion/AccordionTrigger.tsx

@@ -0,0 +1,121 @@
+import { forwardRef, type ButtonHTMLAttributes, type KeyboardEvent, type ReactNode } from 'react';
+import { ChevronDown } from 'lucide-react';
+import clsx from 'clsx';
+import {
+  useAccordionContext,
+  useAccordionItemContext,
+  type AccordionItemContextValue,
+} from './context';
+import type { AccordionHeaderLevel } from './Accordion';
+import styles from './Accordion.module.scss';
+
+export interface AccordionTriggerProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'children'
+> {
+  /**
+   * Override the default trigger indicator icon (rotates 180° when open).
+   * Pass `null` to suppress the icon entirely. Default: `<ChevronDown />`.
+   */
+  icon?: ReactNode | null;
+  /**
+   * Controls rendered at the **right of the header**, OUTSIDE the toggle button —
+   * so their buttons/menus are clickable without toggling the section, and the
+   * heading's accessible name stays just the title. Keep it to a few small
+   * controls (`<Button iconOnly>`, a `<DropdownMenu>` trigger, a `<Switch>`).
+   */
+  actions?: ReactNode;
+  children: ReactNode;
+}
+
+interface ItemContextWithHeaderLevel extends AccordionItemContextValue {
+  headerLevel: AccordionHeaderLevel;
+}
+
+/**
+ * Heading-wrapped button that toggles the parent Item.
+ * @see docs/components/Accordion.md
+ */
+export const AccordionTrigger = forwardRef<HTMLButtonElement, AccordionTriggerProps>(
+  function AccordionTrigger({ icon, actions, children, className, onKeyDown, ...props }, ref) {
+    const { toggle } = useAccordionContext('Trigger');
+    const itemCtx = useAccordionItemContext('Trigger') as ItemContextWithHeaderLevel;
+    const { value, disabled, isOpen, triggerId, contentId, headerLevel } = itemCtx;
+
+    const handleKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+      onKeyDown?.(e);
+      if (e.defaultPrevented) return;
+      const isNav = ['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key);
+      if (!isNav) return;
+      e.preventDefault();
+
+      const root = e.currentTarget.closest<HTMLElement>('[data-accordion]');
+      if (!root) return;
+
+      // Match ONLY accordion toggle buttons (the `data-accordion-trigger` marker),
+      // never an `aria-expanded` control a consumer put in the `actions` slot (a
+      // DropdownMenu/Select trigger). Then scope to THIS root by filtering to
+      // triggers whose nearest accordion ancestor is this root — so ArrowDown from
+      // an outer trigger doesn't jump into a nested Accordion inside open Content.
+      const triggers = Array.from(
+        root.querySelectorAll<HTMLButtonElement>('button[data-accordion-trigger]:not(:disabled)'),
+      ).filter((btn) => btn.closest('[data-accordion]') === root);
+      if (triggers.length === 0) return;
+
+      const current = triggers.indexOf(e.currentTarget);
+      let next = current;
+
+      if (e.key === 'ArrowDown') next = (current + 1) % triggers.length;
+      else if (e.key === 'ArrowUp') next = (current - 1 + triggers.length) % triggers.length;
+      else if (e.key === 'Home') next = 0;
+      else if (e.key === 'End') next = triggers.length - 1;
+
+      triggers[next]?.focus();
+    };
+
+    const renderedIcon =
+      icon === null
+        ? null
+        : (icon ?? <ChevronDown size={16} aria-hidden="true" className={styles.indicator} />);
+
+    // headerLevel is a string union of valid HTML heading tag names; cast to
+    // ElementType for JSX use.
+    const Heading = headerLevel as 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+    return (
+      // Header ROW: the heading (toggle button) + an optional actions slot. Actions
+      // live OUTSIDE the heading/button so they're independently clickable (no
+      // toggle), valid HTML (no nested buttons), and don't pollute the heading's
+      // accessible name.
+      <div className={styles.header}>
+        <Heading className={styles.heading}>
+          {/* Pattern B — {...props} first so component-owned id/aria-expanded/
+              aria-controls/disabled/onClick/onKeyDown/className win and the ARIA
+              contract can't be overridden by a consumer. */}
+          <button
+            {...props}
+            ref={ref}
+            type="button"
+            id={triggerId}
+            // Stable marker so keyboard arrow-nav targets ONLY accordion toggles,
+            // never an aria-expanded control in the `actions` slot.
+            data-accordion-trigger=""
+            aria-expanded={isOpen}
+            aria-controls={contentId}
+            disabled={disabled}
+            onClick={() => toggle(value)}
+            onKeyDown={handleKeyDown}
+            className={clsx(styles.trigger, className)}
+          >
+            <span className={styles.label}>{children}</span>
+            {/* Icon wrapped in a slot so its side is controlled purely by CSS
+                (root data-indicator-side flips its `order`) — works for a custom
+                `icon` too, not just the default chevron. */}
+            {renderedIcon !== null && <span className={styles.indicatorSlot}>{renderedIcon}</span>}
+          </button>
+        </Heading>
+        {actions != null && <div className={styles.actions}>{actions}</div>}
+      </div>
+    );
+  },
+);

package/src/components/Accordion/context.ts

@@ -0,0 +1,47 @@
+import { createContext, useContext } from 'react';
+
+export interface AccordionContextValue {
+  /** Selection mode. */
+  mode: 'single' | 'multiple';
+  /** Whether the given item value is currently open. */
+  isOpen: (value: string) => boolean;
+  /** Toggle the given item value. Closes others in single mode; flips membership in multiple mode. */
+  toggle: (value: string) => void;
+}
+
+export const AccordionContext = createContext<AccordionContextValue | null>(null);
+
+/**
+ * Hook for child components to read the root context. Throws if used outside
+ * an `<Accordion>` — surfaces the bug early instead of silently no-op'ing.
+ */
+export function useAccordionContext(componentName: string): AccordionContextValue {
+  const ctx = useContext(AccordionContext);
+  if (ctx === null) {
+    throw new Error(`<Accordion.${componentName}> must be used inside <Accordion>`);
+  }
+  return ctx;
+}
+
+export interface AccordionItemContextValue {
+  /** This item's unique value. */
+  value: string;
+  /** Whether the item is disabled (Trigger non-interactive, keyboard nav skips). */
+  disabled: boolean;
+  /** Whether the item is currently open (mirrored from root context for convenience). */
+  isOpen: boolean;
+  /** Stable id for the Trigger (so Content's aria-labelledby points at it). */
+  triggerId: string;
+  /** Stable id for the Content (so Trigger's aria-controls points at it). */
+  contentId: string;
+}
+
+export const AccordionItemContext = createContext<AccordionItemContextValue | null>(null);
+
+export function useAccordionItemContext(componentName: string): AccordionItemContextValue {
+  const ctx = useContext(AccordionItemContext);
+  if (ctx === null) {
+    throw new Error(`<Accordion.${componentName}> must be used inside <Accordion.Item>`);
+  }
+  return ctx;
+}

package/src/components/Accordion/index.ts

@@ -0,0 +1,14 @@
+export { Accordion } from './Accordion';
+export type {
+  AccordionProps,
+  AccordionMode,
+  AccordionHeaderLevel,
+  AccordionVariant,
+  AccordionSize,
+  AccordionGap,
+  AccordionIndicatorSide,
+  AccordionActionsWhenClosed,
+} from './Accordion';
+export type { AccordionItemProps } from './AccordionItem';
+export type { AccordionTriggerProps } from './AccordionTrigger';
+export type { AccordionContentProps } from './AccordionContent';

package/src/components/Alert/Alert.module.scss

@@ -0,0 +1,92 @@
+@use '../../styles/mixins' as *;
+@use './Alert.tokens';
+
+.alert {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  gap: var(--alert-gap);
+  align-items: start;
+  padding: var(--alert-padding-y) var(--alert-padding-x);
+  background: var(--alert-bg);
+  border-radius: var(--alert-radius);
+  border-left: var(--alert-border-width) solid var(--alert-border-color);
+  color: var(--alert-fg);
+}
+
+.alert[data-tone='info'] {
+  background: var(--alert-bg-info);
+  border-left-color: var(--alert-border-color-info);
+}
+
+.alert[data-tone='success'] {
+  background: var(--alert-bg-success);
+  border-left-color: var(--alert-border-color-success);
+}
+
+.alert[data-tone='warning'] {
+  background: var(--alert-bg-warning);
+  border-left-color: var(--alert-border-color-warning);
+}
+
+.alert[data-tone='error'] {
+  background: var(--alert-bg-danger);
+  border-left-color: var(--alert-border-color-danger);
+}
+
+.icon {
+  display: grid;
+  place-items: center;
+
+  // Match the first text line's box so the icon sits centered with the title
+  // line (the alert grid is align-items:start, which would otherwise top-align
+  // the 16px icon ~2px above the line's optical center).
+  min-height: var(--alert-icon-row-height);
+  color: var(--alert-icon);
+}
+
+.alert[data-tone='info'] .icon {
+  color: var(--alert-icon-info);
+}
+
+.alert[data-tone='success'] .icon {
+  color: var(--alert-icon-success);
+}
+
+.alert[data-tone='warning'] .icon {
+  color: var(--alert-icon-warning);
+}
+
+.alert[data-tone='error'] .icon {
+  color: var(--alert-icon-danger);
+}
+
+.body {
+  min-width: 0;
+}
+
+.title {
+  display: block;
+  font-size: var(--alert-title-font-size);
+  font-weight: var(--alert-title-font-weight);
+
+  // Keep this 1.4 in sync with --alert-icon-row-height (the icon centers to this
+  // line box).
+  line-height: 1.4;
+  color: var(--alert-title-fg);
+}
+
+.description {
+  font-size: var(--alert-description-font-size);
+  color: var(--alert-description-fg);
+  line-height: 1.5;
+}
+
+.title + .description {
+  // stylelint-disable-next-line property-disallowed-list -- internal spacing between alert title and its description child
+  margin-top: var(--alert-title-description-gap);
+}
+
+.actions {
+  // stylelint-disable-next-line property-disallowed-list -- internal spacing between alert body content and its action row
+  margin-top: var(--alert-actions-gap);
+}

package/src/components/Alert/Alert.tokens.scss

@@ -0,0 +1,60 @@
+// Alert.tokens.scss — Component-scoped tokens for <Alert>. Per-tone bg/fg/icon/border-color pairs for info/success/warning/danger, plus shared shape and typography defaults. Each token defaults to the primitive the SCSS used before this migration.
+:root {
+  // Shared shape + typography
+  --alert-bg: var(--color-bg);
+  --alert-fg: var(--color-fg);
+  --alert-border-color: var(--color-fg-muted);
+  --alert-border-width: var(--border-width-strong);
+  --alert-radius: var(--radius-md);
+  --alert-padding-y: var(--space-3);
+  --alert-padding-x: var(--space-4);
+  --alert-gap: var(--space-3);
+  --alert-icon: var(--color-fg-muted);
+
+  // Title
+  --alert-title-fg: var(--color-fg);
+  --alert-title-font-size: var(--font-size-md);
+  --alert-title-font-weight: var(--font-weight-medium);
+
+  // Icon box height = the title's line box (font-size × 1.4 line-height), so the
+  // icon centers with the first text line instead of top-aligning above it.
+  --alert-icon-row-height: calc(var(--alert-title-font-size) * 1.4);
+
+  // Description
+  --alert-description-fg: var(--color-fg-muted);
+  --alert-description-font-size: var(--font-size-sm);
+
+  // Internal spacing (title-to-description, body-to-actions)
+  --alert-title-description-gap: var(--space-1);
+  --alert-actions-gap: var(--space-2);
+
+  // Per-tone surfaces (background + border + icon)
+  --alert-bg-info: var(--color-info-bg-subtle);
+  --alert-fg-info: var(--color-fg);
+  --alert-icon-info: var(--color-info);
+  --alert-border-color-info: var(--color-info);
+
+  --alert-bg-success: var(--color-success-bg-subtle);
+  --alert-fg-success: var(--color-fg);
+  --alert-icon-success: var(--color-success);
+  --alert-border-color-success: var(--color-success);
+
+  --alert-bg-warning: var(--color-warning-bg-subtle);
+  --alert-fg-warning: var(--color-fg);
+
+  // warning uses --color-warning-strong, not --color-warning, which measures
+  // @contrast --color-warning on --color-bg = 2.14:1 light
+  // @contrast --color-warning-strong on --color-bg = 5.95:1 light
+  // @contrast --color-warning on --color-warning-bg-subtle = 2.01:1 light
+  // @contrast --color-warning-strong on --color-warning-bg-subtle = 5.61:1 light
+  // 2.01:1 on the light tint (and 2.14:1 as an icon or border on --color-bg), below WCAG AA
+  // for text and below 1.4.11's 3:1 for a graphical object. The strong variant
+  // clears both. Dark is unaffected — the two resolve to the same value there.
+  --alert-icon-warning: var(--color-warning-strong);
+  --alert-border-color-warning: var(--color-warning-strong);
+
+  --alert-bg-danger: var(--color-danger-bg-subtle);
+  --alert-fg-danger: var(--color-fg);
+  --alert-icon-danger: var(--color-danger);
+  --alert-border-color-danger: var(--color-danger);
+}

package/src/components/Alert/Alert.tsx

@@ -0,0 +1,136 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { AlertTriangle, CheckCircle2, Info, X, XCircle } from 'lucide-react';
+import clsx from 'clsx';
+import { Button } from '../Button';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './Alert.module.scss';
+
+/**
+ * Tone — drives icon, accent stripe color, tinted background, and ARIA role.
+ *
+ * - `'info'` — blue accent. Neutral updates ("Synced 5 minutes ago").
+ * - `'success'` — green accent. Confirmations ("Changes saved").
+ * - `'warning'` — dark amber accent. Non-blocking heads-up ("Storage at 85%").
+ * - `'error'` — red accent. Failures. ALSO sets `role="alert"` (assertive); the
+ *   other tones use `role="status"` (polite). With `live={false}` every tone
+ *   is a static `role="note"` instead.
+ */
+export type AlertTone = 'info' | 'success' | 'warning' | 'error';
+
+export interface AlertProps extends Omit<HTMLAttributes<HTMLElement>, 'role' | 'title'> {
+  /** Tone. Defaults to `'info'`. See `AlertTone` for full descriptions. */
+  tone?: AlertTone;
+
+  /**
+   * Optional bold heading. Renders above the description. ReactNode so you
+   * can embed inline emphasis (`<>Update <strong>1.2.3</strong> available</>`).
+   *
+   * The native HTML `title` attribute (tooltip-on-hover) is collapsed by this
+   * prop. Use `aria-label` if you need that.
+   */
+  title?: ReactNode;
+
+  /** Description body. Rendered below the title in muted color. */
+  children?: ReactNode;
+
+  /**
+   * Override the tone's default icon. Pass any ReactNode (typically a
+   * lucide-react icon). Pass `null` to hide the icon entirely.
+   *
+   * Defaults: `info` → `Info`, `success` → `CheckCircle2`,
+   * `warning` → `AlertTriangle`, `error` → `XCircle`.
+   */
+  icon?: ReactNode | null;
+
+  /**
+   * Optional action row rendered below the description. Typically a single
+   * Button or a Cluster of two ("Retry", "Dismiss"). The component doesn't
+   * manage the action row's layout — pass a pre-laid-out node.
+   */
+  actions?: ReactNode;
+
+  /**
+   * Whether the Alert is a live region. Defaults to `true`: `role="status"`
+   * (polite), or `role="alert"` (assertive) for `tone="error"` — right for a
+   * message that APPEARS in response to something (a save failed, an update
+   * arrived).
+   *
+   * Pass `false` for a callout that is simply part of the page when it opens —
+   * a "Needs action" note in each card of a list, a standing warning in a
+   * form. It renders `role="note"` with the same visuals and no live
+   * semantics, so screen readers read it in place instead of announcing it.
+   * N live Alerts mounting together can queue N announcements (#547).
+   *
+   * The tone is shown by the icon's shape and the colour only; it is not
+   * exposed to assistive tech in either mode (the icon is decorative). With
+   * `live={false}`, `tone="error"` also loses the "alert" role that browse-mode
+   * readers speak. So put the urgency in `title` ("Needs action").
+   *
+   * Decide it at mount: flipping `false` → `true` on a mounted Alert turns
+   * content that is already there into a live region, which announces nothing.
+   * @default true
+   */
+  live?: boolean;
+
+  /**
+   * Called when the user clicks the close (×) button. When set, the close
+   * button renders; when omitted, no close button. Alert is **controlled** —
+   * the component does NOT manage internal hidden state. Hide via
+   * conditional render in the consumer:
+   *
+   * ```tsx
+   * const [show, setShow] = useState(true);
+   * {show && <Alert tone="success" onDismiss={() => setShow(false)}>Saved</Alert>}
+   * ```
+   */
+  onDismiss?: () => void;
+}
+
+const DEFAULT_ICONS: Record<AlertTone, ReactNode> = {
+  info: <Info size={16} aria-hidden="true" />,
+  success: <CheckCircle2 size={16} aria-hidden="true" />,
+  warning: <AlertTriangle size={16} aria-hidden="true" />,
+  error: <XCircle size={16} aria-hidden="true" />,
+};
+
+/**
+ * Persistent in-flow notification.
+ * @see docs/components/Alert.md
+ */
+export const Alert = forwardRef<HTMLDivElement, AlertProps>(function Alert(
+  { tone = 'info', title, children, icon, actions, live = true, onDismiss, className, ...props },
+  ref,
+) {
+  const t = useTranslation();
+  const role = !live ? 'note' : tone === 'error' ? 'alert' : 'status';
+  const renderedIcon = icon === null ? null : (icon ?? DEFAULT_ICONS[tone]);
+
+  return (
+    <div
+      ref={ref}
+      {...props}
+      // {...props} first so role / data-tone (the ARIA contract) win.
+      role={role}
+      data-tone={tone}
+      className={clsx(styles.alert, className)}
+    >
+      {renderedIcon && <div className={styles.icon}>{renderedIcon}</div>}
+      <div className={styles.body}>
+        {title && <strong className={styles.title}>{title}</strong>}
+        {children && <div className={styles.description}>{children}</div>}
+        {actions && <div className={styles.actions}>{actions}</div>}
+      </div>
+      {onDismiss && (
+        <Button
+          variant="ghost"
+          size="xs"
+          iconOnly
+          aria-label={t('alert.dismiss')}
+          onClick={onDismiss}
+        >
+          <X size={14} aria-hidden="true" />
+        </Button>
+      )}
+    </div>
+  );
+});

package/src/components/Alert/index.ts

@@ -0,0 +1,2 @@
+export { Alert } from './Alert';
+export type { AlertProps, AlertTone } from './Alert';

package/src/components/AppLayout/AppLayout.module.scss

@@ -0,0 +1,130 @@
+// AppLayout is a layout-owning primitive — the documented exception to the
+// "no layout properties on components" rule (like Page / Screen / Rail). Owning
+// the viewport-filling shell is its whole job. The topBar / sidebar slots bring
+// their own surfaces; the main region's only own-styling is its content gutter
+// (--app-layout-content-padding) + subtle canvas (--app-layout-content-background)
+// — the canonical shell look, so a DS-only consumer needs no raw CSS. Matches the
+// CRM shell topology
+// (see the playground AppShell): a full-height sidebar down the left, the top bar
+// over the content column, and the main content below it. (stylelint's
+// property-disallowed-list blocks flex-grow / flex-basis but not the `flex`
+// shorthand, min-height, or min-width, so no disable is needed here.)
+@use './AppLayout.tokens';
+
+// Column: optional full-window banner above the [sidebar | column] row.
+.root {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+
+  // Own stacking context so a nested AppLayout's --z-app-chrome topBar can't
+  // tie with (and win tree-order over) an ancestor AppLayout's topBar —
+  // nesting is sanctioned (demos mount several inside the app's own shell;
+  // see the component JSDoc). `isolation` creates a stacking context WITHOUT
+  // creating a containing block, so it doesn't affect portaled overlays
+  // (Modal/Drawer/Popover — those escape to document.body regardless) or any
+  // in-content `position: fixed` element.
+  isolation: isolate;
+}
+
+.banner,
+.contextBanner {
+  flex: none;
+}
+
+// The original shell row. flex: 1 fills the root's min-height (and a
+// consumer's fixed `height: 100vh` override); min-height: 0 lets that
+// fixed-height mode shrink the row so Rail / main manage their own overflow.
+.row {
+  display: flex;
+  flex: 1;
+  flex-direction: row;
+
+  // Explicit (it's the default) — the full-height sidebar depends on the row
+  // stretching its items to the row's height; don't change this to center/start.
+  align-items: stretch;
+  min-height: 0;
+}
+
+// Full-height sidebar down the left (stretches to the row height). Sets its own
+// width.
+.sidebar {
+  flex: none;
+}
+
+// Viewport-pinned sidebar (sidebarPinned): the sidebar spans exactly the
+// screen, not the row/page. sticky (not fixed) so it keeps its flex-row slot
+// and width; a DEFINITE 100dvh height gives a Rail's `height: 100%` something
+// to resolve against, which is what lets its footer pin to the viewport
+// bottom (the Rail's own scroll body does the pinning, not a spacer).
+// dvh tracks mobile dynamic toolbars;
+// the vh line is the older-engine fallback. overflow-y: auto scrolls an
+// over-tall rail inside the pinned box instead of growing the page.
+.sidebarPinned {
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  height: 100dvh;
+  overflow-y: auto;
+}
+
+// The top bar + content column to the right of the sidebar. min-width:0 lets the
+// column (and wide content like tables) shrink instead of pushing the sidebar.
+.body {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+}
+
+// Top bar over the content column; natural height. Also sticky (redundant
+// with the <TopBar> primitive's own `position: sticky; top: 0`, which alone
+// isn't enough): a sticky element's range is capped by its containing
+// block's box, and this wrapper's containing block is itself — sized to the
+// bar's own content height by `flex: none`. Without its own sticky here, the
+// wrapper (and the bar riding inside it) unsticks and scrolls away the
+// instant the page scrolls past the bar's own height. Stickying the wrapper
+// against `.body` (which spans the full scrollable column) gives it room to
+// stay pinned for the page's whole height. z-index keeps it painting over
+// scrolled-under content — `--z-app-chrome` sits above unpositioned page
+// content but below every overlay tier (dropdown/popover/modal/toast/
+// tooltip), so it never fights a real overlay for stacking order.
+.topBar {
+  flex: none;
+  position: sticky;
+  top: 0;
+  z-index: var(--z-app-chrome);
+}
+
+// Main content fills the rest of the column. Carries the canonical shell content
+// gutter by default (--app-layout-content-padding = --space-6) so a DS-only
+// consumer gets padded routed content with no prop and no raw CSS; override the
+// token to `0` for a full-bleed main region.
+.main {
+  flex: 1;
+  min-width: 0;
+  padding: var(--app-layout-content-padding);
+
+  // Subtle content canvas so page Cards lift off it (default
+  // --color-bg-subtle; override the token to `transparent` for a flat area).
+  background: var(--app-layout-content-background);
+}
+
+// Overlay sidebar (sidebarOverlayBelow): the Drawer panel is 320px
+// (--size-drawer-sm, the sanctioned nav-drawer width) but a <Rail> inside sets
+// its own 240px width and would leave a dead strip. Rebinding the rail's own
+// width token — its documented override surface — makes the rail fill the
+// panel instead. Scoped to this class so it can't leak to an in-flow rail.
+.overlaySidebar {
+  --rail-width-expanded: 100%;
+  --rail-width-collapsed: 100%;
+}
+
+// The Drawer header consumes part of the fixed-height panel. Give the sidebar
+// the remaining block space and allow it to shrink below its automatic
+// min-content size, so a 100%-height Rail keeps its footer inside the panel on
+// short touch viewports.
+.overlaySidebarContent {
+  flex: 1 1 auto;
+  min-height: 0;
+}