Theme: Update Figma plugin to convert additional properties #73407

aduth · 2025-11-18T21:55:03Z

What?

Updates the Theme package internal Figma plugin to handle additional spacing properties added in UI: Implement Box component as part of new UI package #72984, following similar conventions to color property conversions
Expands on documentation to elaborate on what these "conventions" are with regard to expected naming schemes for general design tokens

This is meant to pair with accompanying changes in Automattic/figma-ds-token-manager#6 . This custom Figma plugin is intended to provide designers a way to easily consume design tokens in Figma documents. Word is that Figma will be supporting this natively in the near future, so a custom plugin may not be needed for very long.

Why?

Consistency with color tokens
Better documentation to ensure clear communication of design token decisions

Testing Instructions

Verify accuracy of changes to README.md and figma.json outputs.

Ensure no local changes to commit after running npm run --workspace @wordpress/theme build.

jameskoster

LGTM

Primitives are no longer included in the output, as their values are instead inlined

github-actions · 2025-11-21T15:53:05Z

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 <aduth@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>

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

We no longer export primitive tokens, so no point in creating this grouping

aduth · 2025-11-21T16:46:34Z

@jameskoster I pushed a few more improvements:

Removed "Semantic/" folder in the output
Removed tone values from variable names (already implied by folder)
Removed abbreviations for target elements
Updated source color tokens to express via nesting, e.g. { "bg-surface": {}, "bg-interactive": {} } ➡️ { "bg": { "surface": {}, "interactive": {} } }

Example before / after:

Before: Color/Semantic/Foreground/Success/fgCon-success
After: Color/Foreground/Success/fgContent

jameskoster · 2025-12-01T14:49:10Z

Updated source color tokens to express via nesting, e.g. { "bg-surface": {}, "bg-interactive": {} } ➡️ { "bg": { "surface": {}, "interactive": {} } }

Nice!

jsnajdr · 2025-12-03T13:41:06Z

packages/theme/bin/terrazzo-plugin-figma-ds-token-manager/index.ts

+	'warning',
+	'caution',
+	'error',
+] );


In other places we call these "tones" as "color ramps". Could we use the same name here?

In other places we call these "tones" as "color ramps". Could we use the same name here?

Hm, I think there might be value in differentiating. With how we're using these in color theming, I'd say that we use the seed value for a given tone to produce a color ramp, but not that tone and color ramp are the same (tone being a singular term describing a mood or meaning, and color ramps being the set of color values within that domain). Additionally, we produce color ramps from seeds which aren't associated with tones, like "bg" and "primary".

jsnajdr · 2025-12-03T13:43:00Z

packages/theme/src/prebuilt/json/figma.json

 		"description": "Background color for interactive elements with neutral tone and strong emphasis."
 	},
-	"Color/Semantic/Background/Neutral/bgInt-neutral-strong-active": {
+	"Color/Background/Neutral/bgInteractive-strong-active": {


The token names are now a combination of camel case bgInteractive and kebab case -strong-active. Could we unify that on the better-looking bg-interactive-strong-active? That's also the convention that the associated CSS variables use.

Yeah, I think this could be a good opportunity to revisit these variable renamings. I'm not positive what the original motivation was (perhaps Figma truncation?), but it creates some complexities to try to manage them. It'd be a lot easier to just keep them uniform.

Originally we shortened things like "bgInteractive" to "bgInt" because the variable selection UI is quite narrow, but this doesn't look too bad:

I think there's more value in uniformity.

Speaking of which, I noticed that how we've structured the tokens in Figma means the code snippets in "Dev mode" are pretty wonky:

Maybe we should try restructuring to ensure alignment?

Hm, that's an interesting point on the Dev Mode snippets. I'm not sure we can get those totally correct without completely upending how we've structured the colors into folders.

You mean in Figma? Is there any reason not to do that, if we want to? I think proper alignment would be quite helpful. Probably fine to tackle separately though.

If we wanted parity I think it'd be more like:

wpds-color / bg / surface / ├ brand ├ ...

Which seems like it might be okay:

Yeah we could create a folder for those targets like surface / interactive 👍

I updated to simplify / align how the exported tokens retain details of the original tokens in e748ace. This feels a lot simpler, still creating folders for "type" ("color", "dimension"), "property" ("bg", "fg", "padding", etc.), and "target" ("surface", "interactive", etc.).

This required a few corresponding changes in Automattic/figma-ds-token-manager#6 which are now pushed there (af26c93).

Net result is that Dev Mode snippets are correct:

The variables panel and corresponding display in Figma fields aren't quite as ergonomic, but I think it's acceptable. This is aligned with what you shared above @jameskoster .

I think the color picking experience in Figma is fine, I really appreciate the alignment.

The only question I have now is whether it's worth using Collections. The duplicated collection name + group seems a bit strange, and the fact that each collection will only ever include a single root-level group may also be an indicator that collections aren't necessary...

With that said, a single collection would limit what we can do with modes which might come back to bite us later. Maybe it's fine to go with separate collections if we change the collection name to differentiate from the group (e.g. WPDS Color rather than wpds-color). WDYT?

Yeah, the main thing to keep in mind with collections is ensuring we have room to support distinct modes. Aligning this to the token file groupings is an imperfect but reasonably good fit to be safe. I think this also works well for future compatibility as far as how Figma "Import" mechanic works (i.e. import a single DTCG JSON file to a single collection).

I think capitalizing the collection could be fine enough to implement if it'd help differentiate the collection and top-level group. I might explore if this is something we could add using extensions so we don't have to maintain a manual mapping or rely on some programmatic capitalization (can be error-prone, as mentioned elsewhere)

aduth · 2025-12-09T22:12:47Z

After having spent more time with Figma's recently launched DTCG import functionality, I feel like we can move away entirely from maintaining this Figma-specific plugin and use DTCG tokens directly, with some revisions on our end to fix up and restructure the tokens:

aduth · 2025-12-10T19:35:28Z

Closing in favor of #73860

aduth requested a review from jameskoster November 18, 2025 21:55

aduth mentioned this pull request Nov 18, 2025

Add support for updated tokens conventions (dimension) Automattic/figma-ds-token-manager#6

Closed

aduth added [Type] Task Issues or PRs that have been broken down into an individual action to take [Package] Theme /packages/theme labels Nov 18, 2025

jameskoster approved these changes Nov 19, 2025

View reviewed changes

aduth force-pushed the add/theme-density branch from b7c4da6 to 79291f9 Compare November 19, 2025 14:46

Base automatically changed from add/theme-density to trunk November 20, 2025 18:51

aduth added 3 commits November 21, 2025 10:52

Remove redundant primitives renaming

670812a

Primitives are no longer included in the output, as their values are instead inlined

Theme: Expand README to explain general token naming scheme

3545a95

Theme: Update Figma plugin to convert additional properties

9dc5ed8

aduth force-pushed the update/theme-figma-plugin-density branch from 1a77e22 to 9dc5ed8 Compare November 21, 2025 15:52

aduth marked this pull request as ready for review November 21, 2025 15:52

aduth requested a review from a team as a code owner November 21, 2025 15:52

aduth marked this pull request as draft November 21, 2025 16:06

aduth added 4 commits November 21, 2025 11:07

Remove "Semantic" folder in Figma output

93f30ba

We no longer export primitive tokens, so no point in creating this grouping

Avoid abbreviating Figma output variable names

062fd54

Remove tone from color variable output

de26204

Simplify property name calculation using property

9a5ccab

aduth marked this pull request as ready for review November 21, 2025 16:46

aduth requested a review from jameskoster November 21, 2025 16:47

jsnajdr reviewed Dec 3, 2025

View reviewed changes

Update Figma export to retain original structure

e748ace

aduth mentioned this pull request Dec 9, 2025

Theme: Restructure theme tokens to embed prefix, flattened modifiers #73859

Merged

aduth closed this Dec 10, 2025

aduth deleted the update/theme-figma-plugin-density branch December 10, 2025 19:35

Theme: Update Figma plugin to convert additional properties #73407

Theme: Update Figma plugin to convert additional properties #73407

Uh oh!

Conversation

aduth commented Nov 18, 2025

What?

Why?

Testing Instructions

Uh oh!

jameskoster left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aduth commented Nov 21, 2025

Uh oh!

jameskoster commented Dec 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduth Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduth commented Dec 9, 2025

Uh oh!

aduth commented Dec 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Nov 21, 2025 •

edited

Loading

aduth Dec 5, 2025 •

edited

Loading