Skip to content

Components: Complete WPDS token migration for remaining borders#79003

Merged
ciampo merged 7 commits into
WordPress:trunkfrom
himanshupathak95:upd/79001-components-wpds-border-colors
Jun 16, 2026
Merged

Components: Complete WPDS token migration for remaining borders#79003
ciampo merged 7 commits into
WordPress:trunkfrom
himanshupathak95:upd/79001-components-wpds-border-colors

Conversation

@himanshupathak95

@himanshupathak95 himanshupathak95 commented Jun 8, 2026

Copy link
Copy Markdown
Contributor

What?

Part of #79001

Updates the remaining instances of hardcoded $gray-300 and $components-color-gray-300 borders and inset box-shadows across the @wordpress/components package to use the WPDS stroke-surface-neutral token.

Why?

This is a follow-up to #78397. While the initial PR updated the Site Editor chrome to inherit the user's admin color scheme, several components (Modal, Panel, Form Toggle, Button, Radio Control) still used hardcoded gray borders.

This change ensures these component borders consistently adapt to the active admin color scheme when rendered inside the Site Editor.

How?

Replaced the hardcoded SCSS color variables with the CSS variable var(--wpds-color-stroke-surface-neutral).

Testing Instructions

  1. Run npm run wp-env start and npm run build.
  2. Navigate to your local wp-admin and change your user profile's Admin Color Scheme to a dark theme (e.g., Modern or Midnight).
  3. Navigate to Appearance > Editor (or Add a New Post).
  4. Verify that the borders of Modals, Panels, Buttons, and Toggle/Radio controls accurately reflect the active color scheme rather than appearing as a hardcoded gray.

Screenshots

Component Before ($gray-300) After (stroke-surface-neutral)
Panel
Modal (scrolled content)
Button (disabled)
Form Toggle (disabled)
Radio Control (disabled)

@github-actions github-actions Bot added the [Package] Components /packages/components label Jun 8, 2026
@t-hamano

t-hamano commented Jun 8, 2026

Copy link
Copy Markdown
Contributor

@Infinite-Null @himanshupathak95, Since you are working on the same issue, it would be better to consolidate it into one.

@t-hamano t-hamano added the [Type] Code Quality Issues or PRs that relate to code quality label Jun 8, 2026
@himanshupathak95

himanshupathak95 commented Jun 8, 2026

Copy link
Copy Markdown
Contributor Author

@Infinite-Null @himanshupathak95, Since you are working on the same issue, it would be better to consolidate it into one.

Thanks @t-hamano for looking into this.

@Infinite-Null mentioned their PR is focusing on edit-site while my PR is more focused on the components part, I am going to mention this on the issue as well.

@github-actions

github-actions Bot commented Jun 8, 2026

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: himanshupathak95 <abcd95@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@ciampo

ciampo commented Jun 8, 2026

Copy link
Copy Markdown
Contributor

Thanks for tackling this!

There are more opportunities for refactor that we could tackle in this PR: the search here looks SCSS-only ($gray-300 / $components-color-gray-300), so it misses the gray-300 borders authored in Emotion/JS style files, plus a couple of separators drawn with background-color. These resolve to the same logical token, so for consistency they should move to a WPDS stroke token in the same pass.

Remaining gray-300 borders/strokes + suggested tokens (with help from AI agent to list them):

Decorative boundaries / dividers → --wpds-color-stroke-surface-neutral (value-preserving, matches the panel header migrated here):

  • packages/components/src/tools-panel/styles.ts:37border-top between panel sections
  • packages/components/src/menu/styles.ts:25DEFAULT_BORDER_COLOR (menu popover border). Bonus: the adjacent DIVIDER_COLOR at :26 is gray-200stroke-surface-neutral-weak
  • packages/components/src/toolbar/toolbar-group/style.scss:78 — vertical divider (drawn as a 1px background-color line)
  • packages/components/src/dropdown-menu/style.scss:33 — horizontal separator (same background-color technique)
  • packages/components/src/spinner/styles.ts:40 — an SVG track stroke rather than a true surface boundary, but stroke-surface-neutral works value-wise; worth a quick designer sanity-check

Interactive control borders → --wpds-color-stroke-interactive-*:

  • packages/components/src/toggle-group-control/toggle-group-control/styles.ts:64 — enclosing border → stroke-interactive-neutral, with the :71 hover → stroke-interactive-neutral-active
  • packages/components/src/border-control/styles.ts:87 — fallback border for the color-indicator swatch inside the BorderControl dropdown trigger → stroke-interactive-neutral

Note: stroke-interactive-neutral is #8d8d8d, noticeably darker than the current #ddd, so these are a deliberate visual change rather than a value-preserving swap — worth a design call (cc @jameskoster @fcoveram ).

Re. the disabled-control borders already migrated here (button/toggle/radio), we should usestroke-interactive-neutral-disabled instead.

@jameskoster

Copy link
Copy Markdown
Contributor

I'd be tempted to handle ToggleGroupControl separately as it went through a recent design review.

@himanshupathak95

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed feedback @ciampo! I completely agree with the approach.

I've gone ahead and applied these updates locally:

Swapped the disabled interactive controls (button, form-toggle, radio-control) to use stroke-interactive-neutral-disabled.
Swapped the remaining Emotion/JS files and background-color dividers (tools-panel, menu, dropdown-menu, spinner, and border-control) to their appropriate WPDS stroke tokens as you outlined.
Left ToggleGroupControl untouched.

However, I hit a blocker with the pre-commit hooks when trying to push the Emotion .ts changes. Our ESLint strict configuration is rejecting the direct use of the WPDS tokens inside the styled-components template strings:

/packages/components/src/border-control/styles.ts
  88:6  error  Design System tokens (--wpds-*) should not be used in this context  @wordpress/no-ds-tokens
/packages/components/src/menu/styles.ts
  25:30  error  Design System tokens (--wpds-*) should not be used in this context  @wordpress/no-ds-tokens
✖ 5 problems (5 errors, 0 warnings)

How would you prefer to handle this within @wordpress/components? Should I just add an eslint-disable-next-line @wordpress/no-ds-tokens above these specific usages?

@ciampo

ciampo commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

However, I hit a blocker with the pre-commit hooks when trying to push the Emotion .ts changes. Our ESLint strict configuration is rejecting the direct use of the WPDS tokens inside the styled-components template strings:

@himanshupathak95 you're right, my bad. I forgot that, since we can't reliably add fallback values for the --wpds-* tokens in Emotion styles, we're currently forbidding usage.

For now, we can simply add comments about each instance, something like // TODO: should use a WPDS token when refactored to SCSS modules.

@himanshupathak95 himanshupathak95 force-pushed the upd/79001-components-wpds-border-colors branch from 19d5252 to 56e57e3 Compare June 12, 2026 06:49
@ciampo

ciampo commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

For now, we can simply add comments about each instance, something like // TODO: should use a WPDS token when refactored to SCSS modules.

@himanshupathak95 just in case it was not clear, I'm proposing we add such TODO comments in the Emotion .ts files where we should migrate to the WPDS tokens, but we currently can't.

We should also add a CHANGELOG entry under Unreleased > Enhancements, following the format of other entries in the file.

Comment thread packages/components/src/spinner/styles.ts Outdated
Comment thread packages/components/src/tools-panel/styles.ts Outdated
Comment thread packages/components/CHANGELOG.md Outdated
@ciampo ciampo enabled auto-merge (squash) June 16, 2026 10:00
@ciampo ciampo merged commit dbe78ce into WordPress:trunk Jun 16, 2026
42 of 43 checks passed
@github-actions github-actions Bot added this to the Gutenberg 23.5 milestone Jun 16, 2026
@manzoorwanijk

manzoorwanijk commented Jun 16, 2026

Copy link
Copy Markdown
Member

This PR might have started the Storybook failure in trunk.

It started after this PR was merged - https://github.com/WordPress/gutenberg/actions/workflows/storybook-check.yml?query=branch%3Atrunk

@ciampo

ciampo commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

@manzoorwanijk reverting here #79243

@ciampo

ciampo commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Looks like the error comes from the inline JS comments containing --wpds tokens. I'll create a more focused PR, instead of the revert.

Separately, I'll look into improving the linter to check for code comments, too.

@aduth

aduth commented Jun 16, 2026

Copy link
Copy Markdown
Member

Since it's affecting all new pull requests I'd personally opt to revert first and then unrevert with the focused fix.

ciampo added a commit that referenced this pull request Jun 16, 2026
…ents

The esbuild design-token fallback plugin claims any JS/TS file whose source
text contains the `wpds` token prefix (a plain substring check, comments
included). Claiming the file replaces the Emotion transform, so styled
component selectors throw at runtime ("Component selectors can only be used
in conjunction with @emotion/babel-plugin"). #79003 introduced TODO comments
referencing the full token custom-property names in Emotion `.ts` files,
which broke the Storybook build on trunk.

Rephrase those comments (and pre-existing ones in dropdown-motion,
config-values, and use-modal-exit-animation) to name the WPDS tokens without
the CSS custom-property prefix, so the fallback plugin no longer claims these
files. The `no-ds-tokens` ESLint rule does not catch this because it only
inspects string literals and template elements, not comments.
ciampo added a commit that referenced this pull request Jun 16, 2026
…rs (#79003)" (#79243)

This reverts commit dbe78ce.

---

Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
ciampo added a commit that referenced this pull request Jun 16, 2026
…ents

The esbuild design-token fallback plugin claims any JS/TS file whose source
text contains the `wpds` token prefix (a plain substring check, comments
included). Claiming the file replaces the Emotion transform, so styled
component selectors throw at runtime ("Component selectors can only be used
in conjunction with @emotion/babel-plugin"). #79003 introduced TODO comments
referencing the full token custom-property names in Emotion `.ts` files,
which broke the Storybook build on trunk.

Rephrase those comments (and pre-existing ones in dropdown-motion,
config-values, and use-modal-exit-animation) to name the WPDS tokens without
the CSS custom-property prefix, so the fallback plugin no longer claims these
files. The `no-ds-tokens` ESLint rule does not catch this because it only
inspects string literals and template elements, not comments.
ciampo added a commit that referenced this pull request Jun 16, 2026
…ments (#79244)

* Components: Re-land WPDS border token migration (#79003)

* Components: Avoid full DS token property names in Emotion source comments

The esbuild design-token fallback plugin claims any JS/TS file whose source
text contains the `wpds` token prefix (a plain substring check, comments
included). Claiming the file replaces the Emotion transform, so styled
component selectors throw at runtime ("Component selectors can only be used
in conjunction with @emotion/babel-plugin"). #79003 introduced TODO comments
referencing the full token custom-property names in Emotion `.ts` files,
which broke the Storybook build on trunk.

Rephrase those comments (and pre-existing ones in dropdown-motion,
config-values, and use-modal-exit-animation) to name the WPDS tokens without
the CSS custom-property prefix, so the fallback plugin no longer claims these
files. The `no-ds-tokens` ESLint rule does not catch this because it only
inspects string literals and template elements, not comments.

* Components: Update CHANGELOG PR reference to the re-land PR

---

Co-authored-by: himanshupathak95 <abcd95@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] Components /packages/components [Type] Code Quality Issues or PRs that relate to code quality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants