WPDS token rename sweep for @wordpress/theme 0.16 (for #49272) by CGastrell · Pull Request #50089 · Automattic/jetpack

CGastrell · 2026-06-30T20:25:28Z

Proposed changes

Full-repo WPDS design-token rename for @wordpress/theme 0.16, intended to land with the bundled @wordpress/* update (#49272). This branch is based on #49272's head and adds the token sweep on top, kept separate so a Renovate force-rebase of #49272 can't trash it.

@wordpress/theme 0.16 renames the color tokens and drops the old names, so once #49272 ships @wordpress/ui 0.16 the old names go undefined. This renames every usage across the monorepo:

--wpds-color-bg-* → --wpds-color-background-*
--wpds-color-fg-* → --wpds-color-foreground-*
--wpds-color-stroke-focus-brand → --wpds-color-stroke-focus
--wpds-dimension-base (removed) → --wpds-dimension-size-5xs (both 4px; calc() preserved → masthead 24px, premium-analytics 240px unchanged)

Three tokens that no longer exist were remapped semantically (these are the only non-1:1 cases — the review-risk surface):

--wpds-color-bg-surface-primary → --wpds-color-background-surface-neutral-strong
--wpds-color-stroke-surface-neutral-weaker → --wpds-color-stroke-surface-neutral-weak
--wpds-font-size-sm → --wpds-typography-font-size-sm

Renames are name-only — token values are unchanged (confirmed with the DS team), so there is no intended visual change.

Dependency alignment (first commit)

So the renamed tokens validate, the DS linters are moved to versions whose token vocabulary is 0.16:

Package	From	To	wants `@wordpress/theme`
`@wordpress/theme` (all pins)	0.15.1	0.16.0	—
`@wordpress/stylelint-config`	23.40.1	23.41.0	`^0.16.0`
`@wordpress/eslint-plugin`	25.4.1	25.5.0	`^0.16.0`

Pairs with @wordpress/ui 0.16.0 already in #49272. theme 0.16 and 0.17 ship an identical token set, so the 0.16 line is a safe self-consistent matrix; bumping further to the 0.17 line (theme 0.17 / ui 0.16.1 / eslint-plugin 25.5.1) is an optional follow-up for the DS team.

Verification

The rename is mechanically complete and machine-verified — every --wpds-* token left in source validates against the 0.16 vocabulary on both linters:

stylelint (plugin-wpds/no-unknown-ds-tokens) — green on all 59 changed CSS/SCSS files.
eslint (@wordpress/no-unknown-ds-tokens) — green on all 20 changed TSX/TS files.

What CI can't catch is whether a renamed-but-valid token still renders correctly. Since values are unchanged that risk is low, but the three semantic remaps + the dimension-base calc sites deserve eyes. Same smoke test the @wordpress/ui bump needs anyway.

Testing instructions

Token values are unchanged, so each affected surface should look identical to before. Spot-check the dashboards below (compare against trunk):

Area	URL
Forms responses dashboard	`/wp-admin/admin.php?page=jetpack-forms-admin`
Premium Analytics dashboard (widgets, charts, icons — heaviest changes)	`/wp-admin/admin.php?page=jetpack-premium-analytics`
Jetpack Search dashboard (experience selector + previews)	`/wp-admin/admin.php?page=jetpack-search`
Newsletter / Subscribers (add-subscriber modal, settings cards)	`/wp-admin/admin.php?page=jetpack-newsletter`
Jetpack Social	`/wp-admin/admin.php?page=jetpack-social`
Protect / Scan	`/wp-admin/admin.php?page=jetpack-protect`
Backup	`/wp-admin/admin.php?page=jetpack-backup`
VideoPress	`/wp-admin/admin.php?page=jetpack-videopress`
SEO settings	`/wp-admin/admin.php?page=jetpack#/settings` (Traffic → SEO)
Jetpack settings masthead (the `dimension-base` change)	`/wp-admin/admin.php?page=jetpack`
Shared (footer / admin-page layout / status indicator from js-packages/components)	renders on all Jetpack admin pages above

Couldn't pin a single dedicated screen for: activity-log (renders inside the Jetpack/Backup activity view) and the shared base-styles / charts / components packages (they render within the dashboards listed above rather than a page of their own).

🤖 Generated with Claude Code

github-actions · 2026-06-30T20:26:52Z

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 🤖

🔴 Action required: We would recommend that you add a section to the PR description to specify whether this PR includes any changes to data or privacy, like so:

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

My PR adds *x* and *y*.

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
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!

Jetpack plugin:

The Jetpack plugin has different release cadences depending on the platform:

WordPress.com Simple releases happen as soon as you deploy your changes after merging this PR (PCYsg-Jjm-p2).
WoA releases happen weekly.
Releases to self-hosted sites happen monthly:
- Scheduled release: July 7, 2026
- Code freeze: July 6, 2026

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Protect plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Bumps @wordpress/theme 0.15.1 -> 0.16.0 across all package pins, and the two design-system linters to versions whose token vocabulary matches 0.16 (so the renamed tokens validate): - @wordpress/stylelint-config 23.40.1 -> 23.41.0 (wants @wordpress/theme ^0.16.0) - @wordpress/eslint-plugin 25.4.1 -> 25.5.0 (wants @wordpress/theme ^0.16.0) This pairs with @wordpress/ui 0.16.0 already in this branch. theme 0.16 and 0.17 ship an identical token set, so the 0.16 line is a safe, self-consistent matrix; bumping further to the 0.17 line (theme 0.17 / ui 0.16.1 / eslint-plugin 25.5.1) is a separate, optional follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

@wordpress/theme 0.16 renames the color design tokens and drops the old names: - --wpds-color-bg-* -> --wpds-color-background-* - --wpds-color-fg-* -> --wpds-color-foreground-* - --wpds-color-stroke-focus-brand -> --wpds-color-stroke-focus - --wpds-dimension-base (removed) -> --wpds-dimension-size-5xs (both 4px; calc() preserved) Plus three semantic remaps of tokens that no longer exist: - --wpds-color-bg-surface-primary -> --wpds-color-background-surface-neutral-strong - --wpds-color-stroke-surface-neutral-weaker -> --wpds-color-stroke-surface-neutral-weak - --wpds-font-size-sm -> --wpds-typography-font-size-sm Renames are name-only; token values are unchanged, so there is no intended visual change. Applied across SCSS/CSS and inline-style usages in TSX/TS. Verified: every remaining --wpds-* token in source validates against the 0.16 vocabulary (stylelint plugin-wpds/no-unknown-ds-tokens + eslint @wordpress/no-unknown-ds-tokens both clean). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-30T20:37:07Z

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 update/wpds-token-names-sweep branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/wpds-token-names-sweep

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/wpds-token-names-sweep

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

@wordpress/theme 0.16 promotes ThemeProvider to a stable export and removes `privateApis`. The charts Storybook decorator unlocked `theme.privateApis` to get ThemeProvider, which throws "Cannot unlock an undefined object" under 0.16 and breaks the Storybook tests. Import the stable `ThemeProvider` directly; its props (incl. `color`) are unchanged. Leaves ./unlock orphaned in the charts stories. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

jp-launch-control · 2026-06-30T20:59:11Z

Code Coverage Summary

No summary data is available for parent commit 0722a50, so cannot calculate coverage changes. 😴

If that commit is a feature branch rather than a trunk commit, this is expected. Otherwise, this should be updated once coverage for 0722a50 is available.

Full summary · PHP report · JS report

CGastrell · 2026-06-30T21:23:48Z

 		outline:
 			var(--wpds-border-width-focus, 2px) solid
-			var(--wpds-color-stroke-focus-brand);
+			var(--wpds-color-stroke-focus);


Is this expected?

Yup WordPress/gutenberg#79125

CGastrell · 2026-06-30T21:25:11Z

 	background-color: #fff;
 	padding-bottom: var(--wpds-dimension-gap-sm);
-	width: calc(60 * var(--wpds-dimension-base));
+	width: calc(60 * var(--wpds-dimension-size-5xs));


Validate computed value here

Let's use --wpds-dimension-surface-width-xs instead?

CGastrell · 2026-06-30T21:30:16Z

 	&:hover,
 	&:focus-visible {
-		color: var(--wpds-color-fg-interactive-brand-active);
+		color: var(--wpds-color-foreground-interactive-brand-active);


⚠️ Heads-up: this token isn't a pure name-only rename. --wpds-color-fg-interactive-brand-active was #3858e9 in @wordpress/theme 0.15.1, but --wpds-color-foreground-interactive-brand-active is #0b0070 in 0.16 — a real DS value change, not just a name change. So this :active color (the only usage of this token in the sweep) will render a darker indigo once 0.16 lands. Low blast radius, but it's a genuine visual change — worth a smoke-test on the Search experience selector, and the PR body's blanket "values unchanged / no visual change" doesn't hold for this one.

CGastrell · 2026-06-30T21:30:17Z

 				fontWeight: 600,
-				fontSize: 'var(--wpds-font-size-sm, 14px)',
-				color: 'var(--wpds-color-fg-content-neutral, #1e1e1e)',
+				fontSize: 'var(--wpds-typography-font-size-sm, 14px)',


Note on the three "semantic remaps" flagged as the risk surface — all three live in this single Storybook story (non-production). Two of them also shift the rendered value, because the old names were undefined in 0.15 (so they fell through to the inline fallback) while the new names resolve in 0.16:

stroke-surface-neutral-weaker (undefined → fallback #e0e0e0) → stroke-surface-neutral-weak (resolves to #f0f0f0)

font-size-sm (undefined → fallback 14px) → typography-font-size-sm (resolves to 12px)

bg-surface-primary → background-surface-neutral-strong stays #fff. All Storybook-only, so negligible — just flagging that "no visual change" is technically not true here either.

CGastrell · 2026-06-30T21:30:18Z

@@ -1,15 +1,10 @@
 import { setLocale } from '@automattic/number-formatters';
-import { privateApis as themePrivateApis } from '@wordpress/theme';
+import { ThemeProvider } from '@wordpress/theme';


With ThemeProvider now imported directly (it became public in 0.16), ./unlock is no longer imported here. Can someone confirm src/stories/unlock.ts is now unused repo-wide? If so it's dead code and can be deleted in this PR (only remaining reference is a doc-comment in premium-analytics/.../lock/unlock.ts).

ciampo

Mechanically, this PR feels solid — although I haven't tested things myself, I just review the code.

Also, would it be possible to update to @wordpress/ui@0.16.1 and to @wordpress/theme@0.17.0 directly?

ciampo · 2026-06-30T21:33:01Z

 		outline:
 			var(--wpds-border-width-focus, 2px) solid
-			var(--wpds-color-stroke-focus-brand);
+			var(--wpds-color-stroke-focus);


Yup WordPress/gutenberg#79125

ciampo · 2026-06-30T21:34:33Z

 	background-color: #fff;
 	padding-bottom: var(--wpds-dimension-gap-sm);
-	width: calc(60 * var(--wpds-dimension-base));
+	width: calc(60 * var(--wpds-dimension-size-5xs));


Let's use --wpds-dimension-surface-width-xs instead?

ciampo · 2026-06-30T21:35:06Z

 			width,
 			height,
-			border: '1px solid var(--wpds-color-stroke-surface-neutral-weaker, #e0e0e0)',
+			border: '1px solid var(--wpds-color-stroke-surface-neutral-weak, #e0e0e0)',


If using wp-build, the fallback values should be added automatically (here and everywhere in the PR / repo)

ciampo · 2026-06-30T21:38:08Z

+	width: calc(var(--wpds-dimension-size-5xs, 4px) * 6);
+	height: calc(var(--wpds-dimension-size-5xs, 4px) * 6);


Same here, let's use --wpds-dimension-size-sm instead?

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

CGastrell requested review from a team as code owners June 30, 2026 20:25

github-actions Bot added the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Jun 30, 2026

CGastrell self-assigned this Jun 30, 2026

CGastrell added [Status] In Progress and removed [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. labels Jun 30, 2026

CGastrell and others added 2 commits June 30, 2026 17:35

CGastrell force-pushed the update/wpds-token-names-sweep branch from eb19a59 to 86f64a6 Compare June 30, 2026 20:35

CGastrell requested a review from Copilot June 30, 2026 21:19

Copilot started reviewing on behalf of CGastrell June 30, 2026 21:19 View session

CGastrell commented Jun 30, 2026

View reviewed changes

ciampo reviewed Jun 30, 2026

View reviewed changes

Copilot AI reviewed Jun 30, 2026

kangzj requested a review from adamwoodnz July 1, 2026 03:42

		width: calc(var(--wpds-dimension-size-5xs, 4px) * 6);
		height: calc(var(--wpds-dimension-size-5xs, 4px) * 6);

Uh oh!

Conversation

CGastrell commented Jun 30, 2026

Proposed changes

Dependency alignment (first commit)

Verification

Testing instructions

Uh oh!

github-actions Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jp-launch-control Bot commented Jun 30, 2026

Code Coverage Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 30, 2026 •

edited

Loading

github-actions Bot commented Jun 30, 2026 •

edited

Loading