Skip to content

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

TypeScript

docs(tailwind): a recipe for an app that already uses Tailwind, and what a misplaced @layer line does (#10532)

Cindy Zhang3eeda1b1d6ba
diff --git a/.changeset/tailwind-existing-app-recipe.md b/.changeset/tailwind-existing-app-recipe.md
new file mode 100644
index 0000000000..54b2c832a9
--- /dev/null
+++ b/.changeset/tailwind-existing-app-recipe.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/core': patch
+---
+
+[docs] The Tailwind guide (`astryx docs styling-libraries/tailwind`) adds a recipe for an app that already uses Tailwind: keep the app's own `@import "tailwindcss"`, put the `@layer` line above it, and add the Astryx stylesheets after it. It explains why the `@layer` line must come before the Tailwind import: below it, the Astryx reset outranks every utility class, and nothing reports it. The Core README's Next.js + Tailwind section points to it.
+
+@cixzhang
diff --git a/packages/cli/assets/docs/styling-overview.doc.mjs b/packages/cli/assets/docs/styling-overview.doc.mjs
index 5d8d5087ef..c416ec0873 100644
--- a/packages/cli/assets/docs/styling-overview.doc.mjs
+++ b/packages/cli/assets/docs/styling-overview.doc.mjs
@@ -90,7 +90,7 @@ export const docs = {
{
type: 'code',
lang: 'bash',
- label: 'Install (add to an existing Tailwind v4 app)',
+ label: 'Install',
code: '{@pm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral}',
},
{
@@ -113,7 +113,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',
+ text: 'A project with Tailwind already set up needs a smaller change, which {@link generic:tailwind} shows. For Tailwind v3, see the layer workaround in {@link generic:migration-setup}.',
},
],
},
@@ -162,7 +162,7 @@ export const docs = {
},
{
type: 'prose',
- text: '`{@command swizzle <Component>}` writes an `astryx-swizzle.json` marker into an output folder it owns (one the copy creates, an empty one, or one it marked before); every module under that folder then compiles as Astryx source, so keep copies in a folder of their own, such as the default `components/astryx`. For a folder that already holds other files it writes no marker and says how to add one by hand. With `@astryxdesign/build`\'s Babel, PostCSS and Vite integrations, or `withAstryx()` under webpack, a copy under that folder compiles into `astryx-base`, below `astryx-theme`, so theme component overrides reach it as they reach the package component. Under Turbopack, and with the stock StyleX plugins above, a copy\'s rules land in your own styles, above `astryx-theme`, and theme component overrides do not reach it.',
+ text: "`{@command swizzle <Component>}` writes an `astryx-swizzle.json` marker into an output folder it owns (one the copy creates, an empty one, or one it marked before); every module under that folder then compiles as Astryx source, so keep copies in a folder of their own, such as the default `components/astryx`. For a folder that already holds other files it writes no marker and says how to add one by hand. With `@astryxdesign/build`'s Babel, PostCSS and Vite integrations, or `withAstryx()` under webpack, a copy under that folder compiles into `astryx-base`, below `astryx-theme`, so theme component overrides reach it as they reach the package component. Under Turbopack, and with the stock StyleX plugins above, a copy's rules land in your own styles, above `astryx-theme`, and theme component overrides do not reach it.",
},
],
},
diff --git a/packages/cli/assets/docs/tree/tailwind.doc.mjs b/packages/cli/assets/docs/tree/tailwind.doc.mjs
index 83aa31a9c6..bb425ce5b1 100644
--- a/packages/cli/assets/docs/tree/tailwind.doc.mjs
+++ b/packages/cli/assets/docs/tree/tailwind.doc.mjs
@@ -19,6 +19,8 @@ export const docs = {
'tailwind-theme.css',
'utility classes',
'preflight',
+ 'existing Tailwind app',
+ 'cascade layer order',
],
sections: [
@@ -69,7 +71,45 @@ import {themes, defaultThemeSlug} from './astryx-themes';`,
},
{
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.',
+ 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: 'Add Astryx to an app that already uses Tailwind',
+ content: [
+ {
+ type: 'prose',
+ text: 'The recipe in the Tailwind section is a whole `globals.css` for a new app. An app that already uses Tailwind keeps its own file: its `@import "tailwindcss"`, its `@theme` mapping, and its `:root` variables stay as they are. Add one `@layer` line above the Tailwind import and the Astryx stylesheets below it.',
+ },
+ {
+ type: 'code',
+ lang: 'css',
+ label: 'globals.css (existing Tailwind app)',
+ code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
+
+@import "tailwindcss"; /* the app's own entry, unchanged */
+@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
+@import "@astryxdesign/theme-neutral/theme.css";
+
+/* The app's own @theme and :root rules stay below, unchanged. */`,
+ },
+ {
+ type: 'prose',
+ text: "This recipe leaves out `tailwind-theme.css`. The bridge maps Tailwind theme names to system tokens, including Tailwind's own defaults such as `rounded-lg` and `shadow-md`, so in an existing app it changes what the app's own classes paint. Add it only when the app does not use the names it maps.",
+ },
+ {
+ type: 'prose',
+ text: "Astryx's theme defines its own CSS custom properties (color, spacing, radius, shadow, font, motion and more), and {@link namespace:tokens} has the full list. An app token with one of those names collides in one of two ways. An app `@theme` key takes Astryx's value, because `astryx.css` sets the tokens on `:root` above Tailwind's `theme` layer: with `@theme { --spacing-4: 1.5rem }`, the app's `gap-4` stays 16px. Marking the block `@theme inline` keeps the app's value in its utilities. An app `:root` variable replaces Astryx's value, so Astryx's own components change: `:root { --spacing-4: 1.5rem }` widens Astryx's spacing step 4 from 16px to 24px. Where the root Theme component sets a token again, such as `--color-warning`, the app's own rules inside it read Astryx's value instead. Rename any app token that shares a name.",
+ },
+ {
+ type: 'prose',
+ text: "Put the `@layer` line above the app's `@import \"tailwindcss\"`, never below it. A `@layer` statement orders only the layer names the page has not seen yet, and the Tailwind import names `theme`, `base`, `components`, and `utilities` as it loads. Below that import, the statement can only add `reset`, `astryx-base`, and `astryx-theme` after Tailwind's `utilities`. That inverts the cascade: the Astryx reset then outranks every utility class in the app, and, for example, removes the borders and padding the app's utilities give its controls. Nothing reports it: the build and the browser console stay clean, and the `@layer` line still looks right in the source, so only the rendered page shows the problem.",
+ },
+ {
+ type: 'prose',
+ text: 'The load-order rule from the Tailwind section still applies: `globals.css` must be the first stylesheet the page loads, so its `@layer` line names the layers first.',
},
],
},
diff --git a/packages/cli/test/__golden__/no-icon-set/docs-tree.json b/packages/cli/test/__golden__/no-icon-set/docs-tree.json
index 3b8325f9df..c315038039 100644
--- a/packages/cli/test/__golden__/no-icon-set/docs-tree.json
+++ b/packages/cli/test/__golden__/no-icon-set/docs-tree.json
@@ -1197,7 +1197,8 @@
"styling-libraries/tailwind": {
"type": "docs.detail",
"sections": [
- "tailwind"
+ "tailwind",
+ "add-astryx-to-an-app-that-already-uses-tailwind"
],
"mentions": []
},
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon-set.json b/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
index accaa5ef46..a0b8a5849d 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
@@ -3,7 +3,7 @@
"type": "search",
"data": {
"query": "icon set",
- "matchCount": 387,
+ "matchCount": 389,
"results": [
{
"domain": "doc",
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt b/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
index c205d17e1c..9e94e95097 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
@@ -1,4 +1,4 @@
-Results for "icon set" (20 of 387)
+Results for "icon set" (20 of 389)
name: authoring/building-blocks/templates/build-the-template/template-assets/template-icons
section: use-astryx-icon
domain: doc
diff --git a/packages/core/README.md b/packages/core/README.md
index 2bdfb47c35..c4c656d48e 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -61,8 +61,8 @@ astryx gap-report # report a missing capability
## Related Packages
-| Package | Description |
-| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Package | Description |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`@astryxdesign/cli`](https://github.com/meta/astryx/tree/main/packages/cli) | CLI tooling: component docs, templates, scaffolding, codemods |
| [`@astryxdesign/theme-neutral`](https://github.com/meta/astryx/tree/main/packages/themes/neutral) | Muted, minimal theme (Lucide icons) |
@@ -139,6 +139,8 @@ export default function RootLayout({children}: {children: React.ReactNode}) {
No build plugins needed; Astryx ships pre-built CSS that works alongside Tailwind.
+This `globals.css` is the whole file for a new app. For an app that already uses Tailwind, keep its own `@import "tailwindcss"` and put the `@layer` line above it, as `astryx docs styling-libraries/tailwind` shows under "Add Astryx to an app that already uses Tailwind". A `@layer` line below the Tailwind import silently inverts the cascade.
+
**`src/app/globals.css`**
```css