@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/AppLayout/AppLayout.tokens.scss

@@ -0,0 +1,27 @@
+// AppLayout.tokens.scss — Component-scoped tokens for <AppLayout>.
+@use '../_internal/collapse' as bp;
+
+:root {
+  // Padding of the main content region — the canonical shell content gutter, so
+  // a DS-only consumer gets the shell padding with no prop and no raw CSS.
+  // Defaults to --space-6 (matches the playground AppShell's .content gutter).
+  // Override to `0` (or another token) in your scope for a full-bleed main
+  // region — no prop needed.
+  --app-layout-content-padding: var(--space-6);
+
+  // Background of the main content region — a subtle canvas so page Cards lift
+  // off it (matches every playground mockup). Defaults to --color-bg-subtle.
+  // Override to `transparent` in your scope for a flat content area — no prop.
+  --app-layout-content-background: var(--color-bg-subtle);
+}
+
+// Narrow viewports: --space-6 (24px) each side costs a 380px phone 48px of its
+// width. Step the gutter down so content keeps its room. This only moves the
+// DEFAULT: a consumer override in a scope BELOW :root still wins (e.g. a class
+// on their own root element), but an override written as another :root rule is
+// the same (0,1,0) specificity as this one — whichever rule loads last wins.
+@media (max-width: bp.$collapse-md) {
+  :root {
+    --app-layout-content-padding: var(--space-4);
+  }
+}

package/src/components/AppLayout/AppLayout.tsx

