@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/FormRow/FormRow.tsx

@@ -0,0 +1,37 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { Grid, type GridGap } from '../Grid';
+
+// Extends HTMLAttributes<HTMLElement> (not HTMLDivElement) to match Grid's prop
+// surface, so {...rest} spreads cleanly onto Grid.
+export interface FormRowProps extends HTMLAttributes<HTMLElement> {
+  /** Fixed equal-width column count. Omit for responsive auto-fit (the default). */
+  columns?: 2 | 3;
+  /** Min field width before the row reflows to stacked (auto-fit mode). Default `'16rem'`. */
+  minColumnWidth?: string;
+  /** Gap between fields. Default `'lg'`. */
+  gap?: GridGap;
+  /** The fields (usually `<Field>`). */
+  children: ReactNode;
+}
+
+/**
+ * Lays form fields side by side; auto-fits and reflows to stacked as the container narrows.
+ * @see docs/components/FormRow.md
+ */
+export const FormRow = forwardRef<HTMLDivElement, FormRowProps>(function FormRow(
+  { columns, minColumnWidth, gap = 'lg', children, ...rest },
+  ref,
+) {
+  if (columns !== undefined) {
+    return (
+      <Grid ref={ref} columns={columns} gap={gap} {...rest}>
+        {children}
+      </Grid>
+    );
+  }
+  return (
+    <Grid ref={ref} minColumnWidth={minColumnWidth ?? '16rem'} gap={gap} {...rest}>
+      {children}
+    </Grid>
+  );
+});

package/src/components/FormRow/index.ts

@@ -0,0 +1,2 @@
+export { FormRow } from './FormRow';
+export type { FormRowProps } from './FormRow';

package/src/components/FormSection/FormSection.module.scss

@@ -0,0 +1,24 @@
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+}
+
+// Separator between consecutive sections — padding + border only (no margin),
+// keyed by adjacency so the first section has none.
+.section + .section {
+  padding-top: var(--space-6);
+  border-top: var(--border-width) solid var(--color-border);
+}
+
+.header {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.fields {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+}

package/src/components/FormSection/FormSection.tsx

@@ -0,0 +1,46 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { Title, type TitleOrder } from '../Title';
+import { Text } from '../Text';
+import styles from './FormSection.module.scss';
+
+export interface FormSectionProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  /** Section heading. */
+  title?: ReactNode;
+  /** Secondary text under the heading. */
+  description?: ReactNode;
+  /** Heading level for `title`. Default `2`. */
+  titleOrder?: TitleOrder;
+  /** The fields (usually `<Field>` / `<FormRow>`). */
+  children: ReactNode;
+}
+
+/**
+ * Titled group of form fields: a heading + description over a vertical stack.
+ * @see docs/components/FormSection.md
+ */
+export const FormSection = forwardRef<HTMLElement, FormSectionProps>(function FormSection(
+  { title, description, titleOrder = 2, className, children, ...rest },
+  ref,
+) {
+  const hasHeader = title != null || description != null;
+  return (
+    <section ref={ref} className={clsx(styles.section, className)} {...rest}>
+      {hasHeader && (
+        <div className={styles.header}>
+          {title != null && (
+            <Title order={titleOrder} size="md">
+              {title}
+            </Title>
+          )}
+          {description != null && (
+            <Text as="p" size="sm" tone="muted">
+              {description}
+            </Text>
+          )}
+        </div>
+      )}
+      <div className={styles.fields}>{children}</div>
+    </section>
+  );
+});

package/src/components/FormSection/index.ts

@@ -0,0 +1,2 @@
+export { FormSection } from './FormSection';
+export type { FormSectionProps } from './FormSection';

package/src/components/Grid/Grid.module.scss

