Skip to content

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

TypeScript

fix(docsite): document Overlay props (#2811)

Cindy Zhanga032bc57f514
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 0c7fb17ae7..3993002c02 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -8,15 +8,87 @@
*/
import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
import {describe, it, expect} from 'vitest';
import {packages} from '../generated/packageRegistry';
-import {components, componentCount} from '../generated/componentRegistry';
+import {
+ components,
+ componentCount,
+ type ComponentEntry,
+} from '../generated/componentRegistry';
import {blocks, blockCount, showcaseCount} from '../generated/blockRegistry';
import {templates, templateCount} from '../generated/templateRegistry';
import {docTopics, docsCount} from '../generated/docsRegistry';
import {showcaseRegistry} from '../generated/showcaseRegistry';
import {exampleRegistry} from '../generated/exampleRegistry';
+const REPO_ROOT = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../../../..',
+);
+const CORE_SRC_DIR = path.join(REPO_ROOT, 'packages/core/src');
+
+function findFiles(dir: string, predicate: (filePath: string) => boolean) {
+ const files: string[] = [];
+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+ const fullPath = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ files.push(...findFiles(fullPath, predicate));
+ } else if (predicate(fullPath)) {
+ files.push(fullPath);
+ }
+ }
+ return files;
+}
+
+function getCoreComponentsWithPublicProps() {
+ const names = new Set<string>();
+ for (const filePath of findFiles(CORE_SRC_DIR, file =>
+ file.endsWith('.tsx'),
+ )) {
+ const source = fs.readFileSync(filePath, 'utf-8');
+ for (const match of source.matchAll(
+ /export\s+(?:interface|type)\s+XDS([A-Z]\w*)Props\b/g,
+ )) {
+ names.add(match[1]);
+ }
+ }
+ return names;
+}
+
+function getComponentDocCompletenessIssues(
+ comp: ComponentEntry,
+ componentsWithPublicProps: Set<string>,
+) {
+ const issues: string[] = [];
+ if (comp.params != null || comp.hidden) {
+ return issues;
+ }
+ if (comp.description.trim() === '') {
+ issues.push('missing description');
+ }
+ const usageDescription = comp.usage?.description?.trim() ?? '';
+ if (usageDescription === '') {
+ issues.push('missing usage description');
+ }
+ if (componentsWithPublicProps.has(comp.name) && comp.props.length === 0) {
+ issues.push('missing props');
+ }
+ const incompleteProps = comp.props
+ .filter(
+ prop =>
+ prop.name.trim() === '' ||
+ prop.type.trim() === '' ||
+ prop.description.trim() === '',
+ )
+ .map(prop => prop.name || '<unnamed>');
+ if (incompleteProps.length > 0) {
+ issues.push(`incomplete props: ${incompleteProps.join(', ')}`);
+ }
+ return issues;
+}
+
// ── Package Registry ───────────────────────────────────────────────────
describe('packageRegistry', () => {
@@ -201,6 +273,19 @@ describe('componentRegistry', () => {
expect(button!.parentDoc).toBeNull();
});
+ it('keeps core component docs complete for generated component pages', () => {
+ const componentsWithPublicProps = getCoreComponentsWithPublicProps();
+ const incompleteDocs = components['@xds/core'].flatMap(comp => {
+ const issues = getComponentDocCompletenessIssues(
+ comp,
+ componentsWithPublicProps,
+ );
+ return issues.length > 0 ? [`${comp.name}: ${issues.join(', ')}`] : [];
+ });
+
+ expect(incompleteDocs).toEqual([]);
+ });
+
it('moduleName has XDS prefix for components, not for hooks', () => {
const core = components['@xds/core'];
const button = core.find(c => c.name === 'Button');
diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.doc.mjs b/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.doc.mjs
new file mode 100644
index 0000000000..6b8b92667a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Overlay',
+ name: 'Overlay — Bottom Strip',
+ displayName: 'Overlay — Bottom Strip',
+ description:
+ 'Places compact supporting content in a bottom scrim strip without covering the entire image.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Overlay', 'AspectRatio', 'Badge', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.tsx b/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.tsx
new file mode 100644
index 0000000000..0ac440bfd0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Overlay/OverlayBottomStrip.tsx
@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {XDSOverlay} from '@xds/core/Overlay';
+import {XDSAspectRatio} from '@xds/core/AspectRatio';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const styles = stylex.create({
+ frame: {
+ width: 420,
+ maxWidth: '100%',
+ borderRadius: 12,
+ overflow: 'clip',
+ },
+ image: {
+ width: '100%',
+ height: '100%',
+ objectFit: 'cover',
+ },
+});
+
+export default function OverlayBottomStrip() {
+ return (
+ <XDSOverlay
+ position="bottom"
+ align="start"
+ content={
+ <XDSVStack gap={1}>
+ <XDSBadge label="New" variant="green" />
+ <XDSText type="body" weight="bold" color="inherit">
+ Weekly product highlights
+ </XDSText>
+ <XDSText type="supporting" color="inherit">
+ 12 updates across templates and tokens
+ </XDSText>
+ </XDSVStack>
+ }>
+ <XDSAspectRatio ratio={16 / 9} xstyle={styles.frame}>
+ <img
+ src="https://lookaside.facebook.com/assets/xds_oss/illustrative-horizontal-1.jpg"
+ alt="Product highlight preview"
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.doc.mjs b/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.doc.mjs
new file mode 100644
index 0000000000..8f86308749
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Overlay',
+ name: 'Overlay — Hover Reveal',
+ displayName: 'Overlay — Hover Reveal',
+ description:
+ 'Reveals an overlay action on hover or keyboard focus. Use when actions should stay visually quiet until the media receives attention.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Overlay', 'AspectRatio', 'Button'],
+};
diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.tsx b/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.tsx
new file mode 100644
index 0000000000..db252c946a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Overlay/OverlayHoverReveal.tsx
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {XDSOverlay} from '@xds/core/Overlay';
+import {XDSAspectRatio} from '@xds/core/AspectRatio';
+import {XDSButton} from '@xds/core/Button';
+
+const styles = stylex.create({
+ frame: {
+ width: 420,
+ maxWidth: '100%',
+ borderRadius: 12,
+ overflow: 'clip',
+ },
+ image: {
+ width: '100%',
+ height: '100%',
+ objectFit: 'cover',
+ },
+});
+
+export default function OverlayHoverReveal() {
+ return (
+ <XDSOverlay
+ showOn="hover"
+ align="center"
+ content={<XDSButton label="Quick view" variant="secondary" size="sm" />}>
+ <XDSAspectRatio ratio={16 / 9} xstyle={styles.frame}>
+ <img
+ src="https://lookaside.facebook.com/assets/xds_oss/light-working-horizontal-1.png"
+ alt="Workspace preview"
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.doc.mjs b/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.doc.mjs
new file mode 100644
index 0000000000..26a9ad7718
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.doc.mjs
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Overlay',
+ name: 'Overlay',
+ displayName: 'Overlay',
+ description:
+ 'A media card with an always-visible scrim and centered action content.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ isShowcase: true,
+ componentsUsed: ['Overlay', 'AspectRatio', 'Button', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.tsx b/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.tsx
new file mode 100644
index 0000000000..d95b835dd8
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Overlay/OverlayShowcase.tsx
@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {XDSOverlay} from '@xds/core/Overlay';
+import {XDSAspectRatio} from '@xds/core/AspectRatio';
+import {XDSButton} from '@xds/core/Button';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const styles = stylex.create({
+ frame: {
+ width: 520,
+ maxWidth: '100%',
+ borderRadius: 16,
+ overflow: 'clip',
+ },
+ image: {
+ width: '100%',
+ height: '100%',
+ objectFit: 'cover',
+ },
+ content: {
+ textAlign: 'center',
+ },
+});
+
+export default function OverlayShowcase() {
+ return (
+ <XDSOverlay
+ align="center"
+ content={
+ <XDSVStack gap={2} xstyle={styles.content}>
+ <XDSText type="supporting" weight="bold" color="inherit">
+ Design system foundations
+ </XDSText>
+ <XDSButton label="Open gallery" variant="secondary" size="sm" />
+ </XDSVStack>
+ }>
+ <XDSAspectRatio ratio={16 / 9} xstyle={styles.frame}>
+ <img
+ src="https://lookaside.facebook.com/assets/xds_oss/light-scene-horizontal-1.png"
+ alt="Abstract landscape"
+ {...stylex.props(styles.image)}
+ />
+ </XDSAspectRatio>
+ </XDSOverlay>
+ );
+}
diff --git a/packages/core/src/Overlay/Overlay.doc.mjs b/packages/core/src/Overlay/Overlay.doc.mjs
index 615d8a2c85..10b6a51cf2 100644
--- a/packages/core/src/Overlay/Overlay.doc.mjs
+++ b/packages/core/src/Overlay/Overlay.doc.mjs
@@ -8,17 +8,203 @@ export const docs = {
group: 'Overlay',
category: 'Overlay',
+ keywords: ['overlay', 'scrim', 'media', 'hover', 'focus', 'image', 'card'],
+
usage: {
- description: '',
+ description:
+ 'Overlay layers action or supporting content over media, cards, video, or other bounded surfaces with an optional scrim and reveal behavior.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Use overlays for short, contextual actions or labels that belong directly to the underlying media or surface.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Keep overlay content compact so it remains legible over the scrim and does not obscure important visual information.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Do not use Overlay for floating content anchored outside the surface. Use Popover, Tooltip, or Dialog for those patterns.',
+ },
+ ],
+ anatomy: [
+ {
+ name: 'Base content',
+ required: false,
+ description: 'The media, card, or bounded surface that the overlay sits on top of.',
+ },
+ {
+ name: 'Scrim',
+ required: false,
+ description: 'Optional dark or light overlay background that improves content contrast.',
+ },
+ {
+ name: 'Overlay content',
+ required: true,
+ description: 'Actions, labels, or supporting content rendered above the base surface.',
+ },
+ ],
+ },
+
+ playground: {
+ defaults: {
+ content: {
+ __element: 'XDSButton',
+ props: {label: 'Quick view', variant: 'secondary', size: 'sm'},
+ },
+ children: [
+ {
+ __element: 'XDSAspectRatio',
+ props: {
+ ratio: 1.7777777777777777,
+ style: {
+ width: 320,
+ borderRadius: 12,
+ overflow: 'clip',
+ },
+ },
+ children: {
+ __element: 'div',
+ props: {
+ style: {
+ width: '100%',
+ height: '100%',
+ background:
+ 'linear-gradient(135deg, #172554 0%, #2563eb 55%, #67e8f9 100%)',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ color: 'white',
+ fontWeight: 600,
+ },
+ },
+ children: 'Media preview',
+ },
+ },
+ ],
+ },
},
- props: [],
+ props: [
+ {
+ name: 'content',
+ type: 'ReactNode',
+ description: 'Content rendered inside the overlay scrim.',
+ required: true,
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {label: 'Quick view', variant: 'secondary', size: 'sm'},
+ },
+ {
+ __element: 'XDSText',
+ props: {type: 'body', weight: 'bold'},
+ children: 'Overlay content',
+ },
+ ],
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Base content such as an image, video, card, or media surface that the overlay sits on top of.',
+ slotElements: [
+ {
+ __element: 'XDSAspectRatio',
+ props: {ratio: 1.7777777777777777, style: {width: 320}},
+ children: {
+ __element: 'div',
+ props: {
+ style: {
+ width: '100%',
+ height: '100%',
+ background:
+ 'linear-gradient(135deg, #172554 0%, #2563eb 55%, #67e8f9 100%)',
+ },
+ },
+ },
+ },
+ ],
+ },
+ {
+ name: 'showOn',
+ type: "'hover' | 'always' | 'focus' | 'hover-or-focus'",
+ description:
+ 'Visibility trigger. Hover mode also reveals on focus for keyboard accessibility; hover-or-focus is an alias for hover.',
+ default: "'always'",
+ },
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Controlled visibility override. When set, this takes precedence over showOn and touch toggle behavior.',
+ },
+ {
+ name: 'scrim',
+ type: "'dark' | 'light' | false",
+ description: 'Scrim background mode. Set to false to render overlay content without a scrim background.',
+ default: "'dark'",
+ },
+ {
+ name: 'position',
+ type: "'fill' | 'bottom' | 'top'",
+ description: 'Where the scrim appears within the base surface.',
+ default: "'fill'",
+ },
+ {
+ name: 'align',
+ type: "'start' | 'center' | 'end'",
+ description: 'Alignment of the overlay content within the scrim.',
+ default: "'end'",
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'CSS class name(s) appended to the root element. Prefer xstyle for styling when possible.',
+ },
+ {
+ name: 'style',
+ type: 'React.CSSProperties',
+ description: 'Inline styles applied to the root element. Prefer xstyle for design-system styling.',
+ },
+ {
+ name: 'ref',
+ type: 'Ref<HTMLDivElement>',
+ description: 'Ref forwarded to the overlay root element.',
+ },
+ ],
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: '',
+ description: 'layered content over media/card surfaces with scrim + hover/focus/controlled reveal',
usage: {
- description: '',
+ description:
+ 'Overlay layers compact actions or supporting content over media, cards, or bounded surfaces with optional dark/light scrim and hover/focus/controlled reveal.',
+ bestPractices: [
+ {guidance: true, description: 'Use for short contextual actions/labels tied to the underlying surface.'},
+ {guidance: true, description: 'Keep content compact and legible over the scrim.'},
+ {guidance: false, description: 'Do not use for floating anchored surfaces; use Popover, Tooltip, or Dialog.'},
+ ],
+ },
+ propDescriptions: {
+ content: 'overlay content inside scrim; required',
+ children: 'base media/card/surface beneath overlay',
+ showOn: 'visibility trigger; hover also focus-visible; default always',
+ isOpen: 'controlled visibility override',
+ scrim: 'dark/light scrim or false for no scrim; default dark',
+ position: 'scrim placement: fill, bottom strip, or top strip',
+ align: 'content alignment inside scrim',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ className: 'additional root class names',
+ style: 'inline root styles; prefer xstyle',
+ ref: 'forwarded root div ref',
},
};