Stylelint: no WPDS token fallback values for WP Build routes by simison · Pull Request #50502 · Automattic/jetpack

simison · 2026-07-14T12:39:13Z

Follow-up to #50110 which added linting for WPDS tokens but didn't enforce the "no fallbacks" rule yet.

Proposed changes

Enforces "no fallbacks" rule to paths which are built using wp-Build tooling: build pipeline in wp-build already adds fallbacks at build-time, so this is a safe change.

Manually maintaining fallbacks is error-prone and requires more work during @wordpress/theme updates.

List of paths is manually maintained list since it's meant to be temporary. I'm working through changes across codebase to add fallbacks in Webpack build bundles (#50108). Once that's finished, we can start linting the rest of the stylesheets as well.

On wp-build admin pages, WPDS tokens are always loaded and manual fallbacks are ignored — the browser always uses the token value from the theme.

However, there were some mismatches, and it's worth documenting just in case.

See list by severity

High — wrong token semantics or large visual delta

Token	Removed fallback	WPDS value	File(s)	Notes
`--wpds-color-stroke-interactive-neutral-strong`	`#1d35b4` (admin blue)	`#6e6e6e` (neutral gray)	`videopress/routes/overview/style.scss`	Tab underline indicator. Fallback implied brand color, but token is neutral stroke. With tokens loaded, tabs were already gray. If blue was intended, should use `--wpds-color-stroke-surface-brand-strong` or `--wpds-color-stroke-interactive-brand`.
`--wpds-border-radius-md`	`8px`	`4px`	`premium-analytics/.../post-summary-card.module.scss`	`8px` is `--wpds-border-radius-lg`, not `md`. Likely copy-paste error.
`--wpds-border-radius-sm`	`6px`	`2px`	same file (`.image`)	Image corners were much rounder in the fallback-only path.

Medium — noticeable color differences

Token	Removed fallback(s)	WPDS value	File(s)
`--wpds-color-stroke-surface-neutral`	`#e0e0e0`, `#f0f0f1`	`#dbdbdb`	forms responses + dataviews header; newsletter panel header
`--wpds-color-foreground-content-neutral-weak`	`#50575e`, `#3c434a`, `#757575`	`#707070`	newsletter dashboard (×4), subscribers-announcement, post-summary-card (×2)

The newsletter dashboard even has TODOs about wanting a “muted text” tone — the removed values were WordPress admin grays (#50575e ≈ $gray-50, #3c434a ≈ $gray-60), not WPDS #707070. With tokens loaded, muted text was already #707070.

Low — minor or structural differences

Token	Removed	WPDS	Impact
`--wpds-typography-font-family-heading`	truncated stack (no Oxygen-Sans, Ubuntu, etc.)	full system stack	`forms/routes/response/style.scss` — minor font fallback difference only when tokens missing
`--wpds-color-stroke-focus`	`#1d35b4`	`#3858e9` (runtime) / `var(--wp-admin-theme-color, #3858e9)` (PostCSS fallback)	`videopress/routes/overview/style.scss` — different blue; now theme-aware
`--wpds-border-width-focus`	`2px`	`var(--wp-admin-border-width-focus, 2px)`	premium-analytics stage files — equivalent when admin var is 2px; runtime CSS hardcodes `2px`

Related product discussion/links

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

Testing instructions

Smoke test affected routes:

Forms
Newsletter
Premium Analytics
VideoPress
SEO
Scan
Social
Podcast

No differences in bundles, apart from corrected fallback values (they're now canonical rather than incorrect).

github-actions · 2026-07-14T12:40:23Z

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), and enable the update/stylelint-wp-build-no-token-fallback-values branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/stylelint-wp-build-no-token-fallback-values

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 · 2026-07-14T12:40:38Z

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:

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!

jp-launch-control · 2026-07-14T12:51:41Z

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

simison · 2026-07-14T16:01:06Z

Smoke tested routes:

anomiex · 2026-07-14T18:16:28Z

 			},
 		],
 	},
+	overrides: [


I'd really rather we don't have a big list of permanent overrides in this global configuration file, that people will have to know to maintain. Are these meant to be temporary? If not, please move these into stylelint config files in each project.

I agree and they're indeed meant to be temporary and going away as soon as everything can be linted with the same rule across the repo. It's just easier to migrate in smaller chunks, and this was most pragmatic temporary solution.

Hopefully no longer than just this week!

ok, thanks! 🙂

Aight, got pretty far!

Among files with --wpds-* the linter + build time fallbacks now cover:

Covered Total %

Files 147 173 85.0%

Packages 16 21 76.2%

Not on the rule: charts, components, base-styles, social-previews, plugins/jetpack

I might flip the rule the other way around; ignore those and apply everywhere else.

Those others are pretty complicated:

charts and social-previews use LightningCSS, not PostCSS

Jetpack plugin still relies on old Calypso colour schemes a little too much

components and base-styles are just unique cases otherwise

I will continue after short vacation. :-)

