An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): recommend palette generator for new themes (#6795)
rubyycheungaf76e84d76de
diff --git a/.changeset/calm-colors-guide.md b/.changeset/calm-colors-guide.mdnew file mode 100644index 0000000000..467ac66b3d--- /dev/null+++ b/.changeset/calm-colors-guide.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[docs] Guide new theme authors to the palette generator and keep the broad color scale opt-in in generated theme templates.++@rubyycheungdiff --git a/packages/cli/api/docs/docOverlays.test.mjs b/packages/cli/api/docs/docOverlays.test.mjsindex 4b18de12f1..42f663f5f2 100644--- a/packages/cli/api/docs/docOverlays.test.mjs+++ b/packages/cli/api/docs/docOverlays.test.mjs@@ -171,4 +171,18 @@ describe('the reported defect: docs tokens --dense (#2182)', () => {expect(titles).not.toContain('Dark mode');expect(titles).toContain('深色模式');});++ it('teaches committed palette references in every theme-doc variant', async () => {+ for (const options of [{}, {dense: true}, {zh: true}]) {+ const result = await docs('theme', null, options);+ const rendered = JSON.stringify(result.data.sections);+ expect(rendered).toContain(+ 'astryx theme palette generate palette.config.json --out palette.generated.ts',+ );+ expect(rendered).toContain(+ "import {palette} from './palette.generated';",+ );+ expect(rendered).toContain('palette.neutral.light[100]');+ }+ });});diff --git a/packages/cli/assets/docs/theme.doc.dense.mjs b/packages/cli/assets/docs/theme.doc.dense.mjsindex 9610078d84..d85f57bda9 100644--- a/packages/cli/assets/docs/theme.doc.dense.mjs+++ b/packages/cli/assets/docs/theme.doc.dense.mjs@@ -17,6 +17,8 @@ export const docsDense = {title: 'Custom themes',content: [{type: 'prose', text: '`defineTheme` + token overrides + component overrides. {@link generic:author-a-theme} for full guide.'},+ null,+ {type: 'prose', text: "new palette: `astryx theme palette generate palette.config.json --out palette.generated.ts` → review + commit module and receipt → `import {palette} from './palette.generated';` → map semantic tokens to stable stops such as `palette.neutral.light[100]` / `palette.neutral.dark[15]`. regeneration updates mapped roles; generation does not rewrite the theme."},],},{diff --git a/packages/cli/assets/docs/theme.doc.mjs b/packages/cli/assets/docs/theme.doc.mjsindex cb696c9ee8..a0825465c2 100644--- a/packages/cli/assets/docs/theme.doc.mjs+++ b/packages/cli/assets/docs/theme.doc.mjs@@ -41,6 +41,16 @@ export const docs = {label: 'Quick start',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',},+ {+ type: 'prose',+ text: 'For a new coordinated color system, run `astryx theme palette generate palette.config.json --out palette.generated.ts`. Review and commit the generated palette module and receipt, import its `palette` export, then reference stable stops from semantic tokens. Regenerating an accepted palette updates every mapped token that keeps those references; generation does not rewrite the theme.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Map semantic tokens to generated palette stops',+ code: "import {defineTheme} from '@astryxdesign/core/theme';\nimport {palette} from './palette.generated';\n\nconst myTheme = defineTheme({\n name: 'my-theme',\n tokens: {\n '--color-background-surface': [\n palette.neutral.light[100],\n palette.neutral.dark[15],\n ],\n },\n});",+ },],},{diff --git a/packages/cli/assets/docs/theme.doc.zh.mjs b/packages/cli/assets/docs/theme.doc.zh.mjsindex ef6a06abcc..79193d8a99 100644--- a/packages/cli/assets/docs/theme.doc.zh.mjs+++ b/packages/cli/assets/docs/theme.doc.zh.mjs@@ -21,7 +21,7 @@ export const docsZh = {content: [{type: 'prose',- text: '使用 `defineTheme` 进行令牌覆盖、比例配置和组件样式覆盖。完整指南——调色板生成、主题扩展、自适应、自定义变体和生产构建——请参阅 {@link generic:author-a-theme}。',+ text: '使用 `defineTheme` 进行令牌覆盖、比例配置和组件样式覆盖。新建完整调色板时,请运行 `astryx theme palette generate palette.config.json --out palette.generated.ts`,审核并提交生成的模块和收据,再使用 `import {palette} from \'./palette.generated\';` 导入调色板,让语义令牌引用稳定的色阶,例如 `palette.neutral.light[100]` 和 `palette.neutral.dark[15]`。重新生成已接受的调色板时,所有保留这些引用的映射令牌会一并更新;生成操作不会自动修改主题。完整指南请参阅 {@link generic:author-a-theme}。',},],},diff --git a/packages/cli/assets/theme.template.ts b/packages/cli/assets/theme.template.tsindex 83e3b907a1..81552fa933 100644--- a/packages/cli/assets/theme.template.ts+++ b/packages/cli/assets/theme.template.ts@@ -81,6 +81,7 @@*/import {defineTheme} from '@astryxdesign/core/theme';+// import {palette} from './palette.generated';// import {dracula} from '@astryxdesign/core/theme/syntax';// import {neutralTheme} from '@astryxdesign/theme-neutral';@@ -99,15 +100,25 @@ export const myTheme = defineTheme({// extends: neutralTheme,// ───────────────────────────────────────────────────────────────────────- // Scale configs — a few parameters generate a whole family of tokens.- // Reach for these first. They keep a theme internally consistent and cover- // far more ground than you would hand-write.+ // Scale configs — concise inputs for typography, radius, and motion.+ // The color scale remains supported for existing themes, but it is not the+ // recommended starting point for a new palette; see its note below.// ───────────────────────────────────────────────────────────────────────/**- * Generates the neutral ramp and the accent tokens from a seed colour- * using the HCT perceptual model: surfaces, text, icons, borders, muted- * fills, hover and pressed overlays — light and dark both.+ * Supported compatibility path for existing themes. This expands one accent+ * seed into the neutral ramp, surfaces, text, icons, borders, muted fills,+ * hover and pressed overlays — light and dark both. It is not an accent-only+ * edit.+ *+ * For a new complete palette, run:+ *+ * astryx theme palette generate palette.config.json --out palette.generated.ts+ *+ * Review the generated candidate, then commit the palette module and receipt.+ * Uncomment the `palette` import above and reference its stops from semantic+ * tokens below. Regenerating an accepted palette then updates every mapped+ * token that keeps those references. Generation does not rewrite the theme.** accent seed hex, or a [light, dark] pair to seed each scheme's* palette from its own colour; omit to keep the default@@ -134,7 +145,7 @@ export const myTheme = defineTheme({* `astryx docs tokens/tokens-color` for every colour token and its light/dark* default.*/- color: {accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard'},+ // color: {accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard'},/*** Type scale and the three font roles.@@ -213,12 +224,17 @@ export const myTheme = defineTheme({// --color-syntax-* code highlighting · --color-data-* charts// ───────────────────────────────────────────────────────────────────────tokens: {+ // Keep generated roles connected to the accepted palette. Uncomment the+ // import above, then map each reviewed semantic role this way.+ // '--color-background-surface': [+ // palette.neutral.light[100],+ // palette.neutral.dark[15],+ // ],'--color-accent': ['#0064E0', '#2694FE'],// Changing an accent means owning its on-colour: this is the label that// sits on top of the fill above, in each mode.'--color-on-accent': ['#FFFFFF', '#FFFFFF'],'--color-background-body': ['#F1F4F7', '#111112'],- '--color-background-surface': ['#FFFFFF', '#1F1F22'],'--focus-outline-color': 'var(--color-accent)','--shadow-low': '0 1px 2px light-dark(#0000001A, #00000066)',},diff --git a/scripts/check-theme-template.test.mjs b/scripts/check-theme-template.test.mjsindex 45827ce403..4ed8df58d2 100644--- a/scripts/check-theme-template.test.mjs+++ b/scripts/check-theme-template.test.mjs@@ -312,6 +312,18 @@ describe('theme template stays in sync with the theme system', () => {).toEqual([]);});+ it('documents the color scale without enabling it for new themes', () => {+ expect(template).toMatch(/^ {2}\/\/ color: \{/m);+ expect(template).not.toMatch(/^ {2}color: \{/m);+ expect(template).toContain(+ 'astryx theme palette generate palette.config.json --out palette.generated.ts',+ );+ expect(template).toContain(+ "// import {palette} from './palette.generated';",+ );+ expect(template).toContain('palette.neutral.light[100]');+ });+it('invents no field that defineTheme does not accept', () => {const real = new Set([...defineThemeFields(), 'name']);const invented = templateFields().filter(f => !real.has(f));