Skip to content

Stylelint: configure wp theme style tokens build & linting - #111395

Closed
simison wants to merge 3 commits into
trunkfrom
update/stylelint-wp-theme
Closed

Stylelint: configure wp theme style tokens build & linting#111395
simison wants to merge 3 commits into
trunkfrom
update/stylelint-wp-theme

Conversation

@simison

@simison simison commented Jun 5, 2026

Copy link
Copy Markdown
Member

Proposed Changes

  • Adds build pipeline to inject WPDS token fallbacks: uses shared PostCSS config instead of redefining the plugins list each time
  • Adds stylelint for consistent clean WPDS usage
  • Fix lint issues

See build config and stylelint plugin docs for @wordpress/theme for details.

Why are these changes being made?

  • For consistent design system usage in the repo, guide agents and humans as well. :-)

Testing Instructions

Pre-merge Checklist

  • Has the general commit checklist been followed? (PCYsg-hS-p2)
  • Have you written new tests for your changes?
  • Have you tested the feature in Simple (P9HQHe-k8-p2), Atomic (P9HQHe-jW-p2), and self-hosted Jetpack sites (PCYsg-g6b-p2)?
  • Have you checked for TypeScript, React or other console errors?
  • For UI changes, have you tested the affected components in dark mode?
  • Have you tested accessibility for your changes? Ensure the feature remains usable with various user agents (e.g., browsers), interfaces (e.g., keyboard navigation), and assistive technologies (e.g., screen readers) (PCYsg-S3g-p2).
  • Have you used memoizing on expensive computations? More info in Memoizing with create-selector and Using memoizing selectors and Our Approach to Data
  • Have we added the "[Status] String Freeze" label as soon as any new strings were ready for translation (p4TIVU-5Jq-p2)?
    • For UI changes, have we tested the change in various languages (for example, ES, PT, FR, or DE)? The length of text and words vary significantly between languages.
  • For changes affecting Jetpack: Have we added the "[Status] Needs Privacy Updates" label if this pull request changes what data or activity we track or use (p4TIVU-aUh-p2)?

simison added 2 commits June 5, 2026 17:05
@simison
Add WPDS design token linting and build-time fallbacks.
f406971 
Enable @wordpress/theme stylelint rules and inject --wpds-* token fallbacks via PostCSS so styles render correctly without manual var() fallbacks in source.
@simison
Fix WPDS design token stylelint violations.
12bf79f 
Replace invalid token names, remove manual var() fallbacks, and allow dark-theme brand token overrides where Calypso maps the accent palette.
@github-actions

github-actions Bot commented Jun 5, 2026 •
edited by matticbot
Loading

Copy link
Copy Markdown

Link to live branch is being generated...
Please wait a few minutes and refresh this page.

@simison simison changed the title Update/stylelint wp theme Stylelint: configure wp theme style tokens build & linting Jun 5, 2026
@simison
simison requested review from aduth, ciampo and mirka June 5, 2026 14:29
@matticbot matticbot added the [Status] Needs Review The PR is ready for review. This also triggers e2e canary tests and wp-desktop tests automatically. label Jun 5, 2026
@github-actions

github-actions Bot commented Jun 5, 2026

Copy link
Copy Markdown

Looks like one of the E2E tests has failed.

You can fix them following these steps:

  1. Check out this branch locally: 
    gh pr checkout 111395
  2. Start Claude Code in the repo: 
    claude
  3. Run the /fix-e2e-tests skill, passing this PR number: 
    /fix-e2e-tests 111395

1 similar comment
@github-actions

github-actions Bot commented Jun 5, 2026

Copy link
Copy Markdown

Looks like one of the E2E tests has failed.

You can fix them following these steps:

  1. Check out this branch locally: 
    gh pr checkout 111395
  2. Start Claude Code in the repo: 
    claude
  3. Run the /fix-e2e-tests skill, passing this PR number: 
    /fix-e2e-tests 111395

ciampo
ciampo reviewed Jun 8, 2026
View reviewed changes

@ciampo ciampo 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.

Apart from inline comments, some higher-level notes:

Stale yarn.lock

We'll need to run yarn and update the lock file to fix CI checks. We may also want to silence the warnings about missing peerDependencies for the @wordpress/theme package via the peerDependenciesMeta setting.

DS Tokens changes

Regarding the DS tokens changes, I only flagged the changes that seem to introduce semantic mismatches (eg a stroke token used as background, an interactive token used for non-interactive UI). It looks like there are more changes that tweak the underlying value and therefore are visual changes, but I didn't test them for the lack of testing instructions.

