Semantic content tokens: icon/text interactive ladders disagree, and text.accent is off-scale

[eddiman]

Three inconsistencies in the semantic text.* / icon.* groups, found while applying the new tokens to Chip in Figma. They are the same class of defect — the step assignment for content tokens is not uniform across tones — so they are worth deciding together.

Values below were read from the live Tokens Studio project (semantic set) on 2026-08-12, after the #5283 additions and the #5284 release.

Tone	text.{tone}	text.interactive d/h/p	icon.{tone}	icon.interactive d/h/p
accent	12	10 / 11 / 12	10	11 / 12 / 13
info	10	10 / 11 / 12	10	11 / 12 / 13
success	10	10 / 11 / 12	10	11 / 12 / 13
danger	10	10 / 11 / 12	10	10 / 11 / 12
warning	10	10 / 11 / 12	10	10 / 11 / 12
link	—	info 8 / 9 / 10	—	info 8 / 9 / 10

1. icon.interactive and text.interactive disagree for accent, info and success

Three families (danger, warning, link) put icons on the same steps as their label. Two put icons one step further down the ladder. Accent was already like this; info and success inherited it when they were added in #5283.

Consequence in a real component: in a success Chip the icon renders one step darker than the label at every state (light mode icon.interactive.success.default #205c1f vs text.interactive.success.default #206d1f), while in a danger Chip the two are byte-identical. Same component, same anatomy, different relationship depending on tone.

This was flagged in review on #5284 as "cheap to align now, breaking later". That PR merged on 11 Aug, so the two new families are now public API and aligning them is a visual change rather than a pre-release fix. Worth doing anyway while adoption is a day old.

Decision needed: is 11/12/13 or 10/11/12 canonical for interactive icons? Then align the other families to it.

If the intent behind 11/12/13 is that thin icon strokes need more weight than text, that rationale applies to danger and warning too and they should move up. If there is no such intent, accent/info/success should come down to match text.

2. text.accent sits at step 12 while every other static tone text is at 10

text.accent = {accent.12}. text.danger, text.info, text.success, text.warning are all {tone.10}. All five static icon.{tone} are {tone.10}, so accent is also the only tone where static text and static icon differ from each other.

It also collides exactly with text.interactive.accent.pressed, which is likewise {accent.12} — a static accent label is indistinguishable from a permanently-pressed interactive one.

A plausible rationale is the APCA split in our decisions (LC90 for body text, LC60 for interactive): accent at step 10 may not clear LC90 as body text and was bumped, while interactive text only targets LC60 so 10 is fine there. That is inference, not recorded anywhere.

Decision needed: measure accent.10 against background.surface in both modes. If it clears LC90, bring text.accent down to 10 for consistency with the other four tones. If it does not, keep 12 and document the exception — and check whether the other tones' step 10 actually clears LC90, since if they do not the problem is the reverse.

3. Confirm that state-static neutral interactive text is deliberate

On #5283 the scoping comment excluded text/icon.interactive.neutral as duplicating the primary tokens, and @pomfrida asked whether that means neutral interactive text is intentionally state-static at neutral 12 while accent shifts 10→11→12. That question was not answered before the issue moved on to verification.

The duplication argument only holds if the answer is yes — a neutral ladder that shifted would not duplicate text.primary. Please confirm either way so #5245 can record it as a design choice rather than a gap.

Why now

The Chip migration recipe (#5245) is being written against these tokens. Whatever is decided here should land before that recipe codifies the current inconsistencies as per-tone rules that component authors have to memorise.

Related: #5283, #5284, #5245, #5225.

[claude]

A couple of other open token issues look like they belong to the same class of defect (non-uniform step assignment across tones), so they may be worth deciding alongside this one — beyond #5283 / #5284 / #5245 / #5225 already linked above:

• Semantic border tone ladder was incomplete — add medium/strong for danger, info, success, warning #5328 — Semantic border tone ladder was incomplete — add medium/strong for danger, info, success, warning (open): same shape of problem in the border.* group — accent/neutral had a full ladder while the four status tones did not, plus two named strengths resolving to the same colour. The "align the tones, then document the exception" decision here probably wants to be the same decision there.
• Dark palette scales are non-monotonic: step 6 duplicates step 3 #5282 — Dark palette scales are non-monotonic: step 6 duplicates step 3 (open): affects the primitive steps these semantic tokens point at. Relevant to decision 2 in particular — measuring accent.10 vs background.surface in dark mode rests on the dark ladder being monotonic, and it currently isn't.

This comment was generated by an LLM and may be inaccurate. Please verify that the linked issues are actually relevant.

[eddiman]

Contrast measurements

I measured how readable each colour combination actually is, to work out which step numbers are correct.

How the numbers were produced. Rather than reading the exported CSS, I rebuilt the colours from the formula that generates them — the palette anchors, the lightness scale, and the chroma curve — then converted to sRGB and ran the contrast maths.

As a check that the rebuild is faithful: it produces #206d1f for light green step 10, #20474b for light moss-green 12, and #cfeacc for light green 3. Those match the shipped tokens exactly, so the numbers below describe the real colours, not an approximation.

What the numbers mean. We use APCA for contrast rather than the older WCAG 2 ratio. It gives a score called Lc, roughly 0–106, where higher is more readable. Our targets: Lc 90 for body text, Lc 60 for interactive things like buttons and chips. Below target = fails.

Plain tone text on background.surface — needs Lc 90

Tone	step 10 (light)	step 12 (light)	step 10 (dark)	step 12 (dark)
accent	82.4 ❌	93.6 ✅	83.8 ❌	100.0 ✅
danger	83.8 ❌	94.5 ✅	69.6 ❌	88.3 ⚠️
info	82.6 ❌	93.7 ✅	82.5 ❌	98.5 ✅
success	81.6 ❌	93.2 ✅	84.9 ❌	100.8 ✅
warning	84.0 ❌	94.4 ✅	78.6 ❌	94.3 ✅

This is the opposite of what the issue description assumed. I had flagged text.accent as the odd one out because it sits at step 12 while the other four sit at 10. It turns out step 12 is the only one that passes. Step 10 misses the target for every single tone, by 6–8 points in light mode and 5–20 in dark.

So the fix is to raise text.danger, text.info, text.success and text.warning up to 12, not to bring accent down to 10.

Plain icons are fine as they are. Icons only need Lc 60, and step 10 gives them 81–84. icon.{tone} stays at 10.

This also explains away the "collision" I worried about. If every plain tone text sits at 12, then matching text.interactive.{tone}.pressed is just a consistent rule — plain text is as strong as a button at its most-pressed moment — rather than an accent-only oddity.

One exception: danger at step 12 in dark mode only reaches 88.3, a bit short of 90. Red is the most saturated of our six colours and runs out of room in dark mode. We either accept that as a documented near-miss or give danger its own step 13.

Interactive text and icons on their own muted background — needs Lc 60

A chip's label sits on a pale tinted background (steps 3, 4 and 5 for default, hover and pressed). Here is how the two competing ladders score on it.

Light mode:

Tone	text 10/11/12	icon 11/12/13
accent	65.4 / 64.0 / 60.5 ✅	71.2 / 69.3 / 65.3 ✅
danger	62.6 / 60.4 / 55.8 ❌	68.3 / 65.5 / 60.2 ✅
info	65.4 / 63.9 / 60.3 ✅	71.2 / 69.2 / 65.1 ✅
success	65.1 / 64.0 / 60.9 ✅	71.1 / 69.5 / 65.8 ✅
warning	65.9 / 63.7 / 59.5 ❌	71.3 / 68.7 / 63.9 ✅

Dark mode:

Tone	text 10/11/12	icon 11/12/13
accent	63.9 / 67.8 / 66.0 ✅	73.8 / 74.1 / 70.6 ✅
danger	51.3 / 57.3 / 57.3 ❌	62.7 / 64.5 / 64.6 ✅
info	62.7 / 66.6 / 64.9 ✅	72.6 / 72.8 / 70.3 ✅
success	64.5 / 68.1 / 65.8 ✅	74.3 / 74.2 / 68.3 ✅
warning	59.7 ⚠️ / 63.8 / 62.5	69.4 / 69.9 / 68.7 ✅

This reverses the other half of the issue too. The text ladder (10/11/12) fails in six places — all three danger states in dark, danger and warning when pressed in light, and warning's resting state in dark. The icon ladder (11/12/13) passes everywhere, with its worst case at 60.2.

So 11/12/13 is the ladder to keep, and text should move up to join the icons rather than icons moving down to join the text. Moving icons down, which is what I suggested before running the numbers, would have created six new failures.

Worth noticing: contrast gets worse as you interact with these controls, because the background darkens faster than the text does. Pressed is the weakest state in light mode for every tone, which is exactly where most failures land.

Two things to settle alongside this:

• Lc 60 is a floor, not a comfortable target for a text label. Even at 11/12/13 the best a chip label manages is 71.3. If we want chip labels at Lc 75, no ladder gets there and the pale backgrounds themselves need to be lighter.
• The description above says the muted backgrounds run 2/3/4. They actually run 3/4/5 — I copied that error from my own verification comment on Semantic interactive tokens are missing success and info tones #5283. All the numbers here use the real values.

Solid-filled chips — a sanity check

White text and icons (text.on-emphasis) on the solid fills at steps 9, 10 and 11:

Tone	light d/h/p	dark d/h/p
accent	81.5 / 87.5 / 92.9 ✅	73.5 / 84.0 / 93.2 ✅
danger	83.0 / 88.8 / 94.0 ✅	59.4 ⚠️ / 70.8 / 81.5
info	81.6 / 87.6 / 93.1 ✅	72.5 / 82.8 / 91.9 ✅
success	80.5 / 86.7 / 92.4 ✅	74.7 / 85.0 / 94.0 ✅
warning	83.4 / 89.0 / 94.0 ✅	69.4 / 79.2 / 88.1 ✅
neutral	82.8 / 88.6 / 93.7 ✅	72.2 / 83.0 / 92.4 ✅

Keeping white fixed across all three states is right. Contrast improves as you press here, the opposite of the pale version. One weak spot: dark danger at rest, 59.4, a whisker under 60. Same red-in-dark problem as before.

The neutral question, answered with numbers

Should grey chips keep one fixed text colour, or shift through a ladder like the coloured ones?

	bg 3	bg 4	bg 5
fixed neutral.12 (light)	76.6	69.2	60.2
shifting 10/11/12 (light)	66.0	64.1	60.2
fixed neutral.12 (dark)	79.9	74.1	66.3
shifting 10/11/12 (dark)	63.3	67.7	66.3

Fixed isn't just acceptable, it's better — more readable at rest and on hover in both modes, identical when pressed. So leaving neutral alone was the right call, and this is the reason to write into #5245.

What to change

1. text.{danger,info,success,warning} → step 12, matching accent. 4 tokens.
2. text.interactive.{accent,danger,info,success,warning}.{default,hover,pressed} → 11/12/13, matching the icons. 15 tokens.
3. icon.interactive.{danger,warning}.{default,hover,pressed} → 11/12/13. 6 tokens.
4. Leave alone: plain icons at 10, white-on-solid, neutral, and links.
5. Decide separately on the two red-in-dark near-misses above.

That's 25 existing values repointed. No new tokens, nothing renamed. Everything that currently fails passes afterwards, apart from the two red cases in point 5.

[eddiman]

Where this problem came from — it is not new

Worth writing down, because as the description stands it reads as though the recently added tokens caused this. They didn't.

The #5283 round added exactly 36 tokens. Checked against the live project, these are the step numbers it used:

Group	Count	Steps
background.interactive.{success,info}.emphasis.{d,h,p}	6	9 / 10 / 11
background.interactive.{success,info}.muted.{d,h,p}	6	3 / 4 / 5
border.interactive.{success,info}.emphasis.{d,h,p}	6	9 / 10 / 11
border.interactive.{success,info}.muted.{d,h,p}	6	4 / 5 / 7
text.interactive.{success,info}.{d,h,p}	6	10 / 11 / 12
icon.interactive.{success,info}.{d,h,p}	6	11 / 12 / 13

Every one of those copies a pattern that already existed for another colour. Nothing new was invented.

For backgrounds and borders there was only one existing pattern to copy, so the new colours came out consistent with the old ones. For text and icons there were two existing patterns, and they disagreed with each other:

• Text copied what four of the five colours were already doing: 10/11/12. That is the ladder the measurements show failing in six places.
• Icons copied what accent was doing: 11/12/13, rather than what danger and warning were doing. That is the ladder that passes everywhere.

So the new tokens landed on the right ladder for icons and the wrong one for text — in both cases by faithfully following what was already there. The actual problem is the older split between accent and everything else, which #5283 widened from two colours to three but did not create.

Two things this means for how the issue should be read:

1. Scope. This is not "fix the new tokens." 21 of the 25 values being changed are on tokens that shipped well before Semantic interactive tokens are missing success and info tones #5283. Treating it as a tidy-up of the recent addition would leave most of the failures in place.
2. Process. The only thing that could have been done differently at the time was to point out that the existing patterns contradicted each other, instead of quietly picking one. That is what review on feat: update tokens from Tokens Studio release #5284 later caught. Worth a line in docs: document legacy→beta token migration recipe for /next components #5245: when a new colour has to copy an existing pattern and the existing patterns disagree, flag it rather than choose.

[eddiman]

Why the icons ended up at 11/12/13 — it was left over from an old rename

I dug through the history. The accent icon ladder was never a decision about icons. It came out of repairing a broken set of older tokens.

Before #5280, accent was the only colour that had icon state colours at all:

--eds-icon-accent:         accent-13
--eds-icon-accent-hover:   accent-14
--eds-icon-accent-pressed: accent-15

Danger and warning had no icon state colours. And --eds-text-accent pointed at info-8 — a blue, not the accent teal — a leftover from when "accent" meant "link colour."

That old trio was not a working progression. Our scale runs from light to dark across steps 1–13, then wraps back to the light end for the surface steps. In light mode:

Step	Lightness
13	0.32 (dark teal)
14	0.90 (near white)
15	1.00 (white)

So icon-accent-hover was near-white and icon-accent-pressed was white. On a pale background that progression is dark → invisible → invisible. Dark mode wraps the same way (13 = 0.99, 14 = 0.33, 15 = 0.10).

#5280 (6ebf5b65f, 5 Aug) created the whole *.interactive.* family in one commit. Inside that single commit:

Token group	Ended up at	Why
icon.interactive.accent	11 / 12 / 13	the old trio dragged back into the usable range, giving three consecutive darkening steps (0.42 → 0.37 → 0.32)
text.interactive.accent	10 / 11 / 12	rebuilt from scratch — the old one pointed at the wrong colour and couldn't be reused
text/icon.interactive.{danger,warning}	10 / 11 / 12	brand new, nothing to carry over

So accent's icons and accent's text ended up different from each other purely because one had a broken old token set to salvage and the other had nothing to reuse. Same commit, same person, no intent behind the difference.

For the record, the scale itself did not change in #5280 — accent-13/14/15 resolve to identical values either side of that commit. An earlier version of this comment said the steps had shifted meaning underneath the old tokens; that was wrong. The problem with the old trio was that it spanned the wrap point in the scale, not that the scale moved.

The "icons need to be darker" explanation doesn't hold either. I suggested earlier in this issue that thin icon strokes might need more weight than text. If that had been the thinking, danger and warning would have got the same treatment in the same commit. They didn't. That explanation is ruled out.

I also read through the #5280 review discussion. It goes into the renames and contrast in some detail but never says why accent icons sit one step below accent text. There is no recorded reason because there wasn't one.

For completeness: contrast was reviewed at the time and judged fine on the basis that these colours aren't used on background-canvas. That is still true. The failures found in this issue are on the pale tinted fills at steps 3/4/5, which that check didn't cover. The two findings don't contradict each other.

What this means for the fix

"Which ladder is correct?" was never a choice between two considered options. One colour got salvaged out of a broken state and landed at 11/12/13; the others were written fresh at 10/11/12. That removes the main reason to hesitate about changing either, and it means the answer has to come from measurement — which is what the contrast numbers above give: 11/12/13 passes everywhere, 10/11/12 fails in six places.

Note also that once this is fixed there is no icon-versus-text difference left at all. Text moves up to 11/12/13 too, so every interactive label and icon, in all five colours, uses one ladder. The accent value isn't being kept because it turned out to be clever — it just happens to sit where the readable values are.

So the line for #5245 is: interactive text and icons sit at 11/12/13 because that is what stays readable on the pale backgrounds at 3/4/5 — not because icons differ from text, and not because of anything inherited.

[eddiman]

Which step goes where, and the one real open question

I have been wodnering why the step numbers look inconsistent — why plain icons sit at 10, plain text at 12, and interactive content at 11. They are not arbitrary, but the reason has never been written down. Here it is, plus one genuine problem it exposes.

The step depends on the background and the target, not on whether it's text or an icon

Every content colour has to clear a readability score. We use two targets: Lc 90 for body text and Lc 60 for interactive things. Each token sits at the first step that clears its target on the background it appears on. That's the whole rule.

Token	Target	Sits on	Step	Score
icon.{tone}	60	white surface	10	81–84 ✅
text.{tone}	90	white surface	12	93–95 ✅
text/icon.interactive.* default	60	tinted fill (step 3)	11	68–71 ✅

So text.{tone} is at 12 because body text needs 90 and step 10 only reaches 82. Interactive content is at 11 because it only needs 60, and 11 is what clears it on the tinted fill. Two different bars, each just satisfied — which is why they don't line up.

Interactive tokens are not only for tinted backgrounds

Worth saying, since it's easy to assume from the chip work. A ghost or quiet button puts interactive text straight onto the plain surface with no fill. The ladder has to work on both, so it's sized for the harder one:

Tone	on white, step 11	on tinted fill, step 11
accent	88.3	71.2
danger	89.5	68.3
info	88.4	71.2
success	87.7	71.1
warning	89.5	71.3

Cover the tint and the plain surface comes free. Note that on plain surface, interactive text at step 11 scores 88.3 — almost the same as plain text at step 12 (93.6). The one-step gap only really matters on the tint.

The general rule for #5245: size each ladder for the darkest background the token can legitimately appear on.

Links break that rule, and it matters

text.interactive.link.* sits at info 8/9/10 — deliberately lighter, for brand reasons. That works on plain surface but not on anything tinted:

Background	default / hover / pressed (light)	dark
plain surface	62.9 / 76.3 / 82.6	−61.1 / −71.4 / −82.5
tinted info.3	45.7 ❌ / 59.1 ❌ / 65.4	−41.4 ❌ / −51.7 ❌ / −62.7

So a link inside an info banner or any tinted callout is failing today — 45.7 in light, −41.4 in dark, against a floor of 60. link is a surface-only token and should be scoped as such. Its resting state is also tight even on plain surface: 62.9 light, 61.1 dark.

Status banner icons are failing in dark mode

Banners use background.{tone}, which is step 3 — the same tinted surface a chip uses. But their content stayed on the plain static tokens, so raising interactive content didn't help them:

Tone	icon.{tone} = 10, light	dark
danger	62.6 ✅	−51.3 ❌
info	65.4 ✅	−62.7 ✅
success	65.1 ✅	−64.5 ✅
warning	65.9 ✅	−59.7 ⚠️

A danger banner's icon in dark mode fails outright, and warning is a whisker under. The text.{tone} → 12 change already fixes banner text (62–66 → 73–80), so only icons are left behind.

Fix: icon.{tone} 10 → 11 for all five tones, 5 more tokens. It costs nothing on white (81 → 87) and clears the banner case. It also removes the confusion above, since plain icons and interactive-default icons would both be 11.

The one thing that would actually change our answer

Everything above just aligns tokens to targets we already agreed. This doesn't.

A chip label is text, but we hold it to the interactive bar of 60 rather than the text bar of 90 — purely because it lives inside something clickable. That's what our decisions say, and it's the assumption carrying all the weight here. At Lc 60–71 a chip label is legible but nowhere near as readable as ordinary text on a page.

And it can't be tightened by moving steps. On a step-3 tinted background, even step 13 only reaches about 78–82. Lc 90 for text on the current tinted fills is unreachable at any step. If we want chip and banner labels to read as well as body text, the tinted backgrounds have to get lighter — content steps can't get us there.

That is worth deciding deliberately rather than inheriting. Everything else in this issue is bookkeeping by comparison.

[eddiman]

Btw, this issue is more as a info dump, to understand why we changed the step to 11/12/13.