@@ -0,0 +1,211 @@
+import { forwardRef, useEffect, useRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n';
+import { useBelowBreakpoint } from '../../hooks/useBelowBreakpoint';
+import type { CollapseBreakpoint } from '../_internal/collapse';
+import { useControllableState } from '../_internal/useControllableState';
+import { Drawer } from '../Drawer';
+import styles from './AppLayout.module.scss';
+
+export interface AppLayoutProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * System-wide banner slot — full WINDOW width, above the sidebar + content
+   * row. For messages that apply wherever the user is: maintenance, billing
+   * overdue, impersonation. Pass a `<Banner>` (or several, most severe first).
+   * Not sticky: it scrolls away with the page while the `topBar` stays pinned.
+   * Omit (or pass `null` / `false`) for no wrapper.
+   *
+   * With `sidebarPinned`, the pinned sidebar starts below this banner, so at
+   * scroll position 0 its bottom (a `Rail.Footer`) sits up to one banner height
+   * below the fold until the page scrolls past the banner. This is accepted —
+   * banners are temporary.
+   */
+  banner?: ReactNode;
+  /**
+   * Context banner slot — inside the content column, between the `topBar` and
+   * the padded content region, full-bleed within the column. For messages
+   * scoped to a module or route ("Email sending suspended" on the Email
+   * pages); the app decides which routes render it. Pass a `<Banner>`. Not
+   * sticky. Page-level messages belong in the content as `<Alert>` instead.
+   */
+  contextBanner?: ReactNode;
+  /**
+   * Top bar slot — sits above the main content, spanning the content column to
+   * the right of the sidebar (not the full window width). Omit for no top bar.
+   */
+  topBar?: ReactNode;
+  /**
+   * Sidebar slot — runs the full height down the left, alongside both the top
+   * bar and the content. Sets its own width (intrinsic). Omit for no sidebar.
+   */
+  sidebar?: ReactNode;
+  /**
+   * Pin the sidebar to the viewport: `position: sticky; top: 0; height: 100dvh`
+   * with internal overflow scrolling. On pages taller than the viewport the
+   * sidebar (and a `Rail` inside it — including its `Rail.Footer` /
+   * CollapseToggle) spans exactly the SCREEN, keeping the footer glued to the
+   * viewport bottom instead of the page bottom. Default `false` (sidebar
+   * stretches to the full row/page height — the original behavior).
+   *
+   * Prefer this over wrapping the sidebar slot in `Sticky` — the rail pins its
+   * footer by filling its own `height: 100%` box, which needs a DEFINITE
+   * height to resolve against. `Sticky` sets `align-self: start`, which drops
+   * the row stretch that made it definite, so the footer stops pinning.
+   *
+   * `100dvh` is always relative to the real browser viewport, never to a
+   * nested scroll container — so this only pins correctly when AppLayout is
+   * the actual outermost, page-scroll shell (its documented top-level use).
+   * Nest it inside another scrollable region and the sidebar will size to
+   * the whole window, not that region, and overflow it.
+   */
+  sidebarPinned?: boolean;
+  /**
+   * Move the sidebar out of the flow and into a left-anchored `<Drawer>` while
+   * the **viewport** is at or below a width threshold: `'sm'` 480px / `'md'`
+   * 640px / `'lg'` 768px. Omit for no responsive behavior (the default) — the
+   * sidebar always renders in the flow.
+   *
+   * Below the threshold the content column claims the full viewport width, and
+   * the sidebar is reachable only by opening the drawer. Render your own
+   * trigger (a hamburger in the `topBar`) and drive it with `sidebarOpen` +
+   * `onSidebarOpenChange` — AppLayout deliberately renders no trigger of its
+   * own, since where it belongs in the bar is the consumer's call, which means
+   * both props are effectively required together (see `sidebarOpen`'s doc).
+   * Use the exported `useBelowBreakpoint` hook to show that trigger only while
+   * the overlay mode is active.
+   *
+   * `sidebarPinned` is ignored below the threshold: the drawer owns the
+   * sidebar's box there, and a `sticky; height: 100dvh` wrapper inside it would
+   * size the rail to the window instead of the drawer.
+   *
+   * Measures the viewport (`matchMedia`), not a container — the sidebar's
+   * presence in the row is exactly what the threshold changes, so a container
+   * query would be circular. Same scale and same basis as `<Rail collapseBelow>`.
+   *
+   * The `sidebar` node moves between the in-flow slot and the `Drawer`,
+   * remounting it, so a `Rail`'s internal state (expanded `Rail.Group`s, scroll
+   * position) resets each time, by design. A `<Rail>` in the drawer scrolls its
+   * own body while its footer stays visible; a custom non-`Rail` sidebar needs
+   * its own height-filling scroll container, especially on short viewports
+   * (phone landscape, ~380px).
+   */
+  sidebarOverlayBelow?: CollapseBreakpoint;
+  /**
+   * Open state of the overlay sidebar. Technically optional, but effectively
+   * required together with `onSidebarOpenChange` whenever `sidebarOverlayBelow`
+   * is set — AppLayout renders no trigger of its own (see `sidebarOverlayBelow`),
+   * so with both omitted nothing can ever open the drawer; Esc/backdrop close it,
+   * but there's no way in. Has no effect unless `sidebarOverlayBelow` is set and
+   * the viewport is below it.
+   */
+  sidebarOpen?: boolean;
+  /** Fires whenever the overlay sidebar opens or closes — close button, Esc, backdrop click, swipe, or programmatic. Pair with `sidebarOpen` — see its doc. */
+  onSidebarOpenChange?: (open: boolean) => void;
+  /**
+   * Render the content region as a `<main>` landmark instead of a plain `<div>`.
+   * Pass it on the outermost app shell so the page gets its single `main`
+   * landmark without a wrapper element. Leave it off (default) for nested
+   * use — demos, documentation previews — so the page never gets two `main`s.
+   */
+  mainLandmark?: boolean;
+  /** Main content slot — fills the remaining space below the top bar. */
+  children: ReactNode;
+}
+
+/**
+ * Viewport-filling application shell layout: full-height `sidebar`, optional `topBar` over the content column, main `children` below.
+ * @see docs/components/AppLayout.md
+ */
+export const AppLayout = forwardRef<HTMLDivElement, AppLayoutProps>(function AppLayout(
+  {
+    banner,
+    contextBanner,
+    topBar,
+    sidebar,
+    sidebarPinned,
+    sidebarOverlayBelow,
+    mainLandmark,
+    sidebarOpen,
+    onSidebarOpenChange,
+    children,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const Main = mainLandmark ? 'main' : 'div';
+  const overlay = useBelowBreakpoint(sidebarOverlayBelow) && sidebar != null;
+  // Whether the Drawer should exist AT ALL, independent of the live viewport
+  // threshold. Kept mounted across the crossing (see below) rather than
+  // gated on `overlay` — that's what lets a still-mounted DrawerRoot receive
+  // a real open:true→false PROP transition on the up-crossing instead of
+  // being yanked from the tree mid-open.
+  const overlayConfigured = sidebarOverlayBelow != null && sidebar != null;
+
+  // Uncontrolled fallback so Esc / backdrop still close the drawer when the
+  // consumer passes `sidebarOverlayBelow` without wiring open state.
+  const [open, setOpen] = useControllableState<boolean>({
+    value: sidebarOpen,
+    defaultValue: false,
+    onChange: onSidebarOpenChange,
+  });
+
+  // Crossing back above the threshold must CLOSE the drawer via a real prop
+  // transition, not unmount it out from under an open dialog — DrawerRoot's
+  // own focus-restore effect only fires on open:true→false while mounted, so
+  // Drawer stays mounted (above) and gets `open={overlay && open}`, which
+  // flips synchronously in the same render as the crossing. That alone still
+  // leaves `open` state remembering `true`, so re-entering overlay mode later
+  // would reopen it unprompted — this effect resets the state on the
+  // overlay:true→false EDGE only (a ref, not `!overlay`), so it never fights
+  // a controlled consumer legitimately setting `sidebarOpen` while already
+  // above the threshold.
+  const wasOverlay = useRef(overlay);
+  useEffect(() => {
+    // `&& open` — otherwise every up-crossing fires onSidebarOpenChange(false)
+    // even when the drawer was never opened (setOpen is a no-op value-wise,
+    // but the callback still fires on a resize the consumer didn't ask about).
+    if (wasOverlay.current && !overlay && open) setOpen(false);
+    wasOverlay.current = overlay;
+  }, [overlay, open, setOpen]);
+
+  // Pattern A — props last: AppLayout is a consumer-overridable layout
+  // primitive (like Stack/Card), so {...props} wins over our defaults.
+  // Topology: banner above a row of [full-height sidebar | column of (topBar,
+  // contextBanner, main)] — so
+  // the sidebar spans the whole height and the top bar sits only over the
+  // content column, matching the CRM shell (see playground AppShell).
+  return (
+    <div ref={ref} className={clsx(styles.root, className)} {...props}>
+      {banner != null && banner !== false && <div className={styles.banner}>{banner}</div>}
+      <div className={styles.row}>
+        {sidebar != null && !overlay && (
+          <div className={clsx(styles.sidebar, sidebarPinned && styles.sidebarPinned)}>
+            {sidebar}
+          </div>
+        )}
+        <div className={styles.body}>
+          {topBar != null && <div className={styles.topBar}>{topBar}</div>}
+          {contextBanner != null && contextBanner !== false && (
+            <div className={styles.contextBanner}>{contextBanner}</div>
+          )}
+          <Main className={styles.main}>{children}</Main>
+        </div>
+      </div>
+      {overlayConfigured && (
+        <Drawer
+          open={overlay && open}
+          onOpenChange={setOpen}
+          side="left"
+          size="sm"
+          className={styles.overlaySidebar}
+          aria-label={t('appLayout.sidebar')}
+        >
+          <Drawer.Header>{t('appLayout.sidebar')}</Drawer.Header>
+          <div className={styles.overlaySidebarContent}>{sidebar}</div>
+        </Drawer>
+      )}
+    </div>
+  );
+});

package/src/components/AppLayout/index.ts

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

package/src/components/Avatar/AgentAvatar.module.scss

@@ -0,0 +1,117 @@
+@use './Avatar.tokens';
+
+// Root carries the Avatar size class (diameter); position:relative anchors the
+// .badge (Rule 4 escape hatch for an internal child, same as Avatar's .presence).
+.agent {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border-radius: var(--avatar-radius);
+  user-select: none;
+}
+
+// The circular tile; clips the mark (incl. non-SVG marks) to the circle. The
+// badge is the tile's sibling, not a descendant, so this clip never reaches it.
+.tile {
+  display: flex;
+  overflow: hidden;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--agent-avatar-bg);
+  color: var(--agent-avatar-fg);
+}
+
+.mark {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.mark svg {
+  width: 100%;
+  height: 100%;
+}
+
+.inline .mark {
+  width: var(--agent-avatar-mark-size-inline);
+  height: var(--agent-avatar-mark-size-inline);
+}
+
+.sm .mark {
+  width: var(--agent-avatar-mark-size-sm);
+  height: var(--agent-avatar-mark-size-sm);
+}
+
+.md .mark {
+  width: var(--agent-avatar-mark-size-md);
+  height: var(--agent-avatar-mark-size-md);
+}
+
+.lg .mark {
+  width: var(--agent-avatar-mark-size-lg);
+  height: var(--agent-avatar-mark-size-lg);
+}
+
+.xl .mark {
+  width: var(--agent-avatar-mark-size-xl);
+  height: var(--agent-avatar-mark-size-xl);
+}
+
+// Member badge, bottom-right, with a surface ring. The inner <Avatar> keeps
+// its own size class, so force it to fill the sized badge box.
+.badge {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  border-radius: var(--avatar-radius);
+  box-shadow: 0 0 0 var(--agent-avatar-badge-ring-width) var(--agent-avatar-badge-ring-color);
+  font-size: var(--agent-avatar-badge-font-size);
+}
+
+.badge > span {
+  width: 100%;
+  height: 100%;
+  font-size: inherit;
+}
+
+.erased {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--agent-avatar-bg);
+  color: var(--agent-avatar-fg);
+}
+
+.erased svg {
+  width: 70%;
+  height: 70%;
+}
+
+.sm .badge {
+  width: var(--agent-avatar-badge-size-sm);
+  height: var(--agent-avatar-badge-size-sm);
+}
+
+.md .badge {
+  width: var(--agent-avatar-badge-size-md);
+  height: var(--agent-avatar-badge-size-md);
+}
+
+.lg .badge {
+  width: var(--agent-avatar-badge-size-lg);
+  height: var(--agent-avatar-badge-size-lg);
+}
+
+.xl .badge {
+  width: var(--agent-avatar-badge-size-xl);
+  height: var(--agent-avatar-badge-size-xl);
+}