@@ -0,0 +1,162 @@
+@use './Grid.tokens' as tokens;
+@use '../_internal/collapse' as bp;
+
+.grid {
+  display: grid;
+  grid-template-columns: var(--grid-columns, repeat(auto-fit, minmax(240px, 1fr)));
+}
+
+// Grid.Item placement — the value is resolved in GridItem.tsx and injected
+// as an inline custom property (span N / 1 / -1). Declared before the
+// collapse rules so a collapsed grid's `1 / -1` override wins by source order.
+.item {
+  // stylelint-disable-next-line property-disallowed-list -- Grid.Item's sanctioned job: per-cell column placement is the layout family's own prop, not consumer layout (see GridItem.tsx)
+  grid-column: var(--grid-item-span, auto);
+}
+
+// Gap presets — mirror Stack/Cluster scale + camelCase naming
+.gapXs {
+  gap: var(--grid-gap-xs);
+}
+
+.gapSm {
+  gap: var(--grid-gap-sm);
+}
+
+.gapMd {
+  gap: var(--grid-gap-md);
+}
+
+.gapLg {
+  gap: var(--grid-gap-lg);
+}
+
+.gapXl {
+  gap: var(--grid-gap-xl);
+}
+
+.gap2xl {
+  gap: var(--grid-gap-2xl);
+}
+
+// Item alignment — cross-axis
+.alignItemsStart {
+  align-items: start;
+}
+
+.alignItemsCenter {
+  align-items: center;
+}
+
+.alignItemsEnd {
+  align-items: end;
+}
+
+.alignItemsStretch {
+  align-items: stretch;
+}
+
+// Item alignment — main-axis
+.justifyItemsStart {
+  justify-items: start;
+}
+
+.justifyItemsCenter {
+  justify-items: center;
+}
+
+.justifyItemsEnd {
+  justify-items: end;
+}
+
+.justifyItemsStretch {
+  justify-items: stretch;
+}
+
+// --- collapseBelow -----------------------------------------------------
+// Only grids with the STRING form become size containers themselves, so
+// existing grids get zero containment changes. Safe here because every rule
+// below queries a DESCENDANT (`> *`), never the grid itself.
+.collapsible {
+  container-type: inline-size;
+}
+
+// The map form needs the container on an ANCESTOR instead: its step rules
+// re-template the GRID, and an element is never matched by a query against
+// its own container (Split.module.scss says the same thing). Grid.tsx renders
+// this zero-styling wrapper only for the map form — same trick as
+// DashboardCanvas's `.sizer`.
+// `display: grid` (not the default block) so the wrapper is geometrically
+// transparent: its single child stretches in BOTH axes by default, so a grid
+// that is itself a stretched flex/grid item keeps its height. A block wrapper
+// would take the stretch and leave the grid at content height.
+.stepContainer {
+  display: grid;
+  container-type: inline-size;
+}
+
+// Below the container threshold every direct child spans the full row —
+// the template is untouched but the grid renders as one visual column.
+// Double class (.collapsible.collapseXx) gives specificity (0,2,0) so the
+// collapse beats any single-class consumer `grid-column` rule regardless of
+// CSS bundle emission order; vs `.item` it also still wins by source order.
+@container (max-width: #{bp.$collapse-sm}) {
+  .collapsible.collapseSm > * {
+    // stylelint-disable-next-line property-disallowed-list -- collapse override is Grid's own placement mechanism, same sanction as `.item` above
+    grid-column: 1 / -1;
+  }
+}
+
+@container (max-width: #{bp.$collapse-md}) {
+  .collapsible.collapseMd > * {
+    // stylelint-disable-next-line property-disallowed-list -- collapse override is Grid's own placement mechanism, same sanction as `.item` above
+    grid-column: 1 / -1;
+  }
+}
+
+@container (max-width: #{bp.$collapse-lg}) {
+  .collapsible.collapseLg > * {
+    // stylelint-disable-next-line property-disallowed-list -- collapse override is Grid's own placement mechanism, same sanction as `.item` above
+    grid-column: 1 / -1;
+  }
+}
+
+// --- graduated (map) collapse ------------------------------------------
+// Step track templates + per-item clamped spans are computed in Grid.tsx /
+// GridItem.tsx and injected inline (--grid-columns-<bp>, --grid-item-span-<bp>).
+// Declared lg → md → sm so when several steps match at a narrow width the
+// smallest breakpoint wins by source order (equal specificity). Queried
+// against `.stepContainer`, the wrapper above; `.grid.stepXx` keeps the same
+// (0,2,0) specificity the old `.collapsible.stepXx` pair had.
+@container (max-width: #{bp.$collapse-lg}) {
+  .grid.stepLg {
+    grid-template-columns: var(--grid-columns-lg, none);
+
+    > .item {
+      // stylelint-disable-next-line property-disallowed-list -- graduated collapse override is Grid's own placement mechanism, same sanction as `.item` above
+      grid-column: var(--grid-item-span-lg, auto);
+    }
+  }
+}
+
+@container (max-width: #{bp.$collapse-md}) {
+  .grid.stepMd {
+    grid-template-columns: var(--grid-columns-md, none);
+
+    > .item {
+      // stylelint-disable-next-line property-disallowed-list -- graduated collapse override is Grid's own placement mechanism, same sanction as `.item` above
+      grid-column: var(--grid-item-span-md, auto);
+    }
+  }
+}
+
+@container (max-width: #{bp.$collapse-sm}) {
+  .grid.stepSm {
+    grid-template-columns: var(--grid-columns-sm, none);
+
+    > .item {
+      // stylelint-disable-next-line property-disallowed-list -- graduated collapse override is Grid's own placement mechanism, same sanction as `.item` above
+      grid-column: var(--grid-item-span-sm, auto);
+    }
+  }
+}

