Theme: Some color token values that should differ do not

[jameskoster]

A certain category of color tokens share values when they should be different. For example --wpds-color-fg-interactive-brand and --wpds-color-fg-interactive-brand-active map to the exact same value:

gutenberg/packages/theme/src/prebuilt/css/design-tokens.css

Lines 64 to 65 in 32b24bd

	--wpds-color-fg-interactive-brand: #3858e9; /* Foreground color for interactive elements with brand tone and normal emphasis. */
	--wpds-color-fg-interactive-brand-active: #3858e9; /* Foreground color for interactive elements with brand tone and normal emphasis that are hovered, focused, or active. */

So while --wpds-color-fg-interactive-brand-active is used for the hover color applied to Link, there's no visible change when hovering. Storybook.

This issue seems to affect all --wpds-color-fg-interactive-* tokens, and their -active counterparts.

My expectation is that the -active token would map to a slightly darker (or lighter) value, as the bg tokens do:

gutenberg/packages/theme/src/prebuilt/css/design-tokens.css

Lines 15 to 16 in 32b24bd

	--wpds-color-bg-interactive-brand-strong: #3858e9; /* Background color for interactive elements with brand tone and strong emphasis. */
	--wpds-color-bg-interactive-brand-strong-active: #2e49d9; /* Background color for interactive elements with brand tone and strong emphasis that are hovered, focused, or active. */

[hi0001234d]

I'd like to work on this. My plan: add new primitive ramp steps (fgSurface3Active, fgSurface4Active, fgFillActive, fgFillInvertedActive) using the same
1.2:1 contrast-from-base pattern that bgFill2 uses relative to bgFill1. Then update the 6 semantic tokens to reference these new primitives. Does this
direction align with your intent?

[ciampo]

@hi0001234d let's agree on an approach before working on solutions. Also, as a first-time contributor, I suggest you look for issues marked with the Good first issue label.

[ciampo]

@jameskoster it seems like all fg-interactive-* tokens share the same value between the "resting" and "active" states — which I believe is the result of us working on those tokens with the Button component in mind, where the "active" state is mostly communicated via background color and border changes.

Therefore, I think this needs to first get some design feedback. @jameskoster , in your opinion, assuming the default WordPress color theme (light theme, blueberry blue), should "active" fg color variants get darker or lighter compared to the resting state? Let's make sure these changes can work both in components like Button (ie. with a dedicated bg color) and Link (ie. rendered on top or app surfaces).

This decision will have implications on the solution — notably, not all "resting" tokens are mapped to a color that has a darker variant. For example:

• --wpds-color-fg-interactive-brand maps to primitive.primary.fgSurface3 and therefore the active variant could be mapped to the darker primitive.primary.fgSurface4;
• --wpds-color-fg-interactive-neutral maps to primitive.bg.fgSurface4, and there isn't a primitive.primary.fgSurface5 token (yet).

Happy to schedule a pairing session on this (and maybe collate it with other DS tokens work such as this one)

[jameskoster]

Since they effectively serve no purpose currently the simplest solution might be to remove the -active foreground tokens altogether, then find a different hover treatment for Link that doesn't rely on color. That would probably work a bit better for the neutral scale anyway because there isn't much headroom above #1e1e1e for a discernable hover color (assuming we want the hover color to be darker than the resting one). I guess that's a separate issue...

[ciampo]

I suppose that's one option. Do you have ideas for the alternative treatment? Boldening the text? Thickening the underline?

Alternatively, could we go lighter? Would that work well on both Links and Buttons?

[hi0001234d]

Thanks @ciampo and @jameskoster for the context and for taking the time to explain the reasoning. That makes sense — removing the -active fg tokens sounds cleaner than inventing darker variants, especially given the #1e1e1e headroom issue on the neutral scale. I'll focus on Good first issue tickets going forward, and I'll keep an eye out if a follow-up issue is opened for the Link hover treatment.

[jameskoster]

Thickening the underline seems like the most obvious approach. Maybe increasing the offset slightly too?

Screen.Recording.2026-04-10.at.14.52.29.mov

Alternatively, could we go lighter?

Yes it's an option, I don't have a strong feeling either way. A potential argument for thickening the underline is that (I assume) it's a more obvious effect that reinforces the interaction, and means we can remove some tokens. But if there are backwards compatibility concerns I think it would be fine to go lighter.

[ciampo]

if there are backwards compatibility concerns

In terms of visually breaking changes, or something else?