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

.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

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.",
         },
       ],
     },

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.',
         },
       ],
     },

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": []
   },

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",

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

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