Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(cli): import each Core export from the path `astryx component` prints (#7623)

Joeye26723dcfd02
diff --git a/.changeset/canonical-core-imports.md b/.changeset/canonical-core-imports.md
new file mode 100644
index 0000000000..6912534b65
--- /dev/null
+++ b/.changeset/canonical-core-imports.md
@@ -0,0 +1,12 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/core': patch
+---
+
+[docs] Docs and CLI examples import each Core export from the path `astryx component <Name>` prints.
+
+@josephfarina
+
+- `VStack` and `HStack` come from `@astryxdesign/core/VStack` and `@astryxdesign/core/HStack`, `Heading` from `@astryxdesign/core/Heading`, `Text` from `@astryxdesign/core/Text`, and `Theme` and `defineTheme` from `@astryxdesign/core/theme`.
+- This covers the guides, the `Card` docs, the next steps `astryx init` prints, the install example `astryx theme build` prints, the wiring example `theme add` prints, the build rules, the theme-module fix `astryx doctor` prints, and the annotated theme template.
+- Every path was already exported. Nothing else changes.
diff --git a/packages/cli/api/build/help/help.mjs b/packages/cli/api/build/help/help.mjs
index 6a6d07ace6..d1381f0fe7 100644
--- a/packages/cli/api/build/help/help.mjs
+++ b/packages/cli/api/build/help/help.mjs
@@ -63,7 +63,7 @@ export function buildHelp() {
"Keep the template's page frame, gap, and padding values. Replace its data, copy, and sections.",
'No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
'No style={{}} — use component props, and design tokens for values.',
- "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core') and import core reset.css + astryx.css.",
+ "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core/theme') and import core reset.css + astryx.css.",
],
related: [
{
diff --git a/packages/cli/api/doctor/theme-checks.mjs b/packages/cli/api/doctor/theme-checks.mjs
index f5a0bd7d67..42e8dcf1ba 100644
--- a/packages/cli/api/doctor/theme-checks.mjs
+++ b/packages/cli/api/doctor/theme-checks.mjs
@@ -736,7 +736,7 @@ export async function checkAppThemes(cwd) {
label: 'App imports the theme module',
status: 'warn',
message: `Could not prove that project source imports ${state.module.path}${importEvidence.parseFailures ? `; ${importEvidence.parseFailures} source file(s) could not be parsed` : ''}.`,
- fix: `Import {themes, defaultThemeSlug} from the generated module and {Theme} from '@astryxdesign/core', then render <Theme theme={themes[defaultThemeSlug]}>.`,
+ fix: `Import {themes, defaultThemeSlug} from the generated module and {Theme} from '@astryxdesign/core/theme', then render <Theme theme={themes[defaultThemeSlug]}>.`,
});
}
diff --git a/packages/cli/api/init/run/run.mjs b/packages/cli/api/init/run/run.mjs
index 6aaf318886..3f6568b2da 100644
--- a/packages/cli/api/init/run/run.mjs
+++ b/packages/cli/api/init/run/run.mjs
@@ -50,11 +50,11 @@ export function getNextSteps(invocation) {
` (run \`${invocation} doctor\` to verify)`,
" 2. Import base styles: import '@astryxdesign/core/reset.css'",
" and import '@astryxdesign/core/astryx.css'",
- " 3. Import components: import { Button } from '@astryxdesign/core'",
+ " 3. Import components: import { Button } from '@astryxdesign/core/Button'",
' 4. Add and wire a theme:',
' npm install @astryxdesign/theme-neutral',
` ${invocation} theme add neutral`,
- " import { Theme } from '@astryxdesign/core'",
+ " import { Theme } from '@astryxdesign/core/theme'",
" import { themes, defaultThemeSlug } from './astryx-themes'",
' <Theme theme={themes[defaultThemeSlug]}>...</Theme>',
` Extend an imported theme to customize it. Run \`${invocation} theme eject <slug>\` only to fork source.`,
diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjs
index ae50d49e25..3823063d49 100644
--- a/packages/cli/api/theme/build/build.mjs
+++ b/packages/cli/api/theme/build/build.mjs
@@ -3093,7 +3093,7 @@ function printBuildTrailer(trailer) {
logger.log(`
Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
- import { Theme } from '@astryxdesign/core';
+ import { Theme } from '@astryxdesign/core/theme';
import { ${trailer.exportName} } from '${trailer.jsImport}';
import '${trailer.cssImport}';
@@ -3103,7 +3103,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
Or with a <link> tag:
- import { Theme } from '@astryxdesign/core';
+ import { Theme } from '@astryxdesign/core/theme';
import { ${trailer.exportName} } from '${trailer.jsImport}';
<link rel="stylesheet" href="${trailer.cssImport}" />
@@ -3129,7 +3129,7 @@ export function printBatchTrailer(trailers) {
logger.log(`
Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
- import { Theme } from '@astryxdesign/core';
+ import { Theme } from '@astryxdesign/core/theme';
import { ${first.exportName} } from '${first.jsImport}';
import '${first.cssImport}';
@@ -3139,7 +3139,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
Or with a <link> tag:
- import { Theme } from '@astryxdesign/core';
+ import { Theme } from '@astryxdesign/core/theme';
import { ${first.exportName} } from '${first.jsImport}';
<link rel="stylesheet" href="${first.cssImport}" />
diff --git a/packages/cli/assets/docs/README.md b/packages/cli/assets/docs/README.md
index 4d8a96be36..8f753b09bd 100644
--- a/packages/cli/assets/docs/README.md
+++ b/packages/cli/assets/docs/README.md
@@ -51,6 +51,16 @@ The material is usually good; the finding is placement, not quality. It goes in
Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.
+## Imports in code samples
+
+Import each Core export from the path `astryx component <Name>` prints: the
+component's own entry when Core has one (`@astryxdesign/core/VStack`,
+`@astryxdesign/core/Heading`), and `@astryxdesign/core/theme` for `Theme`,
+`defineTheme` and the rest of the theme API. A reader copies one sample and then
+reads `astryx component`, and two paths for one export read as two different
+things. The no-build CDN page is the exception: its import map names only the
+package root.
+
## Sections are read one at a time
`astryx docs <topic> --index` lists a topic's sections, and readers then open
diff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjs
index 9b7c8f5667..8b02dfce48 100644
--- a/packages/cli/assets/docs/author-a-theme.doc.mjs
+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs
@@ -120,7 +120,7 @@ export const docs = {
['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: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core/theme';\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 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:font-setup} 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}.'},
],
diff --git a/packages/cli/assets/docs/getting-started.doc.mjs b/packages/cli/assets/docs/getting-started.doc.mjs
index 93a9a8efc3..3c8a11bce1 100644
--- a/packages/cli/assets/docs/getting-started.doc.mjs
+++ b/packages/cli/assets/docs/getting-started.doc.mjs
@@ -86,7 +86,7 @@ export const docs = {
type: 'code',
lang: 'tsx',
label: 'App root',
- code: `import {Theme} from '@astryxdesign/core';
+ code: `import {Theme} from '@astryxdesign/core/theme';
import {themes, defaultThemeSlug} from './astryx-themes';
<Theme theme={themes[defaultThemeSlug]}><App /></Theme>`,
@@ -119,14 +119,14 @@ import {themes, defaultThemeSlug} from './astryx-themes';
content: [
{
type: 'prose',
- text: 'Components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear.',
+ text: 'Import each component from its own entry, the path `astryx component <Name>` prints. This keeps bundles small and makes intent clear.',
},
{
type: 'code',
lang: 'tsx',
label: 'app/page.tsx',
code: `import {Button} from '@astryxdesign/core/Button';
-import {VStack} from '@astryxdesign/core/Layout';
+import {VStack} from '@astryxdesign/core/VStack';
export default function Page() {
return (
diff --git a/packages/cli/assets/docs/theme.doc.dense.mjs b/packages/cli/assets/docs/theme.doc.dense.mjs
index 5f48c1491d..6aa26a666d 100644
--- a/packages/cli/assets/docs/theme.doc.dense.mjs
+++ b/packages/cli/assets/docs/theme.doc.dense.mjs
@@ -9,7 +9,7 @@ export const docsDense = {
section: 'Wrap your app in a theme',
title: 'Quick start',
content: [
- {type: 'prose', text: "Install a theme, wrap in `<Theme>` (`import {Theme} from '@astryxdesign/core'`). {@link generic:use-a-theme} for full guide."},
+ {type: 'prose', text: "Install a theme, wrap in `<Theme>` (`import {Theme} from '@astryxdesign/core/theme'`). {@link generic:use-a-theme} for full guide."},
],
},
{
diff --git a/packages/cli/assets/docs/theme.doc.mjs b/packages/cli/assets/docs/theme.doc.mjs
index 00b18617f0..6370536f19 100644
--- a/packages/cli/assets/docs/theme.doc.mjs
+++ b/packages/cli/assets/docs/theme.doc.mjs
@@ -23,7 +23,7 @@ export const docs = {
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}",
+ code: "import {Theme} from '@astryxdesign/core/theme';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n return (\n <Theme theme={themes[defaultThemeSlug]}>\n <YourApp />\n </Theme>\n );\n}",
},
],
},
diff --git a/packages/cli/assets/docs/theme.doc.zh.mjs b/packages/cli/assets/docs/theme.doc.zh.mjs
index 79193d8a99..2bdd7f9e51 100644
--- a/packages/cli/assets/docs/theme.doc.zh.mjs
+++ b/packages/cli/assets/docs/theme.doc.zh.mjs
@@ -11,7 +11,7 @@ export const docsZh = {
content: [
{
type: 'prose',
- text: "安装主题包,用 `<Theme>`(`import {Theme} from '@astryxdesign/core'`)包裹应用,选择浅色或深色模式。完整指南——可用主题、集成主题、深色模式、嵌套主题和生产构建——请参阅 {@link generic:use-a-theme}。",
+ text: "安装主题包,用 `<Theme>`(`import {Theme} from '@astryxdesign/core/theme'`)包裹应用,选择浅色或深色模式。完整指南——可用主题、集成主题、深色模式、嵌套主题和生产构建——请参阅 {@link generic:use-a-theme}。",
},
],
},
diff --git a/packages/cli/assets/docs/tree/type-scale.doc.mjs b/packages/cli/assets/docs/tree/type-scale.doc.mjs
index 127be39399..f907f9246b 100644
--- a/packages/cli/assets/docs/tree/type-scale.doc.mjs
+++ b/packages/cli/assets/docs/tree/type-scale.doc.mjs
@@ -76,7 +76,7 @@ export const docs = {
type: 'code',
lang: 'tsx',
label: 'Heading for document structure',
- code: `import {Heading} from '@astryxdesign/core';
+ code: `import {Heading} from '@astryxdesign/core/Heading';
// Heading levels map to semantic tokens: level 1 → --text-heading-1-*
<Heading level={1}>Page Title</Heading>
@@ -96,7 +96,7 @@ export const docs = {
type: 'code',
lang: 'tsx',
label: 'Text for body, label, and display text',
- code: `import {Text} from '@astryxdesign/core';
+ code: `import {Text} from '@astryxdesign/core/Text';
<Text type="body">Body text at the base scale.</Text>
<Text type="large">Emphasized body text.</Text>
@@ -121,7 +121,7 @@ export const docs = {
type: 'code',
lang: 'tsx',
label: 'Customizing the type scale via defineTheme',
- code: `import {defineTheme} from '@astryxdesign/core';
+ code: `import {defineTheme} from '@astryxdesign/core/theme';
// Adjust the entire ramp holistically with base and ratio
const editorialTheme = defineTheme({
diff --git a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
index f0c9fb7b51..33e48f284b 100644
--- a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
+++ b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
@@ -91,8 +91,9 @@ npx astryx template acme-stat-card src/features/account/StatusCard.tsx`,
lang: 'tsx',
code: `import {Button} from '@astryxdesign/core/Button';
import {Card} from '@astryxdesign/core/Card';
-import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {HStack} from '@astryxdesign/core/HStack';
import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/VStack';
import {AcmeStatusCard} from '@acme/astryx-widgets/components/AcmeStatusCard';
const metrics = [
diff --git a/packages/cli/assets/docs/use-a-theme.doc.mjs b/packages/cli/assets/docs/use-a-theme.doc.mjs
index 6d5d48e583..2fe7cf9f7f 100644
--- a/packages/cli/assets/docs/use-a-theme.doc.mjs
+++ b/packages/cli/assets/docs/use-a-theme.doc.mjs
@@ -25,13 +25,13 @@ export const docs = {
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}",
+ code: "import {Theme} from '@astryxdesign/core/theme';\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 {Theme} from '@astryxdesign/core';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
+ code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core/theme';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
},
{
type: 'prose',
diff --git a/packages/cli/assets/theme.template.ts b/packages/cli/assets/theme.template.ts
index d3ff822ea2..bb8552d1a6 100644
--- a/packages/cli/assets/theme.template.ts
+++ b/packages/cli/assets/theme.template.ts
@@ -18,7 +18,7 @@
*
* 1. WRAP THE APP. A theme does nothing until it is provided.
*
- * import {Theme} from '@astryxdesign/core';
+ * import {Theme} from '@astryxdesign/core/theme';
* import {myTheme} from './theme';
*
* <Theme theme={myTheme} mode="system"> // 'system' | 'light' | 'dark'
diff --git a/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs b/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs
index ef0d358778..fd0b6356ed 100644
--- a/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs
@@ -168,7 +168,9 @@ describe('theme build report', () => {
}
expect(count(out, 'Install in your app')).toBe(1);
expect(count(out, 'Or with a <link> tag:')).toBe(1);
- expect(count(out, "import { Theme } from '@astryxdesign/core';")).toBe(2);
+ expect(
+ count(out, "import { Theme } from '@astryxdesign/core/theme';"),
+ ).toBe(2);
expect(count(out, '[note]')).toBe(1);
expect(count(out, 'note: Font')).toBe(0);
expect(count(out, 'fonts.googleapis.com/css2')).toBe(1);
diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjs
index 3eec657afb..6252d24a03 100644
--- a/packages/cli/clients/cli/commands/build-theme.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.mjs
@@ -397,7 +397,7 @@ function printThemeApp(result) {
emit(
text('Wire the generated module once in the app root:'),
code(
- "import {Theme} from '@astryxdesign/core';\n" +
+ "import {Theme} from '@astryxdesign/core/theme';\n" +
`import {themes, defaultThemeSlug} from './${stem}';\n\n` +
'<Theme theme={themes[defaultThemeSlug]}>\n <App />\n</Theme>',
),
diff --git a/packages/cli/test/__golden__/theme-build-batch-full.txt b/packages/cli/test/__golden__/theme-build-batch-full.txt
index a6e385aceb..48b4cb1310 100644
--- a/packages/cli/test/__golden__/theme-build-batch-full.txt
+++ b/packages/cli/test/__golden__/theme-build-batch-full.txt
@@ -136,7 +136,7 @@ Building theme from themes/orchid.mjs...
Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
- import { Theme } from '@astryxdesign/core';
+ import { Theme } from '@astryxdesign/core/theme';
import { amberTheme } from './themes/amber';
import './themes/amber.css';
@@ -146,7 +146,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
Or with a <link> tag:
- import { Theme } from '@astryxdesign/core';
+ import { Theme } from '@astryxdesign/core/theme';
import { amberTheme } from './themes/amber';
<link rel="stylesheet" href="./themes/amber.css" />
diff --git a/packages/cli/test/taught-core-imports.test.mjs b/packages/cli/test/taught-core-imports.test.mjs
index b71f31582e..bfb64b77ed 100644
--- a/packages/cli/test/taught-core-imports.test.mjs
+++ b/packages/cli/test/taught-core-imports.test.mjs
@@ -8,8 +8,8 @@
* names a subpath Core does not export, or names it with the wrong case, fails
* in the user's app, so every specifier must match an entry in Core's
* package.json `exports`. Wherever command output shows the `<Theme>` wrapper,
- * it also shows where `Theme` comes from, and so does every doc page that shows
- * it.
+ * it also shows that `Theme` comes from `@astryxdesign/core/theme`, the path
+ * `astryx component Theme` prints, and so does every doc page that shows it.
*
* @position packages/cli/test — taught imports
*/
@@ -64,8 +64,7 @@ function isExported(keys, subpath) {
});
}
-const THEME_IMPORT =
- /\{\s*Theme\s*\}\s+from\s+'@astryxdesign\/core(?:\/theme)?'/;
+const THEME_IMPORT = /\{\s*Theme\s*\}\s+from\s+'@astryxdesign\/core\/theme'/;
/**
* Every code block (`{type: 'code', code}`) reachable from a doc module.
@@ -145,9 +144,7 @@ describe('taught @astryxdesign/core imports', () => {
Math.max(previous, index - 400),
lineEnd === -1 ? source.length : lineEnd,
);
- expect(nearby, `${file} at offset ${index}`).toMatch(
- /\{\s*Theme\s*\}\s+from\s+'@astryxdesign\/core'/,
- );
+ expect(nearby, `${file} at offset ${index}`).toMatch(THEME_IMPORT);
});
},
);
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index 247552e656..7dadbb2592 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -83,7 +83,7 @@ export const docs = {
code: `
import {Card} from '@astryxdesign/core/Card';
import {Grid} from '@astryxdesign/core/Grid';
-import {VStack} from '@astryxdesign/core/Layout';
+import {VStack} from '@astryxdesign/core/VStack';
import {Heading} from '@astryxdesign/core/Heading';
import {Text} from '@astryxdesign/core/Text';