Theme: Add design tokens maintainer's guide documentation by aduth · Pull Request #79157 · WordPress/gutenberg

aduth · 2026-06-12T15:17:42Z

What?

Adds a new README.md within the tokens/ directory of the @wordpress/theme package to serve as a maintainer's guide for the WordPress Design System design tokens.

Why?

Adds additional context for how tokens are maintained which has been undocumented until now:
- The difference between primitive and semantic tokens and why they exist the way they do
- Explicit support for Figma variables import, including $extensions['com.figma.scopes'] and where to find information about maintaining those values
Improves the relevance of the package's root README.md to include information about how to use the theme package. Most people shouldn't care about the existence of tokens/color.json and how these files are structured, for example.
Avoids a confusing dead-end if someone were to link to the packages/themes/tokens directory. This would be reasonable to do as it is the source of truth for the design system's design tokens, but currently it lacks any documentation context around what that directory is for if someone arrives there directly.

How?

Adds new packages/theme/tokens/README.md
Shifts "Structure" and "Token Naming" sub-sections of the root README.md into this new file
Maintains existing "Design Tokens" section of the root README.md and adds a link to this new document for more information

Testing Instructions

Review updated documentation for relevance and accuracy.

Use of AI Tools

No AI was used.

github-actions · 2026-06-12T15:18:50Z

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: aduth <[email protected]>
Co-authored-by: shail-mehta <[email protected]>
Co-authored-by: ciampo <[email protected]>

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

github-actions · 2026-06-12T15:50:40Z

Flaky tests detected in af0d860.
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/27717062397
📝 Reported issues:

[Flaky Test] shouldn't conflict with server-side autosave #78706 in /test/e2e/specs/editor/various/autosave.spec.js

ciampo

Looking good overall 🚀

Left some additional feedback, but feel free to merge once addressed

ciampo · 2026-06-16T14:30:58Z

I'm now noticing that this document has a h2 Design Tokens (linking to the separate doc) and also an h3 Design Tokens section . Is this another opportunity for consolidation / removal of duplicated content?

That's a great catch, especially since it's literally in the same hierarchy 😂 🤦 (Theme > Design Tokens > Design Tokens). I consolidated in 62dbe35.

ciampo · 2026-06-16T14:31:58Z

+
+Design tokens are the visual design atoms of a design system. They are named entities that store visual design attributes like colors, spacing, typography, and shadows. They serve as a single source of truth that bridges design and development, ensuring consistency across platforms and making it easy to maintain and evolve the visual language of an application.
+
+Components that use these design tokens benefit from the consistency they guarantee with other components that extend from the same system. Future theming improvements or configurations like color theming (or "dark mode"), density, or roundness will cascade automatically to these components without any additional effort on the part of the component maintainer.


Density is not a tweakable aspect of the theme anymore; we should remove all mentions

Density is not a tweakable aspect of the theme anymore; we should remove all mentions

Yeah I mentioned it in regards to general configurability as something we could do (and AFAIK still have ambitions to do), and even tying it to "Future" as the first word of the sentence, but happy to remove if it risks confusion.

Density is not a tweakable aspect of the theme anymore; we should remove all mentions

Removed density references in 72c2bd7.

ciampo · 2026-06-16T14:33:07Z

+--wpds-dimension-padding-xs: 4px;
+```
+
+Someone using the design system should never see or concern themselves with either the `primitive.space.10` token or the underlying 4 pixel base unit. This also enables the design system to alter these values based on factors like density, which could affect the value of the primitive token and cascade automatically to the CSS properties.


We should remove the mention of density here, too.

Also, the "cascading" part here is slightly redundant after the recent addition of the paragraph at line 5

We should remove the mention of density here, too.

Also, the "cascading" part here is slightly redundant after the recent addition of the paragraph at line 5

I removed this entire sentence as part of 72c2bd7. And then built upon the paragraph in 49e31e7 with a more concrete example of how someone could think about semantics (swapped padding example with element size).

Co-authored-by: Shail Mehta <[email protected]>

Co-authored-by: Marco Ciampini <[email protected]>

Duplicative of the "Primitive and Semantic Tokens" section in the new tokens/README.md

Also aligns better with how we refernce "Design Tokens Reference" in preceding sentence

aduth requested a review from a team as a code owner June 12, 2026 15:17

aduth added [Type] Developer Documentation Documentation for developers Design System Issues related to the system of combining components according to best practices. [Package] Theme /packages/theme labels Jun 12, 2026

github-project-automation Bot added this to Design systems — Backlog Jun 12, 2026

aduth mentioned this pull request Jun 12, 2026

Theme: Add Figma scopes to element size tokens #79032

Merged

shail-mehta reviewed Jun 14, 2026

View reviewed changes

Comment thread packages/theme/tokens/README.md Outdated

ciampo reviewed Jun 15, 2026

View reviewed changes

Comment thread packages/theme/tokens/README.md

Comment thread packages/theme/tokens/README.md

Comment thread packages/theme/tokens/README.md

Comment thread packages/theme/tokens/README.md Outdated

ciampo reviewed Jun 16, 2026

View reviewed changes

ciampo approved these changes Jun 16, 2026

View reviewed changes

aduth and others added 12 commits June 17, 2026 16:16

Theme: Add design tokens maintainer's guide documentation

f06d211

Theme: Simplify language

8857c7f

Fix typo in tokens README heading

2539959

Co-authored-by: Shail Mehta <[email protected]>

Fix JSON syntax for tokens sample

7e25c94

Co-authored-by: Marco Ciampini <[email protected]>

Theme: Emphasize shift from values to semantics

57ec1c9

Co-authored-by: Marco Ciampini <[email protected]>

Remove Architecture section from README

850aef2

Duplicative of the "Primitive and Semantic Tokens" section in the new tokens/README.md

Add paragraph explaining future evolvement/adaptation with tokens

d9c1b8e

theme: Combine Design Tokens sections

477993a

theme: Remove references to density

6bc34ee

theme: Use more concrete example about token semantics

a350a73

theme: Add CHANGELOG for token maintainer's guide

7b47fa8

theme: Use "maintainer's guide" title consistent

af0d860

Also aligns better with how we refernce "Design Tokens Reference" in preceding sentence

aduth force-pushed the add/theme-tokens-maintainers-guide branch from f27353d to af0d860 Compare June 17, 2026 20:17

aduth merged commit 2c2a3f9 into trunk Jun 18, 2026
44 checks passed

aduth deleted the add/theme-tokens-maintainers-guide branch June 18, 2026 12:59

github-project-automation Bot moved this to 💫 Done in Design systems — Backlog Jun 18, 2026

github-actions Bot added this to the Gutenberg 23.5 milestone Jun 18, 2026


		Design tokens are the visual design atoms of a design system. They are named entities that store visual design attributes like colors, spacing, typography, and shadows. They serve as a single source of truth that bridges design and development, ensuring consistency across platforms and making it easy to maintain and evolve the visual language of an application.

		Components that use these design tokens benefit from the consistency they guarantee with other components that extend from the same system. Future theming improvements or configurations like color theming (or "dark mode"), density, or roundness will cascade automatically to these components without any additional effort on the part of the component maintainer.

Uh oh!

Conversation

aduth commented Jun 12, 2026

What?

Why?

How?

Testing Instructions

Use of AI Tools

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ciampo Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

aduth Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

ciampo Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

aduth Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

aduth Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

ciampo Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

aduth Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 12, 2026 •

edited

Loading

github-actions Bot commented Jun 12, 2026 •

edited

Loading