An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): every setup path loads the prebuilt stylesheets (#7587)
Cindy Zhang56f1201acca9
diff --git a/.changeset/setup-docs-prebuilt-css.md b/.changeset/setup-docs-prebuilt-css.mdnew file mode 100644index 0000000000..37703dedd0--- /dev/null+++ b/.changeset/setup-docs-prebuilt-css.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[docs] The styling setup docs now load the prebuilt stylesheets on every path. The "StyleX from source" path becomes "StyleX for your own code": it keeps `astryx.css` and points the StyleX compiler at your own and swizzled source only. A new "Other Astryx packages" section lists each package's stylesheet (`richtext.css`, `lab.css`, `charts.css`) and where to import it. Getting started no longer lists the two example setups that compile Astryx source; the remaining examples all load `astryx.css`.++@cixzhangdiff --git a/packages/cli/assets/docs/getting-started.doc.mjs b/packages/cli/assets/docs/getting-started.doc.mjsindex 9f6fd4021d..93a9a8efc3 100644--- a/packages/cli/assets/docs/getting-started.doc.mjs+++ b/packages/cli/assets/docs/getting-started.doc.mjs@@ -185,16 +185,6 @@ const overrides = stylex.create({'Next.js + Tailwind bridge','[apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind)',],- [- 'Next.js Source',- 'Next.js importing from source',- '[apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source)',- ],- [- 'Vite',- 'Vite',- '[apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite)',- ],['Vite + Tailwind','Vite + Tailwind bridge',diff --git a/packages/cli/assets/docs/styling-overview.doc.mjs b/packages/cli/assets/docs/styling-overview.doc.mjsindex 9917612327..72cde2c32d 100644--- a/packages/cli/assets/docs/styling-overview.doc.mjs+++ b/packages/cli/assets/docs/styling-overview.doc.mjs@@ -4,7 +4,8 @@* @file `astryx docs styling-overview`** One question: "How do I set up CSS?"- * Three paths, each with its exact imports.+ * Three paths, each with its exact imports. Every path loads the prebuilt+ * stylesheets (spec:AST-080 FR5); none compiles Astryx package source.*//** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */@@ -14,7 +15,7 @@ export const docs = {title: 'Styling overview',category: 'guide',description:- 'How to set up CSS — exact imports for three paths: plain, Tailwind, and StyleX from source.',+ 'How to set up CSS — exact imports for three paths: plain, Tailwind, and StyleX for your own code — plus the stylesheet each Astryx package ships.',keywords: ['styling','CSS',@@ -46,15 +47,15 @@ export const docs = {"None beyond Tailwind's own.",],[- 'StyleX from source',- 'Swizzled (ejected) components. Raw StyleX source needs a compiler plugin.',- 'Yes \u2014 a StyleX bundler plugin.',+ 'StyleX for your own code',+ 'Your own `stylex.create()` styles and swizzled (ejected) components. Astryx itself stays prebuilt.',+ 'Yes \u2014 a StyleX plugin for your own code.',],],},{type: 'prose',- text: 'All three resolve to the same design tokens and support theming and dark mode. You can mix them in one app.',+ text: 'All three load the same prebuilt Astryx stylesheets, resolve to the same design tokens, and support theming and dark mode. None of them compiles Astryx package source. You can mix them in one app.',},],},@@ -117,12 +118,12 @@ export const docs = {],},{- id: 'stylex-from-source',- title: 'StyleX from source',+ id: 'stylex-own-code',+ title: 'StyleX for your own code',content: [{type: 'prose',- text: 'Only needed when you swizzle a component (`astryx swizzle <Component>`) or write your own StyleX. The plain path already supports `xstyle` overrides \u2014 this path is for editing component internals. Some built-in page templates also use StyleX for layout; if you scaffold one and see "Unexpected stylex.create call at runtime", add the compiler plugin for your bundler below.',+ text: 'Only needed when you write your own StyleX (`stylex.create()`) or swizzle a component (`astryx swizzle <Component>`), which copies its StyleX source into your app. The plain path already supports `xstyle` overrides \u2014 this path is for your own StyleX code. Some built-in page templates also use StyleX for layout; if you scaffold one and see "Unexpected stylex.create call at runtime", add the compiler plugin for your bundler below.',},{type: 'code',@@ -134,14 +135,13 @@ export const docs = {type: 'code',lang: 'css',label: 'globals.css',- code: `@layer reset, astryx-base, astryx-theme;--@import "@astryxdesign/core/reset.css";+ code: `@import "@astryxdesign/core/reset.css";+@import "@astryxdesign/core/astryx.css";@import "@astryxdesign/theme-neutral/theme.css";`,},{type: 'prose',- text: 'No `astryx.css` \u2014 the StyleX compiler produces component styles from source. Add the plugin for your bundler:',+ text: 'Keep `astryx.css`: Astryx component styles always come from the prebuilt stylesheets. Point the StyleX compiler at your own source only, never at `node_modules/@astryxdesign`. Add the plugin for your bundler:',},{type: 'table',@@ -149,7 +149,10 @@ export const docs = {rows: [['Webpack', '@stylexjs/webpack-plugin'],['Vite / Rollup', '@stylexjs/rollup-plugin'],- ['Babel (any)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],+ [+ 'Babel (any)',+ '@stylexjs/babel-plugin + @stylexjs/postcss-plugin',+ ],['Next.js (keep next/font)', '@stylexswc/nextjs-plugin'],],},@@ -159,6 +162,37 @@ export const docs = {},],},+ {+ id: 'other-packages',+ title: 'Other Astryx packages',+ content: [+ {+ type: 'prose',+ text: 'Every Astryx package whose components carry styles ships its own prebuilt stylesheet. Import it after `astryx.css` for each package you use. All of them place their rules in the same `astryx-base` layer, so your theme overrides win over every package.',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'globals.css',+ code: `@import "@astryxdesign/core/reset.css";+@import "@astryxdesign/core/astryx.css";+@import "@astryxdesign/richtext/richtext.css"; /* Rich Text */+@import "@astryxdesign/lab/lab.css"; /* Lab */+@import "@astryxdesign/charts/charts.css"; /* Charts */+@import "@astryxdesign/theme-neutral/theme.css";`,+ },+ {+ type: 'table',+ headers: ['Package', 'Stylesheet'],+ rows: [+ ['@astryxdesign/core', '@astryxdesign/core/astryx.css'],+ ['@astryxdesign/richtext', '@astryxdesign/richtext/richtext.css'],+ ['@astryxdesign/lab', '@astryxdesign/lab/lab.css'],+ ['@astryxdesign/charts', '@astryxdesign/charts/charts.css'],+ ],+ },+ ],+ },{id: 'what-each-file-does',title: 'What each import does',@@ -175,7 +209,12 @@ export const docs = {['astryx.css','astryx-base',- 'Pre-compiled component styles. Required for plain and Tailwind. Omit when compiling from source.',+ 'Prebuilt component styles. Required on every path.',+ ],+ [+ 'richtext.css, lab.css, charts.css',+ 'astryx-base',+ 'Prebuilt styles for each other Astryx package you use. Load after astryx.css.',],['theme.css',diff --git a/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs b/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjsindex 519ad5ea62..79cb2cef0b 100644--- a/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs+++ b/packages/cli/assets/docs/tree/tokens-and-setup.doc.mjs@@ -77,7 +77,7 @@ const styles = stylex.create({content: [{type: 'prose',- text: 'Astryx components ship pre-compiled, so consuming the published package needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',+ text: 'Astryx components ship pre-compiled: `astryx.css` and each package\'s own stylesheet hold all of their styles, so consuming the published packages needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',},{type: 'table',@@ -105,7 +105,7 @@ const styles = stylex.create({export default stylexPlugin({rsOptions: {- // Resolve @astryxdesign/core's StyleX so swizzled component source compiles.+ // Resolve the Astryx token modules that swizzled source imports.aliases: {'@/*': ['./src/*']},unstable_moduleResolution: {type: 'commonJS'},},@@ -120,6 +120,7 @@ export default stylexPlugin({'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.','A Babel config turns off SWC in Next.js; skip it if you need `next/font`.','Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',+ 'Keep loading `astryx.css` with a StyleX compiler in place. The compiler builds your own and swizzled source only; never add `node_modules/@astryxdesign` to its inputs.',],},],