Charts: tokenize shadow & animation values with WPDS elevation/motion tokens [CHARTS-200]

[adamwoodnz]

Why

The charts package is migrating to WordPress UI + Theme (WPDS), and shadows/motion were the last fully-hardcoded style category — 0% tokenized. Box-shadows were hand-rolled rgba() values and transitions/animations used literal timings (0.15s/0.2s/0.3s, 1s ease-out), so neither could follow the design system or be themed. WPDS now ships both --wpds-elevation-* and --wpds-motion-* tokens, so these can finally be routed through the design system the same way the package's spacing, typography, and border values already are.

Proposed changes

• Box-shadows → --wpds-elevation-sm — base tooltip, line-chart annotation popover, and conversion-funnel tooltip. All three are floating contextual surfaces, which map to elevation-sm ("Tooltips, Snackbar").
• Box-shadow → --wpds-elevation-xs — zoom-reset button. It's a stationary control rendered inside the chart's bounding box, not a floating overlay, so elevation-xs is the correct semantic tier and stays closest to its original subtle rgba(0,0,0,0.08) shadow.
• Transitions → --wpds-motion-duration-sm/md/lg + --wpds-motion-easing-subtle — leaderboard, conversion-funnel, and legend hover/state transitions. The prefers-reduced-motion override that disables these is left intact.
• Reveal animations → --wpds-motion-duration-xl (400ms) + --wpds-motion-easing-expressive — bar/area/line rise and bar/leaderboard/funnel stretch entrance animations.

Per the package's fallback-matches-spec rule (AGENTS.md), every fallback uses the exact WPDS spec value, so this adopts the design-system values rather than preserving the old pixels. Intentional visible consequences:

• Tooltip shadows become the softer, layered WPDS elevation-sm shadow instead of the old single rgba(0,0,0,0.1). The zoom-reset button uses elevation-xs instead — it's a stationary control, not a floating tooltip, and xs stays closest to its original subtle 0.08 shadow.
• Fallback-mode timing/easing shifts (i.e. when WPDS tokens aren't loaded, the fallbacks — which equal the WPDS spec — apply): leaderboard hover transitions go 0.15s → 100ms; the loading-state fade goes 0.3s → 300ms; and ease/ease-in-out are unified to easing-subtle (cubic-bezier(0.15, 0, 0.15, 1)). These are intentional consequences of adopting the DS motion scale, not regressions.
• Chart entrance animations shorten from 1s to 400ms — WPDS motion caps at 400ms, so the reveals move onto the design system's motion scale (a ~2.5× speed-up). This was a deliberate call rather than introducing charts-scoped motion tokens.

Commits are split by concern (shadows / transitions / animations / formatting / changelog) for easy review.

Screenshots

Rendered from the package's real compiled CSS with the WPDS tokens loaded. Both tooltips show the layered --wpds-elevation-sm shadow; the bars use the --wpds-motion-duration-xl (400ms) + easing-expressive reveal.

Related product discussion/links

• Linear: CHARTS-200 (includes the design-analysis P2 and the full hardcoded-instance inventory)

Does this pull request change what data or activity we track or use?

No.

Testing instructions

• Build the package to confirm the SCSS compiles: pnpm --filter @automattic/charts build (or jetpack build js-packages/charts).
• Unit tests: pnpm --filter @automattic/charts test (913 tests).
• In Storybook, open Line Chart (hover a point to show the tooltip) and Bar Chart (reload to replay the entrance animation):
  • The tooltip renders the layered WPDS elevation-sm shadow.
  • The zoom-reset button renders the subtler WPDS elevation-xs shadow.
  • Bars rise over ~400ms with the expressive easing (snappier than before).
• Theming check: with a @wordpress/theme ThemeProvider the shadow/motion follow the theme; without one, the fallbacks (which equal the WPDS spec values) render identically.

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the charts-200-shadowanimation-tokenization branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack charts-200-shadowanimation-tokenization

bin/jetpack-downloader test jetpack-mu-wpcom-plugin charts-200-shadowanimation-tokenization

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[adamwoodnz]

@copilot review this PR. Leave your feedback as review comments only — do NOT push commits, apply suggestions, or modify the branch in any way. I will make all code changes myself.

[jp-launch-control]

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report

[adamwoodnz]

Thanks for the thorough review — addressed below.

Zoom-reset button elevation tier — Good catch, agreed. It's a stationary control inside the chart, not a floating tooltip, and elevation-xs is also the most subtle WPDS shadow so it stays closest to the original 0 1px 2px rgba(0,0,0,0.08). Changed --wpds-elevation-sm → --wpds-elevation-xs in x-zoom.module.scss (dca6efa).

Fallback-mode timing/easing shifts not documented — Fair. Added a "Fallback-mode timing/easing shifts" bullet to the PR description calling out the leaderboard hover 0.15s → 100ms, the loading fade 0.3s → 300ms, and the ease/ease-in-out → easing-subtle unification. As you note, these follow the package's fallback-matches-spec rule and are intentional.

Base-tooltip rgba(0, 0, 0, 0.85) background still hardcoded — Out of scope for this issue (CHARTS-200 is shadow/animation only); color tokenization is tracked separately. Leaving it for that work.

Changelog Charts: prefix — Keeping it. The package's own AGENTS.md documents the convention as -e "Charts: <user-facing change>.", which matches the existing CHANGELOG.md history, so the prefix is correct here.

No functional/security concerns flagged — thanks. Re-requesting review on the updated branch.

[adamwoodnz]

@copilot review this PR. Leave your feedback as review comments only — do NOT push commits, apply suggestions, or modify the branch in any way. I will make all code changes myself.

[adamwoodnz]

@claude please review this PR.

Context: Copilot has completed its rounds (LGTM after addressing the zoom-reset elevation tier). One CI check, WordPress.com Tests, is red — but it passes on every other current open PR, the change is CSS-only token substitution (all local + GitHub JS/lint/changelog checks green), and its log is on internal infra not reachable via gh. Flagging it for a human/maintainer to confirm it's unrelated.

[adamwoodnz]

Thanks @claude — both final-check items verified, no code changes needed:

1. Fallbacks vs WPDS source of truth — cross-checked all changed fallbacks against the installed @wordpress/theme@0.15.1 (build-module/prebuilt/js/design-token-fallbacks.mjs). Byte-identical:

Token	Fallback used = WPDS source
--wpds-elevation-xs	0 1px 1px 0 #00000008, 0 1px 2px 0 #00000005, 0 3px 3px 0 #00000005, 0 4px 4px 0 #00000003
--wpds-elevation-sm	0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005
--wpds-motion-easing-subtle	cubic-bezier(0.15, 0, 0.15, 1)
--wpds-motion-easing-expressive	cubic-bezier(0.25, 0, 0, 1)
--wpds-motion-duration-sm/md/lg/xl	100ms / 200ms / 300ms / 400ms

2. Reduced-motion + the faster reveals — confirmed suppressed. The --animated class is JS-gated, e.g. bar-chart.tsx:502:

[ styles[ `bar-chart--animated${ horizontal ? '-horizontal' : '' }` ] ]:
    animation && ! prefersReducedMotion,

Every animated chart (bar/area/line/leaderboard/funnel) imports usePrefersReducedMotion, so reduced-motion users never receive the keyframe class — the 1s → 400ms change can't affect them.

WordPress.com Tests — agreed it needs a maintainer with sandbox access to confirm; a pure SCSS fallback swap has no path to a PHP/wpcom failure. Leaving it flagged for the human reviewer.

[adamwoodnz]

Review cycle summary

Copilot (2 rounds): Round 1 raised 5 points — addressed the actionable one (zoom-reset button → --wpds-elevation-xs, since it's a stationary control not a tooltip), documented the fallback-mode timing/easing shifts in the PR description, and pushed back on the changelog-prefix suggestion (Charts: is the convention per the package AGENTS.md). Round 2: LGTM.

@claude (final round): LGTM with two non-blocking checks, both verified —

• All changed fallbacks are byte-identical to the installed @wordpress/theme@0.15.1 source (elevation-xs/-sm, easing subtle/expressive, durations sm/md/lg/xl).
• Entrance reveals are JS-gated by usePrefersReducedMotion (animation && ! prefersReducedMotion), so reduced-motion users are unaffected by the 1s → 400ms change.

CI: All GitHub-API-visible checks green (build, JS/PHP tests, lint, E2E, changelogger). WordPress.com Tests is red — it runs on a8c-internal infra not inspectable or rerunnable via gh, passes on every other current open PR, and a pure SCSS fallback swap has no path to a PHP/wpcom failure. Flagged for a maintainer with sandbox access to confirm before merge.

Status: Ready for human merge review. No unaddressed human-reviewer comments; no open inline threads. Sole caveat: the internal WordPress.com Tests check above.