An open source design system that's fully customizable and agent ready
TypeScript
docs: styling overview + fix theme import workflow (#7134)
Joeyfa4c5fcb0f33
diff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjsindex 5e66a830aa..be83fdf484 100644--- a/packages/cli/assets/docs/author-a-theme.doc.mjs+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs@@ -14,10 +14,10 @@ export const docs = {id: 'creating-a-custom-theme',title: 'Custom themes',content: [- {type: 'prose', text: "Start from a bundled theme or one contributed by an installed integration, or write one from scratch with defineTheme. `theme list` names each owner; when packages share a slug, pass `--package`. Only override tokens that differ from defaults; omitted tokens use the design system defaults."},- {type: 'code', lang: 'bash', label: 'Browse, then copy a theme in as editable source', code: 'astryx theme list\nastryx theme add stone\nastryx theme add ocean --package @acme/themes'},+ {type: 'prose', text: "Use an installed built theme as the base for ordinary customization. Import it into your source and pass it as `extends` to `defineTheme({extends: importedTheme, ...})`. Build the result, then add the local slug. Only eject when you need to own and maintain a full source fork."},+ {type: 'code', lang: 'bash', label: 'Add to use, eject to fork', code: 'astryx theme list\nastryx theme add stone --import\nastryx theme eject stone\nastryx theme build src/themes/stone/stoneTheme.ts\nastryx theme add stone --import'},{type: 'prose', text: "For an annotated map of the whole surface (every defineTheme field, the token families, and the component override syntax, each with the CLI command that prints its reference), run `astryx theme template`. It writes `theme.template.ts` into your project to read and copy from (`astryx init --features theme` writes it as part of project setup)."},- {type: 'prose', text: 'To apply a theme you created, see {@link generic:use-a-theme}. To generate colors from seed values, see the Palette section below.'},+ {type: 'prose', text: 'To apply a theme you created, see {@link generic:use-a-theme}. To generate colors from seed values, see the Palette section below. Use `theme eject` only when you want an independent source fork that no longer receives the package owner\u2019s updates.'},],},{diff --git a/packages/cli/assets/docs/styling-overview.doc.mjs b/packages/cli/assets/docs/styling-overview.doc.mjsnew file mode 100644index 0000000000..0be558b182--- /dev/null+++ b/packages/cli/assets/docs/styling-overview.doc.mjs@@ -0,0 +1,211 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file `astryx docs styling-overview`+ *+ * One question: "How do I set up CSS?"+ * Three paths, each with its exact imports.+ */++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ name: 'styling-overview',+ title: 'Styling overview',+ category: 'guide',+ description:+ 'How to set up CSS — exact imports for three paths: plain, Tailwind, and StyleX from source.',+ keywords: [+ 'styling',+ 'CSS',+ 'setup',+ 'imports',+ 'StyleX',+ 'Tailwind',+ 'astryx.css',+ 'globals.css',+ ],++ sections: [+ {+ id: 'pick-a-path',+ title: 'Pick a path',+ content: [+ {+ type: 'table',+ headers: ['Path', 'Good for', 'Build step?'],+ rows: [+ [+ 'Plain CSS',+ 'Most apps. Style with className, xstyle, or any CSS library.',+ 'None.',+ ],+ [+ 'Tailwind',+ 'Apps on Tailwind v4. A CSS bridge maps utility classes to design tokens.',+ "None beyond Tailwind's own.",+ ],+ [+ 'StyleX from source',+ 'Swizzled (ejected) components. Raw StyleX source needs a compiler plugin.',+ 'Yes \u2014 a StyleX bundler plugin.',+ ],+ ],+ },+ {+ type: 'prose',+ text: 'All three resolve to the same design tokens and support theming and dark mode. You can mix them in one app.',+ },+ ],+ },+ {+ id: 'plain',+ title: 'Plain CSS',+ content: [+ {+ type: 'code',+ lang: 'bash',+ label: 'Install',+ code: 'npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'globals.css',+ code: `@import "@astryxdesign/core/reset.css";+@import "@astryxdesign/core/astryx.css";+@import "@astryxdesign/theme-neutral/theme.css";`,+ },+ {+ type: 'prose',+ text: "Done. Components work out of the box \u2014 style them with `className`, `xstyle`, or `style`. Swap `theme-neutral` for any theme package (`astryx theme list` shows what's available).",+ },+ ],+ },+ {+ id: 'tailwind',+ title: 'Tailwind',+ content: [+ {+ type: 'code',+ lang: 'bash',+ label: 'Install (add to an existing Tailwind v4 app)',+ code: 'npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'globals.css',+ code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;++@import "tailwindcss/theme.css" layer(theme);+@import "tailwindcss/preflight.css" layer(base);+@import "@astryxdesign/core/reset.css";+@import "@astryxdesign/core/astryx.css";+@import "@astryxdesign/theme-neutral/theme.css";+@import "@astryxdesign/core/tailwind-theme.css";+@import "tailwindcss/utilities.css" layer(utilities);`,+ },+ {+ type: 'prose',+ text: 'The `@layer` declaration is critical \u2014 without it, component styles outrank Tailwind utilities and `className` overrides stop working. The bridge (`tailwind-theme.css`) maps classes like `text-primary`, `bg-surface`, and `rounded-lg` to design tokens with no JS.',+ },+ {+ type: 'prose',+ text: 'For Tailwind v3, see the layer workaround in {@link generic:migration}.',+ },+ ],+ },+ {+ id: 'stylex-from-source',+ title: 'StyleX from source',+ 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.',+ },+ {+ type: 'code',+ lang: 'bash',+ label: 'Install',+ code: 'npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'globals.css',+ code: `@layer reset, astryx-base, astryx-theme;++@import "@astryxdesign/core/reset.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:',+ },+ {+ type: 'table',+ headers: ['Bundler', 'Plugin'],+ rows: [+ ['Webpack', '@stylexjs/webpack-plugin'],+ ['Vite / Rollup', '@stylexjs/rollup-plugin'],+ ['Babel (any)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],+ ['Next.js (keep next/font)', '@stylexswc/nextjs-plugin'],+ ],+ },+ {+ type: 'prose',+ text: 'If a swizzled component renders with no styles and no error, a missing compiler is almost always why. See the StyleX Build Setup section of {@link generic:styling} for bundler config examples.',+ },+ ],+ },+ {+ id: 'what-each-file-does',+ title: 'What each import does',+ content: [+ {+ type: 'table',+ headers: ['Import', 'Layer', 'Purpose'],+ rows: [+ [+ 'reset.css',+ 'reset',+ 'Cross-browser reset (box-sizing, margins, color-scheme). Zero specificity via :where().',+ ],+ [+ 'astryx.css',+ 'astryx-base',+ 'Pre-compiled component styles. Required for plain and Tailwind. Omit when compiling from source.',+ ],+ [+ 'theme.css',+ 'astryx-theme',+ 'Design tokens (colors, spacing, radius, typography) as CSS custom properties. Swap the package for a different theme.',+ ],+ [+ 'tailwind-theme.css',+ '\u2014',+ 'Tailwind v4 bridge. Maps utility classes to design tokens. Pure CSS, no JS. Tailwind path only.',+ ],+ ],+ },+ ],+ },+ {+ id: 'further-reading',+ title: 'Further reading',+ content: [+ {+ type: 'list',+ style: 'unordered',+ items: [+ '{@link generic:styling} \u2014 xstyle, className, data-attribute selectors, design tokens in code.',+ '{@link generic:styling-libraries} \u2014 Tailwind bridge details, Panda, Chakra, MUI, CSS Modules, and non-CSS token resolution.',+ '{@link generic:use-a-theme} \u2014 applying themes, dark mode, nested themes. {@link generic:author-a-theme} \u2014 defineTheme, overrides, production builds.',+ '{@link generic:migration} \u2014 cascade layer audit, Tailwind v3 coexistence, and foundation smoke test.',+ ],+ },+ ],+ },+ ],+};diff --git a/packages/cli/assets/docs/theme.doc.mjs b/packages/cli/assets/docs/theme.doc.mjsindex e0dd370bc5..cb696c9ee8 100644--- a/packages/cli/assets/docs/theme.doc.mjs+++ b/packages/cli/assets/docs/theme.doc.mjs@@ -17,13 +17,13 @@ export const docs = {content: [{type: 'prose',- text: 'Install a theme package, wrap your app in `<Theme>`, and pick light or dark mode. For the full guide — available themes, integration themes, dark mode, nested themes, and production builds — see {@link generic:use-a-theme}.',+ text: 'Install a theme, import it with the CLI, and wire the generated module once. For the full guide — available themes, integration themes, dark mode, nested themes, and production builds — see {@link generic:use-a-theme}.',},{type: 'code',lang: 'tsx',- label: 'Basic theme setup',- code: "import {Theme} from '@astryxdesign/core';\nimport {neutralTheme} from '@astryxdesign/theme-neutral';\n\nfunction App() {\n return (\n <Theme theme={neutralTheme}>\n <YourApp />\n </Theme>\n );\n}",+ label: 'Wire the generated module once',+ code: "import {Theme} from '@astryxdesign/core';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n return (\n <Theme theme={themes[defaultThemeSlug]}>\n <YourApp />\n </Theme>\n );\n}",},],},@@ -39,7 +39,7 @@ export const docs = {type: 'code',lang: 'bash',label: 'Quick start',- code: 'astryx theme template # annotated starter file\nastryx theme add stone # copy an existing theme\nastryx theme build ./src/themes/my-theme.ts',+ code: 'astryx theme add stone --import # use an existing theme\nastryx theme eject stone # fork its source to customize\nastryx theme build src/themes/stone/stoneTheme.ts',},],},@@ -64,7 +64,7 @@ export const docs = {content: [{type: 'prose',- text: 'Install an integration and Astryx discovers its themes automatically. Copy one into your project with `astryx theme add <name> --package <integration>`. For the full walkthrough, see {@link generic:use-a-theme}.',+ text: 'Install an integration and Astryx discovers its themes automatically. Import one with `astryx theme add <name> --import --package <integration>`. Use `theme eject` only for an independent source fork. For the full walkthrough, see {@link generic:use-a-theme}.',},],},diff --git a/packages/cli/assets/docs/use-a-theme.doc.mjs b/packages/cli/assets/docs/use-a-theme.doc.mjsindex 264028141e..9b43c97b0c 100644--- a/packages/cli/assets/docs/use-a-theme.doc.mjs+++ b/packages/cli/assets/docs/use-a-theme.doc.mjs@@ -6,91 +6,203 @@ export const docs = {name: 'use-a-theme',title: 'Use a theme',category: 'guide',- keywords: ['theme', 'Theme', 'dark mode', 'light', 'nested', 'provider', 'SSR', 'built', 'runtime', 'neutralTheme', 'available themes'],- description: 'Apply a theme to your app: wrap in a provider, pick a theme, switch dark mode, nest themes, and choose runtime or built for production.',+ keywords: ['theme', 'Theme', 'dark mode', 'light', 'nested', 'provider', 'SSR', 'built', 'runtime', 'neutralTheme', 'available themes', 'theme add', 'import', 'astryx-themes', 'eject'],+ description:+ 'Apply a theme to your app: install, import with the CLI, wire the generated module, switch dark mode, nest themes, and choose runtime or built for production.',+sections: [{id: 'quick-start',title: 'Wrap your app in a theme',content: [- {type: 'code', lang: 'bash', label: 'Install a theme package', code: 'npm install @astryxdesign/theme-neutral'},- {type: 'code', lang: 'tsx', label: 'Basic theme setup (runtime injection)', code: "import {Theme} from '@astryxdesign/core';\nimport {neutralTheme} from '@astryxdesign/theme-neutral';\n\nfunction App() {\n return (\n <Theme theme={neutralTheme}>\n <YourApp />\n </Theme>\n );\n}"},- {type: 'code', lang: 'tsx', label: 'Optimized setup (pre-built CSS)', code: "import {Theme} from '@astryxdesign/core';\nimport {neutralTheme} from '@astryxdesign/theme-neutral/built';\nimport '@astryxdesign/theme-neutral/theme.css';\n\nfunction App() {\n return (\n <Theme theme={neutralTheme}>\n <YourApp />\n </Theme>\n );\n}"},- {type: 'prose', text: 'Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>`. The same pattern works for every theme; just swap the package and import name.'},- {type: 'prose', text: 'The default import uses runtime style injection, which works everywhere with no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.'},+ {+ type: 'code',+ lang: 'bash',+ label: 'Install and add a theme',+ code: 'npm install @astryxdesign/theme-neutral\nastryx theme add neutral --import',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Wire the generated module once',+ code: "import {Theme} from '@astryxdesign/core';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n return (\n <Theme theme={themes[defaultThemeSlug]}>\n <YourApp />\n </Theme>\n );\n}",+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Switch among added themes',+ code: "import {useState} from 'react';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",+ },+ {+ type: 'prose',+ text: '`theme add --import` records an installed package theme and regenerates `src/astryx-themes.ts` or `.js` with its built module, production CSS, and optional font CSS. In a project without `src`, the module is at the project root. The first imported theme becomes the default. `theme use <slug>` changes that default, and `theme remove <slug>` removes a non-default theme.',+ },+ {+ type: 'prose',+ text: 'Customize a package theme with `defineTheme({extends: importedTheme, ...})`, then build and add that local theme. Use `theme eject` only when you want an independent source fork that no longer receives the package owner\'s updates. For the full authoring guide, see {@link generic:author-a-theme}.',+ },+ ],+ },+ {+ title: 'Migrating Earlier Theme Copies',+ content: [+ {+ type: 'prose',+ text: 'A theme copied by the released `theme add` stays app source. The upgrade does not move, delete, or rewrite it. It only writes the missing same-stem descriptor with `maintained: false`, so the copy becomes a local theme.',+ },+ {+ type: 'code',+ lang: 'bash',+ label: 'Add descriptors to earlier copies',+ code: 'astryx upgrade --from 0.6.4 --path . --apply',+ },+ {+ type: 'prose',+ text: 'Before the upgrade runs, theme commands skip a descriptor-less copy in `src/themes`. `theme list` and doctor name it as unmigrated and show the upgrade command. A script that meant to copy source now runs `theme eject` with the same arguments. A script that meant to make the app use a theme runs `theme add --import`.',+ },+ {+ type: 'prose',+ text: '`ASTRYX_THEME` is no longer read. Run `theme add <slug> --import` and `theme use <slug>` to choose the default in a generated app theme module. When that module exists, component metadata reads its recorded default theme. Without the module, the released `package.json#astryx.theme` lookup keeps its meaning.',+ },],},{title: 'Available Themes',content: [- {type: 'prose', text: 'Install the theme package you want with `npm install @astryxdesign/theme-{name}`, then import its theme object as shown below.'},- {type: 'table', headers: ['Theme', 'Import', 'Description'], rows: [- ['Neutral', "import {neutralTheme} from '@astryxdesign/theme-neutral'", 'Muted, minimal aesthetic with Figtree typography. A good starting point.'],- ['Butter', "import {butterTheme} from '@astryxdesign/theme-butter'", 'Golden, buttery surfaces with blue accents; Sarina + Outfit type.'],- ['Chocolate', "import {chocolateTheme} from '@astryxdesign/theme-chocolate'", 'Warm brown tones and cozy beige; Fraunces + Albert Sans type.'],- ['Gothic', "import {gothicTheme} from '@astryxdesign/theme-gothic'", 'Dark-only atmospheric theme; deep blue-gray surfaces, distressed display type.'],- ['Matcha', "import {matchaTheme} from '@astryxdesign/theme-matcha'", 'Earthy greens; DM Sans + Playwrite US Trad type.'],- ['Stone', "import {stoneTheme} from '@astryxdesign/theme-stone'", 'Warm stone and slate tones; Montserrat + Figtree type.'],- ['Y2K', "import {y2kTheme} from '@astryxdesign/theme-y2k'", 'Playful Y2K pop; periwinkle body, holographic accents, Poppins + Crimson Text.'],- ]},- {type: 'prose', text: "All theme packages export from two subpaths:\n- `@astryxdesign/theme-{name}`: source theme (runtime injection)\n- `@astryxdesign/theme-{name}/built`: pre-built theme (pair with `theme.css`)"},+ {+ type: 'prose',+ text: 'Install the theme package you want with `npm install @astryxdesign/theme-{name}`, then import its slug with `theme add <slug> --import`. The CLI imports the package\'s built outputs for you.',+ },+ {+ type: 'table',+ headers: ['Theme', 'Add command', 'Description'],+ rows: [+ ['Neutral', 'astryx theme add neutral --import', 'Muted, minimal aesthetic with Figtree typography. A good starting point.'],+ ['Butter', 'astryx theme add butter --import', 'Golden, buttery surfaces with blue accents; Sarina + Outfit type.'],+ ['Chocolate', 'astryx theme add chocolate --import', 'Warm brown tones and cozy beige; Fraunces + Albert Sans type.'],+ ['Gothic', 'astryx theme add gothic --import', 'Dark-only atmospheric theme; deep blue-gray surfaces, distressed display type.'],+ ['Matcha', 'astryx theme add matcha --import', 'Earthy greens; DM Sans + Playwrite US Trad type.'],+ ['Stone', 'astryx theme add stone --import', 'Warm stone and slate tones; Montserrat + Figtree type.'],+ ['Y2K', 'astryx theme add y2k --import', 'Playful Y2K pop; periwinkle body, holographic accents, Poppins + Crimson Text.'],+ ],+ },+ {+ type: 'prose',+ text: 'Every first-party package exports its built theme at `@astryxdesign/theme-{name}/built`, production CSS at `/theme.css`, and font loading CSS at `/fonts.css`. `theme add --import` writes those imports into the generated app module.',+ },],},{title: 'Theme Props',content: [- {type: 'prose', text: "`<Theme>` takes `theme` (required), `mode` (`'system'` by default, or `'light'`/`'dark'`), and `children`. For every prop, run `astryx component Theme`."},+ {+ type: 'prose',+ text: "`<Theme>` takes `theme` (required), `mode` (`'system'` by default, or `'light'`/`'dark'`), and `children`. For every prop, run `astryx component Theme`.",+ },],},{id: 'integration-themes',title: 'Using a Theme from an Integration',content: [- {type: 'prose', text: 'Install the integration as a direct dependency and Astryx discovers its source themes and guide topics without an `astryx.config` file. Install Core too because the copied source imports `defineTheme` from `@astryxdesign/core/theme`.'},- {type: 'code', lang: 'bash', label: 'Install, inspect, copy, and build', code: 'npm install @astryxdesign/core @acme/brand-integration\nastryx theme list --package @acme/brand-integration\nastryx docs brand-theme\nastryx theme add ocean --package @acme/brand-integration\nastryx theme build src/themes/ocean/oceanTheme.ts'},- {type: 'prose', text: "The copy is editable project source, not a reference back into node_modules. The complete theme directory comes with it, including its typed `.doc.mjs`, nested token and palette modules, and receipts. A second add refuses to overwrite those files unless you pass `--overwrite`."},+ {+ type: 'prose',+ text: 'Install the integration as a direct dependency. Astryx discovers its themes and guides without an `astryx.config` entry. A theme can be added only when the installed package exports its built module and production stylesheet.',+ },+ {+ type: 'code',+ lang: 'bash',+ label: 'Install, inspect, and add',+ code: 'npm install @astryxdesign/core @acme/brand-integration\nastryx theme list --package @acme/brand-integration\nastryx docs brand-theme\nastryx theme add ocean --import --package @acme/brand-integration',+ },+ {+ type: 'prose',+ text: '`theme add --import` keeps the owner package in the app record and imports its built module, stylesheet, and optional font stylesheet. Package updates continue to reach the app. Run `theme eject ocean --package @acme/brand-integration` only to copy the source and descriptor into `src/themes/ocean` as an independent local fork.',+ },],},{id: 'light-dark-mode',title: 'Dark mode',content: [- {type: 'prose', text: "Use [light, dark] tuples in token values for automatic mode switching. Use mode='system' (default) on Theme to follow OS preference."},- {type: 'code', lang: 'tsx', label: 'Light/dark tuple', code: "'--color-accent': ['#0064E0', '#2694FE'],\n// ^light ^dark"},- {type: 'code', lang: 'tsx', label: 'Toggle with a button', code: "const [mode, setMode] = useState<'light' | 'dark'>('light');\n\n<Theme theme={myTheme} mode={mode}>\n <Button\n label={mode === 'light' ? 'Switch to Dark' : 'Switch to Light'}\n onClick={() => setMode(m => (m === 'light' ? 'dark' : 'light'))}\n />\n</Theme>;"},- {type: 'prose', text: 'To create a theme with custom dark mode colors, see {@link generic:author-a-theme}.'},+ {+ type: 'prose',+ text: "Use [light, dark] tuples in token values for automatic mode switching. Use mode='system' (default) on Theme to follow OS preference.",+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Light/dark tuple',+ code: "'--color-accent': ['#0064E0', '#2694FE'],\n// ^light ^dark",+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Toggle with a button',+ code: "const [mode, setMode] = useState<'light' | 'dark'>('light');\n\n<Theme theme={myTheme} mode={mode}>\n <Button\n label={mode === 'light' ? 'Switch to Dark' : 'Switch to Light'}\n onClick={() => setMode(m => (m === 'light' ? 'dark' : 'light'))}\n />\n</Theme>;",+ },+ {+ type: 'prose',+ text: 'To create a theme with custom dark mode colors, see {@link generic:author-a-theme}.',+ },],},{id: 'nesting-themes',title: 'Nested themes',content: [- {type: 'prose', text: 'Wrap different sections in separate `<Theme>` providers.'},- {type: 'code', lang: 'tsx', label: 'Dark sidebar with light content', code: "<Theme theme={lightTheme} mode=\"light\">\n <Layout\n header={<LayoutHeader>...</LayoutHeader>}\n start={\n <Theme theme={darkTheme} mode=\"dark\">\n <LayoutPanel>{/* Dark sidebar */}</LayoutPanel>\n </Theme>\n }\n content={<LayoutContent>{/* Light content */}</LayoutContent>}\n />\n</Theme>"},+ {+ type: 'prose',+ text: 'Wrap different sections in separate `<Theme>` providers.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Dark sidebar with light content',+ code: "<Theme theme={lightTheme} mode=\"light\">\n <Layout\n header={<LayoutHeader>...</LayoutHeader>}\n start={\n <Theme theme={darkTheme} mode=\"dark\">\n <LayoutPanel>{/* Dark sidebar */}</LayoutPanel>\n </Theme>\n }\n content={<LayoutContent>{/* Light content */}</LayoutContent>}\n />\n</Theme>",+ },],},{title: 'Runtime vs Built Themes',content: [- {type: 'prose', text: 'Themes work in two modes:'},- {type: 'table', headers: ['', 'Runtime (source)', 'Built'], rows: [- ['Import (published theme)', '@astryxdesign/theme-{name}', '@astryxdesign/theme-{name}/built + theme.css'],- ['Import (custom theme)', 'defineTheme() directly', 'Built .js + .css from `astryx theme build`'],- ['How it works', 'useInsertionEffect injects <style> at hydration', 'Pre-compiled .css file loaded with the page'],- ['Component overrides', 'Injected client-only', 'In static CSS: present during SSR'],- ['SSR safe', 'Tokens yes, component overrides flash on hydration', 'Fully SSR safe: no flash'],- ['Best for', 'Dev, prototyping, client-only SPAs', 'Production, SSR apps (Next.js, Remix)'],- ]},- {type: 'list', style: 'do', items: [- 'Use the /built subpath + theme.css for production SSR apps.',- 'Use runtime themes during development for fast iteration.',- 'Run `astryx theme build` for custom themes to get the built artifacts.',- ]},- {type: 'list', style: 'dont', items: [- 'Use runtime themes in production SSR apps; component overrides will flash on hydration.',- "Import /built without the CSS file; component overrides won't apply.",- ]},- {type: 'prose', text: 'To build a custom theme for production, see the Build section of {@link generic:author-a-theme}.'},+ {+ type: 'prose',+ text: 'Themes work in two modes:',+ },+ {+ type: 'table',+ headers: ['', 'Runtime (source)', 'Built'],+ rows: [+ ['Import (published theme)', '@astryxdesign/theme-{name}', '@astryxdesign/theme-{name}/built + theme.css'],+ ['Import (custom theme)', 'defineTheme() directly', 'Built .js + .css from `astryx theme build`'],+ ['How it works', 'useInsertionEffect injects <style> at hydration', 'Pre-compiled .css file loaded with the page'],+ ['Component overrides', 'Injected client-only', 'In static CSS: present during SSR'],+ ['SSR safe', 'Tokens yes, component overrides flash on hydration', 'Fully SSR safe: no flash'],+ ['Best for', 'Dev, prototyping, client-only SPAs', 'Production, SSR apps (Next.js, Remix)'],+ ],+ },+ {+ type: 'list',+ style: 'do',+ items: [+ 'Use `theme add --import` for production apps; it wires the built module and CSS.',+ 'Use runtime themes during development for fast iteration.',+ 'Run `astryx theme build` for custom themes to get the built artifacts.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Use runtime themes in production SSR apps; component overrides will flash on hydration.',+ "Import /built without the CSS file; component overrides won't apply.",+ ],+ },+ {+ type: 'prose',+ text: 'To build a custom theme for production, see the Build section of {@link generic:author-a-theme}.',+ },],},],diff --git a/packages/cli/clients/cli/commands/docs.test.mjs b/packages/cli/clients/cli/commands/docs.test.mjsindex 9b20ceca3a..c3746f457e 100644--- a/packages/cli/clients/cli/commands/docs.test.mjs+++ b/packages/cli/clients/cli/commands/docs.test.mjs@@ -198,7 +198,7 @@ describe('blocks as text', () => {it('prints the labels of a real section above their fences', async () => {const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);expect(status).toBe(0);- expect(stdout).toContain('Basic theme setup:\n```tsx\nimport {Theme}');+ expect(stdout).toContain('Wire the generated module once:\n```tsx\nimport {Theme}');}, SLOW);});