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/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,41 @@ 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 such as `text-primary` and `bg-surface` to system tokens, so in an app that already defines those names 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: "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/core/README.md

@@ -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