An open source design system that's fully customizable and agent ready
TypeScript
docs: add styling library interop guide (#2816)
Cindy Zhang694914fb65d6
diff --git a/packages/cli/docs/styling-libraries.doc.mjs b/packages/cli/docs/styling-libraries.doc.mjsnew file mode 100644index 0000000000..2d3003f41b--- /dev/null+++ b/packages/cli/docs/styling-libraries.doc.mjs@@ -0,0 +1,465 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../core/src/docs-types').ReferenceDoc} */++export const docs = {+ name: 'styling-libraries',+ title: 'Styling Library Interop',+ category: 'guide',+ description:+ 'Integrate Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, and non-CSS renderers with system tokens.',++ sections: [+ {+ title: 'Core Principle',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'Keep the system as the source of truth for theme values. Components read design tokens from CSS custom properties such as `--color-text-primary`, `--color-background-surface`, `--spacing-4`, and `--radius-container`. Other styling libraries should map their own semantic tokens, utility names, or theme objects to those system CSS variables whenever possible.',+ },+ {+ type: 'prose',+ text: 'Use CSS variables for ordinary DOM styling because they inherit through the tree, follow `data-theme` color mode, respect nested `data-xds-theme` scopes, and update when themes switch. Use token resolver APIs only for non-CSS consumers such as SVG attribute values, canvas, chart configuration, color calculations, or static config generation.',+ },+ {+ type: 'prose',+ text: 'For available token names and values, run `npx xds docs tokens`. Focused references are also available with `npx xds docs color`, `npx xds docs spacing`, `npx xds docs shape`, `npx xds docs typography`, `npx xds docs elevation`, and `npx xds docs motion`.',+ },+ ],+ },+ {+ title: 'Choose an Integration Path',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'Choose the narrowest integration path that fits the styling library. Most DOM styling should stay on the CSS-variable path; JavaScript token resolution is for APIs that cannot consume CSS custom properties.',+ },+ {+ type: 'table',+ headers: ['Path', 'Use when', 'Value shape'],+ rows: [+ [+ 'CSS variable aliases',+ 'The library ultimately writes CSS and accepts string values',+ '`var(--color-text-primary)`',+ ],+ [+ 'StyleX token imports',+ 'You are writing StyleX styles in application code',+ "`colorVars['--color-text-primary']`",+ ],+ [+ 'Tailwind bridge',+ 'You want utility classes backed by active system tokens',+ '`@xds/core/tailwind-theme.css`',+ ],+ [+ 'Token resolver APIs',+ 'JavaScript needs token values for charts, canvas, SVG, or config objects',+ "`resolveXDSThemeToken(theme, '--color-data-categorical-blue', {mode})`",+ ],+ ],+ },+ ],+ },+ {+ title: 'Best Practices',+ category: 'guide',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Map by semantic intent: text, surface, border, accent, status, radius, spacing, typography.',+ 'Let the system own color mode. The root XDSTheme syncs `data-theme="light|dark"` and `data-xds-theme` to `<html>` for portals and first-level theme scope.',+ 'Prefer CSS variables for runtime theme switching and nested themes.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Copy raw hex/px values into a second theme object when a `var(...)` reference would work.',+ 'Run a second unsynchronized dark-mode provider that disagrees with XDSTheme.',+ 'Make another library\'s CSS variables the source of truth for the system. Some consumers need token values outside the DOM.',+ ],+ },+ ],+ },+ {+ title: 'Plain CSS and CSS Modules',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'The simplest integration is direct CSS variable usage. CSS Modules scope class names, but system token variables are global/inherited values supplied by package CSS and the active theme.',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'Card.module.css',+ code: `.card {+ background: var(--color-background-surface);+ color: var(--color-text-primary);+ border: 1px solid var(--color-border);+ border-radius: var(--radius-container);+ padding: var(--spacing-4);+}`,+ },+ {+ type: 'prose',+ text: 'Sass variables are compile-time only. They are useful for generating static CSS, but they do not update when the system switches theme or color mode. Use native CSS custom properties for themeable values.',+ },+ ],+ },+ {+ title: 'StyleX',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'For StyleX styles, prefer the typed token exports from `@xds/core/theme/tokens.stylex`. They provide autocomplete and catch token-name typos while still resolving through the same system CSS variables at runtime.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Typed token imports',+ code: `import * as stylex from '@stylexjs/stylex';+import {colorVars, spacingVars, radiusVars} from '@xds/core/theme/tokens.stylex';++const styles = stylex.create({+ panel: {+ backgroundColor: colorVars['--color-background-surface'],+ color: colorVars['--color-text-primary'],+ padding: spacingVars['--spacing-4'],+ borderRadius: radiusVars['--radius-container'],+ },+});`,+ },+ {+ type: 'prose',+ text: 'Use `xstyle` for component overrides and `stylex.props()` for your own DOM nodes. Use `className` when integrating a non-StyleX styling library.',+ },+ ],+ },+ {+ title: 'Tailwind',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'The Tailwind v4 bridge at `@xds/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme.',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'globals.css',+ code: `@layer reset, theme, base, xds-base, xds-theme, components, utilities;++@import "tailwindcss/theme.css" layer(theme);+@import "tailwindcss/preflight.css" layer(base);+@import "@xds/core/reset.css";+@import "@xds/core/xds.css";+@import "@xds/theme-default/theme.css";+@import "@xds/core/tailwind-theme.css";+@import "tailwindcss/utilities.css" layer(utilities);`,+ },+ {+ type: 'prose',+ text: 'Pre-declare every layer before any imports. This keeps reset lowest, Tailwind preflight above reset, component/theme styles in the middle, and Tailwind utilities last so utility classes on `className` can intentionally override component defaults.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Tailwind classes backed by system tokens',+ code: `<section className="rounded-lg border border-border bg-surface p-4 text-primary shadow-md">+ <XDSButton label="Save" variant="primary" />+</section>`,+ },+ {+ type: 'prose',+ text: 'The Tailwind bridge is the concrete example of the general interop pattern: expose another library\'s semantic API, but point the values at system token variables.',+ },+ ],+ },+ {+ title: 'Panda, Chakra, and Other Semantic Token Systems',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'Libraries like Panda CSS and Chakra UI have first-class semantic token objects. Put system CSS variables at the leaves of those objects so product code can use the library\'s semantic names while the system still owns the values.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'Semantic token aliases',+ code: `semanticTokens: {+ colors: {+ text: {+ primary: {value: 'var(--color-text-primary)'},+ secondary: {value: 'var(--color-text-secondary)'},+ },+ background: {+ surface: {value: 'var(--color-background-surface)'},+ body: {value: 'var(--color-background-body)'},+ },+ border: {+ default: {value: 'var(--color-border)'},+ },+ },+},+tokens: {+ spacing: {+ 4: {value: 'var(--spacing-4)'},+ },+ radii: {+ container: {value: 'var(--radius-container)'},+ },+}`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Panda-style usage',+ code: `<section+ className={css({+ bg: 'background.surface',+ color: 'text.primary',+ borderColor: 'border.default',+ p: '4',+ rounded: 'container',+ })}+/>`,+ },+ {+ type: 'prose',+ text: 'If a semantic-token library needs to generate its own light/dark CSS from raw values, align its mode selector with XDSTheme (`data-theme="light|dark"`) and generate that adapter from system theme data. Otherwise it can drift from nested or runtime themes.',+ },+ ],+ },+ {+ title: 'MUI and Palette-Based Themes',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'MUI expects palette slots such as primary, background, text, and divider. Map those slots to system variables for ordinary component styling. Use raw values only when MUI or your code needs to parse colors for contrast, alpha, lighten, or darken calculations.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'MUI palette mapped to system vars',+ code: `const theme = createTheme({+ cssVariables: true,+ colorSchemes: {+ light: {+ palette: {+ primary: {main: 'var(--color-accent)'},+ background: {+ default: 'var(--color-background-body)',+ paper: 'var(--color-background-surface)',+ },+ text: {+ primary: 'var(--color-text-primary)',+ secondary: 'var(--color-text-secondary)',+ },+ divider: 'var(--color-border)',+ },+ },+ dark: {+ palette: {+ primary: {main: 'var(--color-accent)'},+ background: {+ default: 'var(--color-background-body)',+ paper: 'var(--color-background-surface)',+ },+ text: {+ primary: 'var(--color-text-primary)',+ secondary: 'var(--color-text-secondary)',+ },+ divider: 'var(--color-border)',+ },+ },+ },+});`,+ },+ {+ type: 'prose',+ text: 'If MUI owns color mode in an app, generate the light and dark palette values from system theme data and keep XDSTheme mode synchronized. If XDSTheme owns color mode, keep both MUI schemes pointing at the same system CSS variables.',+ },+ ],+ },+ {+ title: 'Emotion, styled-components, Theme UI, and Styled System',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'Runtime CSS-in-JS libraries usually accept arbitrary theme objects. Keep those objects semantic, but store system CSS variable references as the values. This keeps generated classes stable while the system updates values through the CSS cascade.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'Generic CSS-in-JS theme object',+ code: `const appTheme = {+ colors: {+ textPrimary: 'var(--color-text-primary)',+ textSecondary: 'var(--color-text-secondary)',+ surface: 'var(--color-background-surface)',+ border: 'var(--color-border)',+ accent: 'var(--color-accent)',+ },+ spacing: {+ 4: 'var(--spacing-4)',+ },+ radius: {+ container: 'var(--radius-container)',+ },+};`,+ },+ {+ type: 'prose',+ text: 'Avoid rebuilding CSS-in-JS theme objects with raw color values on every mode switch. CSS variables let the class names stay the same while the browser resolves the active values.',+ },+ ],+ },+ {+ title: 'UnoCSS and Custom Utility Systems',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'Utility generators such as UnoCSS can put system variables in their theme config or shortcuts. Keep classes semantic (`bg-surface`, `text-primary`) and let the values point at system tokens.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'UnoCSS-style config',+ code: `export default defineConfig({+ theme: {+ colors: {+ surface: 'var(--color-background-surface)',+ primary: 'var(--color-text-primary)',+ border: 'var(--color-border)',+ accent: 'var(--color-accent)',+ },+ spacing: {+ 4: 'var(--spacing-4)',+ },+ },+ shortcuts: {+ 'xds-card': 'bg-surface text-primary border border-border rounded-lg p-4',+ },+});`,+ },+ {+ type: 'prose',+ text: 'Static utility extractors cannot see dynamically constructed class names. Prefer explicit class strings or the library\'s safelist/source-registration mechanism.',+ },+ ],+ },+ {+ title: 'Non-CSS Processing',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'Use `resolveXDSThemeTokens()` or `resolveXDSThemeToken()` when code outside React needs token values for a known theme and mode. Use `useXDSTheme()` inside client components when the values should come from the nearest XDSTheme and active mode.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'Resolve tokens without React context',+ code: `import {resolveXDSThemeTokens} from '@xds/core/theme/tokens';+import {defaultTheme} from '@xds/theme-default';++const tokens = resolveXDSThemeTokens(defaultTheme, {mode: 'light'});++const chartOptions = {+ textColor: tokens['--color-text-primary'],+ mutedTextColor: tokens['--color-text-secondary'],+ gridColor: tokens['--color-border'],+ seriesColors: [+ tokens['--color-data-categorical-blue'],+ tokens['--color-data-categorical-orange'],+ tokens['--color-data-categorical-purple'],+ ],+};`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Resolve tokens from the nearest XDSTheme',+ code: `'use client';++import {useMemo} from 'react';+import {useXDSTheme} from '@xds/core/theme';++function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {+ const {mode, tokens} = useXDSTheme();++ const chartOptions = useMemo(+ () => ({+ mode,+ textColor: tokens['--color-text-primary'],+ mutedTextColor: tokens['--color-text-secondary'],+ gridColor: tokens['--color-border'],+ seriesColors: [+ tokens['--color-data-categorical-blue'],+ tokens['--color-data-categorical-orange'],+ tokens['--color-data-categorical-purple'],+ ],+ }),+ [mode, tokens],+ );++ return <ThirdPartyChart data={data} options={chartOptions} />;+}`,+ },+ ],+ },+ {+ title: 'Non-CSS Processing Best Practices',+ category: 'guide',+ content: [+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use the returned `tokens` object as a memo dependency; it is stable until the active theme or mode changes.',+ 'Use data visualization tokens such as `--color-data-categorical-blue` for chart series instead of reusing arbitrary UI colors.',+ 'Prefer CSS variables for SVG elements when possible (`fill="var(--color-accent)"`); use token resolver APIs when an API requires a string value in JavaScript.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Use token resolver APIs for ordinary DOM styling. Use CSS variables, StyleX tokens, xstyle, or library aliases instead.',+ 'Assume the returned values reflect every CSS cascade override. They resolve tokens for the current theme and mode; local media-surface overrides and arbitrary CSS overrides may not be represented in the returned map.',+ ],+ },+ ],+ },+ {+ title: 'Interop Checklist',+ category: 'guide',+ content: [+ {+ type: 'list',+ style: 'ordered',+ items: [+ 'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `npx xds theme build` or published `/built` theme imports plus `theme.css`.',+ 'Choose one owner for color mode. XDSTheme uses `data-theme="light|dark"` and `color-scheme` to resolve `light-dark()` tokens.',+ 'Map the external library\'s semantic layer to system variables by intent, not by exact naming. For example, MUI `background.paper` maps to `--color-background-surface`.',+ 'Use `npx xds docs tokens` and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',+ 'Use token resolver APIs only for non-CSS APIs that need resolved values.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/docs/styling.doc.mjs b/packages/cli/docs/styling.doc.mjsindex 76d334a038..1d68695879 100644--- a/packages/cli/docs/styling.doc.mjs+++ b/packages/cli/docs/styling.doc.mjs@@ -7,7 +7,7 @@ export const docs = {title: 'Styling Components',category: 'guide',description:- 'How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, and theming hooks.',+ 'How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, theming hooks, and styling-library interop.',sections: [{@@ -26,11 +26,12 @@ export const docs = {['Tailwind utilities', 'Layout, wrappers, and utility styling', 'className="flex gap-3 p-4"'],['stylex.create', 'Reusable styles, pseudo-classes, typed tokens', 'stylex.create({ card: { ... } })'],['className', 'Integrating with external CSS or Tailwind on components', 'className="my-card shadow-lg"'],+ ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "colors.surface = 'var(--color-background-surface)'"],],},{type: 'prose',- text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose.',+ text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run `npx xds docs styling-libraries`; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useXDSTheme()` for non-CSS processing.',},],},@@ -91,14 +92,21 @@ const overrides = stylex.create({content: [{type: 'prose',- text: 'The design system ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by design tokens: colors, spacing, radius, shadows, and typography all resolve to the active theme.',+ text: 'The package ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by design tokens: colors, spacing, radius, shadows, and typography all resolve to the active theme.',},{type: 'code',lang: 'css',label: 'globals.css: import the bridge',- code: `@import "tailwindcss";-@import "@xds/core/tailwind-theme.css" layer(theme);`,+ code: `@layer reset, theme, base, xds-base, xds-theme, components, utilities;++@import "tailwindcss/theme.css" layer(theme);+@import "tailwindcss/preflight.css" layer(base);+@import "@xds/core/reset.css";+@import "@xds/core/xds.css";+@import "@xds/theme-default/theme.css";+@import "@xds/core/tailwind-theme.css";+@import "tailwindcss/utilities.css" layer(utilities);`,},{type: 'code',@@ -111,7 +119,7 @@ const overrides = stylex.create({},{type: 'prose',- text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use.',+ text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run `npx xds docs styling-libraries`.',},],},@@ -289,7 +297,7 @@ const overrides = stylex.create({content: [{type: 'prose',- text: 'When writing custom styles, use design tokens instead of hardcoded values. Tokens are CSS custom properties that adapt to the active theme and color mode. The design system provides tokens for spacing, color, radius, shadow, typography, and size.',+ text: 'When writing custom styles, use design tokens instead of hardcoded values. Tokens are CSS custom properties that adapt to the active theme and color mode. The system provides tokens for spacing, color, radius, shadow, typography, and size.',},{type: 'code',diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjsindex 24e0954aa0..e0b1f9e77c 100644--- a/packages/cli/docs/theme.doc.mjs+++ b/packages/cli/docs/theme.doc.mjs@@ -576,7 +576,7 @@ function ChartConfig() {},{type: 'prose',- text: 'See `npx xds docs styling` for component-level customization and `npx xds docs tokens` for the full token reference.',+ text: 'See `npx xds docs styling-libraries` for styling-library interop and `npx xds docs tokens` for the full token reference.',},],},diff --git a/packages/core/README.md b/packages/core/README.mdindex b62f4fdcce..99ea588752 100644--- a/packages/core/README.md+++ b/packages/core/README.md@@ -48,12 +48,12 @@ npx xds gap-report # report a missing capability## Related Packages-| Package | Description |-|---------|-------------|-| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling: component docs, templates, scaffolding, codemods |-| [`@xds/theme-default`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/default) | Default theme (Heroicons) |-| [`@xds/theme-neutral`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/neutral) | Muted, minimal theme (Lucide icons) |-| [`@xds/theme-daily`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/daily) | Warm, productivity-focused theme (Lucide icons) |+| Package | Description |+| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling: component docs, templates, scaffolding, codemods |+| [`@xds/theme-default`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/default) | Default theme (Heroicons) |+| [`@xds/theme-neutral`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/neutral) | Muted, minimal theme (Lucide icons) |+| [`@xds/theme-daily`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/daily) | Warm, productivity-focused theme (Lucide icons) |## Resources@@ -81,16 +81,16 @@ No build plugins needed; XDS ships pre-built CSS that works alongside Tailwind.```css@layer reset, theme, base, xds-base, xds-theme, components, utilities;-@import "tailwindcss/theme.css" layer(theme);-@import "tailwindcss/preflight.css" layer(base);-@import "@xds/core/reset.css";-@import "@xds/core/xds.css";-@import "@xds/theme-default/theme.css";-@import "@xds/core/tailwind-theme.css";-@import "tailwindcss/utilities.css" layer(utilities);+@import 'tailwindcss/theme.css' layer(theme);+@import 'tailwindcss/preflight.css' layer(base);+@import '@xds/core/reset.css';+@import '@xds/core/xds.css';+@import '@xds/theme-default/theme.css';+@import '@xds/core/tailwind-theme.css';+@import 'tailwindcss/utilities.css' layer(utilities);```-The `tailwind-theme.css` import maps XDS tokens to Tailwind utilities via `@theme inline`:+The `tailwind-theme.css` import maps system tokens to Tailwind utilities via `@theme inline`:```tsx// Without the bridge — verbose:@@ -102,15 +102,15 @@ The `tailwind-theme.css` import maps XDS tokens to Tailwind utilities via `@themSome useful mappings:-| Tailwind class | XDS token |-|---|---|-| `text-primary` / `text-secondary` | `--color-text-primary` / `--color-text-secondary` |-| `bg-surface` / `bg-card` / `bg-body` | `--color-background-surface` / `card` / `body` |-| `border-border` / `border-strong` | `--color-border` / `--color-border-emphasized` |-| `bg-success` / `text-error` / `text-warning` | Status tokens |-| `bg-blue-subtle` / `border-blue-ring` / `text-blue-vivid` | Hue palette (×10 hues) |-| `rounded-sm` / `rounded-md` / `rounded-lg` | `--radius-inner` / `element` / `container` |-| `shadow-sm` / `shadow-md` / `shadow-lg` | `--shadow-low` / `med` / `high` |+| Tailwind class | XDS token |+| --------------------------------------------------------- | ------------------------------------------------- |+| `text-primary` / `text-secondary` | `--color-text-primary` / `--color-text-secondary` |+| `bg-surface` / `bg-card` / `bg-body` | `--color-background-surface` / `card` / `body` |+| `border-border` / `border-strong` | `--color-border` / `--color-border-emphasized` |+| `bg-success` / `text-error` / `text-warning` | Status tokens |+| `bg-blue-subtle` / `border-blue-ring` / `text-blue-vivid` | Hue palette (×10 hues) |+| `rounded-sm` / `rounded-md` / `rounded-lg` | `--radius-inner` / `element` / `container` |+| `shadow-sm` / `shadow-md` / `shadow-lg` | `--shadow-low` / `med` / `high` |Spacing references `var(--spacing-1)` as the base unit, so `p-4` = 16px, matching XDS's `--spacing-4`. Arbitrary values still work as an escape hatch: `bg-[var(--color-background-surface)]`.@@ -171,9 +171,9 @@ npm install @xds/core @xds/theme-default**`src/app/globals.css`**```css-@import "@xds/core/reset.css";-@import "@xds/core/xds.css";-@import "@xds/theme-default/theme.css";+@import '@xds/core/reset.css';+@import '@xds/core/xds.css';+@import '@xds/theme-default/theme.css';```Providers and layout are the same as the Tailwind example (use `@xds/theme-default/built`).diff --git a/packages/core/src/tailwind-theme.css b/packages/core/src/tailwind-theme.cssindex de398d8413..5a6df0ae81 100644--- a/packages/core/src/tailwind-theme.css+++ b/packages/core/src/tailwind-theme.css@@ -1,34 +1,38 @@/* Copyright (c) Meta Platforms, Inc. and affiliates. *//**- * XDS Tailwind Bridge+ * Tailwind Bridge*- * Maps XDS design tokens to Tailwind CSS v4 theme variables so you can use- * Tailwind utility classes backed by XDS's theming system.+ * Maps design tokens to Tailwind CSS v4 theme variables so you can use+ * Tailwind utility classes backed by the active theme.** Instead of: class="text-[var(--color-text-primary)] bg-[var(--color-background-surface)]"* Write: class="text-primary bg-surface"** Requires:* - Tailwind CSS v4+- * - XDS CSS loaded (either `@xds/core/xds.css` or a theme package)+ * - core CSS and a theme CSS file loaded before Tailwind utilities** Usage:- * @import "@xds/core/tailwind-theme.css";+ * @layer reset, theme, base, xds-base, xds-theme, components, utilities;*- * Or if you manage your own Tailwind import:- * @import "tailwindcss";- * @import "@xds/core/tailwind-theme.css" layer(theme);+ * @import "tailwindcss/theme.css" layer(theme);+ * @import "tailwindcss/preflight.css" layer(base);+ * @import "@xds/core/reset.css";+ * @import "@xds/core/xds.css";+ * @import "@xds/theme-default/theme.css";+ * @import "@xds/core/tailwind-theme.css";+ * @import "tailwindcss/utilities.css" layer(utilities);*- * @position infrastructure — sits between XDS tokens and Tailwind utility generation+ * @position infrastructure — sits between system tokens and Tailwind utility generation*//** `@theme inline` registers theme variables that Tailwind uses to generate* utility classes, WITHOUT emitting CSS declarations. The actual values come- * from XDS's own CSS custom properties (set by xds.css / theme packages).+ * from the system CSS custom properties (set by xds.css / theme packages).*- * This means theme switching just works — when XDS tokens change (e.g. dark+ * This means theme switching just works — when system tokens change (e.g. dark* mode, custom theme), Tailwind utilities automatically resolve to the new* values because they reference the same CSS custom properties.*/@@ -36,7 +40,7 @@/* =========================================================================* Colors — Semantic*- * These map XDS's purpose-specific tokens to Tailwind color utilities.+ * These map purpose-specific tokens to Tailwind color utilities.* Each name is chosen to read naturally with its most common utility:* text-primary, bg-surface, border-default*@@ -91,7 +95,7 @@--color-shadow: var(--color-shadow);/* --- Hue palette ---- * XDS splits each hue into background/border/icon/text sub-tokens.+ * Each hue is split into background/border/icon/text sub-tokens.* We expose each sub-token as a separate Tailwind color so you can* pick the right intensity per use case:*@@ -144,12 +148,12 @@/* =========================================================================* Spacing*- * XDS uses a named scale (--spacing-0 through --spacing-12) with a 4px base.+ * The system uses a named scale (--spacing-0 through --spacing-12) with a 4px base.* Tailwind v4 uses a base --spacing value with numeric multipliers:* p-4 → calc(var(--spacing) * 4)*- * By referencing --spacing-1 (the XDS base unit), Tailwind's scale- * stays in sync with XDS: p-1 = 4px, p-2 = 8px, p-4 = 16px, etc.+ * By referencing --spacing-1 (the base unit), Tailwind's scale+ * stays in sync with the system: p-1 = 4px, p-2 = 8px, p-4 = 16px, etc.* ========================================================================= */--spacing: var(--spacing-1);@@ -163,9 +167,9 @@--font-heading: var(--font-family-heading);/* --- Font sizes ---- * Maps XDS's named scale to Tailwind's text-* utilities.- * XDS sizes don't map 1:1 to Tailwind's default scale, so we- * use XDS names to avoid confusion.+ * Maps the named scale to Tailwind's text-* utilities.+ * System sizes don't map 1:1 to Tailwind's default scale, so we+ * use system names to avoid confusion.*/--text-2xs: var(--font-size-2xs);--text-xs: var(--font-size-xs);@@ -187,8 +191,8 @@/* =========================================================================* Border radius*- * Maps XDS's semantic radius tokens to Tailwind's rounded-* utilities.- * XDS has: inner (4px) → element (8px) → container (12px) → page (28px)+ * Maps semantic radius tokens to Tailwind's rounded-* utilities.+ * Radius scale: inner (4px) → element (8px) → container (12px) → page (28px)* ========================================================================= */--radius-none: var(--radius-none);--radius-xs: var(--radius-inner);@@ -208,7 +212,7 @@/* =========================================================================* Transitions & Animation*- * XDS has a richer duration/easing system than Tailwind's defaults.+ * The system has a richer duration/easing scale than Tailwind's defaults.* We map the primary durations and expose the standard easing.* ========================================================================= */--transition-property-colors: color, background-color, border-color, text-decoration-color, fill, stroke;diff --git a/packages/core/src/theme/useXDSTheme.doc.mjs b/packages/core/src/theme/useXDSTheme.doc.mjsindex f1a589d200..1d63b84a97 100644--- a/packages/core/src/theme/useXDSTheme.doc.mjs+++ b/packages/core/src/theme/useXDSTheme.doc.mjs@@ -6,21 +6,80 @@ export const docs = {displayName: 'useXDSTheme',group: 'Utilities',category: 'Utility',- keywords: ['theme', 'tokens', 'color', 'mode', 'dark', 'light', 'provider', 'data visualization', 'canvas', 'svg'],+ keywords: [+ 'theme',+ 'tokens',+ 'color',+ 'mode',+ 'dark',+ 'light',+ 'provider',+ 'data visualization',+ 'canvas',+ 'svg',+ 'chart',+ ],params: [],returns: [- {name: 'name', type: 'string', description: 'Name of the nearest XDS theme, or default when no provider is present.'},- {name: 'mode', type: "'light' | 'dark'", description: 'Resolved effective color mode. system mode is resolved to light or dark.'},- {name: 'token', type: '(name: string) => string', description: 'Resolve a single design token to its concrete CSS value for the current mode.'},- {name: 'tokens', type: 'Record<string, string>', description: 'All tokens resolved for the current mode, including defaults and theme overrides. Uses the same resolution logic as resolveXDSThemeTokens(theme, {mode}).'},+ {+ name: 'name',+ type: 'string',+ description:+ 'Name of the nearest theme, or default when no provider is present.',+ },+ {+ name: 'mode',+ type: "'light' | 'dark'",+ description:+ 'Resolved effective color mode. system mode is resolved to light or dark.',+ },+ {+ name: 'token',+ type: '(name: string) => string',+ description:+ 'Resolve a single design token to its current CSS value for the effective mode.',+ },+ {+ name: 'tokens',+ type: 'Record<string, string>',+ description:+ 'All tokens resolved for the current mode, including defaults and theme overrides. Stable until the active theme or mode changes; uses the same resolution logic as resolveXDSThemeTokens(theme, {mode}).',+ },],usage: {- description: 'Programmatic access to resolved XDS theme tokens. Use it for non-CSS consumers like SVG, canvas, Vega, D3, or chart libraries that need concrete values instead of CSS custom property references.',+ description:+ 'Programmatic access to theme tokens for non-CSS consumers like SVG, canvas, Vega, D3, maps, or chart libraries that need values in JavaScript instead of CSS custom property references.',bestPractices: [- {guidance: true, description: 'Use token(name) when integrating theme colors into SVG, canvas, or chart configuration objects inside React components.'},- {guidance: true, description: 'Use resolveXDSThemeTokens(theme, {mode}) for the same token resolution outside React hooks.'},- {guidance: true, description: 'Prefer CSS variables or StyleX tokens for ordinary component styling; use this hook when values must be read in JavaScript.'},- {guidance: false, description: 'Hardcode light/dark colors in data visualizations — resolve them through the current theme instead.'},+ {+ guidance: true,+ description:+ 'Use tokens or token(name) when integrating theme colors into SVG attributes, canvas drawing, chart options, or other non-CSS configuration objects inside React components.',+ },+ {+ guidance: true,+ description:+ 'Use resolveXDSThemeTokens(theme, {mode}) for the same token resolution outside React hooks.',+ },+ {+ guidance: true,+ description:+ 'Prefer CSS variables or StyleX tokens for ordinary component styling; use this hook only when JavaScript needs token values.',+ },+ {+ guidance: true,+ description:+ 'Use data visualization tokens such as --color-data-categorical-blue for chart series instead of arbitrary UI colors.',+ },+ {+ guidance: false,+ description:+ 'Hardcode light/dark colors in data visualizations — resolve them through the current theme instead.',+ },+ {+ guidance: false,+ description:+ 'Assume the hook reflects every CSS cascade override. It resolves tokens for the current XDSTheme mode; local media-surface overrides and arbitrary external CSS may not be represented.',+ },],},relatedComponents: ['Theme'],@@ -30,20 +89,46 @@ export const docs = {/** @type {import('../docs-types').HookTranslationDoc} */export const docsDense = {- description: 'Programmatic access to resolved XDS theme tokens for SVG/canvas/charts needing concrete values instead of CSS vars.',+ description:+ 'Programmatic access to theme tokens for SVG/canvas/charts needing JS values instead of CSS vars.',returnDescriptions: {- name: 'nearest XDS theme name or default.',+ name: 'nearest theme name or default.',mode: 'resolved light/dark mode.',- token: 'resolve one design token to concrete CSS value.',- tokens: 'all resolved tokens for current mode; same resolver as resolveXDSThemeTokens.',+ token: 'resolve one design token for effective mode.',+ tokens:+ 'all tokens resolved for current mode; stable until theme/mode changes; same resolver as resolveXDSThemeTokens.',},usage: {- description: 'Programmatic access to resolved XDS theme tokens for SVG/canvas/charts needing concrete values instead of CSS vars.',+ description:+ 'Programmatic access to theme tokens for SVG/canvas/charts needing JS values instead of CSS vars.',bestPractices: [- {guidance: true, description: 'Use token(name) for SVG/canvas/chart config theme colors in React.'},- {guidance: true, description: 'Use resolveXDSThemeTokens(theme, {mode}) outside React hooks.'},- {guidance: true, description: 'Prefer CSS vars / StyleX tokens for ordinary styling; use hook when JS needs values.'},- {guidance: false, description: 'Hardcode light/dark chart colors — resolve from current theme.'},+ {+ guidance: true,+ description: 'Use tokens/token(name) for SVG/canvas/chart config theme colors in React.',+ },+ {+ guidance: true,+ description:+ 'Use resolveXDSThemeTokens(theme, {mode}) outside React hooks.',+ },+ {+ guidance: true,+ description:+ 'Prefer CSS vars / StyleX tokens for ordinary styling; use hook when JS needs values.',+ },+ {+ guidance: true,+ description: 'Use --color-data-* tokens for chart series.',+ },+ {+ guidance: false,+ description: 'Hardcode light/dark chart colors — resolve from current theme.',+ },+ {+ guidance: false,+ description:+ 'Assume hook reflects arbitrary CSS cascade/media-surface overrides.',+ },],},};