An open source design system that's fully customizable and agent ready
TypeScript
docs(theme): an extending theme's motion inherits field by field (#8748)
Cindy Zhang1b8e9103f86d
diff --git a/.changeset/theme-motion-inherits-field-by-field.md b/.changeset/theme-motion-inherits-field-by-field.mdnew file mode 100644index 0000000000..55020f125d--- /dev/null+++ b/.changeset/theme-motion-inherits-field-by-field.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[docs] The theme authoring guide, and the comment in the theme file `astryx init` and `astryx theme template` write, say an extending theme's `motion` inherits field by field: the child's `fast`, `medium` and `ratio` regenerate the fast and medium duration tokens, and `slow` or `easing` left unset keep the base theme's tokens (an inherited slow band stays at the base's ratio). It used to say the child's motion config replaced the base's entirely.++@cixzhangdiff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjsindex 65190f6150..4d0eb5daff 100644--- a/packages/cli/assets/docs/author-a-theme.doc.mjs+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs@@ -57,7 +57,8 @@ export const docs = {['icons', 'Shallow-merged: child icons override matching names from the base.'],['indicators', 'Shallow-merged: child indicators override matching names from the base.'],['onDark, onLight', "Deep-merged per surface: the base's resolved surface first, then the child's overrides."],- ['typography, motion, radius, color', 'Child config replaces base entirely (these are scale inputs, not additive).'],+ ['motion', "Field by field: the child's `fast`, `medium` and `ratio` regenerate the fast and medium duration tokens; `slow` and `easing` left unset keep the base theme's tokens, so an inherited slow band stays at the base's ratio."],+ ['typography, radius, color', 'Child config replaces base entirely (these are scale inputs, not additive).'],['adaptations', 'Width-breakpoint overrides merge by fixed name. Inherited ordered rules keep their relative order; child rules append and re-resolve against the child root axes.'],]},{type: 'prose', text: "Inheritance is resolved when the theme is defined, so an extended theme is flat: `{@command theme build}` emits one self-contained stylesheet holding everything the child inherited, and the base theme's CSS does not need to be loaded next to it. A base that is not a theme (most often an import that missed) throws when `defineTheme` runs, rather than producing a theme that silently inherits nothing."},diff --git a/packages/cli/assets/theme.template.ts b/packages/cli/assets/theme.template.tsindex bb8552d1a6..781204ec00 100644--- a/packages/cli/assets/theme.template.ts+++ b/packages/cli/assets/theme.template.ts@@ -91,9 +91,11 @@ export const myTheme = defineTheme({/*** Start from another theme instead of the defaults. Tokens are copied then- * overridden, `components` deep-merge, `icons` shallow-merge — but the scale- * configs below REPLACE the base's rather than merging, because they are- * inputs to a generator, not values.+ * overridden, `components` deep-merge, `icons` shallow-merge — but the+ * typography, radius and color scale configs below REPLACE the base's rather+ * than merging, because they are inputs to a generator, not values. `motion`+ * inherits field by field: `fast`, `medium` and `ratio` regenerate the fast+ * and medium durations, and a `slow` or `easing` left unset keeps the base's.** Reference: `astryx theme list` (themes you can install and extend).*/diff --git a/packages/cli/test/__golden__/no-icon-set/docs-topics.json b/packages/cli/test/__golden__/no-icon-set/docs-topics.jsonindex 3c0b69ae58..dd9fe6f0fb 100644--- a/packages/cli/test/__golden__/no-icon-set/docs-topics.json+++ b/packages/cli/test/__golden__/no-icon-set/docs-topics.json@@ -103,7 +103,7 @@"token-utilities","usetheme-hook"],- "skeleton": "4e494f1ed2599a4a3ba54c3f722ae1ff9808fe80843e9ed0c6ab2e8b9f0bb19e",+ "skeleton": "eff6b78c23d611da7d40a9534e421236f5e6fc1f6367d47d6ee02ef76c5a3229","mentions": []},"browser-support": {diff --git a/packages/core/src/theme/defineTheme.test.ts b/packages/core/src/theme/defineTheme.test.tsindex 1f8a9feb59..015ce2cfc1 100644--- a/packages/core/src/theme/defineTheme.test.ts+++ b/packages/core/src/theme/defineTheme.test.ts@@ -1549,6 +1549,32 @@ describe('defineTheme extends', () => {expect(child.tokens['--radius-container']).toBe('16px');});+ it('inherits motion field by field: a field the child leaves unset keeps the base value (spec:AST-108 FR5)', () => {+ const base = defineTheme({+ name: 'base',+ motion: {+ fast: 100,+ medium: 200,+ slow: 400,+ ratio: 0.75,+ easing: 'cubic-bezier(0.2, 0, 0, 1)',+ },+ });+ const child = defineTheme({+ name: 'child',+ extends: base,+ motion: {fast: 120, medium: 240, ratio: 0.8},+ });+ // The fields the child sets regenerate their tokens.+ expect(child.tokens['--duration-fast']).toBe('120ms');+ expect(child.tokens['--duration-medium-min']).toBe('190ms');+ // `slow` and `easing`, left unset, keep the base's tokens: the slow band+ // stays at the base's ratio (400 × 0.75), not the child's.+ expect(child.tokens['--duration-slow']).toBe('400ms');+ expect(child.tokens['--duration-slow-min']).toBe('300ms');+ expect(child.tokens['--ease-standard']).toBe('cubic-bezier(0.2, 0, 0, 1)');+ });+it('overrides base tokens with explicit tokens', () => {const base = defineTheme({name: 'base',