Skip to content

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.mjs
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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);
});