package/src/components/Grid/Grid.tokens.scss

@@ -0,0 +1,13 @@
+// Grid.tokens.scss — Component-scoped tokens for <Grid>. Each token
+// defaults to the primitive the SCSS used before this migration.
+:root {
+  // Gap per size
+  --grid-gap-xs: var(--space-1);
+  --grid-gap-sm: var(--space-2);
+  --grid-gap-md: var(--space-3);
+  --grid-gap-lg: var(--space-4);
+  --grid-gap-xl: var(--space-6);
+  --grid-gap-2xl: var(--space-8);
+}
+
+// Collapse breakpoints live in ../_internal/collapse.scss (shared with Sortable).

package/src/components/Grid/Grid.tsx

@@ -0,0 +1,226 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactElement } from 'react';
+import clsx from 'clsx';
+import styles from './Grid.module.scss';
+import { GridItem } from './GridItem';
+import {
+  CollapseColumnsContext,
+  COLLAPSE_BREAKPOINTS,
+  collapseTrackTemplate,
+  type CollapseBreakpoint,
+  type CollapseColumnsMap,
+} from '../_internal/collapse';
+
+/** Gap between cells. Same scale as Stack/Cluster: pixels 4/8/12/16/24/32. */
+export type GridGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+/** Cross-axis (vertical within row) alignment of each cell. */
+export type GridAlignItems = 'start' | 'center' | 'end' | 'stretch';
+
+/** Main-axis (horizontal within track) alignment of each cell. */
+export type GridJustifyItems = 'start' | 'center' | 'end' | 'stretch';
+
+/** Container-width threshold below which a fixed-column grid collapses. `sm` 480px / `md` 640px / `lg` 768px. */
+export type GridCollapseBreakpoint = CollapseBreakpoint;
+export type { CollapseColumnsMap };
+
+/** Limited polymorphic element type. Covers the layout / semantic elements Grid is likely to render as. */
+export type GridAs =
+  | 'div'
+  | 'section'
+  | 'ul'
+  | 'ol'
+  | 'nav'
+  | 'main'
+  | 'aside'
+  | 'article'
+  | 'header'
+  | 'footer';
+
+interface GridBaseProps {
+  /**
+   * Gap between cells.
+   * `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32).
+   * Same scale as Stack and Cluster.
+   */
+  gap?: GridGap;
+  /**
+   * Cross-axis (vertical within row) alignment of each cell. Default browser
+   * behavior is `stretch`; omit to use the default. Useful for cards of varying intrinsic height.
+   */
+  alignItems?: GridAlignItems;
+  /**
+   * Main-axis (horizontal within track) alignment of each cell. Default
+   * browser behavior is `stretch`; omit to use the default.
+   */
+  justifyItems?: GridJustifyItems;
+  /** Element to render. Default `'div'`. Limited to `div`, `section`, `ul`, `ol`, `nav`, `main`, `aside`, `article`, `header`, `footer` rather than fully polymorphic. */
+  as?: GridAs;
+}
+
+interface GridFixedColumns extends GridBaseProps, HTMLAttributes<HTMLElement> {
+  /** Fixed number of equal-width columns. Mutually exclusive with `minColumnWidth`. */
+  columns: number;
+  minColumnWidth?: never;
+  /**
+   * Collapse to a single visual column when the GRID'S OWN width (container
+   * query, not viewport) drops below the preset: `sm` 480px / `md` 640px /
+   * `lg` 768px. Every child spans the full row below the threshold —
+   * `Grid.Item` spans included. Only valid with `columns` (auto-fit grids
+   * already reflow).
+   *
+   * Consumer inline `style={{ gridColumn }}` on a child still wins below the
+   * threshold (inline beats any stylesheet rule) — don't do that; use
+   * `Grid.Item span` instead.
+   *
+   * ❌ Anti-pattern: a `collapseBelow` grid must get its width from its
+   * parent. `container-type: inline-size` zeroes the grid's contribution to
+   * intrinsic sizing, so in an intrinsic-width context (`Split`'s default
+   * `auto` aside track, a `Cluster` item, `width: max-content`) it renders at
+   * width 0 — give the parent a concrete width instead. Whichever element
+   * carries the containment also becomes the containing block for
+   * absolutely-positioned descendants (layout containment) — the grid itself
+   * for the string form, the wrapper below for the map form.
+   *
+   * Also accepts a graduated breakpoint→columns map, e.g.
+   * `collapseBelow={{ md: 6, sm: 1 }}`: below 640px the grid re-templates to
+   * 6 columns (item spans clamp to fit — a span wider than the step becomes a
+   * full row), and below 480px to a single column. Use when jumping straight
+   * from N columns to 1 wastes tablet widths. When several breakpoints match,
+   * the smallest wins. Only `Grid.Item` children get span clamping; plain
+   * children auto-place into the step's tracks.
+   *
+   * ⚠️ The map form (and ONLY the map form) renders an extra wrapper `<div>`
+   * around the grid element — it carries `container-type: inline-size`,
+   * because re-templating the grid requires querying an ancestor, not the
+   * grid itself. Consequences: a `> child` CSS selector aimed at the grid from
+   * its parent now hits the wrapper instead, and layout the parent applies to
+   * "the Grid" (`flex: 1`, `grid-column`, `align-self` via `className`) lands
+   * on the grid *inside* the wrapper, where the parent's layout can't see it —
+   * put that layout on an element you control around the Grid. `ref`,
+   * `className`, `style`, `as` and all spread props stay on the grid element.
+   */
+  collapseBelow?: GridCollapseBreakpoint | CollapseColumnsMap;
+}
+
+interface GridAutoFit extends GridBaseProps, HTMLAttributes<HTMLElement> {
+  /**
+   * Minimum column width for auto-fit responsive layout. Columns reflow
+   * based on container width — no breakpoints needed. CSS length string
+   * like `'240px'` or `'15rem'`. Defaults to `'240px'` when neither
+   * `columns` nor `minColumnWidth` is provided.
+   */
+  minColumnWidth?: string;
+  columns?: never;
+  collapseBelow?: never;
+}
+
+/** Public props — discriminated union enforces mutual exclusion. */
+export type GridProps = GridFixedColumns | GridAutoFit;
+
+const gapClass: Record<GridGap, string> = {
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+  '2xl': styles.gap2xl,
+};
+
+const alignItemsClass: Record<GridAlignItems, string> = {
+  start: styles.alignItemsStart,
+  center: styles.alignItemsCenter,
+  end: styles.alignItemsEnd,
+  stretch: styles.alignItemsStretch,
+};
+
+const justifyItemsClass: Record<GridJustifyItems, string> = {
+  start: styles.justifyItemsStart,
+  center: styles.justifyItemsCenter,
+  end: styles.justifyItemsEnd,
+  stretch: styles.justifyItemsStretch,
+};
+
+const collapseClass: Record<GridCollapseBreakpoint, string> = {
+  sm: styles.collapseSm,
+  md: styles.collapseMd,
+  lg: styles.collapseLg,
+};
+
+const stepClass: Record<CollapseBreakpoint, string> = {
+  sm: styles.stepSm,
+  md: styles.stepMd,
+  lg: styles.stepLg,
+};
+
+const GridBase = forwardRef<HTMLElement, GridProps>(function Grid(
+  {
+    gap = 'md',
+    alignItems,
+    justifyItems,
+    as = 'div',
+    columns,
+    minColumnWidth,
+    collapseBelow,
+    className,
+    style,
+    ...rest
+  },
+  ref,
+) {
+  const template =
+    columns !== undefined
+      ? collapseTrackTemplate(columns)
+      : `repeat(auto-fit, minmax(${minColumnWidth ?? '240px'}, 1fr))`;
+
+  const collapseMap = typeof collapseBelow === 'object' ? collapseBelow : undefined;
+  const collapseKeys = collapseMap
+    ? COLLAPSE_BREAKPOINTS.filter((b) => collapseMap[b] !== undefined)
+    : [];
+  const stepVars = Object.fromEntries(
+    collapseKeys.map((b) => [`--grid-columns-${b}`, collapseTrackTemplate(collapseMap![b]!)]),
+  );
+
+  // `as` is a string union of intrinsic JSX elements; cast through unknown
+  // for the limited union. At runtime React just uses the element name.
+  const Tag = as as unknown as 'div';
+
+  // Tag is constrained at the type level via GridAs; the ref + rest casts
+  // satisfy React's intrinsic-element signature without per-tag branching.
+  const grid = (
+    <Tag
+      ref={ref as React.Ref<HTMLDivElement>}
+      className={clsx(
+        styles.grid,
+        gapClass[gap],
+        alignItems && alignItemsClass[alignItems],
+        justifyItems && justifyItemsClass[justifyItems],
+        // String form only: those rules query descendants, so the grid can be
+        // its own container. The map form's container is the wrapper below.
+        typeof collapseBelow === 'string' && styles.collapsible,
+        typeof collapseBelow === 'string' && collapseClass[collapseBelow],
+        ...collapseKeys.map((b) => stepClass[b]),
+        className,
+      )}
+      style={{ ...(style as CSSProperties), ...stepVars, ['--grid-columns' as string]: template }}
+      {...(rest as HTMLAttributes<HTMLDivElement>)}
+    />
+  );
+
+  // Map form only: the step rules re-template the grid itself, and a container
+  // query never matches its own container — so the size container has to be a
+  // wrapper. `ref`, `className`, `style`, `as` and `{...rest}` all stay on the
+  // grid element; the wrapper is a bare div that only carries containment.
+  return collapseMap && collapseKeys.length > 0 ? (
+    <CollapseColumnsContext.Provider value={collapseMap}>
+      <div className={styles.stepContainer}>{grid}</div>
+    </CollapseColumnsContext.Provider>
+  ) : (
+    grid
+  );
+}) as <T extends GridProps>(props: T & { ref?: React.Ref<HTMLElement> }) => ReactElement;
+
+/**
+ * 2D layout primitive: a CSS Grid wrapper with token-driven gap.
+ * @see docs/components/Grid.md
+ */
+export const Grid = Object.assign(GridBase, { Item: GridItem });