I might flip the rule the other way around; ignore those and apply everywhere else.

Stylelint: enable no-token-fallback-values (almost) everywhere #50645

anomiex · 2026-07-14T18:24:44Z

 	display: inline-flex;
 	align-items: center;
-	gap: var(--wpds-dimension-gap-xs, 4px);
+	gap: var(--wpds-dimension-gap-xs);


It seems the plugin didn't add a fallback for this one for some reason.

🤔 Just checked it's a real valid token.

https://wordpress.github.io/gutenberg/?path=/docs/design-system-tokens-introduction--docs#dimension

anomiex · 2026-07-14T18:24:50Z

 	 */
 	padding-block-end: 24px;
-	padding-inline: var(--wpds-dimension-padding-2xl, 24px);
+	padding-inline: var(--wpds-dimension-padding-2xl);


It seems the plugin didn't add a fallback for this one for some reason.

simison requested a review from a team July 14, 2026 12:39

simison requested review from a team as code owners July 14, 2026 12:39

simison added the Build label Jul 14, 2026

github-actions Bot added [Feature] Contact Form [Package] Forms [Package] Newsletter [Package] Premium Analytics [Package] VideoPress labels Jul 14, 2026

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 Jul 14, 2026

simison added [Status] Needs Review This PR is ready for review. 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 Jul 14, 2026

simison force-pushed the update/stylelint-wp-build-no-token-fallback-values branch 2 times, most recently from ad86d20 to 798102e Compare July 14, 2026 14:23

simison added 3 commits July 14, 2026 17:51

Stylelint: no token fallback values for WP Build dashboards

9bf88d6

Remove manual WPDS token fallbacks

fc5ed1d

Changelogs

c9137da

simison force-pushed the update/stylelint-wp-build-no-token-fallback-values branch from 798102e to c9137da Compare July 14, 2026 14:53

simison merged commit 3938f22 into trunk Jul 14, 2026
78 checks passed

simison deleted the update/stylelint-wp-build-no-token-fallback-values branch July 14, 2026 16:01

github-actions Bot removed the [Status] Needs Review This PR is ready for review. label Jul 14, 2026

anomiex reviewed Jul 14, 2026

View reviewed changes

This was referenced Jul 15, 2026

Stylelint: no token fallback values (VideoPress, Search, Forms, Publicize, & Boost) #50527

Merged

Premium analytics: remove token fallbacks #50566

Merged

This was referenced Jul 17, 2026

WPDS token fallbacks: clean out various screens (SEO, Newsletter, Scan) #50634

Merged

Stylelint: enable no-token-fallback-values (almost) everywhere #50645

Merged

Navigation Menu

Uh oh!

Stylelint: no WPDS token fallback values for WP Build routes - #50502

Stylelint: no WPDS token fallback values for WP Build routes#50502
simison merged 3 commits into
trunkfrom
update/stylelint-wp-build-no-token-fallback-values

simison commented Jul 14, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

jp-launch-control Bot commented Jul 14, 2026

Uh oh!

simison commented Jul 14, 2026

Uh oh!

Uh oh!

anomiex Jul 14, 2026

Uh oh!

simison Jul 14, 2026

Uh oh!

anomiex Jul 14, 2026

Uh oh!

simison Jul 17, 2026 •

edited

Loading

Uh oh!

simison Jul 17, 2026 •

edited

Loading

Uh oh!

anomiex Jul 14, 2026

Uh oh!

simison Jul 14, 2026

Uh oh!

anomiex Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

simison commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

High — wrong token semantics or large visual delta

Medium — noticeable color differences

Low — minor or structural differences

Related product discussion/links

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

Testing instructions

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

jp-launch-control Bot commented Jul 14, 2026

Code Coverage Summary

Uh oh!

simison commented Jul 14, 2026

Uh oh!

Uh oh!

anomiex Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

simison Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

anomiex Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

simison Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simison Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anomiex Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

simison Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

anomiex Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

simison commented Jul 14, 2026 •

edited

Loading

github-actions Bot commented Jul 14, 2026 •

edited

Loading

github-actions Bot commented Jul 14, 2026 •

edited

Loading

simison Jul 17, 2026 •

edited

Loading

simison Jul 17, 2026 •

edited

Loading