Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat: XDSOverlay — scrim + media theme overlay with CSS-first hover and touch support (#1912)

Cindy Zhang284dc38f27d1
diff --git a/apps/storybook/stories/Overlay.stories.tsx b/apps/storybook/stories/Overlay.stories.tsx
new file mode 100644
index 0000000000..fb5765f5b2
--- /dev/null
+++ b/apps/storybook/stories/Overlay.stories.tsx
@@ -0,0 +1,351 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import React, {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSOverlay, useXDSOverlay} from '@xds/core/Overlay';
+import {XDSAspectRatio} from '@xds/core/AspectRatio';
+import {XDSCard} from '@xds/core/Card';
+import {XDSButton} from '@xds/core/Button';
+import {XDSHeading, XDSText} from '@xds/core/Text';
+import {XDSVStack, XDSLayout, XDSLayoutContent} from '@xds/core/Layout';
+import {XDSSpinner} from '@xds/core/Spinner';
+import {XDSGrid} from '@xds/core/Grid';
+import {
+ colorVars,
+ spacingVars,
+ typographyVars,
+} from '@xds/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ pageWrapper: {
+ backgroundColor: colorVars['--color-background-body'],
+ padding: spacingVars['--spacing-6'],
+ },
+ image: {
+ objectFit: 'cover',
+ width: '100%',
+ height: '100%',
+ display: 'block',
+ },
+ dropZone: {
+ minHeight: 200,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ borderWidth: 2,
+ borderStyle: 'dashed',
+ borderColor: colorVars['--color-border'],
+ borderRadius: 8,
+ padding: spacingVars['--spacing-4'],
+ },
+ dropZoneText: {
+ fontFamily: typographyVars['--font-family-body'],
+ color: colorVars['--color-text-secondary'],
+ },
+ durationBadge: {
+ paddingBlock: 2,
+ paddingInline: 8,
+ borderRadius: 4,
+ backgroundColor: colorVars['--color-overlay'],
+ fontSize: 12,
+ fontWeight: 600,
+ },
+ imageSection: {
+ position: 'relative',
+ },
+ metadata: {
+ padding: 16,
+ },
+});
+
+const SAMPLE_IMAGE = 'https://picsum.photos/seed/xds-overlay/800/450';
+const SAMPLE_IMAGE_2 = 'https://picsum.photos/seed/xds-overlay-2/800/450';
+const SAMPLE_IMAGE_3 = 'https://picsum.photos/seed/xds-overlay-3/800/450';
+const SAMPLE_HERO = 'https://picsum.photos/seed/xds-hero/1200/600';
+
+const meta: Meta<typeof XDSOverlay> = {
+ title: 'Core/Overlay',
+ component: XDSOverlay,
+ tags: ['autodocs'],
+ decorators: [
+ Story => (
+ <div {...stylex.props(styles.pageWrapper)}>
+ <Story />
+ </div>
+ ),
+ ],
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSOverlay>;
+
+/** Basic hover overlay on an image. */
+export const HoverOnImage: Story = {
+ render: () => (
+ <div style={{width: 400}}>
+ <XDSOverlay
+ showOn="hover"
+ align="center"
+ content={<XDSButton label="Quick view" variant="ghost" />}>
+ <XDSAspectRatio ratio={16 / 9}>
+ <img
+ src={SAMPLE_IMAGE}
+ alt="Product"
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ </div>
+ ),
+};
+
+/** Always-visible bottom strip with title over a hero image. */
+export const BottomStrip: Story = {
+ render: () => (
+ <div style={{width: 600}}>
+ <XDSOverlay
+ position="bottom"
+ align="start"
+ content={
+ <XDSVStack gap={1}>
+ <XDSHeading level={3}>Gallery Collection</XDSHeading>
+ <XDSText type="supporting" color="secondary">
+ 24 items · Updated today
+ </XDSText>
+ </XDSVStack>
+ }>
+ <XDSAspectRatio ratio={2}>
+ <img src={SAMPLE_HERO} alt="Hero" {...stylex.props(styles.image)} />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ </div>
+ ),
+};
+
+/** Full overlay wrapping a Card. */
+export const CardOverlay: Story = {
+ render: () => (
+ <XDSOverlay
+ showOn="hover"
+ align="center"
+ content={<XDSButton label="View Details" variant="ghost" />}>
+ <XDSCard width={360}>
+ <XDSLayout
+ content={
+ <XDSLayoutContent>
+ <XDSVStack gap={2}>
+ <XDSHeading level={3}>Project Alpha</XDSHeading>
+ <XDSText>
+ A comprehensive design system for building internal tools with
+ consistent, accessible interfaces.
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Updated 2 hours ago · 12 contributors
+ </XDSText>
+ </XDSVStack>
+ </XDSLayoutContent>
+ }
+ />
+ </XDSCard>
+ </XDSOverlay>
+ ),
+};
+
+/** Hover + focus — also appears on keyboard focus. */
+export const HoverOrFocus: Story = {
+ render: () => (
+ <div style={{width: 400}}>
+ <XDSOverlay
+ showOn="hover-or-focus"
+ align="center"
+ content={<XDSButton label="Edit" variant="ghost" />}>
+ <XDSAspectRatio ratio={16 / 9}>
+ <img
+ src={SAMPLE_IMAGE_2}
+ alt="Photo"
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ </div>
+ ),
+};
+
+/** Light scrim for loading/upload states. */
+export const LoadingOverlay: Story = {
+ render: function LoadingOverlayStory() {
+ const [isUploading, setIsUploading] = useState(false);
+ return (
+ <XDSVStack gap={4} style={{width: 300}}>
+ <XDSButton
+ label={isUploading ? 'Cancel upload' : 'Simulate upload'}
+ onClick={() => setIsUploading(v => !v)}
+ />
+ <XDSOverlay
+ isOpen={isUploading}
+ scrim="light"
+ align="center"
+ content={
+ <XDSVStack gap={2} hAlign="center">
+ <XDSSpinner size="md" />
+ <XDSText weight="bold">Uploading...</XDSText>
+ </XDSVStack>
+ }>
+ <XDSAspectRatio ratio={1}>
+ <img
+ src={SAMPLE_IMAGE_3}
+ alt="Upload"
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ </XDSVStack>
+ );
+ },
+};
+
+/** Gallery grid — each image has its own hover overlay. */
+export const GalleryGrid: Story = {
+ render: () => {
+ const images = [
+ {src: 'https://picsum.photos/seed/g1/400/400', title: 'Mountain Lake'},
+ {src: 'https://picsum.photos/seed/g2/400/400', title: 'Forest Path'},
+ {src: 'https://picsum.photos/seed/g3/400/400', title: 'Ocean Sunset'},
+ {src: 'https://picsum.photos/seed/g4/400/400', title: 'City Skyline'},
+ {src: 'https://picsum.photos/seed/g5/400/400', title: 'Desert Dunes'},
+ {src: 'https://picsum.photos/seed/g6/400/400', title: 'Snowy Peaks'},
+ ];
+ return (
+ <XDSGrid columns={3} gap={4}>
+ {images.map(img => (
+ <XDSOverlay
+ key={img.title}
+ showOn="hover"
+ position="bottom"
+ align="start"
+ content={<XDSText weight="bold">{img.title}</XDSText>}>
+ <XDSAspectRatio ratio={1}>
+ <img
+ src={img.src}
+ alt={img.title}
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ ))}
+ </XDSGrid>
+ );
+ },
+};
+
+/** Video thumbnail with duration badge (always visible) + hover play overlay. */
+export const VideoThumbnail: Story = {
+ render: () => (
+ <div style={{width: 400}}>
+ <XDSOverlay
+ showOn="hover"
+ align="center"
+ content={
+ <XDSVStack gap={2} hAlign="center">
+ <XDSText weight="bold" size="lg">
+ ▶
+ </XDSText>
+ <XDSText weight="bold">Introduction to XDS</XDSText>
+ </XDSVStack>
+ }>
+ <XDSAspectRatio ratio={16 / 9}>
+ <img src={SAMPLE_IMAGE} alt="Video" {...stylex.props(styles.image)} />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ </div>
+ ),
+};
+
+/** Disconnected hover — useXDSOverlay hook on Card. Hover Card reveals overlay on image. */
+export const DisconnectedHover: Story = {
+ render: function DisconnectedHoverStory() {
+ const overlay = useXDSOverlay({
+ showOn: 'hover',
+ position: 'bottom',
+ align: 'start',
+ content: <XDSHeading level={4}>Featured Article</XDSHeading>,
+ });
+
+ return (
+ <XDSCard
+ width={360}
+ ref={overlay.containerRef as React.RefObject<HTMLDivElement>}
+ {...overlay.containerProps}>
+ <div {...stylex.props(styles.imageSection)}>
+ <XDSAspectRatio ratio={16 / 9}>
+ <img
+ src={SAMPLE_IMAGE_2}
+ alt="Article"
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ {overlay.element}
+ </div>
+ <XDSVStack gap={1} xstyle={styles.metadata}>
+ <XDSText type="supporting" color="secondary">
+ Jan 15, 2026 · 5 min read
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ By Jane Author
+ </XDSText>
+ </XDSVStack>
+ </XDSCard>
+ );
+ },
+};
+
+/** Drag-and-drop overlay — simulated with a toggle button. */
+export const DragAndDrop: Story = {
+ render: function DragAndDropStory() {
+ const [isDragOver, setIsDragOver] = useState(false);
+ return (
+ <XDSVStack gap={4} style={{width: 400}}>
+ <XDSButton
+ label={isDragOver ? 'Simulate drag leave' : 'Simulate drag enter'}
+ variant="secondary"
+ onClick={() => setIsDragOver(v => !v)}
+ />
+ <XDSOverlay
+ isOpen={isDragOver}
+ align="center"
+ content={
+ <XDSVStack gap={2} hAlign="center">
+ <XDSText size="lg">📁</XDSText>
+ <XDSText weight="bold">Drop files here</XDSText>
+ </XDSVStack>
+ }>
+ <div {...stylex.props(styles.dropZone)}>
+ <p {...stylex.props(styles.dropZoneText)}>
+ Drop files here or click to browse
+ </p>
+ </div>
+ </XDSOverlay>
+ </XDSVStack>
+ );
+ },
+};
+
+/** No scrim — content-only overlay without a background. */
+export const NoScrim: Story = {
+ render: () => (
+ <div style={{width: 300}}>
+ <XDSOverlay
+ showOn="hover"
+ scrim={false}
+ align="center"
+ content={<XDSButton label="♡" variant="ghost" />}>
+ <XDSAspectRatio ratio={1}>
+ <img
+ src={SAMPLE_IMAGE_3}
+ alt="Selected"
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ </div>
+ ),
+};
diff --git a/packages/core/package.json b/packages/core/package.json
index 97facac3fa..2e5c84184d 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -330,6 +330,12 @@
"import": "./dist/OverflowList/index.mjs",
"require": "./dist/OverflowList/index.js"
},
+ "./Overlay": {
+ "source": "./src/Overlay/index.ts",
+ "types": "./dist/Overlay/index.d.ts",
+ "import": "./dist/Overlay/index.mjs",
+ "require": "./dist/Overlay/index.js"
+ },
"./Pagination": {
"source": "./src/Pagination/index.ts",
"types": "./dist/Pagination/index.d.ts",
diff --git a/packages/core/src/Overlay/OverlayScrim.tsx b/packages/core/src/Overlay/OverlayScrim.tsx
new file mode 100644
index 0000000000..c070e402b3
--- /dev/null
+++ b/packages/core/src/Overlay/OverlayScrim.tsx
@@ -0,0 +1,283 @@
+'use client';
+
+/**
+ * @file OverlayScrim.tsx
+ * @input Scrim props (mode, position, align, visibility)
+ * @output Renders the scrim div with background, media theme, transitions
+ * @position Internal rendering primitive; used by XDSOverlay and useXDSOverlay
+ *
+ * Not exported directly — consumers use XDSOverlay (component) or
+ * useXDSOverlay (hook), both of which render this internally.
+ */
+
+import {type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ durationVars,
+ easeVars,
+ spacingVars,
+} from '../theme/tokens.stylex';
+import {XDSMediaTheme} from '../theme/XDSMediaTheme';
+import {xdsClassName, mergeProps} from '../utils';
+import {overlayScope} from './overlay.markers.stylex';
+
+// =============================================================================
+// Types (re-exported from index.ts for consumers)
+// =============================================================================
+
+export type OverlayScrimMode = 'dark' | 'light' | false;
+export type OverlayPosition = 'fill' | 'bottom' | 'top';
+export type OverlayAlign = 'start' | 'center' | 'end';
+export type OverlayShowOn = 'hover' | 'always' | 'focus' | 'hover-or-focus';
+
+export interface OverlayScrimProps {
+ scrim: OverlayScrimMode;
+ position: OverlayPosition;
+ align: OverlayAlign;
+ showOn: OverlayShowOn;
+ isOpen: boolean | undefined;
+ children: ReactNode;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ base: {
+ position: 'absolute',
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-2'],
+ padding: spacingVars['--spacing-3'],
+ pointerEvents: 'none',
+ transitionProperty: 'opacity, visibility, transform',
+ transitionDuration: {
+ default: durationVars['--duration-fast'],
+ '@media (prefers-reduced-motion: reduce)': '0s',
+ },
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+
+ // Position variants
+ fill: {inset: 0},
+ bottom: {insetInline: 0, bottom: 0},
+ top: {insetInline: 0, top: 0},
+
+ // Alignment
+ alignStart: {alignItems: 'flex-start', justifyContent: 'flex-start'},
+ alignCenter: {alignItems: 'center', justifyContent: 'center'},
+ alignEnd: {alignItems: 'flex-end', justifyContent: 'flex-start'},
+
+ // Scrim backgrounds
+ scrimDark: {backgroundColor: colorVars['--color-overlay']},
+ // TODO: Replace with --color-overlay-light token when added
+ scrimLight: {backgroundColor: 'color-mix(in srgb, white 60%, transparent)'},
+
+ // Hidden: strips slide out, fill fades
+ hidden: {opacity: 0, visibility: 'hidden'},
+ hiddenBottom: {transform: 'translateY(100%)'},
+ hiddenTop: {transform: 'translateY(-100%)'},
+
+ // Visible
+ visible: {
+ opacity: 1,
+ visibility: 'visible',
+ pointerEvents: 'auto',
+ transform: 'translateY(0)',
+ '@starting-style': {
+ opacity: 0,
+ },
+ },
+
+ // @starting-style for strips: slide in on mount
+ visibleFromBottom: {
+ '@starting-style': {
+ opacity: 0,
+ transform: 'translateY(100%)',
+ },
+ },
+ visibleFromTop: {
+ '@starting-style': {
+ opacity: 0,
+ transform: 'translateY(-100%)',
+ },
+ },
+
+ // CSS-driven: ancestor hover + focus (accessible default)
+ hoverReveal: {
+ opacity: {
+ default: 0,
+ [stylex.when.ancestor(':hover', overlayScope)]: {
+ '@media (hover: hover)': 1,
+ },
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 1,
+ },
+ visibility: {
+ default: 'hidden',
+ [stylex.when.ancestor(':hover', overlayScope)]: {
+ '@media (hover: hover)': 'visible',
+ },
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'visible',
+ },
+ pointerEvents: {
+ default: 'none',
+ [stylex.when.ancestor(':hover', overlayScope)]: {
+ '@media (hover: hover)': 'auto',
+ },
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'auto',
+ },
+ },
+
+ // Slide transform for strip hover reveal
+ hoverRevealBottom: {
+ transform: {
+ default: 'translateY(100%)',
+ [stylex.when.ancestor(':hover', overlayScope)]: {
+ '@media (hover: hover)': 'translateY(0)',
+ },
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'translateY(0)',
+ },
+ },
+ hoverRevealTop: {
+ transform: {
+ default: 'translateY(-100%)',
+ [stylex.when.ancestor(':hover', overlayScope)]: {
+ '@media (hover: hover)': 'translateY(0)',
+ },
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'translateY(0)',
+ },
+ },
+
+ // CSS-driven: focus-within only
+ focusReveal: {
+ opacity: {
+ default: 0,
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 1,
+ },
+ visibility: {
+ default: 'hidden',
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'visible',
+ },
+ pointerEvents: {
+ default: 'none',
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'auto',
+ },
+ },
+
+ focusRevealBottom: {
+ transform: {
+ default: 'translateY(100%)',
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'translateY(0)',
+ },
+ },
+ focusRevealTop: {
+ transform: {
+ default: 'translateY(-100%)',
+ [stylex.when.ancestor(':focus-within', overlayScope)]: 'translateY(0)',
+ },
+ },
+});
+
+const alignMap = {
+ start: styles.alignStart,
+ center: styles.alignCenter,
+ end: styles.alignEnd,
+} as const;
+
+const positionMap = {
+ fill: styles.fill,
+ bottom: styles.bottom,
+ top: styles.top,
+} as const;
+
+// =============================================================================
+// Component (internal)
+// =============================================================================
+
+export function OverlayScrim({
+ scrim,
+ position,
+ align,
+ showOn,
+ isOpen,
+ children,
+}: OverlayScrimProps) {
+ const isHoverMode = showOn === 'hover' || showOn === 'hover-or-focus';
+ const isStrip = position === 'bottom' || position === 'top';
+ const isControlled = isOpen !== undefined;
+
+ const themeMode =
+ scrim === 'dark' ? 'dark' : scrim === 'light' ? 'light' : null;
+
+ const content = themeMode ? (
+ <XDSMediaTheme mode={themeMode}>{children}</XDSMediaTheme>
+ ) : (
+ children
+ );
+
+ return (
+ <div
+ {...mergeProps(
+ xdsClassName('overlay-scrim', {position}),
+ stylex.props(
+ styles.base,
+ positionMap[position],
+ alignMap[align],
+ scrim === 'dark' && styles.scrimDark,
+ scrim === 'light' && styles.scrimLight,
+
+ // JS-controlled visibility
+ isControlled && isOpen && styles.visible,
+ isControlled &&
+ isOpen &&
+ position === 'bottom' &&
+ styles.visibleFromBottom,
+ isControlled && isOpen && position === 'top' && styles.visibleFromTop,
+ isControlled && !isOpen && styles.hidden,
+ isControlled &&
+ !isOpen &&
+ position === 'bottom' &&
+ styles.hiddenBottom,
+ isControlled && !isOpen && position === 'top' && styles.hiddenTop,
+
+ // showOn="always"
+ !isControlled && showOn === 'always' && styles.visible,
+ !isControlled &&
+ showOn === 'always' &&
+ position === 'bottom' &&
+ styles.visibleFromBottom,
+ !isControlled &&
+ showOn === 'always' &&
+ position === 'top' &&
+ styles.visibleFromTop,
+
+ // showOn="hover" / "hover-or-focus"
+ !isControlled && isHoverMode && styles.hoverReveal,
+ !isControlled &&
+ isHoverMode &&
+ position === 'bottom' &&
+ styles.hoverRevealBottom,
+ !isControlled &&
+ isHoverMode &&
+ position === 'top' &&
+ styles.hoverRevealTop,
+
+ // showOn="focus"
+ !isControlled && showOn === 'focus' && styles.focusReveal,
+ !isControlled &&
+ showOn === 'focus' &&
+ position === 'bottom' &&
+ styles.focusRevealBottom,
+ !isControlled &&
+ showOn === 'focus' &&
+ position === 'top' &&
+ styles.focusRevealTop,
+ ),
+ )}
+ inert={isControlled && !isOpen ? true : undefined}>
+ {content}
+ </div>
+ );
+}
diff --git a/packages/core/src/Overlay/XDSOverlay.tsx b/packages/core/src/Overlay/XDSOverlay.tsx
new file mode 100644
index 0000000000..ee8058bc56
--- /dev/null
+++ b/packages/core/src/Overlay/XDSOverlay.tsx
@@ -0,0 +1,134 @@
+'use client';
+
+/**
+ * @file XDSOverlay.tsx
+ * @input Uses React, useXDSOverlay
+ * @output Exports XDSOverlay component
+ * @position Overlay system component; thin wrapper over useXDSOverlay
+ *
+ * Wraps content with an overlay scrim. Same pattern as XDSTooltip:
+ * `children` is the base content, `content` is what appears on top.
+ *
+ * For applying overlay behavior to an existing container (XDSCard),
+ * use the useXDSOverlay hook directly.
+ */
+
+import {type ReactNode, type Ref} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {xdsClassName, mergeProps} from '../utils';
+import {useXDSOverlay} from './useXDSOverlay';
+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {overlayScope, overlayContainerStyles} from './overlay.markers.stylex';
+import type {
+ OverlayScrimMode,
+ OverlayPosition,
+ OverlayAlign,
+ OverlayShowOn,
+} from './OverlayScrim';
+
+export interface XDSOverlayProps {
+ /** Ref forwarded to the container element. */
+ ref?: Ref<HTMLDivElement>;
+ /** Base content (image, card, video, etc.). */
+ children?: ReactNode;
+ /** Content rendered inside the overlay scrim. */
+ content: ReactNode;
+ /** @default "always" */
+ showOn?: OverlayShowOn;
+ /** JS-controlled visibility override. */
+ isOpen?: boolean;
+ /** @default "dark" */
+ scrim?: OverlayScrimMode;
+ /** @default "fill" */
+ position?: OverlayPosition;
+ /** @default "end" */
+ align?: OverlayAlign;
+ /** StyleX style overrides on the container. */
+ xstyle?: StyleXStyles;
+ /** CSS class name(s) appended to the root element. */
+ className?: string;
+ /** Inline styles. */
+ style?: React.CSSProperties;
+}
+
+/**
+ * Overlay — renders content on top of media with a scrim background
+ * and automatic theme inversion.
+ *
+ * `children` = base content, `content` = what appears on top.
+ *
+ * @compositionHint Wrap images, video, or media content.
+ *
+ * @example
+ * ```
+ * <XDSOverlay
+ * showOn="hover"
+ * content={<XDSButton label="Quick view" variant="ghost" />}
+ * >
+ * <XDSAspectRatio ratio={16/9}>
+ * <img src="hero.jpg" style={{objectFit: 'cover', width: '100%', height: '100%'}} />
+ * </XDSAspectRatio>
+ * </XDSOverlay>
+ * ```
+ */
+export function XDSOverlay({
+ children,
+ content,
+ showOn,
+ isOpen,
+ scrim,
+ position,
+ align,
+ xstyle,
+ className,
+ style,
+ ref,
+}: XDSOverlayProps) {
+ const overlay = useXDSOverlay({
+ content,
+ showOn,
+ isOpen,
+ scrim,
+ position,
+ align,
+ });
+
+ // Border radius: mirror first child's radius onto the wrapper.
+ // Only the component needs this — hook consumers have their own radius.
+ useIsomorphicLayoutEffect(() => {
+ const el = overlay.containerRef.current;
+ if (!el) return;
+ const firstChild = el.firstElementChild as HTMLElement | null;
+ if (!firstChild) return;
+ const radius = getComputedStyle(firstChild).borderRadius;
+ if (radius && radius !== '0px') {
+ el.style.borderRadius = radius;
+ }
+ }, []);
+
+ return (
+ <div
+ ref={(node: HTMLDivElement | null) => {
+ (
+ overlay.containerRef as React.MutableRefObject<HTMLElement | null>
+ ).current = node;
+ if (typeof ref === 'function') ref(node);
+ else if (ref != null)
+ (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
+ }}
+ {...mergeProps(
+ xdsClassName('overlay'),
+ stylex.props(overlayScope, overlayContainerStyles.root, xstyle),
+ className,
+ style,
+ )}
+ onClick={overlay.containerProps.onClick}
+ onMouseUp={overlay.containerProps.onMouseUp}>
+ {children}
+ {overlay.element}
+ </div>
+ );
+}
+
+XDSOverlay.displayName = 'XDSOverlay';
diff --git a/packages/core/src/Overlay/index.ts b/packages/core/src/Overlay/index.ts
new file mode 100644
index 0000000000..d0b3928425
--- /dev/null
+++ b/packages/core/src/Overlay/index.ts
@@ -0,0 +1,17 @@
+/**
+ * @file index.ts
+ * @position Overlay barrel export
+ */
+
+export {XDSOverlay} from './XDSOverlay';
+export type {XDSOverlayProps} from './XDSOverlay';
+
+export {useXDSOverlay} from './useXDSOverlay';
+export type {UseXDSOverlayOptions, UseXDSOverlayResult} from './useXDSOverlay';
+
+export type {
+ OverlayScrimMode,
+ OverlayPosition,
+ OverlayAlign,
+ OverlayShowOn,
+} from './OverlayScrim';
diff --git a/packages/core/src/Overlay/overlay.markers.stylex.ts b/packages/core/src/Overlay/overlay.markers.stylex.ts
new file mode 100644
index 0000000000..d827edbcc4
--- /dev/null
+++ b/packages/core/src/Overlay/overlay.markers.stylex.ts
@@ -0,0 +1,24 @@
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Scoped marker for Overlay ancestor hover selectors.
+ * When applied to a container, enables XDSOverlayScrim's
+ * CSS-driven showOn="hover" / "focus" / "hover-or-focus" behavior.
+ */
+export const overlayScope: ReturnType<typeof stylex.defineMarker> =
+ stylex.defineMarker();
+
+/**
+ * Container styles that pair with overlayScope.
+ * Sets position: relative + overflow: clip so the scrim
+ * can use position: absolute + inset: 0 correctly.
+ *
+ * Override individual properties by applying your own styles after:
+ * stylex.props(overlayContainerStyles.root, myStyles.sticky)
+ */
+export const overlayContainerStyles = stylex.create({
+ root: {
+ position: 'relative',
+ overflow: 'clip',
+ },
+});
diff --git a/packages/core/src/Overlay/useXDSOverlay.tsx b/packages/core/src/Overlay/useXDSOverlay.tsx
new file mode 100644
index 0000000000..678a12c1ff
--- /dev/null
+++ b/packages/core/src/Overlay/useXDSOverlay.tsx
@@ -0,0 +1,241 @@
+'use client';
+
+/**
+ * @file useXDSOverlay.tsx
+ * @input Overlay options (showOn, scrim, position, content, etc.)
+ * @output containerRef, containerProps, element, renderOverlay
+ * @position Core hook for overlay system — same pattern as useXDSTooltip
+ *
+ * For applying overlay behavior to an existing container (XDSCard,
+ * custom elements) without a wrapper. Returns props to spread on the
+ * container and the scrim to render inside it.
+ *
+ * Handles: marker, positioning, touch toggle (via useClickableContainer),
+ * and scrim rendering.
+ */
+
+import {
+ type ReactNode,
+ type ReactElement,
+ type MouseEvent,
+ useState,
+ useRef,
+ useCallback,
+ useMemo,
+ useSyncExternalStore,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {useClickableContainer} from '../hooks/useClickableContainer';
+import {overlayScope, overlayContainerStyles} from './overlay.markers.stylex';
+import {OverlayScrim} from './OverlayScrim';
+import type {
+ OverlayScrimMode,
+ OverlayPosition,
+ OverlayAlign,
+ OverlayShowOn,
+} from './OverlayScrim';
+
+// =============================================================================
+// Touch detection
+// =============================================================================
+
+function getIsTouchDevice(): boolean {
+ if (typeof window === 'undefined') return false;
+ return window.matchMedia('(hover: none)').matches;
+}
+
+function subscribeToHoverChange(callback: () => void): () => void {
+ if (typeof window === 'undefined') return () => {};
+ const mql = window.matchMedia('(hover: none)');
+ mql.addEventListener('change', callback);
+ return () => mql.removeEventListener('change', callback);
+}
+
+function getServerSnapshot(): boolean {
+ return false;
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface UseXDSOverlayOptions {
+ /** Content rendered inside the scrim overlay. */
+ content?: ReactNode;
+
+ /**
+ * CSS-driven visibility trigger.
+ * - `"always"` — always visible
+ * - `"hover"` — hover + focus (accessible default). Touch: strip = always visible, fill = tap-to-toggle.
+ * - `"focus"` — focus-within only
+ * - `"hover-or-focus"` — alias for "hover"
+ * @default "always"
+ */
+ showOn?: OverlayShowOn;
+
+ /**
+ * JS-controlled visibility override. Takes precedence over showOn + touch.
+ */
+ isOpen?: boolean;
+
+ /**
+ * Scrim background mode.
+ * @default "dark"
+ */
+ scrim?: OverlayScrimMode;
+
+ /**
+ * Scrim placement.
+ * @default "fill"
+ */
+ position?: OverlayPosition;
+
+ /**
+ * Content alignment.
+ * @default "end"
+ */
+ align?: OverlayAlign;
+}
+
+export interface OverlayContainerProps {
+ /** CSS class names for marker + positioning. */
+ className: string | undefined;
+ /** Inline styles for marker + positioning. */
+ style: React.CSSProperties | undefined;
+ /** Touch tap-to-toggle handler. Only set on touch devices with full overlays. */
+ onClick: ((e: MouseEvent<HTMLElement>) => void) | undefined;
+ /** Touch tap-to-toggle handler. Only set on touch devices with full overlays. */
+ onMouseUp: ((e: MouseEvent<HTMLElement>) => void) | undefined;
+}
+
+export interface UseXDSOverlayResult {
+ /** Ref — attach to the container element. */
+ containerRef: React.RefObject<HTMLElement | null>;
+
+ /** Props to spread on the container element. */
+ containerProps: OverlayContainerProps;
+
+ /**
+ * Pre-rendered scrim element — place inside the container.
+ * Only available when `content` is provided in options.
+ */
+ element: ReactElement | null;
+
+ /**
+ * Render function for the overlay scrim. Use when you want to
+ * control where/when the scrim mounts, or pass dynamic content.
+ * Same pattern as useXDSTooltip's renderTooltip.
+ */
+ renderOverlay: (children: ReactNode) => ReactElement;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Hook for overlay behavior on an existing container.
+ * Returns containerRef, containerProps, and scrim element/render function.
+ *
+ * @example
+ * ```
+ * const overlay = useXDSOverlay({
+ * showOn: 'hover',
+ * content: <XDSButton label="Quick view" variant="ghost" />,
+ * });
+ *
+ * <XDSCard ref={overlay.containerRef} {...overlay.containerProps}>
+ * <XDSLayout content={...} />
+ * {overlay.element}
+ * </XDSCard>
+ * ```
+ *
+ * @example
+ * ```
+ * // Callback mode — render on demand
+ * const overlay = useXDSOverlay({ showOn: 'hover' });
+ *
+ * <div ref={overlay.containerRef} {...overlay.containerProps}>
+ * <img src={src} />
+ * {overlay.renderOverlay(<XDSButton label="Quick view" />)}
+ * </div>
+ * ```
+ */
+export function useXDSOverlay({
+ content,
+ showOn = 'always',
+ isOpen: isOpenProp,
+ scrim = 'dark',
+ position = 'fill',
+ align = 'end',
+}: UseXDSOverlayOptions = {}): UseXDSOverlayResult {
+ const containerRef = useRef<HTMLElement | null>(null);
+
+ const isTouchDevice = useSyncExternalStore(
+ subscribeToHoverChange,
+ getIsTouchDevice,
+ getServerSnapshot,
+ );
+
+ const [touchOpen, setTouchOpen] = useState(false);
+
+ const isHoverMode = showOn === 'hover' || showOn === 'hover-or-focus';
+
+ const needsTouchToggle = isTouchDevice && isHoverMode;
+
+ const handleToggle = useCallback(() => {
+ setTouchOpen(prev => !prev);
+ }, []);
+
+ const {onClick, onMouseUp} = useClickableContainer({
+ containerRef,
+ onClick: needsTouchToggle ? handleToggle : undefined,
+ disabled: !needsTouchToggle,
+ });
+
+ // Resolve isOpen: consumer prop > touch toggle > undefined (CSS)
+ const effectiveIsOpen =
+ isOpenProp !== undefined
+ ? isOpenProp
+ : needsTouchToggle
+ ? touchOpen
+ : undefined;
+
+ // Container styles (marker + positioning)
+ const resolved = stylex.props(overlayScope, overlayContainerStyles.root);
+
+ const containerProps = useMemo<OverlayContainerProps>(
+ () => ({
+ className: resolved.className ?? undefined,
+ style: resolved.style ?? undefined,
+ onClick: needsTouchToggle ? onClick : undefined,
+ onMouseUp: needsTouchToggle ? onMouseUp : undefined,
+ }),
+ [resolved.className, resolved.style, needsTouchToggle, onClick, onMouseUp],
+ );
+
+ // Render function — matches tooltip's renderTooltip pattern
+ const renderOverlay = useCallback(
+ (children: ReactNode): ReactElement => (
+ <OverlayScrim
+ scrim={scrim}
+ position={position}
+ align={align}
+ showOn={showOn}
+ isOpen={effectiveIsOpen}>
+ {children}
+ </OverlayScrim>
+ ),
+ [scrim, position, align, showOn, effectiveIsOpen],
+ );
+
+ // Pre-rendered element when content is provided
+ const element = content != null ? renderOverlay(content) : null;
+
+ return {
+ containerRef,
+ containerProps,
+ element,
+ renderOverlay,
+ };
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 4894e9c43c..9a49bed460 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -138,6 +138,9 @@ export * from './Spinner';
// Timestamp display
export * from './Timestamp';
+// Overlay
+export * from './Overlay';
+
// Overflow list
export * from './OverflowList';