An open source design system that's fully customizable and agent ready
TypeScript
feat: Tailwind v4 theme bridge (#1649)
Cindy Zhang33ac1414462a
diff --git a/apps/example-nextjs-tailwind/README.md b/apps/example-nextjs-tailwind/README.mdindex 60dd95f11a..47a164e512 100644--- a/apps/example-nextjs-tailwind/README.md+++ b/apps/example-nextjs-tailwind/README.md@@ -44,14 +44,34 @@ Without this declaration, XDS layers are created *after* Tailwind's declared lay</main>```-### XDS tokens in Tailwind arbitrary values+### XDS Tailwind Bridge (recommended)-XDS design tokens are CSS custom properties, so they work in Tailwind's bracket syntax:+Import `@xds/core/tailwind-theme.css` to register XDS tokens as Tailwind theme variables. This maps all XDS design tokens to native Tailwind utilities — no `var()` needed:```tsx+// Before (verbose arbitrary values):<div className="rounded-[var(--radius-container)] bg-[var(--color-background-surface)] p-[var(--spacing-4)]"><p className="text-[var(--color-text-primary)]">Styled with XDS tokens</p></div>++// After (with tailwind-theme.css):+<div className="rounded-lg bg-surface p-4">+ <p className="text-primary">Styled with XDS tokens</p>+</div>+```++The bridge uses Tailwind v4's `@theme inline` — it tells Tailwind to generate utilities from XDS's existing CSS custom properties without emitting duplicate declarations. Theme switching just works.++Available utilities include `text-primary`, `text-secondary`, `bg-surface`, `bg-card`, `border-strong`, `text-error`, `bg-success`, `bg-blue-subtle`, `text-blue-vivid`, `border-blue-ring`, and 80+ more.++### XDS tokens via arbitrary values (escape hatch)++If you need a token the bridge doesn't cover, you can still use Tailwind's bracket syntax:++```tsx+<div className="bg-[var(--color-background-surface)]">+ <p className="text-[var(--color-text-primary)]">Escape hatch</p>+</div>```### Tailwind overrides on XDS componentsdiff --git a/apps/example-nextjs-tailwind/src/app/globals.css b/apps/example-nextjs-tailwind/src/app/globals.cssindex 0a464938a3..ed764fa43f 100644--- a/apps/example-nextjs-tailwind/src/app/globals.css+++ b/apps/example-nextjs-tailwind/src/app/globals.css@@ -22,4 +22,5 @@@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);diff --git a/apps/example-nextjs-tailwind/src/app/page.tsx b/apps/example-nextjs-tailwind/src/app/page.tsxindex 18052cd5af..b7dd9df631 100644--- a/apps/example-nextjs-tailwind/src/app/page.tsx+++ b/apps/example-nextjs-tailwind/src/app/page.tsx@@ -49,7 +49,7 @@ export default function Home() {const [input2, setInput2] = useState('');return (- <main className="min-h-screen bg-[var(--color-background-body)] p-8">+ <main className="min-h-screen bg-body p-8"><div className="mx-auto max-w-3xl"><XDSVStack gap={8}><XDSVStack gap={2}>@@ -92,23 +92,134 @@ export default function Home() {<XDSDivider />- {/* XDS tokens in Tailwind arbitrary values */}+ {/* Tailwind Bridge — the main demo */}<XDSVStack gap={3}>- <XDSHeading level={2}>XDS tokens in Tailwind</XDSHeading>- <div className="rounded-[var(--radius-container)] border border-[var(--color-border)] bg-[var(--color-background-surface)] p-[var(--spacing-4)]">- <p className="text-[var(--color-text-primary)] text-[var(--font-size-base)]">- Card built with Tailwind using XDS tokens via{' '}- <code className="text-[var(--font-size-sm)] text-[var(--color-text-secondary)]">- var(--radius-container)- </code>- , etc.- </p>+ <XDSHeading level={2}>Tailwind Bridge</XDSHeading>+ <XDSText type="supporting" color="secondary">+ With{' '}+ <code className="rounded-sm bg-gray-100 px-1 py-0.5 text-xs">+ @xds/core/tailwind-theme.css+ </code>+ , XDS tokens become native Tailwind utilities. No{' '}+ <code className="rounded-sm bg-gray-100 px-1 py-0.5 text-xs">+ var()+ </code>{' '}+ needed.+ </XDSText>++ {/* Before / After comparison */}+ <div className="grid grid-cols-2 gap-6">+ {/* Before: verbose arbitrary values */}+ <XDSVStack gap={2}>+ <XDSText type="label">Before (arbitrary values)</XDSText>+ <div className="rounded-[var(--radius-container)] border border-[var(--color-border)] bg-[var(--color-background-surface)] p-[var(--spacing-4)]">+ <p className="text-[var(--color-text-primary)] text-[var(--font-size-base)]">+ 35+ chars per token 😬+ </p>+ <p className="mt-2 text-[var(--color-text-secondary)] text-[var(--font-size-sm)]">+ bg-[var(--color-background-surface)]+ </p>+ </div>+ </XDSVStack>++ {/* After: clean bridge utilities */}+ <XDSVStack gap={2}>+ <XDSText type="label">After (bridge utilities)</XDSText>+ <div className="rounded-lg border border-border bg-surface p-4">+ <p className="text-base text-primary">+ Short and clean ✨+ </p>+ <p className="mt-2 text-sm text-secondary">+ bg-surface text-primary+ </p>+ </div>+ </XDSVStack>+ </div>++ {/* Status colors */}+ <XDSText type="label">Status colors</XDSText>+ <div className="flex gap-3">+ <div className="flex items-center gap-2 rounded-md bg-success/10 px-3 py-2">+ <div className="h-2 w-2 rounded-full bg-success" />+ <span className="text-sm font-medium text-success">+ Success+ </span>+ </div>+ <div className="flex items-center gap-2 rounded-md bg-error/10 px-3 py-2">+ <div className="h-2 w-2 rounded-full bg-error" />+ <span className="text-sm font-medium text-error">Error</span>+ </div>+ <div className="flex items-center gap-2 rounded-md bg-warning/10 px-3 py-2">+ <div className="h-2 w-2 rounded-full bg-warning" />+ <span className="text-sm font-medium text-warning">+ Warning+ </span>+ </div>+ </div>++ {/* Hue palette */}+ <XDSText type="label">Hue palette (subtle / ring / vivid)</XDSText>+ <div className="grid grid-cols-5 gap-3">+ <div className="rounded-md border border-blue-ring bg-blue-subtle p-3 text-center">+ <span className="text-sm font-medium text-blue-vivid">+ blue+ </span>+ </div>+ <div className="rounded-md border border-green-ring bg-green-subtle p-3 text-center">+ <span className="text-sm font-medium text-green-vivid">+ green+ </span>+ </div>+ <div className="rounded-md border border-purple-ring bg-purple-subtle p-3 text-center">+ <span className="text-sm font-medium text-purple-vivid">+ purple+ </span>+ </div>+ <div className="rounded-md border border-orange-ring bg-orange-subtle p-3 text-center">+ <span className="text-sm font-medium text-orange-vivid">+ orange+ </span>+ </div>+ <div className="rounded-md border border-red-ring bg-red-subtle p-3 text-center">+ <span className="text-sm font-medium text-red-vivid">red</span>+ </div></div>- <div className="flex gap-[var(--spacing-3)]">- <div className="h-12 w-12 rounded-[var(--radius-element)] bg-[var(--color-accent)]" />- <div className="h-12 w-12 rounded-[var(--radius-element)] bg-[var(--color-success)]" />- <div className="h-12 w-12 rounded-[var(--radius-element)] bg-[var(--color-error)]" />- <div className="h-12 w-12 rounded-[var(--radius-element)] bg-[var(--color-warning)]" />++ {/* Semantic surfaces */}+ <XDSText type="label">Semantic surfaces</XDSText>+ <div className="grid grid-cols-3 gap-3">+ <div className="rounded-lg bg-surface p-4 shadow-sm">+ <p className="text-sm font-medium text-primary">bg-surface</p>+ <p className="text-xs text-secondary">Cards, panels</p>+ </div>+ <div className="rounded-lg bg-body p-4 shadow-sm">+ <p className="text-sm font-medium text-primary">bg-body</p>+ <p className="text-xs text-secondary">Page background</p>+ </div>+ <div className="rounded-lg bg-muted p-4 shadow-sm">+ <p className="text-sm font-medium text-primary">bg-muted</p>+ <p className="text-xs text-secondary">Subtle emphasis</p>+ </div>+ </div>++ {/* Spacing + radius */}+ <XDSText type="label">Spacing & radius</XDSText>+ <div className="flex items-end gap-3">+ <div className="rounded-xs bg-accent-bg p-1 text-center">+ <span className="text-xs text-on-accent">p-1</span>+ </div>+ <div className="rounded-sm bg-accent-bg p-2 text-center">+ <span className="text-xs text-on-accent">p-2</span>+ </div>+ <div className="rounded-md bg-accent-bg p-3 text-center">+ <span className="text-xs text-on-accent">p-3</span>+ </div>+ <div className="rounded-lg bg-accent-bg p-4 text-center">+ <span className="text-xs text-on-accent">p-4</span>+ </div>+ <div className="rounded-xl bg-accent-bg p-6 text-center">+ <span className="text-xs text-on-accent">p-6</span>+ </div></div></XDSVStack>diff --git a/packages/core/README.md b/packages/core/README.mdindex 7cdcc1c036..5ddf2e3e7e 100644--- a/packages/core/README.md+++ b/packages/core/README.md@@ -84,9 +84,34 @@ No build plugins needed — XDS ships pre-built CSS that works alongside Tailwin@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`:++```tsx+// Without the bridge — verbose:+<div className="rounded-[var(--radius-container)] bg-[var(--color-background-surface)] text-[var(--color-text-primary)]">++// With the bridge — just works:+<div className="rounded-lg bg-surface text-primary">+```++Some 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` |++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)]`.+**`src/app/providers.tsx`**```tsxdiff --git a/packages/core/package.json b/packages/core/package.jsonindex a3e70f8fcc..8b6ca2176c 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -27,6 +27,10 @@"types": "./src/xds.css.d.ts","default": "./dist/xds.css"},+ "./tailwind-theme.css": {+ "types": "./src/tailwind-theme.css.d.ts",+ "default": "./src/tailwind-theme.css"+ },"./theme/tokens.stylex": {"source": "./src/theme/tokens.stylex.ts","types": "./dist/theme/tokens.stylex.d.ts",diff --git a/packages/core/src/tailwind-theme.css b/packages/core/src/tailwind-theme.cssnew file mode 100644index 0000000000..0b2e4b8651--- /dev/null+++ b/packages/core/src/tailwind-theme.css@@ -0,0 +1,224 @@+/**+ * XDS 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.+ *+ * 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)+ *+ * Usage:+ * @import "@xds/core/tailwind-theme.css";+ *+ * Or if you manage your own Tailwind import:+ * @import "tailwindcss";+ * @import "@xds/core/tailwind-theme.css" layer(theme);+ *+ * @position infrastructure — sits between XDS 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).+ *+ * This means theme switching just works — when XDS tokens change (e.g. dark+ * mode, custom theme), Tailwind utilities automatically resolve to the new+ * values because they reference the same CSS custom properties.+ */+@theme inline {+ /* =========================================================================+ * Colors — Semantic+ *+ * These map XDS's 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+ *+ * But since Tailwind generates ALL color utilities from --color-*, you+ * also get bg-primary, text-surface, etc. — which can be useful.+ * ========================================================================= */++ /* --- Text --- */+ --color-primary: var(--color-text-primary);+ --color-secondary: var(--color-text-secondary);+ --color-disabled: var(--color-text-disabled);+ --color-accent: var(--color-text-accent);++ /* --- Surfaces --- */+ --color-surface: var(--color-background-surface);+ --color-body: var(--color-background-body);+ --color-card: var(--color-background-card);+ --color-popover: var(--color-background-popover);+ --color-muted: var(--color-background-muted);+ --color-inverted: var(--color-background-inverted);+ --color-overlay: var(--color-overlay);++ /* --- Interactive --- */+ --color-accent-bg: var(--color-accent);+ --color-accent-muted: var(--color-accent-muted);+ --color-on-accent: var(--color-on-accent);+ --color-neutral: var(--color-neutral);+ --color-overlay-hover: var(--color-overlay-hover);+ --color-overlay-pressed: var(--color-overlay-pressed);+ --color-tint-hover: var(--color-tint-hover);++ /* --- Status --- */+ --color-success: var(--color-success);+ --color-success-muted: var(--color-success-muted);+ --color-on-success: var(--color-on-success);+ --color-error: var(--color-error);+ --color-error-muted: var(--color-error-muted);+ --color-on-error: var(--color-on-error);+ --color-warning: var(--color-warning);+ --color-warning-muted: var(--color-warning-muted);+ --color-on-warning: var(--color-on-warning);++ /* --- Borders --- */+ --color-border: var(--color-border);+ --color-border-strong: var(--color-border-emphasized);++ /* --- Utility --- */+ --color-on-dark: var(--color-on-dark);+ --color-on-light: var(--color-on-light);+ --color-skeleton: var(--color-skeleton);+ --color-shadow: var(--color-shadow);++ /* --- Hue palette ---+ * XDS splits each hue 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:+ *+ * bg-blue-subtle → light tinted background+ * border-blue-ring → saturated border+ * text-blue-vivid → high-contrast text+ *+ * The icon variant is omitted — use the vivid text color for icons.+ */+ --color-blue-subtle: var(--color-background-blue);+ --color-blue-ring: var(--color-border-blue);+ --color-blue-vivid: var(--color-text-blue);++ --color-cyan-subtle: var(--color-background-cyan);+ --color-cyan-ring: var(--color-border-cyan);+ --color-cyan-vivid: var(--color-text-cyan);++ --color-gray-subtle: var(--color-background-gray);+ --color-gray-ring: var(--color-border-gray);+ --color-gray-vivid: var(--color-text-gray);++ --color-green-subtle: var(--color-background-green);+ --color-green-ring: var(--color-border-green);+ --color-green-vivid: var(--color-text-green);++ --color-orange-subtle: var(--color-background-orange);+ --color-orange-ring: var(--color-border-orange);+ --color-orange-vivid: var(--color-text-orange);++ --color-pink-subtle: var(--color-background-pink);+ --color-pink-ring: var(--color-border-pink);+ --color-pink-vivid: var(--color-text-pink);++ --color-purple-subtle: var(--color-background-purple);+ --color-purple-ring: var(--color-border-purple);+ --color-purple-vivid: var(--color-text-purple);++ --color-red-subtle: var(--color-background-red);+ --color-red-ring: var(--color-border-red);+ --color-red-vivid: var(--color-text-red);++ --color-teal-subtle: var(--color-background-teal);+ --color-teal-ring: var(--color-border-teal);+ --color-teal-vivid: var(--color-text-teal);++ --color-yellow-subtle: var(--color-background-yellow);+ --color-yellow-ring: var(--color-border-yellow);+ --color-yellow-vivid: var(--color-text-yellow);++ /* =========================================================================+ * Spacing+ *+ * XDS 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.+ * ========================================================================= */+ --spacing: var(--spacing-1);++ /* =========================================================================+ * Typography+ * ========================================================================= */++ /* --- Font families --- */+ --font-sans: var(--font-family-body);+ --font-mono: var(--font-family-code);+ --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.+ */+ --text-2xs: var(--font-size-2xs);+ --text-xs: var(--font-size-xs);+ --text-sm: var(--font-size-sm);+ --text-base: var(--font-size-base);+ --text-lg: var(--font-size-lg);+ --text-xl: var(--font-size-xl);+ --text-2xl: var(--font-size-2xl);+ --text-3xl: var(--font-size-3xl);+ --text-4xl: var(--font-size-4xl);+ --text-5xl: var(--font-size-5xl);++ /* --- Font weights --- */+ --font-weight-normal: var(--font-weight-normal);+ --font-weight-medium: var(--font-weight-medium);+ --font-weight-semibold: var(--font-weight-semibold);+ --font-weight-bold: var(--font-weight-bold);++ /* =========================================================================+ * Border radius+ *+ * Maps XDS's semantic radius tokens to Tailwind's rounded-* utilities.+ * XDS has: inner (4px) → element (8px) → container (12px) → page (28px)+ * ========================================================================= */+ --radius-none: var(--radius-none);+ --radius-xs: var(--radius-inner);+ --radius-sm: var(--radius-inner);+ --radius-md: var(--radius-element);+ --radius-lg: var(--radius-container);+ --radius-xl: var(--radius-page);+ --radius-full: var(--radius-full);++ /* =========================================================================+ * Shadows+ * ========================================================================= */+ --shadow-sm: var(--shadow-low);+ --shadow-md: var(--shadow-med);+ --shadow-lg: var(--shadow-high);++ /* =========================================================================+ * Transitions & Animation+ *+ * XDS has a richer duration/easing system 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;+ --transition-property-opacity: opacity;+ --transition-property-shadow: box-shadow;+ --transition-property-transform: transform;++ --ease-out: var(--ease-standard);++ /* =========================================================================+ * Element sizing+ * ========================================================================= */+ --size-sm: var(--size-element-sm);+ --size-md: var(--size-element-md);+ --size-lg: var(--size-element-lg);+}diff --git a/packages/core/src/tailwind-theme.css.d.ts b/packages/core/src/tailwind-theme.css.d.tsnew file mode 100644index 0000000000..153572561d--- /dev/null+++ b/packages/core/src/tailwind-theme.css.d.ts@@ -0,0 +1,2 @@+declare const styles: string;+export default styles;diff --git a/scripts/sync-exports.js b/scripts/sync-exports.jsindex 17bced062a..cc37e3a8e1 100644--- a/scripts/sync-exports.js+++ b/scripts/sync-exports.js@@ -57,6 +57,10 @@ const STATIC_EXPORTS = {types: './src/xds.css.d.ts',default: './dist/xds.css',},+ './tailwind-theme.css': {+ types: './src/tailwind-theme.css.d.ts',+ default: './src/tailwind-theme.css',+ },'./theme/tokens.stylex': {source: './src/theme/tokens.stylex.ts',types: './dist/theme/tokens.stylex.d.ts',