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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/apps/example-nextjs-tailwind/README.md b/apps/example-nextjs-tailwind/README.mdindex 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.mjsindex 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.mdindex 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.jsonindex 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.cssindex 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.tsnew file mode 100644index 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.yamlindex 52ef732956..c9d5fb8422 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -882,6 +882,9 @@ importers:'@types/babel__core':specifier: ^7.20.5version: 7.20.5+ tailwindcss:+ specifier: ^4.3.2+ version: 4.3.2packages/lab:dependencies: