An open source design system that's fully customizable and agent ready
TypeScript
docs: import the layer-order stylesheet first in Tailwind and migration setup (#7534)
Cindy Zhange7ad1c4c5189
diff --git a/.changeset/cli-docs-tailwind-layer-first-import.md b/.changeset/cli-docs-tailwind-layer-first-import.mdnew file mode 100644index 0000000000..ad0c8978ee--- /dev/null+++ b/.changeset/cli-docs-tailwind-layer-first-import.md@@ -0,0 +1,6 @@+---+'@astryxdesign/cli': patch+---++[docs] The Tailwind and migration setup docs now say that `globals.css` (or a `layers.css` holding only the `@layer` line) must be the first import in the root layout or app entry, before the `astryx-themes` module or any component that imports theme CSS; otherwise Tailwind preflight overrides Astryx base styles and theme overrides lose. The Tailwind v3 coexistence snippet moves its `@layer` line into a `layers.css` imported first, because Next.js (webpack or Turbopack) hoists CSS imports above an inline `@layer` line.+@cixzhangdiff --git a/packages/cli/assets/docs/tree/migration-setup.doc.mjs b/packages/cli/assets/docs/tree/migration-setup.doc.mjsindex 85c5323151..48525f0a2b 100644--- a/packages/cli/assets/docs/tree/migration-setup.doc.mjs+++ b/packages/cli/assets/docs/tree/migration-setup.doc.mjs@@ -129,15 +129,31 @@ export function AppRoot({children}: {children: React.ReactNode}) {},{type: 'prose',- text: 'On Tailwind v3 there is no preflight.css to import, so wrap the @tailwind base directive in a named layer instead. Keep utilities unlayered so existing app utility classes still win everywhere.',+ text: 'A layer\'s rank is set by the first stylesheet on the page that names it, so the global CSS file (or a `layers.css` holding only the `@layer` line) must be the first import in the root layout or app entry. Import it before any module that imports Astryx or theme CSS, including the `astryx-themes` module generated by `astryx theme add` and a root component like the `AppRoot` above that imports `theme.css`. If a theme stylesheet loads first, Tailwind preflight overrides Astryx base styles and theme overrides lose.',},{type: 'code',- lang: 'css',- label: 'Tailwind v3 coexistence',- code: `@layer reset, tw-preflight, astryx-base, astryx-theme;+ lang: 'tsx',+ label: 'Root layout or app entry',+ code: `import './globals.css'; // first: declares the cascade-layer order-@import "@astryxdesign/core/reset.css";+import {AppRoot} from './AppRoot';`,+ },+ {+ type: 'prose',+ text: 'On Tailwind v3 there is no preflight.css to import, so wrap the @tailwind base directive in a named layer instead. Keep utilities unlayered so existing app utility classes still win everywhere. Put the `@layer` order line in its own `layers.css` and import it first, before `globals.css`: Next.js (webpack or Turbopack) and other bundlers that hoist CSS imports move the imported files above an inline `@layer` line, so the order would arrive too late.',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'layers.css (imported first)',+ code: `@layer reset, tw-preflight, astryx-base, astryx-theme;`,+ },+ {+ type: 'code',+ lang: 'css',+ label: 'globals.css (Tailwind v3 coexistence)',+ code: `@import "@astryxdesign/core/reset.css";@import "@astryxdesign/core/astryx.css";@import "@astryxdesign/theme-neutral/theme.css";@@ -147,6 +163,15 @@ export function AppRoot({children}: {children: React.ReactNode}) {@tailwind components;@tailwind utilities; /* unlayered: legacy utility classes keep winning */`,},+ {+ type: 'code',+ lang: 'tsx',+ label: 'Root layout or app entry (Tailwind v3)',+ code: `import './layers.css'; // first: declares the cascade-layer order+import './globals.css';++import {AppRoot} from './AppRoot';`,+ },],},{@@ -186,7 +211,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {type: 'list',style: 'unordered',items: [- 'Declare the canonical @layer order once, before any @import. With webpack-based bundlers (including Next.js) the order declaration must live in its own CSS file imported first, such as layers.css, because webpack hoists @import content above the inline CSS that follows it.',+ 'Declare the canonical @layer order once, before any @import. With Next.js (webpack or Turbopack) and other bundlers that hoist CSS imports, the order declaration must live in its own CSS file imported first, such as layers.css, because the bundler hoists @import content above the inline CSS that follows it.','Audit every pre-existing global or reset stylesheet and assign each one to a layer deliberately. Top-level imports without layer() stay unlayered and beat every layer; imports nested inside a layered file inherit that layer.','Remove or demote the app legacy reset. The design system ships its own :where() reset in the lowest layer, so any app reset belongs in that same reset layer and never in a layer above astryx-base.','Layer Tailwind preflight. On Tailwind v4, import preflight.css with layer(base). On Tailwind v3, wrap the @tailwind base directive in a named layer (see the snippet in Theme and CSS Setup). Unlayered preflight overrides theme CSS silently.',diff --git a/packages/cli/assets/docs/tree/tailwind.doc.mjs b/packages/cli/assets/docs/tree/tailwind.doc.mjsindex 33d7ea3d47..2303bdf47b 100644--- a/packages/cli/assets/docs/tree/tailwind.doc.mjs+++ b/packages/cli/assets/docs/tree/tailwind.doc.mjs@@ -47,6 +47,18 @@ export const docs = {type: 'prose',text: 'Pre-declare every layer before any imports. This keeps reset lowest, Tailwind preflight above reset, component/theme styles in the middle, and Tailwind utilities last so utility classes on `className` can intentionally override component defaults.',},+ {+ type: 'prose',+ text: 'A layer\'s rank is set by the first stylesheet on the page that names it, so this order only holds when `globals.css` loads first. Make it the first import in the root layout or app entry, before any module that imports Astryx or theme CSS. That includes the `astryx-themes` module generated by `astryx theme add` and any root component that imports a theme\'s `theme.css`. If a theme stylesheet loads first, Tailwind preflight overrides Astryx base styles and theme overrides lose. If `globals.css` cannot come first, move the `@layer` line into its own `layers.css` and import that first instead.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Root layout or app entry',+ code: `import './globals.css'; // first: declares the cascade-layer order++import {themes, defaultThemeSlug} from './astryx-themes';`,+ },{type: 'code',lang: 'tsx',