Apps with own PostCSS

The changes to the shared postcss.config.js are likely not picked up by apps that override the default getWebpackConfig with their own config:

  • apps/help-center/postcss.config.js
  • apps/notifications/postcss.config.js

Not sure if these apps consume any WPDS tokens, but it may be worth applying those changes to their configs, too

Comment thread client/my-sites/podcast/style.scss
inset-inline-end: 16px;
padding: 4px 10px;
background: var( --wpds-color-bg-content-neutral-medium, #50575e );
background: var( --wpds-color-bg-interactive-neutral-strong );

@ciampo ciampo Jun 8, 2026

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.

Looks like we're using a interactive DS token for non-interactive UI (badge)

Comment thread client/my-sites/podcast/style.scss

&.is-recommended {
background: var( --wpds-color-bg-status-success-strong, #1a8d36 );
background: var( --wpds-color-stroke-surface-success-strong );

@ciampo ciampo Jun 8, 2026

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.

We shouldn't be using a stroke DS token for a background color

Comment thread client/my-sites/podcast/style.scss
block-size: 32px;
border-radius: 50%;
background: var( --wpds-color-bg-content-neutral-strong, #2c3338 );
background: var( --wpds-color-bg-interactive-neutral-strong );

@ciampo ciampo Jun 8, 2026

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.

Same here — we shoulnd't use interactive DS tokens for non=interactive UI

Comment thread client/components/jetpack/jetpack-footer/style.scss
@@ -44,10 +44,10 @@
}

.jetpack-footer__logo-text {

@ciampo ciampo Jun 8, 2026

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.

Is this an opportunity to use the Text component from @wordpress/ui?

Comment thread client/components/jetpack/jetpack-footer/style.scss
Comment on lines -13 to +16
font-family: var(--wpds-font-family-body);
font-size: var(--wpds-font-size-sm, 12px);
font-weight: var(--wpds-font-weight-regular, 400);
line-height: var(--wpds-font-line-height-xs, 16px);
font-family: var(--wpds-typography-font-family-body);
font-size: var(--wpds-typography-font-size-sm);
font-weight: var(--wpds-typography-font-weight-regular);
line-height: var(--wpds-typography-line-height-xs);

@ciampo ciampo Jun 8, 2026

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.

Same here re. Text component

Comment thread packages/calypso-build/package.json
"@swc/core": "^1.11.24",
"@types/webpack-env": "^1.18.8",
"@wordpress/browserslist-config": "^6.46.0",
"@wordpress/theme": "^0.13.0",

@ciampo ciampo Jun 8, 2026

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.

Nit: not in alphabetical order

mirka
mirka reviewed Jun 18, 2026
View reviewed changes

@mirka mirka left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Are we also going to load the design-tokens stylesheet in all the environments? The fallback plugin is more like a backup and/or transitional mechanism, so ultimately it would be good to load the tokens stylesheet everywhere. (Not saying it has to happen in this PR though.)

@ciampo

ciampo commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

WordPress/gutenberg#78664 may be relevant to add as context here, where the @wordpress/theme stylesheets are enqueued from the PHP side

@github-actions

github-actions Bot commented Aug 24, 2026

Copy link
Copy Markdown

This PR has been marked as stale. This happened because:

  • It has been inactive for the past 3 months.
  • It hasn't been labeled `[Pri] BLOCKER`, `[Pri] High`, `[Status] Keep Open`, etc.

If this PR is still useful, please do a trunk merge or rebase and otherwise make sure it's up to date and has clear testing instructions. You may also want to ping possible reviewers in case they've forgotten about it. Please close this PR if you think it's not valid anymore — if you do, please add a brief explanation.

If the PR is not updated (or at least commented on) in another month, it will be automatically closed.

@github-actions

github-actions Bot commented Sep 24, 2026

Copy link
Copy Markdown

This PR has been automatically closed as it has not been updated in some time. If you want to resume work on the PR, feel free to restore the branch and reopen the PR.

@github-actions github-actions Bot closed this Sep 24, 2026
@github-actions
github-actions Bot deleted the update/stylelint-wp-theme branch September 24, 2026 18:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mirka mirka mirka left review comments
@ciampo ciampo ciampo left review comments
@aduth aduth Awaiting requested review from aduth

Assignees

No one assigned

Labels

[Status] Needs Review The PR is ready for review. This also triggers e2e canary tests and wp-desktop tests automatically. [Status] Stale

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@simison @ciampo @mirka @matticbot