[TEST] Update base and display color scales

[danielguillan]

Summary

Brand Color Scale Alignment POC

This branch updates Primer Primitives' base and display color scales to align with the Brand Refactor color palette (Figma / Primer Brand). It's a proof of concept to assess feasibility, preview changes in dotcom, surface potential breaking changes early, and gather information for a full implementation.

What changed

1. Base neutral scales

The light and dark neutral scales were updated to match Brand Refactor's greenish-gray palette.

• neutrals shifted from a blue-gray hue to a green-gray hue.
• black changed from #1f2328 (dark blue-gray) to #000000 (true black).
• Step 13 (lightest in dark mode) changed from pure white (#fff) to #f2f5f3, which had downstream consequences (see below).

2. Display hue scales aligned with base scales

The display hue scales (gray, blue, green, red, orange, yellow, purple, pink, coral) were realigned so that display colors derive from their base scale counterparts.

3. New borderColor.onMuted display tokens

A new borderColor.onMuted token was added for all display hues. This token is purpose-built for borders rendered on top of bgColor-muted backgrounds, ensuring the border-on-muted contrast requirement is met independently from borderColor-emphasis (which targets contrast against bgColor-muted from the page level).

The contrast config was updated to check borderColor-onMuted against bgColor-muted instead of borderColor-emphasis. This was required to workaround contrast issues.

4. Functional token adjustments

Many functional tokens needed step-level adjustments to maintain contrast with the new scale values:

File	Key changes
fgColor.json5	Dark neutral.13 → {base.color.white} for tokens semantically meaning white; accent/success bumped up steps
bgColor.json5	HC overrides shifted (e.g. muted light-HC n.3→n.2, dark-HC n.2→n.1); inverse/white dark → {base.color.white}; success-emphasis dark green.5→6; success-muted dark-PD alpha 0.2→0.15
borderColor.json5	emphasis neutral.8→9; dark mode default/muted stepped down for contrast
control.json5	HC hover/active shifted (e.g. n.5→n.3, n.6→n.4); knob.checked dark → {base.color.white}
button.json5	All dark neutral.13 fg refs → {base.color.white}; HC danger overrides adjusted
display.json5	161+ step changes across emphasis, muted, borderColor for all hues × all themes
avatar.json5	Dark border → {base.color.white}
header.json5	Dark text → {base.color.white}
syntax.json5	Dark comment color adjusted

Key challenges

The neutral.13 ≠ white problem

The old neutral scale had step 13 as #ffffff. Many dark-mode tokens referenced neutral.13 to mean "white". When the new scale changed step 13 to #f2f5f3, all those tokens broke contrast.

Fix: Replaced {base.color.neutral.13} with {base.color.white} wherever the intent was a true white value. This is semantically cleaner but is a pattern change that needs to be applied consistently across the full token set.

Contrast cascade

Changing scale hex values at the base level triggers a cascade of contrast failures in functional tokens. A single scale update can break dozens of theme × token combinations because:

• Each token may have overrides for up to 13 themes
• High-contrast themes have stricter ratios (7:1 text, 4.5:1 border vs 4.5:1 and 3:1)
• Dark HC themes are the hardest to satisfy, sometimes opposing requirements make it structurally impossible for a single scale step to work

Structurally impossible HC contrasts

Some high-contrast requirements are in tension. For example, a token may need to be:

• Dark enough to meet 7:1 against a light background
• Light enough to meet 7:1 against a dark background

When no single scale step satisfies both, custom hex values between scale steps are needed (an existing pattern in the codebase, see fgColor.success light-HC override).

Breaking changes

This is a visually breaking change across the board:

1. All neutral surfaces shift hue: every gray in the UI moves from blue-gray to green-gray
2. Display colors shift: labels, tags, avatars, and other decorative elements change
3. Contrast step changes: emphasis levels, muted backgrounds, and border weights subtly shift
4. ~1,800 lines of token source changes
5. ~1,860 snapshot files regenerated

Affected color token stats:

Category	Affected	New	Total	%
Base	216	0	290	74,5%
Functional	401	19	526	79,8%
Component	260	0	349	74,5%
Total	877	19	1.165	76,9%

There are no structural breaking changes (no tokens renamed, removed, or added except borderColor.onMuted).

Risks and considerations

• Visual review needed: Automated checks pass, but the green-gray shift needs visual QA across dotcom surfaces. Screenshots/Storybook preview should be reviewed by design.
• Figma-code sync: This PoC was done with hex values extracted from Figma. A production implementation should verify these are the final approved values.
• HC custom hex values: A few high-contrast overrides use custom hex values between scale steps. These are hard to maintain and should be documented.
• borderColor.onMuted is new API: Consumers using borderColor-emphasis on bgColor-muted backgrounds should migrate to borderColor-onMuted. Doing this in the implementation will require migration guidance.
• Display token overrides: The display.json5 file grew significantly (+1,000 lines) due to per-hue × per-theme overrides. Consider whether the override strategy scales or if a different approach is needed.
• Redundant base and display tokens: Base and display scale tokens map to the exact same values. Moving froward with this approach might require a larger refactor/merge/deprecation strategy.
• A complete overhaul of the color scales like the one in this PoC affects approximately 77% of the total color tokens in this library and introduces significant risks.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5ed6389

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Design Token Diff (CSS)

The message is too long to be displayed here. For more details, please check the job summary.

[github-actions]

Design Token Diff (StyleLint)

The message is too long to be displayed here. For more details, please check the job summary.

[github-actions]

Design Token Diff (Figma)

The message is too long to be displayed here. For more details, please check the job summary.