package/src/components/Grid/GridItem.tsx

@@ -0,0 +1,77 @@
+import { forwardRef, useContext, type CSSProperties, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import {
+  resolveGridItemSpan,
+  resolveCollapsedGridItemSpan,
+  type GridItemSpan,
+} from '../_internal/gridSpan';
+import { CollapseColumnsContext } from '../_internal/collapse';
+import styles from './Grid.module.scss';
+
+// The span vocabulary (type + fraction→track resolver) is shared with
+// Sortable.Item's grid arrangement; it lives in _internal/gridSpan so neither
+// component imports the other. Re-exported here so `GridItemSpan` stays part of
+// Grid's public type surface.
+export type { GridItemSpan };
+
+/** Elements `Grid.Item` can render as. `'li'` pairs with `<Grid as="ul">`. */
+export type GridItemAs = 'div' | 'li' | 'section' | 'article' | 'aside';
+
+export interface GridItemProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Column span. Omit for a single track (auto placement).
+   * - number — `span N` of the parent's `columns`.
+   * - `'25%' | '33%' | '50%' | '67%' | '75%'` — fractions of a 12-column
+   *   grid; use with `columns={12}` (other counts won't produce the named
+   *   fraction — documented, not validated).
+   * - `'100%'` / `'full'` — the entire row; safe with any Grid variant.
+   */
+  span?: GridItemSpan;
+  /** Element to render. Default `'div'`. Use `'li'` inside `<Grid as="ul">`. */
+  as?: GridItemAs;
+}
+
+/**
+ * A cell of `<Grid>` with an explicit column span.
+ * @see docs/components/Grid.md
+ */
+export const GridItem = forwardRef<HTMLElement, GridItemProps>(function GridItem(
+  { span, as = 'div', className, style, ...rest },
+  ref,
+) {
+  const resolved = resolveGridItemSpan(span);
+
+  // Set only when a graduated (map-form) `collapseBelow` grid is an
+  // ancestor — same always-stamp rationale as `--grid-item-span`: custom
+  // properties inherit, so every map key present on the container gets
+  // stamped on every Item (see resolveCollapsedGridItemSpan for clamping).
+  const collapseMap = useContext(CollapseColumnsContext);
+  const collapseVars = collapseMap
+    ? Object.fromEntries(
+        (Object.keys(collapseMap) as (keyof typeof collapseMap)[]).map((b) => [
+          `--grid-item-span-${b}`,
+          resolveCollapsedGridItemSpan(span, collapseMap[b]!),
+        ]),
+      )
+    : undefined;
+
+  const Tag = as as unknown as 'div';
+  return (
+    // Grid/Stack/Cluster are the layout primitives — `grid-column` via the
+    // `.item` class is Grid.Item's sanctioned job (Rule 4 does not apply to
+    // the layout family's own placement props).
+    <Tag
+      ref={ref as React.Ref<HTMLDivElement>}
+      className={clsx(styles.item, className)}
+      // Always set the property — custom properties inherit, so an unset
+      // span-less item nested under a spanned one would resolve the
+      // ancestor's value instead of `auto`.
+      style={{
+        ...(style as CSSProperties),
+        ...collapseVars,
+        ['--grid-item-span' as string]: resolved ?? 'auto',
+      }}
+      {...(rest as HTMLAttributes<HTMLDivElement>)}
+    />
+  );
+});

