An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): clarify imported theme icon build requirements (#5099)
Jiun Shin0fee3bccdaf6
diff --git a/.changeset/document-the-theme-icons-sidecar-contract-in-the-4s0f.md b/.changeset/document-the-theme-icons-sidecar-contract-in-the-4s0f.mdnew file mode 100644index 0000000000..8f64bb5ddd--- /dev/null+++ b/.changeset/document-the-theme-icons-sidecar-contract-in-the-4s0f.md@@ -0,0 +1,8 @@+---+'@astryxdesign/cli': patch+---++[docs] Clarify how to build themes with imported icon registries, including the current omission of inline registries and the separate registry compilation step.+@jiunshinn++The theme guide distinguishes a missing compiled registry from an extensionless source import: the former breaks both loading and bundling, while the latter can resolve in a bundler when the source remains beside the generated module. English, dense, and Chinese guidance now explains how output paths and `--icons-specifier` affect resolution.diff --git a/packages/cli/assets/docs/theme.doc.dense.mjs b/packages/cli/assets/docs/theme.doc.dense.mjsindex 4aef03af86..7c157dfee6 100644--- a/packages/cli/assets/docs/theme.doc.dense.mjs+++ b/packages/cli/assets/docs/theme.doc.dense.mjs@@ -110,6 +110,21 @@ export const docsDense = {null,null,null,+ {+ type: 'prose',+ text: 'current build detects named imports used by icons:. registry module is not compiled. inline/local registries accepted by defineTheme are omitted from built output; move them to a separate module and import by name.',+ },+ null,+ {+ type: 'prose',+ text: '--out dist/theme.css --icons-specifier ./icons.mjs requires dist/icons.mjs. skipping its compilation can leave theme build successful but breaks loading and bundling. flag changes the import; it does not create/verify the file. keep react + icon library external.',+ },+ {+ type: 'prose',+ text: 'without --icons-specifier, source import is copied unchanged. default flow without --out: bundlers can resolve ./icons to neighboring icons.tsx; Node ESM fails with ERR_MODULE_NOT_FOUND. moving output changes relative import resolution.',+ },+ null,+ null,null,],},diff --git a/packages/cli/assets/docs/theme.doc.mjs b/packages/cli/assets/docs/theme.doc.mjsindex c4bdc5357f..dc8dab6b23 100644--- a/packages/cli/assets/docs/theme.doc.mjs+++ b/packages/cli/assets/docs/theme.doc.mjs@@ -506,7 +506,7 @@ const brandTheme = defineTheme({],['ocean.js',- 'ES module exporting the theme object with `__built: true` and pre-resolved token values. Also re-exports the icon registry if the source theme declares one.',+ 'ES module exporting the theme object with `__built: true` and pre-resolved token values. Also imports and re-exports an icon registry when the build detects its named import in the source theme (see the limitations below).',],['ocean.d.ts',@@ -518,6 +518,29 @@ const brandTheme = defineTheme({],],},+ {+ type: 'prose',+ text: "The current `theme build` implementation emits an icon import when it detects a named import used by the theme’s `icons:` field, such as `import {oceanIcons} from './icons'` with `icons: oceanIcons`. It does not compile that registry module. Inline registries, including local constants, are currently omitted from the generated theme even though `defineTheme` accepts them at runtime. Move the registry to a separate module and use a named import for this build flow. For a registry that uses React and lucide-react, the following example compiles it alongside the generated theme:",+ },+ {+ type: 'code',+ lang: 'bash',+ label: 'Compiling the icon registry sidecar',+ code: `# Emit the built theme; point its icon import at the file the next step produces+astryx theme build ./src/themes/ocean.ts -o dist/theme.css --icons-specifier ./icons.mjs++# Compile the icon registry to a real ES module next to the generated JS+esbuild src/themes/icons.tsx --bundle --format=esm --outfile=dist/icons.mjs \\+ --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. Keep `react` and the icon library external so the registry does not bundle its own copies of those dependencies.',+ },+ {+ type: 'prose',+ text: 'Without `--icons-specifier`, the detected source import specifier is emitted unchanged. In the default no-`--out` flow, a bundler can resolve an extensionless `./icons` to the neighboring `icons.tsx` source. Node ESM does not perform that lookup and reports `ERR_MODULE_NOT_FOUND`. Moving the output with `--out` also changes where relative imports resolve; the generated module cannot find the original source merely because a bundler is used.',+ },{type: 'prose',text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it.',diff --git a/packages/cli/assets/docs/theme.doc.zh.mjs b/packages/cli/assets/docs/theme.doc.zh.mjsindex 4f851ded67..58392b697e 100644--- a/packages/cli/assets/docs/theme.doc.zh.mjs+++ b/packages/cli/assets/docs/theme.doc.zh.mjs@@ -10,7 +10,7 @@ export const docsZh = {{ section: 'Theme Props', title: 'Theme 属性', content: [null] },{ section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '用 `theme list` + `theme add <slug>` 从内置主题开始,或用 defineTheme 从零编写。只覆盖与默认值不同的令牌。' }, null, { type: 'prose', text: '`astryx theme template` 会写入 theme.template.ts:带注释的完整参考,涵盖每个 defineTheme 字段、令牌族和覆盖语法,并标明打印各自参考的 CLI 命令。' }] },{ section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置(color、typography、radius、motion)+ 显式令牌覆盖 + 组件覆盖。color 通过 HCT 从 accent 派生完整调色板;accent 接受单个十六进制值或 [light, dark] 元组(每个模式使用各自的种子色)。tokens 覆盖按令牌逐个生效;--color-on-accent 始终由 color.accent 计算得出,因此优先使用元组 accent 而不是覆盖 --color-accent。' }, null, null] },- { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }, null, null, null, null] },+ { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }, null, null, null, { type: 'prose', text: '当前 theme build 仅在检测到 icons: 字段使用的具名导入时,才在生成的模块中导入图标注册表;它不会编译注册表模块。defineTheme 在运行时接受的内联注册表(包括本地常量)目前会在构建产物中被省略。使用此构建流程时,请把注册表移到独立模块并使用具名导入。以下示例适用于使用 React 和 lucide-react 的注册表。' }, null, { type: 'prose', text: '上例中生成的主题从 dist 导入 ./icons.mjs。如果跳过第二条命令,theme build 仍可能成功,但加载或打包生成的模块都会因缺少 dist/icons.mjs 而失败。--icons-specifier 只更改生成的导入,不会创建或验证目标文件。路径应相对于生成的 JS 文件可解析。将 react 和图标库标记为 external,避免在注册表中重复打包这些依赖。' }, { type: 'prose', text: '不传 --icons-specifier 时,会原样保留检测到的源码导入路径。默认不传 --out 时,打包器可以把无扩展名的 ./icons 解析为旁边的 icons.tsx;Node ESM 不执行这种查找,会报 ERR_MODULE_NOT_FOUND。用 --out 移动输出位置也会改变相对导入的解析位置;使用打包器并不意味着它能自动找到原来的源码。' }, null, null, null] },{ section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时:useInsertionEffect 在客户端注入样式。构建:静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },{ section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'(默认)跟随系统偏好。" }, null, null] },{ section: 'Nesting Themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },