Skip to content

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.md
index 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 components
diff --git a/apps/example-nextjs-tailwind/src/app/globals.css b/apps/example-nextjs-tailwind/src/app/globals.css
index 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.tsx
index 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 &amp; 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.md
index 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`**
```tsx
diff --git a/packages/core/package.json b/packages/core/package.json
index 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.css
new file mode 100644
index 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.ts
new file mode 100644
index 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.js
index 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',