package/src/components/Grid/index.ts

@@ -0,0 +1,11 @@
+export { Grid } from './Grid';
+export type {
+  GridProps,
+  GridGap,
+  GridAlignItems,
+  GridJustifyItems,
+  GridAs,
+  GridCollapseBreakpoint,
+  CollapseColumnsMap,
+} from './Grid';
+export type { GridItemProps, GridItemSpan, GridItemAs } from './GridItem';

package/src/components/Highlight/Highlight.module.scss

@@ -0,0 +1,43 @@
+@use './Highlight.tokens';
+@use '../../styles/mixins' as *;
+
+// The overlay HighlightOverlay portals to <body>: position: fixed and its
+// rect are inline (like Tour's spotlight), sized to the child's visible rect.
+// Nothing on the child changes — its own shadow/outline/tone stripe stay.
+// The ring is an outline outside the box; the waves (mixin pseudo-elements)
+// grow outward from the edge. Being fixed on <body>, nothing clips either.
+.overlay {
+  z-index: var(--highlight-z);
+  pointer-events: none;
+  border-radius: var(--highlight-radius);
+  outline: var(--highlight-ring-width) solid var(--highlight-color);
+  outline-offset: 0;
+
+  @include attention-waves(
+    var(--highlight-color),
+    var(--highlight-wave-duration),
+    var(--highlight-wave-delay),
+    var(--highlight-wave-reach),
+    var(--highlight-wave-edge),
+    var(--highlight-wave-glow),
+    var(--highlight-radius)
+  );
+}
+
+.overlay[data-in-overlay] {
+  z-index: var(--z-overlay-floating);
+}
+
+// Transition only on the fade-out, so entry appears at once.
+.overlay[data-stage='fading'] {
+  opacity: var(--opacity-hidden);
+  transition: opacity var(--highlight-fade);
+}
+
+// Waves are hidden by the mixin; the ring stays static and drops at once
+// (onDone fires straight after `duration`, no fading stage).
+@media (prefers-reduced-motion: reduce) {
+  .overlay[data-stage='fading'] {
+    transition: none;
+  }
+}