Skip to content

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.md
new file mode 100644
index 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.
+
+@rubyycheung
diff --git a/packages/cli/api/docs/docOverlays.test.mjs b/packages/cli/api/docs/docOverlays.test.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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.mjs
index 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));