Skip to content

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

TypeScript

fix(core): keep Tailwind bridge reference-only (#6797)

Cindy Zhang6b72a508fa79
diff --git a/.changeset/tailwind-reference-only.md b/.changeset/tailwind-reference-only.md
new file mode 100644
index 0000000000..cd1054d9d0
--- /dev/null
+++ b/.changeset/tailwind-reference-only.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Keep Tailwind bridge tokens reference-only so utilities follow the active theme without emitting competing runtime declarations.
+
+@cixzhang
diff --git a/apps/example-nextjs-tailwind/README.md b/apps/example-nextjs-tailwind/README.md
index 261ca6921f..20b544f48a 100644
--- a/apps/example-nextjs-tailwind/README.md
+++ b/apps/example-nextjs-tailwind/README.md
@@ -60,7 +60,7 @@ Import `@astryxdesign/core/tailwind-theme.css` to register Astryx tokens as Tail
</div>
```
-The bridge uses Tailwind v4's `@theme inline`: it tells Tailwind to generate utilities from Astryx's existing CSS custom properties without emitting duplicate declarations. Theme switching just works.
+The bridge uses Tailwind v4's `@theme reference inline`: `reference` prevents runtime token declarations, while `inline` generates utilities that read Astryx's existing CSS custom properties. 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.
diff --git a/packages/cli/assets/docs/styling-libraries.doc.mjs b/packages/cli/assets/docs/styling-libraries.doc.mjs
index d494f7e582..05f4cb9a14 100644
--- a/packages/cli/assets/docs/styling-libraries.doc.mjs
+++ b/packages/cli/assets/docs/styling-libraries.doc.mjs
@@ -150,7 +150,7 @@ const styles = stylex.create({
content: [
{
type: 'prose',
- text: 'The Tailwind v4 bridge at `@astryxdesign/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.',
+ text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme reference inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme without emitting competing runtime declarations.',
},
{
type: 'code',
diff --git a/packages/core/README.md b/packages/core/README.md
index 2891bc6803..07899643f1 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -153,7 +153,7 @@ No build plugins needed; Astryx ships pre-built CSS that works alongside Tailwin
@import 'tailwindcss/utilities.css' layer(utilities);
```
-The `tailwind-theme.css` import maps system tokens to Tailwind utilities via `@theme inline`:
+The `tailwind-theme.css` import maps system tokens to Tailwind utilities via `@theme reference inline`, so the mappings generate utilities without redeclaring the tokens at runtime:
```tsx
// Without the bridge — verbose:
diff --git a/packages/core/package.json b/packages/core/package.json
index 4a7b823b6c..517a45af7e 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -717,7 +717,8 @@
"@testing-library/dom": "^10.0.0",
"@testing-library/jest-dom": "catalog:",
"@testing-library/react": "catalog:",
- "@types/babel__core": "^7.20.5"
+ "@types/babel__core": "^7.20.5",
+ "tailwindcss": "^4.3.2"
},
"dependencies": {
"intl-messageformat": "^11.2.9"
diff --git a/packages/core/src/tailwind-theme.css b/packages/core/src/tailwind-theme.css
index 1bd3f07dfa..3a55523d89 100644
--- a/packages/core/src/tailwind-theme.css
+++ b/packages/core/src/tailwind-theme.css
@@ -28,15 +28,17 @@
*/
/*
- * `@theme inline` registers theme variables that Tailwind uses to generate
- * utility classes, WITHOUT emitting CSS declarations. The actual values come
+ * `@theme reference inline` registers theme variables that Tailwind uses to
+ * generate utility classes. `reference` prevents Tailwind from emitting those
+ * variables as runtime declarations, while `inline` places the mapped system
+ * custom property directly in each generated utility. The actual values come
* from the system CSS custom properties (set by astryx.css / theme packages).
*
* 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.
*/
-@theme inline {
+@theme reference inline {
/* =========================================================================
* Colors — Semantic
*
@@ -182,6 +184,12 @@
--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
*
diff --git a/packages/core/src/tailwind-theme.test.ts b/packages/core/src/tailwind-theme.test.ts
new file mode 100644
index 0000000000..9a648d448a
--- /dev/null
+++ b/packages/core/src/tailwind-theme.test.ts
@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file tailwind-theme.test.ts
+ * @input Uses the public Tailwind bridge and Tailwind's compiler
+ * @output Regression coverage for reference-only token registration and
+ * token-backed utility generation
+ * @position Package-contract test for the Tailwind v4 bridge
+ */
+
+import {readFileSync} from 'node:fs';
+import path from 'node:path';
+
+import {compile} from 'tailwindcss';
+import {describe, expect, it} from 'vitest';
+
+const bridgeCSS = readFileSync(
+ path.resolve(__dirname, 'tailwind-theme.css'),
+ 'utf8',
+);
+
+const sameNameColorTokens = [
+ '--color-overlay',
+ '--color-accent-muted',
+ '--color-on-accent',
+ '--color-neutral',
+ '--color-overlay-hover',
+ '--color-overlay-pressed',
+ '--color-tint-hover',
+ '--color-success',
+ '--color-success-muted',
+ '--color-on-success',
+ '--color-error',
+ '--color-error-muted',
+ '--color-on-error',
+ '--color-warning',
+ '--color-warning-muted',
+ '--color-on-warning',
+ '--color-border',
+ '--color-on-dark',
+ '--color-on-light',
+ '--color-skeleton',
+ '--color-track',
+ '--color-shadow',
+] as const;
+
+const sameNameFontWeightTokens = [
+ '--font-weight-normal',
+ '--font-weight-medium',
+ '--font-weight-semibold',
+ '--font-weight-bold',
+] as const;
+
+const sameNameRadiusTokens = ['--radius-none', '--radius-full'] as const;
+
+function suffix(token: string, prefix: string): string {
+ return token.slice(prefix.length);
+}
+
+async function compileBridge(): Promise<string> {
+ const compiler = await compile(`${bridgeCSS}\n@tailwind utilities;`);
+ return compiler.build([
+ ...sameNameColorTokens.map(token => `bg-${suffix(token, '--color-')}`),
+ ...sameNameFontWeightTokens.map(
+ token => `font-${suffix(token, '--font-weight-')}`,
+ ),
+ ...sameNameRadiusTokens.map(
+ token => `rounded-${suffix(token, '--radius-')}`,
+ ),
+ 'bg-surface',
+ ]);
+}
+
+describe('Tailwind theme bridge', () => {
+ it('does not emit runtime theme declarations', async () => {
+ const css = await compileBridge();
+
+ expect(bridgeCSS).toContain('@theme reference inline');
+ expect(css).not.toMatch(/:root|:host/);
+ });
+
+ it('keeps every same-name token family external', async () => {
+ const css = await compileBridge();
+
+ for (const token of sameNameColorTokens) {
+ expect(css).toContain(`background-color: var(${token});`);
+ }
+ for (const token of sameNameFontWeightTokens) {
+ expect(css).toContain(`font-weight: var(${token});`);
+ }
+ for (const token of sameNameRadiusTokens) {
+ expect(css).toContain(`border-radius: var(${token});`);
+ }
+ });
+
+ it('keeps renamed mappings inline in generated utilities', async () => {
+ const css = await compileBridge();
+
+ expect(css).toContain('background-color: var(--color-background-surface);');
+ expect(css).not.toContain('background-color: var(--color-surface);');
+ });
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 52ef732956..c9d5fb8422 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -882,6 +882,9 @@ importers:
'@types/babel__core':
specifier: ^7.20.5
version: 7.20.5
+ tailwindcss:
+ specifier: ^4.3.2
+ version: 4.3.2
packages/lab:
dependencies: