Theme: Move token structure descriptions into tokens document#78438
Merged
Conversation
aduth
added
[Type] Developer Documentation
|
Size Change: 0 B Total Size: 7.97 MB ℹ️ View Unchanged
|
|
Flaky tests detected in 740fa94. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/26115155075
|
ciampo
approved these changes
May 19, 2026
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Member
Author
Yeah, that's a good idea. I was also looking at opportunities to improve the descriptions of the tokens. For example, I think we do a really good job explaining semantic purpose for elevation tokens use-cases and some of that might be worth considering for other tokens like dimension. The color descriptions read pretty well to me personally, but the anecdotal observation that AI would choose to use interactive background colors for non-interactive elements might suggest there's some improvement opportunity there. |
Member
Author
|
I took these changes for a spin using a prompt from an anecdotal demo interface build that had previously used incorrect tokens (using interactive tokens for a chat bubble background in a hypothetical chat UI). It seemed to work a lot better this time using the Prompt:
AI response (Claude Opus 4.7):
The note about "the token system doesn't expose a dedicated |
Contributor
cc @jameskoster — maybe we need to be more explicit with combining bg and fg tokens in the docs? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Moves token documentation about naming structure and purpose from
@wordpress/theme'sREADME.mdinto itsdocs/tokens.md.Related discussions:
Why?
This is primarily aimed at enabling two things:
get_design_tokenstool fetches thistokens.mddocument directly, so additional context here should prove valuable for AI agents to understand how to use design tokens effectively.How?
Because
tokens.mdis generated dynamically from the source tokens using a custom Terrazzo plugin, the text is injected in the plugin code itself rather than modifying the.mdfile directly.Testing Instructions
Review the updated documents for accuracy:
Verify that the tokens built output produces no changes and includes revised content:
(This check is already guaranteed through CI)
Use of AI Tools
Claude Code + Opus 4.7 to research AI limitations in using existing content, plus the mechanical operation of moving content. The content itself largely existed already, though a brief introduction was added. This was originally written by AI, but I reviewed, iterated, and replaced some parts myself.