An open source design system that's fully customizable and agent ready
TypeScript
docs: restore guidance the layout and theme splits dropped (#7204)
Joeycc0df20f09c9
diff --git a/.changeset/restore-split-doc-guidance.md b/.changeset/restore-split-doc-guidance.mdnew file mode 100644index 0000000000..8ba4edacb7--- /dev/null+++ b/.changeset/restore-split-doc-guidance.md@@ -0,0 +1,8 @@+---+'@astryxdesign/cli': patch+---++[docs] `astryx docs layout` opens with its overview again, and `astryx docs author-a-theme` and `use-a-theme` restore guidance the theme split dropped: what a bad `extends` base does, how adaptation rules are validated, what `__built` means, the icon-registry specifier traps, `registerTheme`, and wiring built themes in development too.++(#7204)+@josephfarinadiff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjsindex c4123a86b8..2bedadf05a 100644--- a/packages/cli/assets/docs/author-a-theme.doc.mjs+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs@@ -34,7 +34,7 @@ export const docs = {{title: 'defineTheme',content: [- {type: 'prose', text: "defineTheme creates a theme from token overrides and optional scale configs. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values, token by token. localTokens accepts any valid CSS custom-property name; prefixes do not establish ownership. One caveat for the accent: overriding --color-accent in tokens re-points the reference tokens (--color-accent-muted, --color-text-accent, --color-icon-accent) but NOT --color-on-accent, which stays baked from the color.accent seed. To give each scheme its own accent with a consistent derived palette, pass a [light, dark] tuple to color.accent instead of overriding the token."},+ {type: 'prose', text: "defineTheme creates a theme from token overrides and optional scale configs. Only override tokens that differ from defaults; omitted tokens use the design system defaults. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values, token by token. localTokens accepts any valid CSS custom-property name; prefixes do not establish ownership. One caveat for the accent: overriding --color-accent in tokens re-points the reference tokens (--color-accent-muted, --color-text-accent, --color-icon-accent) but NOT --color-on-accent, which stays baked from the color.accent seed. To give each scheme its own accent with a consistent derived palette, pass a [light, dark] tuple to color.accent instead of overriding the token."},{type: 'code', lang: 'tsx', label: 'defineTheme with scale configs', code: "import {defineTheme} from '@astryxdesign/core/theme';\n\nconst myTheme = defineTheme({\n name: 'my-theme',\n // accent: single hex, or [light, dark] tuple to seed each scheme separately\n color: { accent: ['#7B61FF', '#9B85FF'], neutralStyle: 'cool' },\n typography: {\n scale: { base: 14, ratio: 1.2 },\n body: { family: 'Inter', fallbacks: '-apple-system, sans-serif' },\n },\n radius: { base: 4, multiplier: 1 },\n motion: { fast: 175, medium: 410, ratio: 0.75 },\n tokens: {\n // Explicit overrides take precedence over scale-generated values\n '--color-background-body': ['#FFFFFF', '#0A0A0A'],\n },\n});"},{type: 'table', headers: ['Config', 'Generates', 'Parameters'], rows: [['color', '--color-accent, --color-background-*, --color-text-*, --color-border, etc.', 'accent? (hex or [light, dark] tuple; omit for neutral-only), neutralStyle? (warm|cool|neutral), contrast? (standard|high)'],@@ -60,7 +60,7 @@ export const docs = {['typography, motion, radius, color', 'Child config replaces base entirely (these are scale inputs, not additive).'],['adaptations', 'Width-breakpoint overrides merge by fixed name. Inherited ordered rules keep their relative order; child rules append and re-resolve against the child root axes.'],]},- {type: 'prose', text: "Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme's CSS does not need to be loaded next to it."},+ {type: 'prose', text: "Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme's CSS does not need to be loaded next to it. A base that is not a theme (most often an import that missed) throws when `defineTheme` runs, rather than producing a theme that silently inherits nothing."},{type: 'prose', text: 'For the integration-specific guidance on mapping a palette to tokens when extending, see `astryx docs cli/integrations/building-blocks/themes/define-the-theme`.'},],},@@ -71,7 +71,7 @@ export const docs = {{type: 'code', lang: 'tsx', label: 'Component overrides with standard CSS', code: "components: {\n card: {\n base: { borderRadius: '20px', padding: '24px' },\n },\n button: {\n base: {\n borderRadius: '9999px',\n textTransform: 'uppercase',\n '--button-focus-offset': '3px',\n },\n 'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },\n },\n}"},{type: 'prose', text: "Run `astryx theme targets` for every themeable key in the system (`astryx theme targets <Name>` to scope it, `--json` to lint a theme against it), and `astryx component <Name>` for one component's theming targets, public CSS variables, and which standard CSS properties are supported."},{type: 'list', style: 'do', items: ['Write standard CSS properties (borderRadius, padding); the pipeline expands them into internal vars.', 'Set public CSS vars directly when no standard property equivalent exists.']},- {type: 'list', style: 'dont', items: ['Set private CSS vars (prefixed --_) directly. Use standard CSS properties instead. `astryx theme build` will error.']},+ {type: 'list', style: 'dont', items: ['Set private CSS vars (prefixed --_) directly. Use standard CSS properties instead. `astryx theme build` will error.', 'Set a public CSS var the component does not define. It compiles to CSS that never applies, and the build does not warn. Take the names from `astryx component <Name>`.']},],},{@@ -94,7 +94,7 @@ export const docs = {['contrast', 'more | less | no-preference'],['motion', 'reduce | no-preference'],]},- {type: 'prose', text: "`widthBreakpoints` are fixed named start points. Defaults are 640 / 768 / 1024 / 1280 / 1536 CSS pixels. `from` includes its point; `below` excludes it."},+ {type: 'prose', text: "`widthBreakpoints` are fixed named start points. Defaults are 640 / 768 / 1024 / 1280 / 1536 CSS pixels. `from` includes its point; `below` excludes it. Breakpoint configuration alone emits no CSS."},],},{@@ -103,6 +103,7 @@ export const docs = {content: [{type: 'prose', text: "Precedence follows rule order. Root theme values apply first, then every matching rule in declaration order. A later rule may deliberately restore a root value. `onDark` and `onLight` media-surface overrides apply after adaptations and win on the same leaf."},{type: 'prose', text: "`extends` preserves the base rule order and appends child rules. Inherited conditions use the child's effective breakpoint map. An empty child rule is a no-op, not a removal operator."},+ {type: 'prose', text: "A rule may replace a theme-local token only when the exact name is already enrolled by root `localTokens` or an enrolled base. Component writes in a rule are validated exactly like root `components`: same targets, axes, and value domains. The one addition is that a rule may not be the only place a custom value is enrolled: a value that is valid only because a theme enrolls it generates unconditional type augmentation, so declare it on the root theme first and let rules restyle it. Built-in values need no root declaration. When rules can match together, their ordered portable and local token writes are validated as one effective graph; any reachable cycle fails before CSS is emitted."},{type: 'prose', text: 'Adaptations compile to CSS media queries with no resize listener or styling rerender. Runtime and `astryx theme build` use the same compiler, but only a built theme is present at first paint in an SSR app.'},],},@@ -118,8 +119,9 @@ export const docs = {['ocean.d.ts', 'TypeScript declarations for the theme and icon registry exports'],['ocean.variants.d.ts', "(Optional) Module augmentations for custom component prop values"],]},+ {type: 'prose', text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it. Load the generated CSS wherever you load the module.'},{type: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core';\nimport {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<Theme theme={oceanTheme}>\n <App />\n</Theme>"},- {type: 'prose', text: "After upgrading Astryx, rerun `astryx theme build` for every custom prebuilt theme. Deploy the regenerated files together. The build also warns when the theme names font families it does not load. See {@link generic:typography} for the full recipe."},+ {type: 'prose', text: "After upgrading Astryx, rerun `astryx theme build` for every custom prebuilt theme. Deploy the regenerated files together. The runtime intentionally trusts `__built: true` and will not repair stale CSS from an older build. The build also warns when the theme names font families it does not load. See {@link generic:typography} for the full recipe."},{type: 'prose', text: 'For the runtime vs built tradeoff, see the Runtime vs Built section of {@link generic:use-a-theme}.'},],},@@ -129,13 +131,15 @@ export const docs = {content: [{type: 'prose', text: "`theme build` emits an icon import when it detects a named import used by the theme's `icons:` field. It does not compile that registry module. Move the registry to a separate module and use a named import."},{type: 'code', lang: 'bash', label: 'Compiling the icon registry sidecar', code: "# Emit the built theme\nastryx theme build ./src/themes/ocean.ts -o dist/theme.css --icons-specifier ./icons.mjs\n\n# Compile the icon registry alongside it\nesbuild src/themes/icons.tsx --bundle --format=esm --outfile=dist/icons.mjs \\\n --external:react --external:lucide-react --jsx=automatic"},+ {type: 'prose', text: 'In the example above, the generated theme imports `./icons.mjs` from `dist`. If the second command is skipped, `theme build` can still succeed, but loading or bundling the generated module fails because `dist/icons.mjs` is missing. `--icons-specifier` changes the emitted import; it does not create or verify the target file. Match the specifier to a module that resolves from the generated JS file.'},+ {type: 'prose', text: 'Without `--icons-specifier`, the detected source import specifier is emitted unchanged. In the default flow without `--out`, a bundler can resolve an extensionless `./icons` to the neighboring `icons.tsx` source, but Node ESM does not perform that lookup and reports `ERR_MODULE_NOT_FOUND`. Moving the output with `--out` also changes where relative imports resolve from.'},{type: 'prose', text: 'Keep `react` and the icon library external so the registry does not bundle its own copies of those dependencies.'},],},{title: 'Building a Theme Family',content: [- {type: 'prose', text: 'Use family mode when an app switches among one base theme and its selected descendants. The build writes one keyed CSS file containing every member, plus one keyed JavaScript module and one declaration file.'},+ {type: 'prose', text: 'Use family mode when an app switches among one base theme and its selected descendants. The build writes one keyed CSS file containing every member, plus one keyed JavaScript module and one declaration file, beside the root source.'},{type: 'code', lang: 'bash', label: 'Build one family', code: "astryx theme build --family \\\n ./src/themes/ocean.mjs \\\n ./src/themes/ocean-calm.mjs \\\n ./src/themes/ocean-calm-deep.mjs \\\n --family-key ocean-family"},{type: 'prose', text: 'The family stylesheet eagerly downloads every selected member so first paint is complete. Switching members changes only the theme identity; it does not add, remove, or reorder stylesheets.'},],@@ -143,9 +147,10 @@ export const docs = {{title: 'Token Utilities',content: [- {type: 'prose', text: 'Use `tokenVar()` when a non-StyleX styling library wants a CSS variable reference, and `resolveThemeTokens()` when JavaScript needs token values for a specific theme and mode without React context.'},+ {type: 'prose', text: 'Use `tokenVar()` when a non-StyleX styling library wants a CSS variable reference, and `resolveThemeTokens()` when JavaScript needs token values for a specific theme and mode without React context. Themes are registered by name when created with `defineTheme()`; call `registerTheme(theme)` for prebuilt or object-literal themes that need name-based SSR lookup.'},{type: 'code', lang: 'ts', label: 'CSS var references for styling-library configs', code: "import {tokenVar, tokenVars} from '@astryxdesign/core/theme/tokens';\n\nconst pandaOrEmotionTheme = {\n colors: {\n text: tokenVar('--color-text-primary'),\n surface: tokenVars['--color-background-surface'],\n },\n};"},{type: 'code', lang: 'ts', label: 'Resolve token values without a hook', code: "import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';\nimport {neutralTheme} from '@astryxdesign/theme-neutral';\n\nconst lightTokens = resolveThemeTokens(neutralTheme, {mode: 'light'});\nconst chartTheme = {\n textColor: lightTokens['--color-text-primary'],\n seriesColor: lightTokens['--color-data-categorical-blue'],\n};"},+ {type: 'prose', text: 'The `@astryxdesign/core/theme/tokens` subpath is server-safe and does not require React. The main `@astryxdesign/core/theme` barrel also re-exports these helpers for client code that already imports theme APIs.'},{type: 'prose', text: 'For styling library interop patterns, see {@link generic:styling-libraries}.'},],},diff --git a/packages/cli/assets/docs/tree/layout.doc.mjs b/packages/cli/assets/docs/tree/layout.doc.mjsindex 5624e0e64f..13450939cb 100644--- a/packages/cli/assets/docs/tree/layout.doc.mjs+++ b/packages/cli/assets/docs/tree/layout.doc.mjs@@ -26,6 +26,26 @@ export const docs = {'SideNav','TopNav',],+ blocks: [+ {+ type: 'prose',+ text: "Build a layout outside-in. Settle the shell and its region budgets before any content exists, then work inward. Content-first layouts drift into a padded column of cards, because every section ends up inventing its own container.",+ },+ {+ type: 'list',+ style: 'ordered',+ items: [+ "Scaffold: pick the shell, budget each region, and choose navigation",+ "Structure: rank the content in each region, then pick the weakest container that groups it",+ "Spacing: hold one content line per region, then tune gaps and density",+ "Breakpoints: decide what each region does as width changes",+ ],+ },+ {+ type: 'prose',+ text: "This guide decides layout, not component APIs. Run `npx astryx build \"<idea>\"` to start from the closest template for your app type, and `npx astryx component <Name>` for a component's props.",+ },+ ],slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}},},diff --git a/packages/cli/assets/docs/use-a-theme.doc.mjs b/packages/cli/assets/docs/use-a-theme.doc.mjsindex 32155d4b7d..6563319448 100644--- a/packages/cli/assets/docs/use-a-theme.doc.mjs+++ b/packages/cli/assets/docs/use-a-theme.doc.mjs@@ -179,7 +179,7 @@ export const docs = {['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)'],+ ['Best for', 'Authoring input for `astryx theme build`', 'App wiring, in development and production'],],},{@@ -187,7 +187,8 @@ export const docs = {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.',+ 'Import `themes` and `defaultThemeSlug` from the generated module once, and keep that wiring in development too.',+ 'While you edit a local theme, run `astryx theme build --watch` so its built files stay current.','Run `astryx theme build` for custom themes to get the built artifacts.',],},@@ -197,6 +198,8 @@ export const docs = {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.",+ 'Import package theme source into app runtime code.',+ 'Hand-edit the generated theme module; `theme add`, `theme remove`, and `theme use` regenerate it.',],},{