Skip to content

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

TypeScript

fix(docsite): improve theme component examples (#2747)

Cindy Zhang507af2894db4
diff --git a/apps/docsite/src/components/component-detail/InteractivePreview.tsx b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
index 25e1cad471..715052d2dd 100644
--- a/apps/docsite/src/components/component-detail/InteractivePreview.tsx
+++ b/apps/docsite/src/components/component-detail/InteractivePreview.tsx
@@ -19,7 +19,9 @@ import {CodeExampleBlock} from '../CodeExampleBlock';
import {XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
import {XDSTheme} from '@xds/core/theme';
+import {allSyntaxPresets} from '@xds/core/theme/syntax';
import {neutralTheme} from '@xds/theme-neutral/built';
+import {themeObjectsFull} from '../../generated/themeRegistry';
import {useThemeMode} from '../../app/providers';
import {Code} from 'lucide-react';
import {
@@ -75,16 +77,56 @@ function pickPrimaryProps(name: string, props: PropDoc[]): KnobProp[] {
}));
}
+function resolveThemeValue(value: unknown): unknown {
+ if (typeof value !== 'string') {
+ return resolveValue(value);
+ }
+
+ const byPackageName = themeObjectsFull[value];
+ if (byPackageName) {
+ return byPackageName;
+ }
+
+ return (
+ Object.values(themeObjectsFull).find(theme => theme.name === value) ?? value
+ );
+}
+
+function resolveSyntaxThemeValue(value: unknown): unknown {
+ if (typeof value !== 'string') {
+ return resolveValue(value);
+ }
+
+ return allSyntaxPresets.find(theme => theme.name === value) ?? value;
+}
+
+function resolveDefaultValue(
+ value: unknown,
+ control: PropControlDescriptor | undefined,
+): unknown {
+ if (control?.kind === 'theme') {
+ return resolveThemeValue(value);
+ }
+ if (control?.kind === 'syntax-theme') {
+ return resolveSyntaxThemeValue(value);
+ }
+ return resolveValue(value);
+}
+
function buildInitialState(
knobs: KnobProp[],
playground?: PlaygroundConfig | null,
): Record<string, unknown> {
const state: Record<string, unknown> = {};
+ const controlByName = new Map(
+ knobs.map(({row, control}) => [row.name, control]),
+ );
+
// Apply playground defaults first (resolved from ElementDescriptor if needed)
if (playground?.defaults) {
for (const [key, value] of Object.entries(playground.defaults)) {
- state[key] = resolveValue(value);
+ state[key] = resolveDefaultValue(value, controlByName.get(key));
}
}
@@ -121,6 +163,12 @@ function buildInitialState(
case 'enum':
state[row.name] = control.options[0];
break;
+ case 'theme':
+ state[row.name] = Object.values(themeObjectsFull)[0];
+ break;
+ case 'syntax-theme':
+ state[row.name] = allSyntaxPresets[0];
+ break;
case 'boolean':
state[row.name] = false;
break;
@@ -136,13 +184,41 @@ function buildInitialState(
return state;
}
-function formatValue(value: unknown): string {
+function toIdentifierName(name: string): string {
+ return name
+ .split(/[^a-zA-Z0-9]+/)
+ .filter(Boolean)
+ .map((part, index) => {
+ const lower = part.charAt(0).toLowerCase() + part.slice(1);
+ if (index === 0) {
+ return lower;
+ }
+ return lower.charAt(0).toUpperCase() + lower.slice(1);
+ })
+ .join('');
+}
+
+function formatValue(
+ value: unknown,
+ propName?: string,
+ componentName?: string,
+): string {
if (value === undefined) {
return 'undefined';
}
if (value === null) {
return 'null';
}
+ if (
+ value != null &&
+ typeof value === 'object' &&
+ 'name' in value &&
+ typeof value.name === 'string' &&
+ propName === 'theme'
+ ) {
+ const identifier = toIdentifierName(value.name);
+ return componentName === 'Theme' ? `${identifier}Theme` : identifier;
+ }
if (typeof value === 'string') {
return `"${value}"`;
}
@@ -193,7 +269,7 @@ function generateCode(name: string, state: Record<string, unknown>): string {
if (typeof value === 'string') {
return ` ${key}="${value}"`;
}
- return ` ${key}={${formatValue(value)}}`;
+ return ` ${key}={${formatValue(value, key, name)}}`;
});
return `<${componentName}\n${propLines.join('\n')}\n/>`;
diff --git a/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx b/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx
index 9cee998342..155bd8bbda 100644
--- a/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx
+++ b/apps/docsite/src/components/component-detail/PlaygroundPropsTable.tsx
@@ -15,6 +15,8 @@ import {XDSBadge} from '@xds/core/Badge';
import {XDSIconButton} from '@xds/core/IconButton';
import {Minus, Plus} from 'lucide-react';
import {useMediaQuery} from '@xds/core/hooks';
+import {allSyntaxPresets} from '@xds/core/theme/syntax';
+import {themeObjectsFull} from '../../generated/themeRegistry';
import type {PropControlDescriptor} from './parsePropType';
import type {KnobProp} from './InteractivePreview';
import {resolveElementDescriptor} from './resolveElements';
@@ -79,6 +81,107 @@ function resolveSlotElement(
}
}
+function humanizePackageName(pkgName: string): string {
+ return pkgName
+ .replace('@xds/theme-', '')
+ .split('-')
+ .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+ .join(' ');
+}
+
+const themeOptions = Object.entries(themeObjectsFull).map(
+ ([pkgName, theme]) => ({
+ value: pkgName,
+ label: humanizePackageName(pkgName),
+ theme,
+ }),
+);
+
+const syntaxThemeOptions = allSyntaxPresets.map(theme => ({
+ value: theme.name,
+ label: theme.name
+ .split('-')
+ .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+ .join(' '),
+ theme,
+}));
+
+function ThemeControl({
+ value,
+ onChange,
+}: {
+ value: unknown;
+ onChange: (next: unknown) => void;
+}) {
+ if (themeOptions.length === 0) {
+ return null;
+ }
+
+ const selected =
+ themeOptions.find(
+ option =>
+ option.theme === value ||
+ (value != null &&
+ typeof value === 'object' &&
+ 'name' in value &&
+ option.theme.name === value.name),
+ )?.value ?? themeOptions[0].value;
+
+ return (
+ <XDSSelector
+ label="Theme"
+ isLabelHidden
+ value={selected}
+ options={themeOptions.map(({value: optionValue, label}) => ({
+ value: optionValue,
+ label,
+ }))}
+ onChange={next => {
+ const match = themeOptions.find(option => option.value === next);
+ if (match) {
+ onChange(match.theme);
+ }
+ }}
+ />
+ );
+}
+
+function SyntaxThemeControl({
+ value,
+ onChange,
+}: {
+ value: unknown;
+ onChange: (next: unknown) => void;
+}) {
+ const selected =
+ syntaxThemeOptions.find(
+ option =>
+ option.theme === value ||
+ (value != null &&
+ typeof value === 'object' &&
+ 'name' in value &&
+ option.theme.name === value.name),
+ )?.value ?? syntaxThemeOptions[0].value;
+
+ return (
+ <XDSSelector
+ label="Syntax theme"
+ isLabelHidden
+ value={selected}
+ options={syntaxThemeOptions.map(({value: optionValue, label}) => ({
+ value: optionValue,
+ label,
+ }))}
+ onChange={next => {
+ const match = syntaxThemeOptions.find(option => option.value === next);
+ if (match) {
+ onChange(match.theme);
+ }
+ }}
+ />
+ );
+}
+
function ElementControl({
control,
value,
@@ -111,7 +214,8 @@ function ElementControl({
return (
<XDSSelector
- label=""
+ label={prop.name}
+ isLabelHidden
placeholder="None"
value={value != null ? selected : 'None'}
options={['None', ...control.options.map(o => o.label)]}
@@ -230,13 +334,18 @@ function InlineControl({
const isNumeric = control.options.every(o => /^-?\d+(\.\d+)?$/.test(o));
return (
<XDSSelector
- label=""
+ label={prop.name}
+ isLabelHidden
value={String(value ?? control.options[0])}
options={control.options}
onChange={next => onChange(isNumeric ? Number(next) : next)}
/>
);
}
+ case 'theme':
+ return <ThemeControl value={value} onChange={onChange} />;
+ case 'syntax-theme':
+ return <SyntaxThemeControl value={value} onChange={onChange} />;
case 'string':
return (
<XDSTextInput
diff --git a/apps/docsite/src/components/component-detail/parsePropType.ts b/apps/docsite/src/components/component-detail/parsePropType.ts
index 05fa7655a0..da9e611fa4 100644
--- a/apps/docsite/src/components/component-detail/parsePropType.ts
+++ b/apps/docsite/src/components/component-detail/parsePropType.ts
@@ -14,6 +14,8 @@ export interface ElementOption {
export type PropControlDescriptor =
| {kind: 'enum'; options: string[]; allowEmpty: boolean}
+ | {kind: 'theme'}
+ | {kind: 'syntax-theme'}
| {kind: 'boolean'}
| {kind: 'string'}
| {kind: 'number'}
@@ -110,6 +112,12 @@ export function parsePropType(
if (t === 'SizeValue') {
return {kind: 'number'};
}
+ if (t === 'XDSDefinedTheme') {
+ return {kind: 'theme'};
+ }
+ if (t === 'SyntaxTheme') {
+ return {kind: 'syntax-theme'};
+ }
if (t === 'XDSIconType' || t === 'XDSIconName') {
return {
kind: 'enum',
diff --git a/packages/cli/templates/blocks/components/MediaTheme/MediaThemeImageOverlay.doc.mjs b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeImageOverlay.doc.mjs
new file mode 100644
index 0000000000..ae179b0c1e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeImageOverlay.doc.mjs
@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'MediaTheme',
+ name: 'MediaTheme — Image Overlay',
+ displayName: 'MediaTheme — Image Overlay',
+ description:
+ 'A common image card pattern: place text and actions over a dark gradient and wrap the overlay content in XDSMediaTheme mode="dark".',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'MediaTheme',
+ 'AspectRatio',
+ 'Button',
+ 'Section',
+ 'Layout',
+ 'Text',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/MediaTheme/MediaThemeImageOverlay.tsx b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeImageOverlay.tsx
new file mode 100644
index 0000000000..a7d15d4029
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeImageOverlay.tsx
@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSMediaTheme} from '@xds/core/theme';
+import {XDSAspectRatio} from '@xds/core/AspectRatio';
+import {XDSButton} from '@xds/core/Button';
+import {XDSSection} from '@xds/core/Section';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+// light-scene-horizontal-1 from xds_oss asset set
+const LANDSCAPE_IMAGE_URL =
+ 'https://lookaside.facebook.com/assets/xds_oss/light-scene-horizontal-1.png';
+
+export default function MediaThemeImageOverlay() {
+ return (
+ <XDSAspectRatio
+ ratio={16 / 9}
+ style={{
+ width: 360,
+ maxWidth: '100%',
+ borderRadius: 'var(--radius-container)',
+ }}>
+ <img
+ src={LANDSCAPE_IMAGE_URL}
+ alt="Landscape"
+ style={{width: '100%', height: '100%', objectFit: 'cover'}}
+ />
+ <XDSSection
+ variant="transparent"
+ padding={4}
+ style={{
+ position: 'absolute',
+ insetInline: 0,
+ insetBlockEnd: 0,
+ background:
+ 'linear-gradient(180deg, transparent, rgba(10,19,23,0.78))',
+ }}>
+ <XDSMediaTheme mode="dark">
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="body" weight="bold">
+ Product launch livestream
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ MediaTheme keeps overlay text and controls readable without
+ hard-coded color overrides.
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ <XDSButton label="Watch" size="sm" />
+ <XDSButton label="Details" variant="secondary" size="sm" />
+ </XDSStack>
+ </XDSStack>
+ </XDSMediaTheme>
+ </XDSSection>
+ </XDSAspectRatio>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/MediaTheme/MediaThemeLightScrim.doc.mjs b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeLightScrim.doc.mjs
new file mode 100644
index 0000000000..9226f74796
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeLightScrim.doc.mjs
@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'MediaTheme',
+ name: 'MediaTheme — Light Scrim',
+ displayName: 'MediaTheme — Light Scrim',
+ description:
+ 'A light scrim over an image. Use XDSMediaTheme mode="light" so text and ghost buttons use dark-on-light tokens.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: [
+ 'MediaTheme',
+ 'AspectRatio',
+ 'Button',
+ 'Section',
+ 'Layout',
+ 'Text',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/MediaTheme/MediaThemeLightScrim.tsx b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeLightScrim.tsx
new file mode 100644
index 0000000000..9439cef3fd
--- /dev/null
+++ b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeLightScrim.tsx
@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSMediaTheme} from '@xds/core/theme';
+import {XDSAspectRatio} from '@xds/core/AspectRatio';
+import {XDSButton} from '@xds/core/Button';
+import {XDSSection} from '@xds/core/Section';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+// light-home-square-1 from xds_oss asset set
+const BRIGHT_ROOM_IMAGE_URL =
+ 'https://lookaside.facebook.com/assets/xds_oss/light-home-square-1.png';
+
+export default function MediaThemeLightScrim() {
+ return (
+ <XDSAspectRatio
+ ratio={16 / 9}
+ style={{
+ width: 360,
+ maxWidth: '100%',
+ borderRadius: 'var(--radius-container)',
+ }}>
+ <img
+ src={BRIGHT_ROOM_IMAGE_URL}
+ alt="Bright room"
+ style={{width: '100%', height: '100%', objectFit: 'cover'}}
+ />
+ <XDSSection
+ variant="transparent"
+ padding={4}
+ style={{
+ position: 'absolute',
+ insetBlockStart: 16,
+ insetInlineStart: 16,
+ maxWidth: 250,
+ background: 'rgba(255,255,255,0.82)',
+ borderRadius: 'var(--radius-container)',
+ boxShadow: 'var(--shadow-med)',
+ }}>
+ <XDSMediaTheme mode="light">
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="body" weight="bold">
+ Bright media surface
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ Use mode="light" when content sits on a light card or scrim.
+ </XDSText>
+ <XDSButton label="Open" variant="ghost" size="sm" />
+ </XDSStack>
+ </XDSMediaTheme>
+ </XDSSection>
+ </XDSAspectRatio>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/MediaTheme/MediaThemeShowcase.doc.mjs b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeShowcase.doc.mjs
index 719d732a18..ff787f3d0b 100644
--- a/packages/cli/templates/blocks/components/MediaTheme/MediaThemeShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeShowcase.doc.mjs
@@ -4,12 +4,20 @@
export const doc = {
type: 'block',
exampleFor: 'MediaTheme',
- name: 'MediaTheme — Inverted Surfaces',
- displayName: 'MediaTheme — Inverted Surfaces',
+ name: 'MediaTheme — Media Overlay',
+ displayName: 'MediaTheme — Media Overlay',
description:
- 'Content rendered over inverted surfaces — dark backgrounds (media, overlays, toasts) and light scrims. XDSMediaTheme provides the correct token overrides so text and controls remain legible.',
+ 'A compact media overlay showing XDSMediaTheme adapting text, icons, badges, and button variants over an image-backed dark surface.',
isReady: true,
isShowcase: true,
- aspectRatio: 16 / 9,
- componentsUsed: ['MediaTheme', 'Section', 'Layout', 'Text', 'Button'],
+ aspectRatio: 4 / 3,
+ componentsUsed: [
+ 'MediaTheme',
+ 'Section',
+ 'Layout',
+ 'Text',
+ 'Button',
+ 'Badge',
+ 'Icon',
+ ],
};
diff --git a/packages/cli/templates/blocks/components/MediaTheme/MediaThemeShowcase.tsx b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeShowcase.tsx
index 885a408a49..e31546995e 100644
--- a/packages/cli/templates/blocks/components/MediaTheme/MediaThemeShowcase.tsx
+++ b/packages/cli/templates/blocks/components/MediaTheme/MediaThemeShowcase.tsx
@@ -7,45 +7,50 @@ import {XDSSection} from '@xds/core/Section';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
import {XDSButton} from '@xds/core/Button';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSIcon} from '@xds/core/Icon';
+
+// light-scene-horizontal-1 from xds_oss asset set
+const SHOWCASE_IMAGE_URL =
+ 'https://lookaside.facebook.com/assets/xds_oss/light-scene-horizontal-1.png';
export default function MediaThemeShowcase() {
return (
- <XDSStack direction="horizontal" gap={4} vAlign="stretch">
- <XDSSection
- variant="transparent"
- padding={4}
- style={{
- flex: 1,
- backgroundColor: 'var(--color-background-inverted)',
- borderRadius: 'var(--radius-container)',
- }}>
- <XDSMediaTheme mode="dark">
- <XDSStack direction="vertical" gap={2}>
+ <XDSSection
+ variant="transparent"
+ padding={4}
+ style={{
+ width: 360,
+ maxWidth: '100%',
+ minHeight: 230,
+ display: 'flex',
+ alignItems: 'flex-end',
+ backgroundImage: `linear-gradient(180deg, rgba(10,19,23,0.05) 0%, rgba(10,19,23,0.82) 100%), url(${SHOWCASE_IMAGE_URL})`,
+ backgroundSize: 'cover',
+ backgroundPosition: 'center',
+ borderRadius: 'var(--radius-container)',
+ boxShadow: 'var(--shadow-med)',
+ }}>
+ <XDSMediaTheme mode="dark">
+ <XDSStack direction="vertical" gap={3}>
+ <XDSStack direction="horizontal" gap={2} vAlign="center">
+ <XDSIcon icon="info" size="md" />
<XDSText type="body" weight="bold">
- Dark surface
- </XDSText>
- <XDSText type="supporting" color="secondary">
- Content over media, overlays, or inverted backgrounds like toasts
- and tooltips.
+ Media overlay
</XDSText>
- <XDSButton label="Action" variant="ghost" />
+ <XDSBadge label="Live" />
</XDSStack>
- </XDSMediaTheme>
- </XDSSection>
- <XDSSection variant="muted" padding={4} style={{flex: 1}}>
- <XDSMediaTheme mode="light">
- <XDSStack direction="vertical" gap={2}>
- <XDSText type="body" weight="bold">
- Light surface
- </XDSText>
- <XDSText type="supporting" color="secondary">
- Content on light overlays or scrims where the background is
- bright.
- </XDSText>
- <XDSButton label="Action" variant="ghost" />
+ <XDSText type="supporting" color="secondary">
+ Text, icons, badges, and button variants inherit legible colors on
+ top of the dark image treatment.
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ <XDSButton label="Primary" variant="primary" size="sm" />
+ <XDSButton label="Secondary" variant="secondary" size="sm" />
+ <XDSButton label="Ghost" variant="ghost" size="sm" />
</XDSStack>
- </XDSMediaTheme>
- </XDSSection>
- </XDSStack>
+ </XDSStack>
+ </XDSMediaTheme>
+ </XDSSection>
);
}
diff --git a/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeDarkPreset.doc.mjs b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeDarkPreset.doc.mjs
new file mode 100644
index 0000000000..802bb6753f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeDarkPreset.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: 'SyntaxTheme',
+ name: 'SyntaxTheme — Dark Preset',
+ displayName: 'SyntaxTheme — Dark Preset',
+ description:
+ 'Wrap a code block in XDSSyntaxTheme to apply a dark syntax preset such as Dracula.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['SyntaxTheme', 'CodeBlock'],
+};
diff --git a/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeDarkPreset.tsx b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeDarkPreset.tsx
new file mode 100644
index 0000000000..02e567cb5e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeDarkPreset.tsx
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSSyntaxTheme} from '@xds/core/theme';
+import {dracula} from '@xds/core/theme/syntax';
+import {XDSCodeBlock} from '@xds/core/CodeBlock';
+
+const code = `function greet(name: string) {
+ return \`Hello, \${name}!\`;
+}`;
+
+export default function SyntaxThemeDarkPreset() {
+ return (
+ <XDSSyntaxTheme theme={dracula}>
+ <XDSCodeBlock code={code} language="tsx" title="Dracula preset" />
+ </XDSSyntaxTheme>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeLightPreset.doc.mjs b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeLightPreset.doc.mjs
new file mode 100644
index 0000000000..76d6cfece2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeLightPreset.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: 'SyntaxTheme',
+ name: 'SyntaxTheme — Light Preset',
+ displayName: 'SyntaxTheme — Light Preset',
+ description:
+ 'Use a light syntax preset for code examples that need to sit on light documentation surfaces.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['SyntaxTheme', 'CodeBlock'],
+};
diff --git a/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeLightPreset.tsx b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeLightPreset.tsx
new file mode 100644
index 0000000000..5d585e4a64
--- /dev/null
+++ b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeLightPreset.tsx
@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSSyntaxTheme} from '@xds/core/theme';
+import {githubLight} from '@xds/core/theme/syntax';
+import {XDSCodeBlock} from '@xds/core/CodeBlock';
+
+const code = `const status = response.ok ? 'success' : 'error';
+console.log({status});`;
+
+export default function SyntaxThemeLightPreset() {
+ return (
+ <XDSSyntaxTheme theme={githubLight}>
+ <XDSCodeBlock code={code} language="tsx" title="GitHub Light preset" />
+ </XDSSyntaxTheme>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeShowcase.doc.mjs b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeShowcase.doc.mjs
index 529d95524d..7b97239034 100644
--- a/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeShowcase.doc.mjs
@@ -4,10 +4,10 @@
export const doc = {
type: 'block',
exampleFor: 'SyntaxTheme',
- name: 'SyntaxTheme — Presets',
- displayName: 'SyntaxTheme — Presets',
+ name: 'SyntaxTheme — Compact Preset',
+ displayName: 'SyntaxTheme — Compact Preset',
description:
- 'The same code block rendered with three different syntax themes — GitHub Light, One Dark Pro, and Dracula — showing how XDSSyntaxTheme changes code highlighting colors.',
+ 'A concise code block rendered with the One Dark Pro syntax preset to show how XDSSyntaxTheme changes highlighting colors without making the page long.',
isReady: true,
isShowcase: true,
aspectRatio: 4 / 3,
diff --git a/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeShowcase.tsx b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeShowcase.tsx
index 9cd14cd4e5..1ebed7e791 100644
--- a/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeShowcase.tsx
+++ b/packages/cli/templates/blocks/components/SyntaxTheme/SyntaxThemeShowcase.tsx
@@ -3,48 +3,28 @@
'use client';
import {XDSSyntaxTheme} from '@xds/core/theme';
-import {oneDarkPro, githubLight, dracula} from '@xds/core/theme/syntax';
+import {oneDarkPro} from '@xds/core/theme/syntax';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
-const sampleCode = `import {XDSButton} from '@xds/core/Button';
-
-export function App() {
- return (
- <XDSButton
- label="Hello XDS"
- variant="primary"
- onClick={() => console.log('clicked')}
- />
- );
+const sampleCode = `async function save() {
+ await api.update(values);
+ toast.show('Saved');
}`;
-function ThemePreview({
- theme,
- label,
-}: {
- theme: Parameters<typeof XDSSyntaxTheme>[0]['theme'];
- label: string;
-}) {
+export default function SyntaxThemeShowcase() {
return (
- <XDSSyntaxTheme theme={theme}>
- <XDSStack direction="vertical" gap={1}>
+ <XDSSyntaxTheme theme={oneDarkPro}>
+ <XDSStack
+ direction="vertical"
+ gap={2}
+ style={{width: 360, maxWidth: '100%'}}>
<XDSText type="supporting" weight="bold" color="secondary">
- {label}
+ One Dark Pro preset
</XDSText>
<XDSCodeBlock code={sampleCode} language="tsx" />
</XDSStack>
</XDSSyntaxTheme>
);
}
-
-export default function SyntaxThemeShowcase() {
- return (
- <XDSStack direction="vertical" gap={4}>
- <ThemePreview theme={githubLight} label="GitHub Light" />
- <ThemePreview theme={oneDarkPro} label="One Dark Pro" />
- <ThemePreview theme={dracula} label="Dracula" />
- </XDSStack>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Theme/ThemeApply.doc.mjs b/packages/cli/templates/blocks/components/Theme/ThemeApply.doc.mjs
new file mode 100644
index 0000000000..8df4e445a2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Theme/ThemeApply.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: 'Theme',
+ name: 'Theme — Apply Theme',
+ displayName: 'Theme — Apply Theme',
+ description:
+ 'Wrap a subtree in XDSTheme to apply a theme to every child component in that region.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Theme', 'Card', 'Button', 'Section', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Theme/ThemeApply.tsx b/packages/cli/templates/blocks/components/Theme/ThemeApply.tsx
new file mode 100644
index 0000000000..9238992251
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Theme/ThemeApply.tsx
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSTheme, defineTheme} from '@xds/core/theme';
+import {XDSCard} from '@xds/core/Card';
+import {XDSButton} from '@xds/core/Button';
+import {XDSSection} from '@xds/core/Section';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSHeading, XDSText} from '@xds/core/Text';
+
+const forestTheme = defineTheme({
+ name: 'forest-docs',
+ tokens: {
+ '--color-accent': ['#15803D', '#86EFAC'],
+ '--color-background-card': ['#FFFFFF', '#0F3D24'],
+ '--color-text-primary': ['#052E16', '#DCFCE7'],
+ '--color-text-secondary': ['#166534', '#BBF7D0'],
+ '--color-border': ['#BBF7D0', '#15803D66'],
+ },
+});
+
+export default function ThemeApply() {
+ return (
+ <XDSSection variant="muted" padding={4} maxWidth={420}>
+ <XDSTheme theme={forestTheme}>
+ <XDSCard padding={4} width="100%">
+ <XDSStack direction="vertical" gap={3}>
+ <XDSHeading level={4}>Forest workspace</XDSHeading>
+ <XDSText type="body" color="secondary">
+ Wrap any subtree to apply a theme locally.
+ </XDSText>
+ <XDSButton label="Create project" />
+ </XDSStack>
+ </XDSCard>
+ </XDSTheme>
+ </XDSSection>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Theme/ThemeNested.doc.mjs b/packages/cli/templates/blocks/components/Theme/ThemeNested.doc.mjs
new file mode 100644
index 0000000000..ae40c02865
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Theme/ThemeNested.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: 'Theme',
+ name: 'Theme — Nested Theme',
+ displayName: 'Theme — Nested Theme',
+ description:
+ 'Nested XDSTheme providers let a local region use a different theme without affecting the rest of the page.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Theme', 'Card', 'Button', 'Section', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Theme/ThemeNested.tsx b/packages/cli/templates/blocks/components/Theme/ThemeNested.tsx
new file mode 100644
index 0000000000..586e9520a9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Theme/ThemeNested.tsx
@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSTheme, defineTheme} from '@xds/core/theme';
+import {XDSCard} from '@xds/core/Card';
+import {XDSButton} from '@xds/core/Button';
+import {XDSSection} from '@xds/core/Section';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSHeading, XDSText} from '@xds/core/Text';
+
+const warmTheme = defineTheme({
+ name: 'warm-docs',
+ tokens: {
+ '--color-accent': ['#D97706', '#FBBF24'],
+ '--color-background-surface': ['#FFF7ED', '#1F1300'],
+ '--color-background-card': ['#FFFBEB', '#2A1A05'],
+ '--color-text-primary': ['#3B2F15', '#FEF3C7'],
+ '--color-text-secondary': ['#92400E', '#FCD34D'],
+ '--color-border': ['#FED7AA', '#92400E66'],
+ '--radius-container': '20px',
+ },
+});
+
+const forestTheme = defineTheme({
+ name: 'forest-docs',
+ tokens: {
+ '--color-accent': ['#15803D', '#86EFAC'],
+ '--color-background-surface': ['#F0FDF4', '#052E16'],
+ '--color-background-card': ['#FFFFFF', '#0F3D24'],
+ '--color-text-primary': ['#052E16', '#DCFCE7'],
+ '--color-text-secondary': ['#166534', '#BBF7D0'],
+ '--color-border': ['#BBF7D0', '#15803D66'],
+ '--radius-container': '8px',
+ },
+});
+export default function ThemeNested() {
+ return (
+ <XDSSection variant="muted" padding={4} maxWidth={460}>
+ <XDSTheme theme={warmTheme}>
+ <XDSCard padding={4} width="100%">
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={2}>
+ <XDSHeading level={4}>Outer Warm theme</XDSHeading>
+ <XDSText type="body" color="secondary">
+ The parent section uses Warm.
+ </XDSText>
+ </XDSStack>
+ <XDSTheme theme={forestTheme}>
+ <XDSCard padding={3} width="100%">
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="body" weight="bold">
+ Nested Forest section
+ </XDSText>
+ <XDSButton label="Nested action" size="sm" />
+ </XDSStack>
+ </XDSCard>
+ </XDSTheme>
+ </XDSStack>
+ </XDSCard>
+ </XDSTheme>
+ </XDSSection>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Theme/ThemeShowcase.doc.mjs b/packages/cli/templates/blocks/components/Theme/ThemeShowcase.doc.mjs
index 1c74b63eaa..fd3c9f88b7 100644
--- a/packages/cli/templates/blocks/components/Theme/ThemeShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/Theme/ThemeShowcase.doc.mjs
@@ -4,12 +4,21 @@
export const doc = {
type: 'block',
exampleFor: 'Theme',
- name: 'Theme — Side by Side',
- displayName: 'Theme — Side by Side',
+ name: 'Theme — Distinct Themes',
+ displayName: 'Theme — Distinct Themes',
description:
- 'Two theme providers wrapping identical content to show how XDSTheme changes the visual treatment of all child components.',
+ 'Two visually distinct theme providers wrapping identical content to show how XDSTheme changes the visual treatment of child components.',
isReady: true,
isShowcase: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Theme', 'Card', 'Layout', 'Text', 'Button', 'Badge'],
+ componentsUsed: [
+ 'Theme',
+ 'Card',
+ 'Grid',
+ 'Section',
+ 'Layout',
+ 'Text',
+ 'Button',
+ 'Badge',
+ ],
};
diff --git a/packages/cli/templates/blocks/components/Theme/ThemeShowcase.tsx b/packages/cli/templates/blocks/components/Theme/ThemeShowcase.tsx
index 844a165491..eecb63fae2 100644
--- a/packages/cli/templates/blocks/components/Theme/ThemeShowcase.tsx
+++ b/packages/cli/templates/blocks/components/Theme/ThemeShowcase.tsx
@@ -2,31 +2,57 @@
'use client';
-import {XDSTheme} from '@xds/core/theme';
+import {XDSTheme, defineTheme} from '@xds/core/theme';
import {XDSCard} from '@xds/core/Card';
+import {XDSGrid} from '@xds/core/Grid';
+import {XDSSection} from '@xds/core/Section';
import {XDSStack} from '@xds/core/Layout';
import {XDSHeading, XDSText} from '@xds/core/Text';
import {XDSButton} from '@xds/core/Button';
import {XDSBadge} from '@xds/core/Badge';
-import {defaultTheme} from '@xds/theme-default/built';
-import {neutralTheme} from '@xds/theme-neutral/built';
+
+const warmTheme = defineTheme({
+ name: 'warm-docs',
+ tokens: {
+ '--color-accent': ['#D97706', '#FBBF24'],
+ '--color-background-surface': ['#FFF7ED', '#1F1300'],
+ '--color-background-card': ['#FFFBEB', '#2A1A05'],
+ '--color-text-primary': ['#3B2F15', '#FEF3C7'],
+ '--color-text-secondary': ['#92400E', '#FCD34D'],
+ '--color-border': ['#FED7AA', '#92400E66'],
+ '--radius-container': '20px',
+ },
+});
+
+const forestTheme = defineTheme({
+ name: 'forest-docs',
+ tokens: {
+ '--color-accent': ['#15803D', '#86EFAC'],
+ '--color-background-surface': ['#F0FDF4', '#052E16'],
+ '--color-background-card': ['#FFFFFF', '#0F3D24'],
+ '--color-text-primary': ['#052E16', '#DCFCE7'],
+ '--color-text-secondary': ['#166534', '#BBF7D0'],
+ '--color-border': ['#BBF7D0', '#15803D66'],
+ '--radius-container': '8px',
+ },
+});
function ThemeCard({label}: {label: string}) {
return (
- <XDSCard padding={4}>
+ <XDSCard padding={4} width="100%">
<XDSStack direction="vertical" gap={3}>
<XDSStack direction="horizontal" gap={2} vAlign="center">
<XDSHeading level={4}>{label}</XDSHeading>
<XDSBadge label="Active" variant="success" />
</XDSStack>
<XDSText type="body" color="secondary">
- Components inherit colors, typography, and radius from the nearest
- theme provider.
+ The same content inherits this provider's colors, typography, radius,
+ and component treatment.
</XDSText>
- <XDSStack direction="horizontal" gap={2}>
- <XDSButton label="Primary" variant="primary" />
- <XDSButton label="Secondary" variant="secondary" />
- <XDSButton label="Ghost" variant="ghost" />
+ <XDSStack direction="horizontal" gap={2} wrap="wrap">
+ <XDSButton label="Primary" variant="primary" size="sm" />
+ <XDSButton label="Secondary" variant="secondary" size="sm" />
+ <XDSButton label="Ghost" variant="ghost" size="sm" />
</XDSStack>
</XDSStack>
</XDSCard>
@@ -35,13 +61,15 @@ function ThemeCard({label}: {label: string}) {
export default function ThemeShowcase() {
return (
- <XDSStack direction="horizontal" gap={4}>
- <XDSTheme theme={defaultTheme}>
- <ThemeCard label="Default" />
- </XDSTheme>
- <XDSTheme theme={neutralTheme}>
- <ThemeCard label="Neutral" />
- </XDSTheme>
- </XDSStack>
+ <XDSSection variant="muted" padding={4} maxWidth={600}>
+ <XDSGrid columns={{minWidth: 240, repeat: 'fit'}} gap={3} width="100%">
+ <XDSTheme theme={warmTheme}>
+ <ThemeCard label="Warm" />
+ </XDSTheme>
+ <XDSTheme theme={forestTheme}>
+ <ThemeCard label="Forest" />
+ </XDSTheme>
+ </XDSGrid>
+ </XDSSection>
);
}
diff --git a/packages/cli/templates/blocks/components/Theme/ThemeSwitcher.doc.mjs b/packages/cli/templates/blocks/components/Theme/ThemeSwitcher.doc.mjs
new file mode 100644
index 0000000000..86c64dd46a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Theme/ThemeSwitcher.doc.mjs
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Theme',
+ name: 'Theme — Switch Themes',
+ displayName: 'Theme — Switch Themes',
+ description:
+ 'Use state to switch the theme object passed to XDSTheme and preview a different visual treatment.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: [
+ 'Theme',
+ 'Card',
+ 'Button',
+ 'Section',
+ 'Layout',
+ 'Selector',
+ 'Text',
+ ],
+};
diff --git a/packages/cli/templates/blocks/components/Theme/ThemeSwitcher.tsx b/packages/cli/templates/blocks/components/Theme/ThemeSwitcher.tsx
new file mode 100644
index 0000000000..27950f82a3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Theme/ThemeSwitcher.tsx
@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {XDSTheme, defineTheme} from '@xds/core/theme';
+import {XDSCard} from '@xds/core/Card';
+import {XDSButton} from '@xds/core/Button';
+import {XDSSection} from '@xds/core/Section';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSSelector} from '@xds/core/Selector';
+import {XDSHeading, XDSText} from '@xds/core/Text';
+
+const warmTheme = defineTheme({
+ name: 'warm-docs',
+ tokens: {
+ '--color-accent': ['#D97706', '#FBBF24'],
+ '--color-background-surface': ['#FFF7ED', '#1F1300'],
+ '--color-background-card': ['#FFFBEB', '#2A1A05'],
+ '--color-text-primary': ['#3B2F15', '#FEF3C7'],
+ '--color-text-secondary': ['#92400E', '#FCD34D'],
+ '--color-border': ['#FED7AA', '#92400E66'],
+ '--radius-container': '20px',
+ },
+});
+
+const forestTheme = defineTheme({
+ name: 'forest-docs',
+ tokens: {
+ '--color-accent': ['#15803D', '#86EFAC'],
+ '--color-background-surface': ['#F0FDF4', '#052E16'],
+ '--color-background-card': ['#FFFFFF', '#0F3D24'],
+ '--color-text-primary': ['#052E16', '#DCFCE7'],
+ '--color-text-secondary': ['#166534', '#BBF7D0'],
+ '--color-border': ['#BBF7D0', '#15803D66'],
+ '--radius-container': '8px',
+ },
+});
+const themes = {
+ Warm: warmTheme,
+ Forest: forestTheme,
+};
+
+type ThemeName = keyof typeof themes;
+
+export default function ThemeSwitcher() {
+ const [themeName, setThemeName] = useState<ThemeName>('Warm');
+
+ return (
+ <XDSSection variant="muted" padding={4} maxWidth={420}>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSSelector
+ label="Theme"
+ value={themeName}
+ options={Object.keys(themes)}
+ onChange={next => setThemeName(next as ThemeName)}
+ />
+ <XDSTheme theme={themes[themeName]}>
+ <XDSCard padding={4} width="100%">
+ <XDSStack direction="vertical" gap={3}>
+ <XDSHeading level={4}>{themeName} preview</XDSHeading>
+ <XDSText type="body" color="secondary">
+ Switching the theme object updates all tokens and component
+ styles below the provider.
+ </XDSText>
+ <XDSButton label="Save changes" />
+ </XDSStack>
+ </XDSCard>
+ </XDSTheme>
+ </XDSStack>
+ </XDSSection>
+ );
+}
diff --git a/packages/core/src/theme/MediaTheme.doc.mjs b/packages/core/src/theme/MediaTheme.doc.mjs
index 50fb36490d..c195456cad 100644
--- a/packages/core/src/theme/MediaTheme.doc.mjs
+++ b/packages/core/src/theme/MediaTheme.doc.mjs
@@ -8,20 +8,95 @@ export const docs = {
group: 'Utilities',
category: 'Utility',
isHiddenFromOverview: true,
- keywords: ['theme', 'dark-mode', 'light-mode', 'media', 'inverted', 'overlay', 'scrim', 'toast', 'tooltip'],
+ keywords: [
+ 'theme',
+ 'dark-mode',
+ 'light-mode',
+ 'media',
+ 'inverted',
+ 'overlay',
+ 'scrim',
+ 'toast',
+ 'tooltip',
+ ],
+ playground: {
+ defaults: {
+ mode: 'dark',
+ children: {
+ __element: 'XDSSection',
+ props: {
+ variant: 'transparent',
+ padding: 4,
+ style: {
+ maxWidth: 360,
+ backgroundColor: 'var(--color-background-inverted)',
+ borderRadius: 'var(--radius-container)',
+ },
+ },
+ children: {
+ __element: 'XDSVStack',
+ props: {gap: 2},
+ children: [
+ {
+ __element: 'XDSText',
+ props: {type: 'body', weight: 'bold'},
+ children: 'Media overlay',
+ },
+ {
+ __element: 'XDSText',
+ props: {type: 'supporting', color: 'secondary'},
+ children: 'Text and actions adapt to the dark media surface.',
+ },
+ {
+ __element: 'XDSButton',
+ props: {label: 'Watch now', variant: 'secondary', size: 'sm'},
+ },
+ ],
+ },
+ },
+ },
+ },
usage: {
description:
'Provides token overrides for content rendered on inverted surfaces — media overlays, scrims, toasts, and tooltips. The base behavior flips color-scheme so all light-dark() tokens resolve to the correct side. Only a small set of tokens need explicit overrides beyond that. Themes can further customize component appearance on media surfaces via onDark/onLight in defineTheme(), with both token overrides (e.g. "--color-accent": "#90CAF9") and component overrides (e.g. ghost buttons get a border on dark surfaces).',
bestPractices: [
- {guidance: true, description: 'Use for any content placed over a dark background (image overlays, video scrims, dark cards) or other inverted surfaces like toasts and tooltips.'},
- {guidance: true, description: 'Pair with a background color — MediaTheme flips the token context but does not add a background. Set backgroundColor on the parent element.'},
- {guidance: true, description: 'Themes can customize components on media surfaces via onDark.components and onLight.components in defineTheme(). For example, add a border to ghost buttons on dark surfaces.'},
- {guidance: false, description: 'Use MediaTheme for app-level dark mode — use XDSTheme with mode="dark" or mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.'},
+ {
+ guidance: true,
+ description:
+ 'Use for any content placed over a dark background (image overlays, video scrims, dark cards) or other inverted surfaces like toasts and tooltips.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Pair with a background color — MediaTheme flips the token context but does not add a background. Set backgroundColor on the parent element.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Themes can customize components on media surfaces via onDark.components and onLight.components in defineTheme(). For example, add a border to ghost buttons on dark surfaces.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use MediaTheme for app-level dark mode — use XDSTheme with mode="dark" or mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.',
+ },
],
},
props: [
- {name: 'mode', type: "'dark' | 'light'", required: true, description: 'Surface luminance context — dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions).'},
- {name: 'children', type: 'ReactNode', required: true, description: 'Content to render with inverted token context. Components inherit the correct colors automatically.'},
+ {
+ name: 'mode',
+ type: "'dark' | 'light'",
+ required: true,
+ description:
+ 'Surface luminance context — dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions).',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ required: true,
+ description:
+ 'Content to render with inverted token context. Components inherit the correct colors automatically.',
+ },
],
};
@@ -31,10 +106,26 @@ export const docsDense = {
description:
'Token overrides for content on inverted surfaces — media overlays, scrims, toasts, tooltips. Base behavior flips color-scheme so all light-dark() tokens resolve to correct side; only a small set of tokens need explicit overrides beyond that. Themes can further customize component appearance on media surfaces via onDark/onLight in defineTheme(), w/ token overrides (e.g. "--color-accent": "#90CAF9") + component overrides (e.g. ghost buttons get border on dark surfaces).',
bestPractices: [
- {guidance: true, description: 'Use for any content over dark background (image overlays, video scrims, dark cards) or other inverted surfaces like toasts/tooltips.'},
- {guidance: true, description: 'Pair w/ background color — MediaTheme flips token context but does NOT add background. Set backgroundColor on parent element.'},
- {guidance: true, description: 'Themes can customize components on media surfaces via onDark.components + onLight.components in defineTheme(). E.g. add border to ghost buttons on dark surfaces.'},
- {guidance: false, description: 'Use MediaTheme for app-level dark mode — use XDSTheme w/ mode="dark"/mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.'},
+ {
+ guidance: true,
+ description:
+ 'Use for any content over dark background (image overlays, video scrims, dark cards) or other inverted surfaces like toasts/tooltips.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Pair w/ background color — MediaTheme flips token context but does NOT add background. Set backgroundColor on parent element.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Themes can customize components on media surfaces via onDark.components + onLight.components in defineTheme(). E.g. add border to ghost buttons on dark surfaces.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use MediaTheme for app-level dark mode — use XDSTheme w/ mode="dark"/mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.',
+ },
],
},
propDescriptions: {
diff --git a/packages/core/src/theme/SyntaxTheme.doc.mjs b/packages/core/src/theme/SyntaxTheme.doc.mjs
index 1092dd19a6..40e8502eb7 100644
--- a/packages/core/src/theme/SyntaxTheme.doc.mjs
+++ b/packages/core/src/theme/SyntaxTheme.doc.mjs
@@ -8,20 +8,69 @@ export const docs = {
group: 'Utilities',
category: 'Utility',
isHiddenFromOverview: true,
- keywords: ['syntax', 'highlighting', 'code', 'theme', 'codeblock', 'prism', 'shiki'],
+ keywords: [
+ 'syntax',
+ 'highlighting',
+ 'code',
+ 'theme',
+ 'codeblock',
+ 'prism',
+ 'shiki',
+ ],
+ playground: {
+ defaults: {
+ theme: 'github-light',
+ children: {
+ __element: 'XDSCodeBlock',
+ props: {
+ code: "const status = response.ok ? 'success' : 'error';",
+ language: 'tsx',
+ title: 'status.ts',
+ },
+ },
+ },
+ },
usage: {
description:
'Applies syntax highlighting colors to XDSCodeBlock and any code component in the subtree. By default, code components use the theme-level syntax colors (set via defineTheme({ syntax: ... })), which derive from the palette (--color-text-accent for keywords, --color-text-green for strings, etc.). XDSSyntaxTheme lets you override those per-region. The system uses 14 semantic tokens (keyword, string, comment, number, function, type, variable, operator, constant, tag, attribute, property, punctuation, background) validated against 11 community themes. Custom themes are created with defineSyntaxTheme() and can use [light, dark] tuples for automatic color-scheme adaptation. Built-in presets: oneDarkPro, dracula, monokai, nord, tokyoNight, catppuccinMocha, githubLight, githubDark, solarizedLight, oneLight (import from @xds/core/theme/syntax).',
bestPractices: [
- {guidance: true, description: 'Use the syntax field in defineTheme() for app-wide code styling. Use XDSSyntaxTheme only when a specific section needs a different look.'},
- {guidance: true, description: 'Pick from built-in presets or create a custom theme with defineSyntaxTheme() for brand-specific colors.'},
- {guidance: true, description: 'Syntax themes support light-dark() tuples — each token can have different values for light and dark mode, resolved automatically by the color scheme.'},
- {guidance: false, description: 'Wrap individual CodeBlock instances with XDSSyntaxTheme — use the syntaxTheme prop on XDSCodeBlock directly for per-instance overrides.'},
+ {
+ guidance: true,
+ description:
+ 'Use the syntax field in defineTheme() for app-wide code styling. Use XDSSyntaxTheme only when a specific section needs a different look.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Pick from built-in presets or create a custom theme with defineSyntaxTheme() for brand-specific colors.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Syntax themes support light-dark() tuples — each token can have different values for light and dark mode, resolved automatically by the color scheme.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Wrap individual CodeBlock instances with XDSSyntaxTheme — use the syntaxTheme prop on XDSCodeBlock directly for per-instance overrides.',
+ },
],
},
props: [
- {name: 'theme', type: 'SyntaxTheme', required: true, description: 'Syntax highlighting theme — a preset from @xds/core/theme/syntax or a custom theme created with defineSyntaxTheme().'},
- {name: 'children', type: 'ReactNode', required: true, description: 'Content subtree. All XDSCodeBlock components within will use this syntax theme.'},
+ {
+ name: 'theme',
+ type: 'SyntaxTheme',
+ required: true,
+ description:
+ 'Syntax highlighting theme — a preset from @xds/core/theme/syntax or a custom theme created with defineSyntaxTheme().',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ required: true,
+ description:
+ 'Content subtree. All XDSCodeBlock components within will use this syntax theme.',
+ },
],
};
@@ -31,13 +80,30 @@ export const docsDense = {
description:
'Applies syntax highlighting colors to XDSCodeBlock + any code component in subtree. By default code components use theme-level syntax colors (set via defineTheme({ syntax: ... })), which derive from palette (--color-text-accent for keywords, --color-text-green for strings, etc.); XDSSyntaxTheme overrides those per-region. 14 semantic tokens (keyword, string, comment, number, function, type, variable, operator, constant, tag, attribute, property, punctuation, background) validated against 11 community themes. Custom themes created w/ defineSyntaxTheme(), can use [light, dark] tuples for automatic color-scheme adaptation. Built-in presets: oneDarkPro, dracula, monokai, nord, tokyoNight, catppuccinMocha, githubLight, githubDark, solarizedLight, oneLight (import from @xds/core/theme/syntax).',
bestPractices: [
- {guidance: true, description: 'Use syntax field in defineTheme() for app-wide code styling. Use XDSSyntaxTheme only when a specific section needs different look.'},
- {guidance: true, description: 'Pick from built-in presets or create custom theme w/ defineSyntaxTheme() for brand-specific colors.'},
- {guidance: true, description: 'Syntax themes support light-dark() tuples — each token can have different values for light/dark mode, resolved automatically by color scheme.'},
- {guidance: false, description: 'Wrap individual CodeBlock instances w/ XDSSyntaxTheme — use syntaxTheme prop on XDSCodeBlock directly for per-instance overrides instead.'},
+ {
+ guidance: true,
+ description:
+ 'Use syntax field in defineTheme() for app-wide code styling. Use XDSSyntaxTheme only when a specific section needs different look.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Pick from built-in presets or create custom theme w/ defineSyntaxTheme() for brand-specific colors.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Syntax themes support light-dark() tuples — each token can have different values for light/dark mode, resolved automatically by color scheme.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Wrap individual CodeBlock instances w/ XDSSyntaxTheme — use syntaxTheme prop on XDSCodeBlock directly for per-instance overrides instead.',
+ },
],
},
propDescriptions: {
- theme: 'syntax highlighting theme — preset from @xds/core/theme/syntax or custom theme created w/ defineSyntaxTheme(). **(required)**',
+ theme:
+ 'syntax highlighting theme — preset from @xds/core/theme/syntax or custom theme created w/ defineSyntaxTheme(). **(required)**',
},
};
diff --git a/packages/core/src/theme/XDSTheme.doc.mjs b/packages/core/src/theme/XDSTheme.doc.mjs
index 89d90743d0..2989289d8f 100644
--- a/packages/core/src/theme/XDSTheme.doc.mjs
+++ b/packages/core/src/theme/XDSTheme.doc.mjs
@@ -9,13 +9,75 @@ export const docs = {
category: 'Utility',
isHiddenFromOverview: true,
keywords: ['theme', 'theming', 'provider', 'color-scheme'],
+ playground: {
+ defaults: {
+ theme: '@xds/theme-matcha',
+ mode: 'light',
+ children: {
+ __element: 'XDSCard',
+ props: {padding: 4, style: {maxWidth: 360}},
+ children: {
+ __element: 'XDSVStack',
+ props: {gap: 3},
+ children: [
+ {
+ __element: 'XDSHeading',
+ props: {level: 4},
+ children: 'Theme preview',
+ },
+ {
+ __element: 'XDSText',
+ props: {type: 'body', color: 'secondary'},
+ children:
+ 'Cards, text, and buttons inherit tokens from the selected theme.',
+ },
+ {__element: 'XDSButton', props: {label: 'Primary action'}},
+ ],
+ },
+ },
+ },
+ },
usage: {
- description: 'Wraps a subtree with a specific XDS theme. Use at the app root or around sections that need a different visual treatment.',
+ description:
+ 'Wraps a subtree with a specific XDS theme. For static production themes, use `npx xds theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Build app themes that are known ahead of time with `npx xds theme build`, then import the generated CSS and built theme object.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use runtime themes when the theme is created or edited in the browser, such as theme editors, user branding, or prototypes.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Default to runtime themes in SSR production apps. Component overrides inject after hydration instead of shipping as static CSS.',
+ },
+ ],
},
props: [
- {name: 'theme', type: 'XDSDefinedTheme', required: true, description: 'Theme created by defineTheme().'},
- {name: 'mode', type: "'light' | 'dark' | 'system'", default: "'system'", description: 'Color mode — system follows OS preference.'},
- {name: 'children', type: 'ReactNode', required: true, description: 'Content to render with the theme.'},
+ {
+ name: 'theme',
+ type: 'XDSDefinedTheme',
+ required: true,
+ description:
+ 'Theme object to apply. Prefer built theme objects for static production themes; use runtime `defineTheme()` for dynamic themes.',
+ },
+ {
+ name: 'mode',
+ type: "'light' | 'dark' | 'system'",
+ default: "'system'",
+ description: 'Color mode. System follows OS preference.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ required: true,
+ description: 'Content to render with the theme.',
+ },
],
};
@@ -23,10 +85,28 @@ export const docs = {
export const docsDense = {
usage: {
description:
- 'Wraps subtree w/ a specific XDS theme. Use at app root or around sections that need different visual treatment.',
+ 'Wraps subtree w/ specific XDS theme. For static production themes, use `npx xds theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Build app themes known ahead of time w/ `npx xds theme build`; import generated CSS + built theme object.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use runtime themes when theme is created/edited in browser, e.g. theme editor, user branding, prototype.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Default to runtime themes in SSR production apps. Component overrides inject after hydration instead of static CSS.',
+ },
+ ],
},
propDescriptions: {
- theme: 'theme created by defineTheme(). **(required)**',
- mode: 'color mode — system follows OS preference. defaults to "system"',
+ theme:
+ 'theme object to apply. Prefer built theme objects for static production themes; use runtime `defineTheme()` for dynamic themes.',
+ mode: 'color mode. System follows OS preference. defaults to "system"',
},
};