Theme: Expose legacy color alias defaults in design token CSS

[ciampo]

What?

Follow up to #77462.

Adds default legacy --wp-components-* color aliases to the generated @wordpress/theme design token CSS.

These aliases are compatibility defaults for consumers that still reference the old @wordpress/components color variables directly. ThemeProvider keeps emitting the same provider-scoped legacy aliases as before, using the same shared alias definitions as the static CSS generation.

Why?

The design token stylesheet is the static baseline for WordPress Design System tokens. Without these aliases, bare legacy references such as var(--wp-components-color-accent) only resolve when a runtime provider or another legacy theme layer defines them.

Adding low-specificity defaults to design-tokens.css fills that static compatibility gap without making the aliases new design tokens.

Keeping the runtime provider bridge unchanged avoids adding custom-color tracking or cascade-sensitive runtime behavior just to support the static defaults.

How?

• Defines the legacy alias list once for both runtime and generated CSS use.
• Appends default legacy --wp-components-* aliases during the design token build.
• Derives static fallbacks for --wpds-* alias targets from the generated design token fallback map.
• Keeps explicit fallbacks only for legacy --wp-admin-theme-color* targets.
• Emits the defaults under :where(:root) so they stay low specificity.
• Keeps the existing ThemeProvider runtime legacy aliases in place for scoped theming.
• Documents the legacy alias compatibility behavior in the README delivery model.

Testing Instructions

• npm run --workspace @wordpress/theme build:tokens
• npm run --workspace @wordpress/theme postbuild
• npm run test:unit -- packages/theme/src/test/use-theme-provider-styles.test.tsx
• npm run lint:js -- packages/theme/bin/build-design-tokens/index.ts packages/theme/src/legacy-color-aliases.ts packages/theme/src/test/use-theme-provider-styles.test.tsx
• npx tsgo --build packages/theme/tsconfig.json
• git diff --check

Known existing docs-lint noise: npm run lint:md:docs -- packages/theme/README.md packages/theme/CHANGELOG.md still reports pre-existing MD033 in the README and MD041/MD024 in the changelog.

Testing Instructions for Keyboard

No UI behavior changed.

Screenshots or screencast

Not applicable.

Use of AI Tools

Codex was used to help implement, test, and prepare this PR.

[github-actions]

Size Change: +1.07 kB (+0.01%)

Total Size: 7.67 MB

📦 View Changed

Filename	Size	Change
build/modules/boot/index.min.js	51.5 kB	+182 B (+0.35%)
build/scripts/theme/index.min.js	22.6 kB	+19 B (+0.08%)
build/styles/theme/design-tokens-rtl.css	3.62 kB	+240 B (+7.11%)	🔍
build/styles/theme/design-tokens-rtl.min.css	1.81 kB	+195 B (+12.1%)	⚠️
build/styles/theme/design-tokens.css	3.62 kB	+240 B (+7.11%)	🔍
build/styles/theme/design-tokens.min.css	1.81 kB	+195 B (+12.1%)	⚠️

_{compressed-size-action}

[github-actions]

Flaky tests detected in ad403cc.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/28850935121
📝 Reported issues:

• [Flaky Test] activate block theme when live previewing in edit mode #77712 in /test/e2e/specs/site-editor/activate-theme.spec.js
• [Flaky Test] can use appender in site editor sidebar list view #79632 in /test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js
• [Flaky Test] should update the HTML only for the latest navigation #78835 in /test/e2e/specs/interactivity/router-navigate.spec.ts
• [Flaky Test] three users concurrently edit a large post with diverse blocks (RTC WebSocket) #79926 in /test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts

[github-actions]

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: ciampo <mciampini@git.wordpress.org>

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

[ciampo]

On second thought, I think this PR can be closed.

The fallback values for the --wp-components variables were already added in #78664 directly in the @wordpress/components package. We shouldn't promote legacy components internals into the theme package’s static contract.