package/src/components/Avatar/AgentAvatar.tsx

@@ -0,0 +1,122 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { Bot, User } from 'lucide-react';
+import { useTranslation } from '../../i18n';
+import { Avatar, type AvatarSize } from './Avatar';
+import avatarStyles from './Avatar.module.scss';
+import styles from './AgentAvatar.module.scss';
+
+/** The member an agent acts for, shown as a badge on the tile. */
+export interface AgentAvatarMember {
+  /** Member's full name; drives the badge initials and the accessible name. */
+  name: string;
+  /** Member's photo URL; initials are shown when omitted or it fails to load. */
+  src?: string;
+}
+
+export interface AgentAvatarProps extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * Agent label; drives the accessible name (an empty label reads as "?",
+   * like `Avatar`). Unused when `decorative`.
+   */
+  name: string;
+  /** Agent mark, inherits `currentColor` (a neutral foreground), so pass a glyph drawn with `fill`/`stroke="currentColor"`; marks with hard-coded fills keep their colours (the app's responsibility). Defaults to a lucide `Bot`. */
+  mark?: ReactNode;
+  /**
+   * The member the agent acts for. Omit for an agent alone (no badge); `null`
+   * or an empty name for an erased member (placeholder badge).
+   */
+  member?: AgentAvatarMember | null;
+  /** Diameter, same scale as `Avatar`. The member badge is hidden at `inline`. */
+  size?: AvatarSize;
+  /**
+   * Hide the avatar from assistive tech (`aria-hidden`, no role or label). Use
+   * when visible text next to it already names the agent and the member, e.g.
+   * a Thread node beside a "Scout for Sarah Chen" byline; otherwise both are
+   * announced. Without such text keep the default: a `role="img"` named
+   * "{agent}, on behalf of {member}". `PersonDisplay.AgentAvatar` always sets
+   * it. Defaults to `false`.
+   */
+  decorative?: boolean;
+}
+
+const sizeClass: Record<AvatarSize, string> = {
+  inline: styles.inline,
+  sm: styles.sm,
+  md: styles.md,
+  lg: styles.lg,
+  xl: styles.xl,
+};
+
+const avatarSizeClass: Record<AvatarSize, string> = {
+  inline: avatarStyles.inline,
+  sm: avatarStyles.sm,
+  md: avatarStyles.md,
+  lg: avatarStyles.lg,
+  xl: avatarStyles.xl,
+};
+
+/**
+ * AI agent tile with an optional badge of the member it acts for.
+ * @see docs/components/AgentAvatar.md
+ */
+export const AgentAvatar = forwardRef<HTMLSpanElement, AgentAvatarProps>(function AgentAvatar(
+  { name, mark, member, size = 'md', decorative, className, ...props },
+  ref,
+) {
+  const t = useTranslation();
+  const agent = name.trim() === '' ? '?' : name.trim();
+  const memberName = member?.name?.trim() ?? '';
+  const erased = member === null || (member !== undefined && memberName === '');
+
+  const label = erased
+    ? t('avatar.agent.onBehalfOfFormer', { agent })
+    : member
+      ? t('avatar.agent.onBehalfOf', { agent, member: memberName })
+      : agent;
+
+  const badge =
+    size === 'inline' || member === undefined ? null : (
+      <span
+        aria-hidden="true"
+        className={styles.badge}
+        data-part="badge"
+        data-erased={erased || undefined}
+      >
+        {erased ? (
+          <span className={styles.erased}>
+            <User />
+          </span>
+        ) : (
+          <Avatar size="sm" name={memberName} src={member?.src} />
+        )}
+      </span>
+    );
+
+  // {...props} first so component-owned ARIA (role, aria-label) wins. Decorative
+  // strips consumer role/label; otherwise aria-labelledby is dropped so it can't
+  // override the computed aria-label.
+  return (
+    <span
+      {...props}
+      ref={ref}
+      {...(decorative
+        ? {
+            'aria-hidden': true,
+            role: undefined,
+            'aria-label': undefined,
+            'aria-labelledby': undefined,
+          }
+        : { role: 'img', 'aria-label': label, 'aria-labelledby': undefined })}
+      className={clsx(styles.agent, avatarSizeClass[size], sizeClass[size], className)}
+      data-agent-avatar=""
+    >
+      <span className={styles.tile}>
+        <span aria-hidden="true" className={styles.mark} data-part="mark">
+          {mark ?? <Bot />}
+        </span>
+      </span>
+      {badge}
+    </span>
+  );
+});

package/src/components/Avatar/Avatar.module.scss

@@ -0,0 +1,181 @@
+@use './Avatar.tokens';
+
+// Outer wrapper — position:relative anchors the .presence dot (Rule 4 escape
+// hatch for an internal child). No overflow:hidden here — that lives on .crop
+// so the presence dot sibling is never clipped.
+.avatar {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border-radius: var(--avatar-radius);
+  color: var(--avatar-fg);
+  font-weight: var(--avatar-font-weight);
+  text-transform: uppercase;
+  user-select: none;
+}
+
+// Inner crop — clips the image or initials into a circle. Inherits the
+// background color CSS variable set on the outer wrapper.
+.crop {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: inherit;
+  overflow: hidden;
+  background: var(--avatar-bg, var(--avatar-bg-fallback));
+}
+
+.crop img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+// Font-relative (#579): one line of the surrounding text tall. `lh` resolves
+// against THIS element's line-height, so the wrapper must keep the inherited
+// font-size — the initials get their smaller size on .crop instead.
+.inline {
+  width: var(--avatar-size-inline);
+  height: var(--avatar-size-inline);
+
+  // In running text the default baseline is the initials' (or, for a photo,
+  // the box's bottom), which pushes the 1lh box off the line and grows it.
+  // A box exactly one line tall aligned to the line box's top fills it
+  // without growing it. Ignored in flex rows, which centre it.
+  vertical-align: top;
+
+  .crop {
+    font-size: var(--avatar-font-size-inline);
+  }
+}
+
+.sm {
+  width: var(--avatar-size-sm);
+  height: var(--avatar-size-sm);
+  font-size: var(--avatar-font-size-sm);
+}
+
+.md {
+  width: var(--avatar-size-md);
+  height: var(--avatar-size-md);
+  font-size: var(--avatar-font-size-md);
+}
+
+.lg {
+  width: var(--avatar-size-lg);
+  height: var(--avatar-size-lg);
+  font-size: var(--avatar-font-size-lg);
+}
+
+.xl {
+  width: var(--avatar-size-xl);
+  height: var(--avatar-size-xl);
+  font-size: var(--avatar-font-size-xl);
+}
+
+// Presence dot (Avatar status). Anchored to the bottom-right via the
+// parent's position:relative. Carries a 2px ring of --color-bg so the dot
+// stays visible on tinted ancestors.
+.presence {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  border-radius: var(--avatar-presence-radius);
+  box-shadow: 0 0 0 var(--avatar-presence-ring-width) var(--avatar-presence-ring-color);
+
+  // Each status carries a distinct SILHOUETTE as well as a colour (#506).
+  // Colour was the entire channel, and OKLab separation — what the presence
+  // gate in contrast.test.ts measures — is blind to colour-vision deficiency:
+  // light away/busy collapses from 0.158 to roughly 0.015 under simulated
+  // protanopia while that gate passes. No palette choice fixes it, because
+  // `away` has to read as yellow and no amber-or-yellow candidate separates
+  // from `busy`. A second channel is the only lever, so:
+  //   online   filled disc
+  //   away     half disc, the cut edge vertical through the centre
+  //   busy     filled disc with a bar across it
+  //   offline  hollow ring
+  // Filled / half / barred / hollow stay distinguishable at --size-presence-sm,
+  // which is 8px, and none of them depend on hue. Each cut is painted in
+  // --color-bg — the same colour as the ring the dot already carries, so the cut
+  // and the ring read as one continuous hole rather than as a second colour.
+  // That matches the surface exactly only ON --color-bg; on a sunken panel or a
+  // selected row the dot sits on its own slightly-off chip, which the pre-existing
+  // ring did too. The channel does not depend on the match: cut-vs-fill runs
+  // 4.52-11.86:1, so the silhouette survives greyscale and every dichromacy
+  // either way. (The 4.52 is offline, the status this branch re-pointed — an
+  // earlier version of this line said "5-12:1" and excluded the one value the
+  // same commit had just changed.)
+  &[data-status='online'] {
+    background: var(--avatar-presence-bg-online);
+  }
+
+  &[data-status='busy'] {
+    background: var(--avatar-presence-bg-busy);
+  }
+
+  // The bar. `inset` keeps it centred at every dot size without a per-size
+  // rule, and it is painted in the surface colour so it reads as a cut.
+  &[data-status='busy']::after {
+    position: absolute;
+    inset: calc(50% - (var(--avatar-presence-bar-height) / 2)) 20%;
+    background: var(--avatar-presence-glyph-color);
+    content: '';
+  }
+
+  // Half disc. A hard-stop gradient rather than a pseudo-element, so the shape
+  // survives the border-radius clip at any size.
+  &[data-status='away'] {
+    background-image: linear-gradient(
+      to right,
+      var(--avatar-presence-bg-away) 0 50%,
+      var(--avatar-presence-glyph-color) 50% 100%
+    );
+  }
+
+  // Hollow. The inset shadow draws the stroke inside the same circle, so the
+  // outer ring against the avatar is unaffected.
+  &[data-status='offline'] {
+    background: var(--avatar-presence-glyph-color);
+    box-shadow:
+      0 0 0 var(--avatar-presence-ring-width) var(--avatar-presence-ring-color),
+      inset 0 0 0 var(--avatar-presence-hollow-width) var(--avatar-presence-bg-offline);
+  }
+}
+
+// Per-size dot dimensions. The size class lives on the avatar wrapper (the
+// .presence child's parent), so a descendant selector picks the right size.
+.inline .presence {
+  width: var(--avatar-presence-size-inline);
+  height: var(--avatar-presence-size-inline);
+}
+
+.sm .presence {
+  width: var(--avatar-presence-size-sm);
+  height: var(--avatar-presence-size-sm);
+}
+
+.md .presence {
+  width: var(--avatar-presence-size-md);
+  height: var(--avatar-presence-size-md);
+}
+
+.lg .presence {
+  width: var(--avatar-presence-size-lg);
+  height: var(--avatar-presence-size-lg);
+}
+
+.xl .presence {
+  width: var(--avatar-presence-size-xl);
+  height: var(--avatar-presence-size-xl);
+}
+
+// When inside an AvatarGroup, each avatar picks up a --color-bg ring so
+// stacked siblings read as distinct.
+.inGroup {
+  box-shadow: 0 0 0 var(--avatar-in-group-ring-width) var(--avatar-in-group-ring-color);
+}