An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): teach palette refs in author-a-theme (#7268)
rubyycheung81dc9bb77d7f
diff --git a/.changeset/guide-theme-palette-refs.md b/.changeset/guide-theme-palette-refs.mdnew file mode 100644index 0000000000..16f781f011--- /dev/null+++ b/.changeset/guide-theme-palette-refs.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] Teach generated palette references in the full custom-theme authoring guide.++@rubyycheungdiff --git a/packages/cli/api/docs/compiled-topics.test.mjs b/packages/cli/api/docs/compiled-topics.test.mjsindex 6d73b220c3..1569e9822a 100644--- a/packages/cli/api/docs/compiled-topics.test.mjs+++ b/packages/cli/api/docs/compiled-topics.test.mjs@@ -48,6 +48,22 @@ describe('every shipped topic compiles to plain JSON', () => {);});+describe('author-a-theme color guidance', () => {+ it('teaches committed generated palette references as the main example', async () => {+ const catalog = await loadDocsCatalog();+ const topic = detailView(+ await compileTopic(catalog, catalog.resolve('author-a-theme')),+ );+ const rendered = JSON.stringify(topic);++ expect(rendered).toContain("import {palette} from './palette.generated';");+ expect(rendered).toContain('palette.neutral.light[100]');+ expect(rendered).toContain('palette.neutral.dark[15]');+ expect(rendered).toContain('color (existing themes)');+ expect(rendered).not.toContain("color: { accent: ['#7B61FF'");+ });+});+describe('reads that share a catalog', () => {it('never let one read change another',diff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjsindex 808488e1a3..a3186808fe 100644--- a/packages/cli/assets/docs/author-a-theme.doc.mjs+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs@@ -34,10 +34,10 @@ export const docs = {{title: 'defineTheme',content: [- {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: 'prose', text: 'defineTheme creates a theme from explicit token overrides and optional scale configs. Existing themes may use `color` to expand an accent seed into neutral, surface, text, border, and related values; it is not an accent-only edit. Keep that configuration when preserving existing output. For new complete palettes, generate and review a committed palette module, then import its `palette` export and reference stable stops from semantic tokens. This keeps mapped roles coherent when the accepted palette is regenerated; generation itself does not rewrite the theme. Other scale configs generate typography, radius, and motion values from parameters. Explicit token overrides always take precedence over scale-generated values, token by token. When an existing `color` config is in use, overriding `--color-accent` in `tokens` re-points `--color-accent-muted`, `--color-text-accent`, and `--color-icon-accent`, but `--color-on-accent` stays baked from the `color.accent` seed. Prefer a `[light, dark]` tuple for `color.accent` over overriding `--color-accent` alone. localTokens accepts any valid CSS custom-property name; prefixes do not establish ownership.'},+ {type: 'code', lang: 'tsx', label: 'defineTheme with generated palette references and non-color scale configs', code: "import {defineTheme} from '@astryxdesign/core/theme';\nimport {palette} from './palette.generated';\n\nconst myTheme = defineTheme({\n name: 'my-theme',\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 '--color-background-surface': [\n palette.neutral.light[100],\n palette.neutral.dark[15],\n ],\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)'],+ ['color (existing themes)', '--color-accent, --color-background-*, --color-text-*, --color-border, etc.', 'Supported broad scale: accent? (hex or [light, dark] tuple), neutralStyle? (warm|cool|neutral), contrast? (standard|high). Use theme palette generate for new complete palettes.'],['typography.scale', '--text-heading-*-size/weight/leading, --text-body-size/weight/leading', 'base (px), ratio'],['typography.body/heading/code', '--font-family-body, --font-family-heading, --font-family-code', 'family, fallbacks?, url?, weight?'],['radius', '--radius-inner, --radius-element, --radius-container, --radius-page, --radius-chat', 'base (px), multiplier (0–2)'],