Skip to content

docs(motion): use the motion tokens in your own CSS, with the Reduce Motion fallback - #12535

Draft
cixzhang wants to merge 9 commits into
mainfrom
lane2/docs-motion-tokens-own-css
Draft

cixzhang wants to merge 9 commits into
mainfrom
lane2/docs-motion-tokens-own-css

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

User impact

A builder who animates their own element (a panel, a toast, a custom disclosure) in plain CSS had no example of using Astryx's motion tokens there, or of the Reduce Motion fallback Astryx components follow. Their animation ignored the theme's motion, or kept sliding for a person who asked for less motion. The Motion foundations doc now has one section, "Motion tokens in your CSS": a panel that slides in on --duration-medium and --ease-entrance, and its Reduce Motion fallback per design:reduced-motion DR1–DR3. With Reduce Motion on there is no travel, the change is immediate with a mouse, and under a finger an opacity cross-fade of 200 ms or less plays both when the panel shows and when it hides. For the Web Animations API, it says to read the token's computed value with getComputedStyle first.

Docs only: one section in packages/cli/assets/docs/motion.doc.mjs (what astryx docs motion and the docsite's Motion page show) and a [docs] Changeset for @astryxdesign/cli, since the doc ships with the package. No token, behavior or record changes.

Overlap checked: none (no open pull request touches packages/cli/assets/docs/motion.doc.mjs)

Docsite screenshots

Real Chrome on the pull request's preview at e080029, the new section with its heading near the top. The head after it (9be91b7) only adds four lines to the example's code block (the panel leaves on --duration-exit and --ease-exit); the heading, the table of contents and the inline code are unchanged. Before: the production docsite at main c3b7f32, where "Animate with motion tokens" is followed by "Tune motion from the theme" and the section does not exist. The table-of-contents entry fits at 1280 px, and inline code stays on one line at 390 px.

Light Dark
1280 px After, desktop, light After, desktop, dark
390 px After, phone, light After, phone, dark

Before (main, 1280 px, light):

Before, desktop, light

Test plan

  • astryx docs motion own-css prints the new section; the doc module loads with its 11 sections.
  • check:changesets and check:knowledge pass; the section and the Changeset are Prettier-clean.
  • The example's panel enters on --ease-entrance and leaves on --duration-exit and --ease-exit, as the section above it says.
  • The example's touch cross-fade plays both ways: .panel, .panel[data-hidden] share the coarse-pointer transition, so the hiding state's transition: none does not win.

@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Building Building Preview Nov 20, 2026 2:53am UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 18, 2026
@astracat-bot

astracat-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🔄 In progress (for maintainers only) Nov 20, 2026, 2:54 AM UTC

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec a642094

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec ef2ed6a

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the new "Using motion tokens in your own CSS" section fills a real gap, but its example does not do what the section says under a finger.

  • In packages/cli/assets/docs/motion.doc.mjs (lines 171-182), .panel[data-hidden] in the Reduce Motion block outranks .panel in the coarse-pointer block, so with Reduce Motion on a touch screen the panel fades in but vanishes at once when hidden; listing .panel, .panel[data-hidden] in the coarse-pointer block makes the exit cross-fade too.
  • The test plan promises docsite screenshots of the new section "below", but neither the description nor a comment includes them, so attach them or drop that line.

A smaller point: the Web Animations sentence could say to convert the value to milliseconds, because getPropertyValue('--duration-medium') returns a string such as 410ms, which element.animate() rejects as a duration.

Claims and files checked

Review mode: full; reason: no-earlier-review

  • Claim: the Motion doc gains one section on using the motion tokens in plain CSS: verified (lines 146-186).
  • Claim: the example slides a panel in on --duration-medium and --ease-entrance: verified; both tokens exist in Core's token defaults.
  • Claim: under Reduce Motion nothing travels and a mouse or trackpad changes at once: verified in Chromium.
  • Claim: under a finger the change becomes an opacity cross-fade of 200 ms or less: true for the prose and the entry, false for the example's exit.
  • Claim: the doc says to read a token's computed value for the Web Animations API: verified (line 153).
  • Claim: docs only, two files, no token, behavior or record changes: verified.
  • Claim: no open pull request touches the Motion doc: not checked against every open pull request.
  • Claim: astryx docs motion own-css prints the section and the doc has 11 sections: verified.
  • Claim: check:changesets and check:knowledge pass, and the new section and the Changeset are Prettier-clean: verified.
  • Claim: docsite screenshots are included below: false.
  • Changeset claim: the doc shows the tokens in your own CSS with a Reduce Motion fallback (no travel, immediate with a mouse, a cross-fade of 200 ms or less under a finger): true for the prose, false for the example's exit.
  • File .changeset/motion-doc-own-css.md: clear; its claim holds once the example's exit is fixed.
  • File packages/cli/assets/docs/motion.doc.mjs: the example's exit finding, plus the Web Animations note.

Automated review (maintainer link)

Comment thread packages/cli/assets/docs/motion.doc.mjs Resolved
Comment thread packages/cli/assets/docs/motion.doc.mjs Resolved
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec e3b741b

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec e080029

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the touch cross-fade now plays when the panel hides too, but the example's exit and the description still need fixes.

  • Miss: in packages/cli/assets/docs/motion.doc.mjs (lines 159-167), hiding the panel inherits var(--ease-entrance), so it leaves on the decelerating arrival curve although the same doc tells readers to ease something leaving on --ease-exit; adding .panel[data-hidden] { transition-timing-function: var(--ease-exit); } after the hidden rule fixes it and keeps the Reduce Motion blocks winning.
  • The description says the new section is called "Using motion tokens in your own CSS", but its heading at this head is "Motion tokens in your CSS", so update the description.
  • The test plan still promises docsite screenshots of the new section "below", but neither the description nor a comment includes them, so attach them or drop that line.

A smaller, non-blocking point: the Web Animations sentence could say to convert the token's value to milliseconds, since getPropertyValue('--duration-medium') returns a string such as 410ms, which element.animate() rejects as a duration.

Claims and files checked

Review mode: incremental; reason: none

  • changed rules (0): none
  • Claim: the Motion doc gains one section on using the motion tokens in plain CSS: verified (lines 146-187).
  • Claim: that section is called "Using motion tokens in your own CSS": false; its heading is "Motion tokens in your CSS" (line 148).
  • Claim: the example slides a panel in on --duration-medium and --ease-entrance: verified; both tokens exist in Core's token defaults.
  • Claim: under Reduce Motion nothing travels, a mouse or trackpad changes at once, and a finger gets an opacity cross-fade of 200 ms or less: verified in Chromium, for showing and for hiding.
  • Claim: for the Web Animations API the doc says to read the token's computed value first: verified (line 153).
  • Claim: docs only, two files, no token, behavior or record changes: verified.
  • Claim: no open pull request touches the Motion doc: not checked against every open pull request.
  • Claim: astryx docs motion own-css prints the new section and the doc has 11 sections: verified.
  • Claim: check:changesets and check:knowledge pass, and the new section and the Changeset are Prettier-clean: verified; Prettier's warnings on the file are all on older lines.
  • Claim: docsite screenshots are included below: false.
  • Changeset claim: the doc shows the tokens in your own CSS with the Reduce Motion fallback (no travel, immediate with a mouse, a cross-fade of 200 ms or less under a finger): verified.
  • File .changeset/motion-doc-own-css.md: clear.
  • File packages/cli/assets/docs/motion.doc.mjs: the exit-easing finding, plus the Web Animations note.

Automated review (maintainer link)

Comment thread packages/cli/assets/docs/motion.doc.mjs Resolved
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` 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.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: a token read with getComputedStyle(el).getPropertyValue('--duration-medium') is the string 410ms, and element.animate() rejects that as a duration. Saying to convert it to milliseconds first would save readers the TypeError.

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 9be91b7

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI is still running on this head, so it is not ready to merge until the required checks pass.

The new "Motion tokens in your CSS" section and its panel example follow the exit tokens and the Reduce Motion fallback when the panel shows and when it hides, and the two earlier example fixes hold.

  • Non-blocking: the Web Animations sentence (packages/cli/assets/docs/motion.doc.mjs:153) could add that a token read with getComputedStyle, such as 410ms, has to be converted to milliseconds before element.animate() accepts it.
Claims and files checked

Review mode: same-head; reason: none

Claims:

  • Changeset: the Motion doc shows the --duration-* and --ease-* tokens in your own CSS with the Reduce Motion fallback (no travel, an immediate change with a mouse, an opacity cross-fade of 200 ms or less under a finger): verified, motion.doc.mjs:147-188.
  • Changeset: a patch release note for @astryxdesign/cli, the package that ships the doc: verified, packages/cli/package.json publishes assets, and check:changesets passes.
  • Description: one new section, "Motion tokens in your CSS": verified, motion.doc.mjs:148.
  • Description: the panel slides in on --duration-medium and --ease-entrance: verified, :160-162.
  • Description: under Reduce Motion there is no travel, the change is immediate with a mouse, and a 200 ms opacity cross-fade plays under a finger when the panel shows and when it hides: verified, :173-187.
  • Description: for the Web Animations API the section says to read the token's computed value with getComputedStyle first: verified, :153.
  • Description: docs only, one section plus a Changeset, with no token, behavior or record change: verified, the diff touches only those two files.
  • Description: no open pull request touches the Motion doc: verified as far as checked: none of the 113 open pull requests that mention motion changes it.
  • Description: the screenshots' revision differs from the head only by four lines in the example's code block, where the panel leaves on the exit tokens: verified, those four lines are :167-170.
  • Description: before the change, "Animate with motion tokens" is followed by "Tune motion from the theme" and the section does not exist: verified at the base.
  • Description: the table-of-contents entry fits at 1280 px and inline code stays on one line at 390 px: verified from the head text (a 25-character heading; the longest inline code span is 16 characters) and the description's screenshots.
  • Test plan: astryx docs motion own-css prints the new section, and the doc loads with 11 sections: verified, the doc module loads with 11 sections including own-css, and the docs command prints a topic's section by its key.
  • Test plan: check:changesets and check:knowledge pass, and both files are Prettier-clean: verified, check:changesets passes on this head, and CI's knowledge-schema, formatting and Changeset-coverage checks pass.
  • Test plan: the panel enters on --ease-entrance and leaves on --duration-exit and --ease-exit: verified, :160-170.
  • Test plan: the touch cross-fade plays both ways because both selectors share the coarse-pointer block: verified, :184-186 comes last at equal specificity.

Files:

  • .changeset/motion-doc-own-css.md: clear.
  • packages/cli/assets/docs/motion.doc.mjs: clear apart from the non-blocking note on line 153.

Automated review (maintainer link)

@cixzhang
cixzhang marked this pull request as ready for review November 19, 2026 11:58
@cixzhang
cixzhang marked this pull request as draft November 19, 2026 12:22

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the new "Motion tokens in your CSS" section and its panel example are right, but CI fails on this head because the CLI's docs goldens were not updated for the new section.

  • Found by CI: packages/cli/test/__golden__/no-icon-set/docs-topics.json and docs-tree.json still list the Motion doc's sections without own-css (and with the old skeleton hash), so packages/cli/test/experimental-isolation.test.mjs fails in test-node (8/9); run vitest run packages/cli/test/experimental-isolation.test.mjs --update in the branch and commit the two golden diffs.

Otherwise the example follows the exit tokens and the Reduce Motion fallback when the panel shows and when it hides, and the two earlier example fixes hold. One non-blocking suggestion stands on line 153: say that a token read with getComputedStyle, such as 410ms, has to be converted to milliseconds before element.animate() accepts it.

Claims and files checked

Review mode: same-head; reason: none

Claims:

  • Changeset: the Motion doc shows the --duration-* and --ease-* tokens in your own CSS with the Reduce Motion fallback (no travel, an immediate change with a mouse, an opacity cross-fade of 200 ms or less under a finger): verified, motion.doc.mjs:147-188.
  • Changeset: a patch release note for @astryxdesign/cli, the package that ships the doc: verified, packages/cli/package.json publishes assets, and check:changesets passes.
  • Description: one new section, "Motion tokens in your CSS": verified, motion.doc.mjs:148.
  • Description: the panel slides in on --duration-medium and --ease-entrance: verified, :160-162.
  • Description: under Reduce Motion there is no travel, the change is immediate with a mouse, and a 200 ms opacity cross-fade plays under a finger when the panel shows and when it hides: verified, :173-187.
  • Description: for the Web Animations API the section says to read the token's computed value with getComputedStyle first: verified, :153.
  • Description: docs only, one section plus a Changeset, with no token, behavior or record change: verified, the diff touches only those two files.
  • Description: no open pull request touches the Motion doc: verified as far as checked: none of the 113 open pull requests that mention motion changes it.
  • Description: the screenshots' revision differs from the head only by four lines in the example's code block, where the panel leaves on the exit tokens: verified, those four lines are :167-170.
  • Description: before the change, "Animate with motion tokens" is followed by "Tune motion from the theme" and the section does not exist: verified at the base.
  • Description: the table-of-contents entry fits at 1280 px and inline code stays on one line at 390 px: verified in the docsite build of this head: the entry is one line at 1280 px and each inline code span stays on one line at 390 px.
  • Test plan: astryx docs motion own-css prints the new section, and the doc loads with 11 sections: verified, the doc module loads with 11 sections including own-css, and the docs command prints a topic's section by its key.
  • Test plan: check:changesets and check:knowledge pass, and both files are Prettier-clean: verified, check:changesets passes on this head, and CI's knowledge-schema, formatting and Changeset-coverage checks pass.
  • Test plan: the panel enters on --ease-entrance and leaves on --duration-exit and --ease-exit: verified, :160-170.
  • Test plan: the touch cross-fade plays both ways because both selectors share the coarse-pointer block: verified, :184-186 comes last at equal specificity.

Files:

  • .changeset/motion-doc-own-css.md: clear.
  • packages/cli/assets/docs/motion.doc.mjs: the new section changes the CLI's stable docs listing, whose goldens this pull request does not update (blocking, above); otherwise clear apart from the non-blocking note on line 153.

Automated review (maintainer link)

Comment thread packages/cli/assets/docs/motion.doc.mjs Resolved
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 1643c85

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet, because the pull request is a draft; marking it ready for review starts it.

The regenerated CLI docs goldens fix the earlier blocker, and packages/cli/test/experimental-isolation.test.mjs passes with the new own-css section. One non-blocking suggestion stands on line 153 of motion.doc.mjs: say that a token read with getComputedStyle, such as 410ms, has to be converted to milliseconds before element.animate() accepts it.

Claims and files checked

Review mode: incremental; reason: none

changed rules (0): none

Claims:

  • Changeset: the Motion doc shows the --duration-* and --ease-* tokens in your own CSS with the Reduce Motion fallback (no travel, an immediate change with a mouse, an opacity cross-fade of 200 ms or less under a finger): verified, motion.doc.mjs:147-188.
  • Changeset: a patch release note for @astryxdesign/cli, the package that ships the doc: verified, the package publishes assets, and check:changesets passes.
  • Description: one new section, "Motion tokens in your CSS": verified, motion.doc.mjs:148.
  • Description: the panel slides in on --duration-medium and --ease-entrance: verified, :160-162.
  • Description: under Reduce Motion there is no travel, the change is immediate with a mouse, and an opacity cross-fade of 200 ms or less plays under a finger when the panel shows and when it hides: verified, :173-187.
  • Description: for the Web Animations API the section says to read the token's computed value with getComputedStyle first: verified, :153.
  • Description: docs only, one section plus a Changeset, with no token, behavior or record change: verified; the branch also regenerates two CLI test goldens, which change no behavior.
  • Description: no open pull request touches the Motion doc: verified as far as checked: none of the 114 open pull requests that mention motion changes it.
  • Description: the screenshots' revision differs from the next one only by four lines in the example, where the panel leaves on the exit tokens: verified, those four lines are :167-170.
  • Description: before the change, "Animate with motion tokens" is followed by "Tune motion from the theme" and the section does not exist: verified at the base.
  • Description: the contents entry fits at 1280 px and inline code stays on one line at 390 px: verified on the docsite build of the previous revision; the section's source is unchanged since.
  • Test plan: astryx docs motion own-css prints the new section, and the doc loads with 11 sections: verified on this head.
  • Test plan: check:changesets and check:knowledge pass, and the section and the Changeset are Prettier-clean: verified on this head; Prettier's other differences in motion.doc.mjs are on lines the pull request does not touch.
  • Test plan: the panel enters on --ease-entrance and leaves on --duration-exit and --ease-exit: verified, :160-170.
  • Test plan: the touch cross-fade plays both ways because both selectors share the coarse-pointer block: verified, :184-186.

Files:

  • .changeset/motion-doc-own-css.md: clear.
  • packages/cli/assets/docs/motion.doc.mjs: clear apart from the non-blocking note on line 153.
  • packages/cli/test/__golden__/no-icon-set/docs-topics.json: clear; lists own-css after usage, as the doc orders it, with the new skeleton hash.
  • packages/cli/test/__golden__/no-icon-set/docs-tree.json: clear; the same section list.

Automated review (maintainer link)

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec d39ecf0

This branch was successfully deployed

1 active (outdated) deployment
Preview — 1643c85c Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant