From c781563921f4b8c3ee2a0d5e6ddf0ccd95f654fa Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 17 Nov 2026 16:56:46 -0800 Subject: [PATCH 1/7] docs(motion): use the motion tokens in your own CSS, with the Reduce Motion fallback --- .changeset/motion-doc-own-css.md | 7 +++++ packages/cli/assets/docs/motion.doc.mjs | 41 +++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 .changeset/motion-doc-own-css.md diff --git a/.changeset/motion-doc-own-css.md b/.changeset/motion-doc-own-css.md new file mode 100644 index 0000000000000..9fe54793fb31a --- /dev/null +++ b/.changeset/motion-doc-own-css.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/cli': patch +--- + +[docs] The Motion foundations doc shows how to use the `--duration-*` and `--ease-*` motion tokens in your own CSS, with the Reduce Motion fallback: no travel, an immediate change with a mouse, and an opacity cross-fade of 200 ms or less under a finger. + +@cixzhang diff --git a/packages/cli/assets/docs/motion.doc.mjs b/packages/cli/assets/docs/motion.doc.mjs index 128b5464159b0..9519a569bc373 100644 --- a/packages/cli/assets/docs/motion.doc.mjs +++ b/packages/cli/assets/docs/motion.doc.mjs @@ -143,6 +143,47 @@ const styles = stylex.create({ }, ], }, + { + id: 'own-css', + title: 'Using motion tokens in your own CSS', + category: 'foundations', + content: [ + { + type: 'prose', + text: "The motion tokens are CSS custom properties, so plain CSS reads them with `var()`; for the Web Animations API, read a token's value with `getComputedStyle(element).getPropertyValue('--duration-medium')` first. Time an animation with a `--duration-*` token and ease it with an `--ease-*` token, so it follows the theme's motion. Under Reduce Motion, keep the change but drop the travel: nothing moves, scales or clips. With a mouse or trackpad the change happens at once; under a finger it cross-fades, opacity only, in 200 ms or less.", + }, + { + type: 'code', + lang: 'css', + label: 'A panel that slides in, with its Reduce Motion fallback', + code: `.panel { + transition: + transform var(--duration-medium) var(--ease-entrance), + opacity var(--duration-medium) var(--ease-entrance); +} +.panel[data-hidden] { + transform: translateY(16px); + opacity: 0; +} + +@media (prefers-reduced-motion: reduce) { + /* No travel: the panel appears in its final place. */ + .panel, + .panel[data-hidden] { + transform: none; + transition: none; + } +} + +@media (prefers-reduced-motion: reduce) and (pointer: coarse) { + /* Under a finger, a short cross-fade instead. */ + .panel { + transition: opacity 200ms linear; + } +}`, + }, + ], + }, { id: 'theme-motion', title: 'Tune motion from the theme', From a642094bd3909194a4f4e220d6399a9a2ae1e994 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 17 Nov 2026 17:08:47 -0800 Subject: [PATCH 2/7] docs(motion): say that your own CSS follows the person's setting, not a theme's reducedMotion 'always' --- packages/cli/assets/docs/motion.doc.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/cli/assets/docs/motion.doc.mjs b/packages/cli/assets/docs/motion.doc.mjs index 9519a569bc373..561b5df9bb2ec 100644 --- a/packages/cli/assets/docs/motion.doc.mjs +++ b/packages/cli/assets/docs/motion.doc.mjs @@ -150,7 +150,7 @@ const styles = stylex.create({ content: [ { type: 'prose', - text: "The motion tokens are CSS custom properties, so plain CSS reads them with `var()`; for the Web Animations API, read a token's value with `getComputedStyle(element).getPropertyValue('--duration-medium')` first. Time an animation with a `--duration-*` token and ease it with an `--ease-*` token, so it follows the theme's motion. Under Reduce Motion, keep the change but drop the travel: nothing moves, scales or clips. With a mouse or trackpad the change happens at once; under a finger it cross-fades, opacity only, in 200 ms or less.", + text: "The motion tokens are CSS custom properties, so plain CSS reads them with `var()`; for the Web Animations API, read a token's value with `getComputedStyle(element).getPropertyValue('--duration-medium')` first. Time an animation with a `--duration-*` token and ease it with an `--ease-*` token, so it follows the theme's motion. Under Reduce Motion, keep the change but drop the travel: nothing moves, scales or clips. With a mouse or trackpad the change happens at once; under a finger it cross-fades, opacity only, in 200 ms or less. This CSS follows each person's Reduce Motion setting. A theme's `reducedMotion: 'always'` reduces Astryx's own motion, but your CSS cannot see it, so your own animations follow only the person's setting.", }, { type: 'code', From ef2ed6a92cc980fa945a42b2bfc5f6bd53d367be Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 17 Nov 2026 17:16:56 -0800 Subject: [PATCH 3/7] docs(motion): drop the sentence about reducedMotion 'always', which no public theme can set yet --- packages/cli/assets/docs/motion.doc.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/cli/assets/docs/motion.doc.mjs b/packages/cli/assets/docs/motion.doc.mjs index 561b5df9bb2ec..9519a569bc373 100644 --- a/packages/cli/assets/docs/motion.doc.mjs +++ b/packages/cli/assets/docs/motion.doc.mjs @@ -150,7 +150,7 @@ const styles = stylex.create({ content: [ { type: 'prose', - text: "The motion tokens are CSS custom properties, so plain CSS reads them with `var()`; for the Web Animations API, read a token's value with `getComputedStyle(element).getPropertyValue('--duration-medium')` first. Time an animation with a `--duration-*` token and ease it with an `--ease-*` token, so it follows the theme's motion. Under Reduce Motion, keep the change but drop the travel: nothing moves, scales or clips. With a mouse or trackpad the change happens at once; under a finger it cross-fades, opacity only, in 200 ms or less. This CSS follows each person's Reduce Motion setting. A theme's `reducedMotion: 'always'` reduces Astryx's own motion, but your CSS cannot see it, so your own animations follow only the person's setting.", + text: "The motion tokens are CSS custom properties, so plain CSS reads them with `var()`; for the Web Animations API, read a token's value with `getComputedStyle(element).getPropertyValue('--duration-medium')` first. Time an animation with a `--duration-*` token and ease it with an `--ease-*` token, so it follows the theme's motion. Under Reduce Motion, keep the change but drop the travel: nothing moves, scales or clips. With a mouse or trackpad the change happens at once; under a finger it cross-fades, opacity only, in 200 ms or less.", }, { type: 'code', From e3b741b2674cd0e202da292ec96725d413651949 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 17 Nov 2026 17:38:57 -0800 Subject: [PATCH 4/7] docs(motion): a shorter heading for the table of contents, and no long inline call that wraps on a phone --- packages/cli/assets/docs/motion.doc.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cli/assets/docs/motion.doc.mjs b/packages/cli/assets/docs/motion.doc.mjs index 9519a569bc373..b9aa89ecd34ab 100644 --- a/packages/cli/assets/docs/motion.doc.mjs +++ b/packages/cli/assets/docs/motion.doc.mjs @@ -145,12 +145,12 @@ const styles = stylex.create({ }, { id: 'own-css', - title: 'Using motion tokens in your own CSS', + title: 'Motion tokens in your CSS', category: 'foundations', content: [ { type: 'prose', - text: "The motion tokens are CSS custom properties, so plain CSS reads them with `var()`; for the Web Animations API, read a token's value with `getComputedStyle(element).getPropertyValue('--duration-medium')` first. Time an animation with a `--duration-*` token and ease it with an `--ease-*` token, so it follows the theme's motion. Under Reduce Motion, keep the change but drop the travel: nothing moves, scales or clips. With a mouse or trackpad the change happens at once; under a finger it cross-fades, opacity only, in 200 ms or less.", + text: "The motion tokens are CSS custom properties, so plain CSS reads them with `var()`; for the Web Animations API, read a token's value with `getComputedStyle` first. Time an animation with a `--duration-*` token and ease it with an `--ease-*` token, so it follows the theme's motion. Under Reduce Motion, keep the change but drop the travel: nothing moves, scales or clips. With a mouse or trackpad the change happens at once; under a finger it cross-fades, opacity only, in 200 ms or less.", }, { type: 'code', From e080029ec58b1c0d34e37d9435d72aa7841569a5 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 17 Nov 2026 17:40:22 -0800 Subject: [PATCH 5/7] docs(motion): the touch cross-fade also plays when the panel hides --- packages/cli/assets/docs/motion.doc.mjs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/cli/assets/docs/motion.doc.mjs b/packages/cli/assets/docs/motion.doc.mjs index b9aa89ecd34ab..9fdb037e2af3d 100644 --- a/packages/cli/assets/docs/motion.doc.mjs +++ b/packages/cli/assets/docs/motion.doc.mjs @@ -176,8 +176,9 @@ const styles = stylex.create({ } @media (prefers-reduced-motion: reduce) and (pointer: coarse) { - /* Under a finger, a short cross-fade instead. */ - .panel { + /* Under a finger, a short cross-fade instead, both ways. */ + .panel, + .panel[data-hidden] { transition: opacity 200ms linear; } }`, From 9be91b772dccc0ac776375117afd028b028a4158 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 17 Nov 2026 18:00:51 -0800 Subject: [PATCH 6/7] docs(motion): the example's panel leaves on the exit tokens --- packages/cli/assets/docs/motion.doc.mjs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/cli/assets/docs/motion.doc.mjs b/packages/cli/assets/docs/motion.doc.mjs index 9fdb037e2af3d..93f864e605de0 100644 --- a/packages/cli/assets/docs/motion.doc.mjs +++ b/packages/cli/assets/docs/motion.doc.mjs @@ -164,6 +164,10 @@ const styles = stylex.create({ .panel[data-hidden] { transform: translateY(16px); opacity: 0; + /* Leaving eases on the exit tokens. */ + transition: + transform var(--duration-exit) var(--ease-exit), + opacity var(--duration-exit) var(--ease-exit); } @media (prefers-reduced-motion: reduce) { From 1643c85c08434b74271565914b54aed89b02022a Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Thu, 19 Nov 2026 05:30:39 -0800 Subject: [PATCH 7/7] test(cli): the stable docs goldens list the Motion doc's own-css section --- packages/cli/test/__golden__/no-icon-set/docs-topics.json | 3 ++- packages/cli/test/__golden__/no-icon-set/docs-tree.json | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) 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 de2a82e5a5fda..976a2a32c3992 100644 --- a/packages/cli/test/__golden__/no-icon-set/docs-topics.json +++ b/packages/cli/test/__golden__/no-icon-set/docs-topics.json @@ -202,10 +202,11 @@ "movement-principles", "respecting-user-preferences", "usage", + "own-css", "theme-motion", "best-practices" ], - "skeleton": "fd00e4ddb07bfdb6b20ba2d257fe04877d634ce3906fa2fae2a0c21da4161e2f", + "skeleton": "8a2a77f6eb2c4fe1f9238f9c12c3fad4ca21ebfdc4af699fac795c541dc9faca", "mentions": [] }, "principles": { diff --git a/packages/cli/test/__golden__/no-icon-set/docs-tree.json b/packages/cli/test/__golden__/no-icon-set/docs-tree.json index d9810f4c501c6..07f7f74c4a51f 100644 --- a/packages/cli/test/__golden__/no-icon-set/docs-tree.json +++ b/packages/cli/test/__golden__/no-icon-set/docs-tree.json @@ -1112,6 +1112,7 @@ "movement-principles", "respecting-user-preferences", "usage", + "own-css", "theme-motion", "best-practices" ],