@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Rail/Rail.module.scss

@@ -0,0 +1,510 @@
+@use '../../styles/mixins' as *;
+@use './Rail.tokens';
+
+// ─── Root ───────────────────────────────────────────────────────────────
+// stylelint-disable property-disallowed-list -- Rail is a layout-owning
+// primitive (Hard rule 4 exception). Like <Modal>, <Drawer>, <Page>, the
+// rail owns its OWN width and height: that IS its job as a left-nav layout
+// container. The consumer chooses where to place the rail by styling its
+// parent; the rail itself is a flex column with animated width.
+.rail {
+  width: var(--rail-width-expanded);
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+
+  // Only the bottom edge here: the top and inline padding move onto .body and
+  // .footerWrap so a pinned <Rail.Header> can sit flush at the top and run
+  // edge to edge (#650). The resolved geometry of every other child is
+  // unchanged.
+  padding-bottom: var(--rail-padding-y);
+  background: var(--rail-bg);
+  border-right: var(--rail-border-width) solid var(--rail-border-color);
+  transition: var(--rail-collapse-transition);
+
+  // Horizontal-only clip — labels disappear during the width transition.
+  // The Y-axis scroll lives on .body, not here.
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- horizontal label clip during animation
+  overflow-x: hidden;
+}
+
+// Scrollable body — holds Header + Sections + Spacer. The .footerWrap is
+// a separate flex child OUTSIDE the scroll area so it always pins at the
+// bottom of the rail without sticky-positioning quirks. With overflow-y
+// here (not on .rail), items below the visible window scroll within this
+// box; the footer sees no scroll and stays put.
+.body {
+  flex: 1 1 auto;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--rail-section-gap);
+  padding: var(--rail-padding-y) var(--rail-padding-x) 0;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- scroll long item lists
+  overflow-y: auto;
+
+  // Y scrolls, X clips — never the other way. Declaring only `overflow-y`
+  // leaves X at `visible`, which the spec then computes to `auto` because the
+  // other axis isn't visible: the box becomes horizontally scrollable. That
+  // bites in collapsed mode, where the 56px rail leaves a ~39px body, the
+  // vertical gutter eats ~10px of it, and the remaining ~29px is narrower than
+  // an item row's min-content width — so a horizontal scrollbar appears under
+  // the icons. Clipping X is also just correct: the rail is a fixed-width nav
+  // and labels are meant to be clipped during the collapse transition (.rail
+  // clips X for the same reason).
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- horizontal label clip, never a horizontal scroll
+  overflow-x: hidden;
+}
+
+// Collapsed = icon-only at 56px. A ~10px scroll gutter is a quarter of the
+// body's width there: it shifts every item pill off-center (8px from the rail's
+// left edge, 19px from the right) and crowds the icon column. Hide the bar in
+// this mode only — wheel, keyboard, and scroll-into-view on focus all still
+// work, and the rail expands to a full-width bar the moment it's opened.
+.collapsed .body {
+  scrollbar-width: none;
+}
+
+.collapsed {
+  width: var(--rail-width-collapsed);
+}
+// stylelint-enable property-disallowed-list
+
+// ─── Header / Footer / Spacer ───────────────────────────────────────────
+// A leading <Rail.Header> is a direct child of .rail (hoisted out of .body by
+// Rail.tsx), so it stays pinned while the item list scrolls and spans the full
+// rail width — its divider meets the rail's border-right. Sized to
+// --rail-header-height (default --topbar-height) with the brand vertically
+// centred, so the divider continues an adjacent TopBar's bottom border.
+// The defaults are var() fallbacks HERE, not :root values, so they resolve on
+// this element (see Rail.tokens.scss).
+// Padding: the inline inset is the sum of the two an item icon sits behind
+// (--rail-padding-x + --rail-item-padding-x), putting the brand mark on the
+// icon column. The top inset equals the divider width, so the brand centres in
+// the FULL header height (window top edge → bottom of the divider). With a 1px
+// divider the content box above it is an odd 55px, which parks an even-height
+// mark on a half pixel (32px → y 11.5); the engine then snaps the image down
+// and the wordmark's baseline up, and the two visibly misalign by ~1px.
+// Centring in the even 56px puts the mark on a whole pixel.
+.header {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  min-height: var(--rail-header-height, var(--topbar-height));
+  padding: var(
+    --rail-header-padding,
+    var(--rail-header-divider-width) calc(var(--rail-padding-x) + var(--rail-item-padding-x)) 0
+  );
+  border-bottom: var(--rail-header-divider-width) solid var(--rail-border-color);
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- collapse-mode clip per spec
+  overflow: hidden;
+}
+
+// The consumer's children live in this plain block box, so their own flow is
+// exactly what it was before the header became a centring flex container:
+// inline children (`<img/> Acme`) stay on one line, block children stack.
+// stylelint-disable property-disallowed-list -- the inner box fills the header
+// row expanded and shrinks to its content collapsed so it can be centred.
+.headerInner {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.collapsed .headerInner {
+  flex: none;
+}
+// stylelint-enable property-disallowed-list
+
+// Collapsed = a 56px icon-only track. Center the brand there so the mark lands
+// within a pixel or two of the item icons' axis. They are not exactly equal, and
+// the whole difference is the icon overflowing its row: the header's content box
+// and the item's content region share a centre at 27.5, but the 18px icon is
+// flex-shrink: 0 inside a 15px region, so it start-aligns at 20 and runs to 38 —
+// centre 29, i.e. (18 − 15) / 2 = 1.5px right. The rail's 1px border-right only
+// narrows that region (16 → 15) and so deepens the same overflow; it is not a
+// separate contributor.
+// Horizontal centering is scoped to the collapsed state on purpose: expanded,
+// the brand is already aligned by --rail-header-padding's horizontal inset and
+// .headerInner fills the row. Collapsed, .headerInner shrinks to its content
+// and that box is what gets centred. (Vertical centering applies in both states.)
+// The horizontal inset is dropped here because it is an *alignment* value for
+// the expanded rail; at 56px it would leave a 15px content box (56 − 1px
+// border-right − 2×20 header inset) that a 32px mark immediately
+// overflows, and the centering would then be measured against the wrong box.
+.collapsed .header {
+  justify-content: center;
+  padding-inline: 0;
+}
+
+// `safe` matters: on a brand too wide for the collapsed track, plain `center`
+// overflows both edges and clips the mark itself — the one part a collapsed rail
+// must keep. `safe` start-aligns in exactly that case, so the mark stays visible
+// and only the trailing wordmark is clipped.
+// It has to be a separate @supports rule rather than a second declaration in the
+// block above. A minifier collapses duplicate properties inside one rule, so the
+// usual two-declaration cascade survives review and then dies in the build —
+// verified against this repo's own production bundle, which kept only
+// `justify-content:safe center`. That would leave engines unable to parse `safe`
+// dropping the declaration entirely and falling to flex-start: the mark
+// un-centered in EVERY collapsed rail, a broader regression than the oversized
+// brand this guards against. Across separate rules there is nothing to merge.
+@supports (justify-content: safe center) {
+  .collapsed .header {
+    justify-content: safe center;
+  }
+}
+
+// Wrapper around any <Rail.Footer> children — sits as a flex item BELOW
+// the scrollable .body. Because it's outside the scroll container, it
+// always stays visible at the bottom of the rail without sticky tricks.
+.footerWrap {
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+
+  // Small top spacing so the footer area visually separates from the last
+  // scrolled item without needing a divider; the inline inset is the rail's.
+  padding: var(--space-2) var(--rail-padding-x) 0;
+}
+
+// Direct <Rail.Footer> — visual styling only (no sticky now that the
+// .footerWrap is structurally separated from the scroll body).
+.footer {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.spacer {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+// ─── Collapse toggle ────────────────────────────────────────────────────
+// Renders the toggle as a row matching Rail.Item's geometry so the chevron
+// icon aligns with the column of item icons regardless of collapse state.
+// Icon direction flips via React (ChevronsLeft → ChevronsRight) rather than
+// a CSS transform — rotating the whole button would mirror its content and
+// visually jump the icon from row-start to row-end.
+.collapseToggle {
+  // Override the default <Button iconOnly> centering: stretch to fill the
+  // footer row and left-align the icon at the same X as item icons.
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- match item row width
+  width: 100%;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- align with item icons
+  justify-content: flex-start;
+  padding: var(--rail-item-padding-y) var(--rail-item-padding-x);
+}
+
+// ─── Section ────────────────────────────────────────────────────────────
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.sectionTitle {
+  padding: var(--rail-section-title-padding);
+  font-size: var(--rail-section-title-font-size);
+  font-weight: var(--rail-section-title-font-weight);
+  letter-spacing: var(--rail-section-title-letter-spacing);
+  text-transform: uppercase;
+  color: var(--rail-section-title-fg);
+  opacity: var(--rail-label-opacity-visible);
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- multi-prop shorthand for two transitioned props
+  transition:
+    opacity var(--transition-fast),
+    height var(--transition-fast);
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- nowrap clip during collapse
+  white-space: nowrap;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- collapse clip
+  overflow: hidden;
+}
+
+.collapsed .sectionTitle {
+  opacity: var(--rail-label-opacity-hidden);
+  pointer-events: none;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- collapse-time height zero is intentional
+  height: 0;
+  padding: 0;
+}
+
+// ─── Item ───────────────────────────────────────────────────────────────
+.item {
+  display: flex;
+  align-items: center;
+  gap: var(--rail-item-gap);
+  padding: var(--rail-item-padding-y) var(--rail-item-padding-x);
+  color: var(--rail-item-fg);
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- anchor reset
+  text-decoration: none;
+  border-radius: var(--rail-item-radius);
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- nowrap clip during collapse
+  white-space: nowrap;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- collapse clip
+  overflow: hidden;
+  cursor: pointer;
+}
+
+.item:hover {
+  background: var(--rail-item-bg-hover);
+
+  // Some consumer global styles (and the modern reset) add `text-decoration:
+  // underline` on `<a>:hover`. The rail's items are nav buttons styled as
+  // pill rows — they shouldn't underline like body links.
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- anchor underline reset on hover
+  text-decoration: none;
+}
+
+// Inset: `.item` renders both in the rail body (an overflow scroller) and,
+// portaled, inside a flyout header — its clipping ancestor is `.body` in the
+// rail, `.flyout` when portaled. Either way an outset ring loses a band.
+.item:focus-visible {
+  @include focus-ring($offset: calc(-1 * var(--ring-offset)));
+}
+
+// Active-state styling. Two selectors so we catch both shapes:
+// (1) the `.item` element itself carries `aria-current="page"` (e.g. user
+//     passed it directly via the polymorphic `as` element).
+// (2) the `.item` wrapper has a descendant with `aria-current="page"` —
+//     this is the NavLink case, where the rendered anchor IS the wrapper
+//     and react-router sets aria-current on the rendered element directly.
+.item[aria-current='page'],
+.item:has([aria-current='page']) {
+  background: var(--rail-item-bg-active);
+  color: var(--rail-item-fg-active);
+}
+
+.itemIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--rail-item-icon-size);
+  height: var(--rail-item-icon-size);
+  flex-shrink: 0;
+}
+
+.itemLabel {
+  flex: 1 1 auto;
+  min-width: 0;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- collapse clip
+  overflow: hidden;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- truncation marker
+  text-overflow: ellipsis;
+  transition: var(--rail-label-transition);
+}
+
+.collapsed .itemLabel,
+.collapsed .itemBadge {
+  opacity: var(--rail-label-opacity-hidden);
+  pointer-events: none;
+}
+
+.itemBadge {
+  flex-shrink: 0;
+  font-size: var(--font-size-xs);
+  transition: var(--rail-label-transition);
+}
+
+// ─── Group ──────────────────────────────────────────────────────────────
+.group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+// Same shape as .item but rendered as a <button>, so we reset native button
+// chrome (border, background, font inheritance).
+.groupTrigger {
+  display: flex;
+  align-items: center;
+  gap: var(--rail-item-gap);
+  padding: var(--rail-item-padding-y) var(--rail-item-padding-x);
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- button-reset, layout fills the rail width
+  width: 100%;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- native button border reset
+  border: 0;
+  background: transparent;
+  border-radius: var(--rail-item-radius);
+  color: var(--rail-item-fg);
+  cursor: pointer;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- inherit page font
+  font: inherit;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- match left-anchored items
+  text-align: start;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- nowrap clip during collapse
+  white-space: nowrap;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- collapse clip
+  overflow: hidden;
+}
+
+.groupTrigger:hover {
+  background: var(--rail-item-bg-hover);
+}
+
+// Inset, like `.item` and `.groupChevronButton`. This used to be a SECOND
+// `.groupTrigger:focus-visible` at +2px which, being later at equal
+// specificity, won — and left the correct -2px rule further up dead while the
+// ring clipped against `.body`'s overflow on both sides. One rule now.
+.groupTrigger:focus-visible {
+  @include focus-ring($offset: calc(-1 * var(--ring-offset)));
+}
+
+// Parent-active styling: the group's trigger picks up the active accent
+// when any descendant subitem is current. `:has()` walks the .group block,
+// not the trigger, so both inline subitems and popover subitems light up
+// their parent. On a linkable group the chevron button is the trigger's
+// counterpart — the label link already lights up on its own via
+// `.item[aria-current='page']`.
+.group:has([aria-current='page']) .groupTrigger,
+.group:has([aria-current='page']) .groupChevronButton {
+  color: var(--rail-item-fg-active);
+}
+
+// ─── Linkable group row (`<Rail.Group as={NavLink}>`) ───────────────────
+// Two hit-targets on one row: the label link (an `.item`, so it inherits
+// every item visual including the active accent) and the chevron button.
+.groupRow {
+  display: flex;
+  align-items: center;
+  gap: var(--rail-group-row-gap);
+}
+
+.groupRow .item {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+// Chevron reset — same button-chrome reset as .groupTrigger, sized down to a
+// square affordance that sits beside the link instead of spanning the row.
+.groupChevronButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  padding: var(--rail-group-chevron-padding);
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- native button border reset
+  border: 0;
+  background: transparent;
+  border-radius: var(--rail-item-radius);
+  color: var(--rail-item-fg);
+  cursor: pointer;
+}
+
+.groupChevronButton:hover {
+  background: var(--rail-item-bg-hover);
+}
+
+// Inset: the rail body is an overflow scroller, so an outset ring loses its
+// outer bands.
+.groupChevronButton:focus-visible {
+  @include focus-ring($offset: calc(-1 * var(--ring-offset)));
+}
+
+.groupChevron {
+  flex-shrink: 0;
+  transition: var(--rail-chevron-transition);
+}
+
+.groupChevronOpen {
+  transform: rotate(90deg);
+}
+
+.subitems {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+// The `hidden` HTML attribute is set by RailGroup when the group is closed
+// (and the rail is expanded). The UA stylesheet's `[hidden] { display: none }`
+// loses against `.subitems { display: flex }` because class beats attribute
+// selectors. Re-state it explicitly so the closed state actually hides.
+// stylelint-disable-next-line declaration-property-value-disallowed-list -- collapse closed state
+.subitems[hidden] {
+  display: none;
+}
+
+.subitems .item {
+  padding-left: var(--rail-subitem-padding-left);
+}
+
+// When the rail is collapsed, inline subitems disappear (they live in the
+// flyout popover instead).
+.collapsed .subitems {
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- collapsed mode hides inline subitems
+  display: none;
+}
+
+// ─── Collapsed-mode flyout (Popover content) ────────────────────────────
+.flyout {
+  display: flex;
+  flex-direction: column;
+  min-width: var(--rail-flyout-min-width);
+
+  // #273: without an explicit z the body-portaled flyout sat at z-auto —
+  // below --z-modal AND below any positive-z page content (e.g. Table's
+  // sticky header).
+  z-index: var(--rail-flyout-z);
+  background: var(--rail-flyout-bg);
+  border: var(--rail-flyout-border-width) solid var(--rail-flyout-border-color);
+  border-radius: var(--rail-flyout-radius);
+  box-shadow: var(--rail-flyout-shadow);
+
+  // Clip child rounded corners (subitems with hover backgrounds) to the
+  // flyout's rounded outer edge.
+  overflow: hidden;
+}
+
+.flyout[data-in-overlay] {
+  // #272-pattern: inside a Modal/Drawer (or another elevated surface) the
+  // base z sits below --z-modal — elevate above the host, below toasts.
+  z-index: var(--z-overlay-floating);
+}
+
+// #685: the tour's current target is INSIDE this surface — drop just under the
+// scrim (--z-tour) so only the target is lit, not the whole panel.
+.flyout[data-in-overlay]:has([data-tour-current-target]) {
+  z-index: calc(var(--z-tour) - 1);
+}
+
+.flyoutHeader {
+  padding: var(--rail-flyout-header-padding);
+  font-weight: var(--rail-flyout-header-font-weight);
+  color: var(--rail-flyout-header-fg);
+  border-bottom: var(--border-width) solid var(--rail-flyout-header-border);
+}
+
+// A linkable group's flyout header renders its label as a link to the group's
+// own destination. The padding moves from the wrapper onto the link so the
+// whole header strip is clickable rather than just the text box.
+.flyoutHeader:has(.flyoutHeaderLink) {
+  padding: 0;
+}
+
+.flyoutHeaderLink {
+  display: block;
+  padding: var(--rail-flyout-header-padding);
+  color: inherit;
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- anchor reset
+  text-decoration: none;
+}
+
+.flyoutHeaderLink:hover {
+  color: var(--rail-item-fg-active);
+}
+
+// Inset: the flyout is `createPortal(..., document.body)` (RailGroup.tsx), so
+// this link is not a descendant of `.body` — its clipping ancestor is
+// `.flyout` itself, which sets `overflow: hidden`.
+.flyoutHeaderLink:focus-visible {
+  @include focus-ring($offset: calc(-1 * var(--ring-offset)));
+}
+
+.flyoutBody {
+  display: flex;
+  flex-direction: column;
+  gap: var(--rail-flyout-body-gap);
+  padding: var(--rail-flyout-body-padding);
+}

package/src/components/Rail/Rail.tokens.scss

@@ -0,0 +1,92 @@
+// Rail.tokens.scss — Component-scoped tokens for <Rail>. Each token defaults
+// to the primitive that the SCSS would otherwise use directly. Consumers can
+// rebind any of these at a higher level (`.theme-foo :root { --rail-bg: … }`)
+// to retheme the rail without forking its module.scss.
+@use '../TopBar/TopBar.tokens';
+
+:root {
+  // Width — the rail switches between two fixed widths via `[data-collapsed]`.
+  --rail-width-expanded: 240px;
+  --rail-width-collapsed: 56px;
+
+  // Outer chrome
+  --rail-padding-y: var(--space-2);
+  --rail-padding-x: var(--space-2);
+  --rail-bg: var(--color-bg);
+  --rail-border-color: var(--color-border);
+  --rail-border-width: var(--border-width);
+
+  // Header (brand area) — a brand block over a header→nav divider by default, so
+  // a DS-only consumer matches the mockup rail brand with no raw CSS. Divider
+  // color reuses --rail-border-color. Override either token to `0` for a bare
+  // header slot.
+  // Height and padding are declared `initial` (guaranteed-invalid) on purpose:
+  // their real defaults live as var() fallbacks in .header, so they resolve ON
+  // the header element. A default written here would resolve once at :root, and
+  // a --topbar-height / --rail-padding-x retuned on a theme wrapper, the
+  // AppLayout or the rail itself would never reach the header (#650). Setting
+  // either token anywhere above the rail still overrides the fallback.
+  // Defaults (see .header in Rail.module.scss):
+  //   --rail-header-height  → var(--topbar-height) — a min-height, so the
+  //     divider continues an adjacent TopBar's bottom border. `auto` = content
+  //     height. TopBar's tokens are @used above so it resolves without a TopBar.
+  //   --rail-header-padding → divider-width top, rail + item inline inset, 0
+  //     bottom — see the .header comment for why.
+  --rail-header-height: initial;
+  --rail-header-padding: initial;
+  --rail-header-divider-width: var(--border-width);
+
+  // Section grouping
+  --rail-section-gap: var(--space-3);
+  --rail-section-title-fg: var(--color-fg-muted);
+  --rail-section-title-font-size: var(--font-size-xs);
+  --rail-section-title-font-weight: var(--font-weight-semibold);
+  --rail-section-title-letter-spacing: var(--letter-spacing-caps);
+  --rail-section-title-padding: var(--space-2) var(--space-3);
+
+  // Item visuals
+  --rail-item-padding-x: var(--space-3);
+  --rail-item-padding-y: var(--space-2);
+  --rail-item-gap: var(--space-2);
+  --rail-item-radius: var(--radius-sm);
+  --rail-item-bg-hover: var(--color-bg-muted);
+  --rail-item-fg: var(--color-fg);
+  --rail-item-bg-active: var(--color-accent-subtle-bg);
+  --rail-item-fg-active: var(--color-accent);
+  --rail-item-icon-size: 18px;
+
+  // Linkable group row (`<Rail.Group as={NavLink}>`) — the gap between the
+  // label link and its sibling chevron button, and the chevron's own padding
+  // (which sets its hit-target size around the 14px glyph).
+  --rail-group-row-gap: var(--space-1);
+  --rail-group-chevron-padding: var(--space-2);
+
+  // Sub-item indent (extra left padding so subitems visually nest under
+  // their group icon). No --space-7 (28px) exists, so we use --space-6 (24px).
+  --rail-subitem-padding-left: var(--space-6);
+
+  // Collapsed flyout (the hover popover surface for collapsed groups)
+  --rail-flyout-min-width: 200px;
+  --rail-flyout-z: var(--z-popover);
+  --rail-flyout-bg: var(--color-bg);
+  --rail-flyout-border-color: var(--color-border);
+  --rail-flyout-border-width: var(--border-width);
+  --rail-flyout-radius: var(--radius-md);
+  --rail-flyout-shadow: var(--shadow-md);
+  --rail-flyout-header-padding: var(--space-2) var(--space-3);
+  --rail-flyout-body-padding: var(--space-2);
+  --rail-flyout-body-gap: var(--space-1);
+  --rail-flyout-header-fg: var(--color-fg);
+  --rail-flyout-header-font-weight: var(--font-weight-semibold);
+  --rail-flyout-header-border: var(--color-border);
+
+  // Label / title fade opacities. Bound to the global --opacity-* scale so
+  // a theme can retune visibility crossover without forking this file.
+  --rail-label-opacity-visible: var(--opacity-visible);
+  --rail-label-opacity-hidden: var(--opacity-hidden);
+
+  // Transitions
+  --rail-collapse-transition: width var(--transition-base);
+  --rail-label-transition: opacity var(--transition-fast);
+  --rail-chevron-transition: transform var(--transition-fast);
+}