Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjs
index 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.ts
index 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.json
index 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.ts
index 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',