docs: 16-step hybrid approach comparison analysis by lukasoppermann · Pull Request #1364 · primer/primitives

lukasoppermann · 2026-04-30T08:22:25Z

Visual & Technical Comparison: 16-Step Hybrid Approach vs PR #1340

📊 What's Included

Interactive Visual Comparison (docs/scale-analysis/index.html)
- Color swatches side-by-side (PR [TEST] Update base and display color scales #1340 vs Hybrid)
- Hex values and step labels
- Open in browser for interactive view
Detailed Technical Documentation (docs/scale-analysis/SCALE_COMPARISON.md)
- Contrast metrics and violation breakdown
- Root cause analysis
- Comparison of implementation costs
Token Changes Reference (docs/scale-analysis/TOKENS_CHANGED.md)
- Exact file/line changes
- Impact analysis for each change
- Deployment strategy

🎯 Key Findings

Metric	PR #1340	Hybrid Approach
Functional token changes	1,800+	2 ✅
Scale preservation (0-13)	Remapped	Unchanged ✅
Contrast violations	0	~70 (mostly marginal)
Implementation complexity	Very High	Low ✅

📈 Results

✅ Violations reduced: 190 → ~70 (63% improvement)
✅ Critical dark mode contrast fixed: 1.64:1 → 6.43:1
✅ Scale architecture preserved
⚠️ Light theme emphasis still needs attention

👀 View It

# View interactive comparison
open docs/scale-analysis/index.html

# Read full analysis
cat docs/scale-analysis/SCALE_COMPARISON.md

# Quick token reference
cat docs/scale-analysis/TOKENS_CHANGED.md

- Extended neutral scale from 13 to 16 steps (0-15) - Added neutral.14 (#F4F7F6, L=96.3%) and neutral.15 (#FDFCFC, L=99.0%) to light theme - Added neutral.14 (#FBFDFB, L=97.75%) and neutral.15 (#FDFDFC, L=99%) to dark theme - Updated all neutral colors to green-gray palette from PR #1340 - Fixed fgColor-onEmphasis dark override to use white instead of neutral.13 - Preserved 3-region scale architecture (light zone, text zone, 7↔8 break point) Contrast status: 190 total violations (mostly ~0.3:1 below threshold) - Critical: fgColor-onEmphasis vs neutral-emphasis colors (contrast too low) - Minor: ~99% of failures are 0.1-0.4:1 below threshold - Suggests fine-tuning needed, not fundamental architecture flaw Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Applied S+1.5%, L-1% adjustments to green-gray palette (light & dark) - Shifted bgColor-neutral-emphasis dark override: neutral.8 → neutral.9 - Improved fgColor-onEmphasis contrast from 1.64:1 to ~2.0+:1 in many cases - Reduced total violations from 190 → ~70 - Remaining violations are mostly 0.1-0.5:1 marginal shortfalls This demonstrates the hybrid approach viability: ✓ Preserves 16-step scale (0-13 unchanged for functional tokens) ✓ Minimal palette adjustment (S+1.5%, L-1%) ✓ Targeted functional token shifts (1 key change) ✗ Still ~70 contrast violations (but most are minor) Note: fgColor-onEmphasis in light theme still struggles (white vs adjusted neutral-emphasis is still low contrast) May require additional semantic updates or design constraints. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Interactive HTML comparison of PR #1340 vs hybrid approach - Detailed markdown documentation with contrast metrics - Token changes reference (only 2 functional tokens adjusted) - README explaining the analysis and viewing instructions Key findings: - Hybrid approach reduces token changes from 1,800+ to 2 - Contrast violations reduced from 190 to ~70 (63% improvement) - Scale steps 0-13 completely preserved (no reference updates needed) - Minimal palette adjustments (S+1.5%, L-1%) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

changeset-bot · 2026-04-30T08:22:36Z

⚠️ No Changeset found

Latest commit: 4793c17

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 · 2026-04-30T08:24:55Z

Design Token Diff (CSS)

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

github-actions · 2026-04-30T08:24:56Z

Design Token Diff (StyleLint)

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

github-actions · 2026-04-30T08:24:58Z

Design Token Diff (Figma)

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

Copilot

Pull request overview

This PR documents and evaluates a proposed “16-step hybrid” neutral scale approach (vs PR #1340) and also applies corresponding token changes to the base light/dark neutral scales plus two functional token overrides.

Changes:

Adds a new docs/scale-analysis/ package of reference docs (HTML + Markdown) describing the hybrid approach, metrics, and impacted tokens.
Updates base neutral scales in src/tokens/base/color/light/light.json5 and src/tokens/base/color/dark/dark.json5 (including adding neutral.14/neutral.15 in dark).
Adjusts two functional overrides: fgColor.onEmphasis (dark) and bgColor.neutral.emphasis (dark + dark-dimmed).

Show a summary per file

File	Description
src/tokens/functional/color/fgColor.json5	Changes `fgColor.onEmphasis` dark override to reference `{base.color.white}`.
src/tokens/functional/color/bgColor.json5	Changes `bgColor.neutral.emphasis` dark/dark-dimmed overrides from `neutral.8` → `neutral.9`.
src/tokens/base/color/light/light.json5	Rewrites light base palette (notably neutral scale) and changes formatting/quoting.
src/tokens/base/color/dark/dark.json5	Rewrites dark base palette (neutral scale) and adds `neutral.14`/`neutral.15`.
docs/scale-analysis/index.html	Adds an interactive visual comparison page for PR #1340 vs the hybrid approach.
docs/scale-analysis/README.md	Adds a landing page explaining what the analysis contains and key claims.
docs/scale-analysis/SCALE_COMPARISON.md	Adds detailed technical comparison write-up, metrics, and “files modified” list.
docs/scale-analysis/TOKENS_CHANGED.md	Adds a “what changed” reference doc listing the intended token deltas and rationale.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (9)

src/tokens/base/color/dark/dark.json5:312

neutral.14 / neutral.15 hex values are uppercase (#FBFDFB, #FDFDFC) while most other hex values in this repo are lowercase. Please normalize hex casing to a single style to keep token diffs stable and consistent.

              140,
              6.5,
              97.75,
            ],
            hex: "#FBFDFB",

src/tokens/base/color/dark/dark.json5:8

This file switches to double quotes for keys/strings (e.g. colorSpace: "hsl", "org.primer.figma") while other token JSON5 files use single quotes (e.g. src/tokens/base/color/dark/dark.dimmed.json5:1-20). This increases diff noise and makes token sources inconsistent; please keep the existing quoting style when updating values.

      black: {
        $value: {
          colorSpace: "hsl",
          components: [
            217.5,

docs/scale-analysis/SCALE_COMPARISON.md:175

This section says src/tokens/base/color/light/light.json5 “Added neutral 14-15 ultra-light steps”, but that file in this PR does not include neutral.14 / neutral.15. Please either add the missing steps to the light scale or update this list to match reality.

1. `src/tokens/base/color/light/light.json5`
   - Updated neutral 0-13 with S+1.5%, L-1% adjustments
   - Added neutral 14-15 ultra-light steps

src/tokens/base/color/dark/dark.json5:244

The dark neutral scale is not monotonic here: neutral.9 has L=82.7, but neutral.10 has L=72.1 (darker than step 9). Neutral scale steps are expected to progress in a consistent direction; please verify the step ordering/values (these look like they may have been copied from the light scale out of order).

              133.3,
              8.1,
              72.1,
            ],
            hex: "#b2bdb4",

src/tokens/base/color/light/light.json5:8

This file switches to double quotes for keys/strings (e.g. colorSpace: "hsl", "org.primer.figma") while other token JSON5 files use single quotes (e.g. src/tokens/base/color/dark/dark.dimmed.json5:1-20). This increases diff noise and makes token sources inconsistent; please keep the existing quoting style when updating values.

      black: {
        $value: {
          colorSpace: "hsl",
          components: [
            0,

src/tokens/base/color/light/light.json5:25

In the light theme file, base.color.inset is tagged with the Figma collection base/color/dark, which looks incorrect for a light-mode token. This will misclassify the token in Figma sync/export; it should likely be base/color/light (consistent with the rest of this file’s tokens).

      inset: {
        $value: "{base.color.neutral.0}",
        $type: "color",
        $extensions: {
          "org.primer.figma": {

src/tokens/base/color/dark/dark.json5:124

neutral.3’s HSL lightness is serialized as 15.100000000000001, which looks like an unrounded float artifact. Please round HSL component values to a reasonable precision (and keep it consistent with other steps) to avoid unnecessary churn and improve readability.

            components: [
              140,
              8.8,
              15.100000000000001,
            ],

docs/scale-analysis/TOKENS_CHANGED.md:94

This section claims the light theme base scale adds neutral.14 / neutral.15, but src/tokens/base/color/light/light.json5 in this PR has no such steps. Please align this doc with the actual token changes (or add the missing steps).

**Changes**:
- Applied S+1.5%, L-1% adjustments to neutral steps 0-13
- Added neutral.14 (#F4F7F6) and neutral.15 (#FDFCFC)

docs/scale-analysis/README.md:66

This section claims the hybrid solution keeps scale steps 0–13 “completely unchanged”, but the token files in this PR change the neutral step values (and only add 14/15 in dark). Please reconcile this statement with the actual changes so the analysis doesn’t mislead readers.

- **Hybrid solution**: Keep scale steps 0-13 completely unchanged
  - Add steps 14-15 for ultra-light zone (new capacity)
  - Adjust palette subtly (S+1.5%, L-1%)
  - Fix contrast with 2 targeted token shifts
  - Result: ~70 remaining violations (mostly <0.5:1 below threshold, acceptable)

Files reviewed: 8/8 changed files
Comments generated: 7

Copilot · 2026-04-30T08:29:53Z

 {
  base: {
    color: {
      black: {
        $value: {


The header JSDoc describing the theme was removed from this base token file, but other base color theme files keep this header (e.g. src/tokens/base/color/dark/dark.dimmed.json5:1-4). Please restore the theme header so the intent/usage of this file remains documented.

This issue also appears in the following locations of the same file:

line 4

line 21

Copilot · 2026-04-30T08:29:54Z

+    emphasis: {
+      dark: {base.color.neutral.8}
+    }


The JSON5 examples omit quotes around token references (e.g. dark: {base.color.neutral.8}), but the actual token source uses string references like dark: '{base.color.neutral.8}'. Please update examples to match the real token syntax to avoid copy/paste errors.

This issue also appears on line 91 of the same file.

Copilot · 2026-04-30T08:29:54Z

+            dark: '{base.color.neutral.9}',
+            'dark-dimmed': '{base.color.neutral.9}',


With the updated dark neutral scale in this PR, {base.color.neutral.9} is lighter than {base.color.neutral.8} (see src/tokens/base/color/dark/dark.json5 neutral.8/9). Changing bgColor.neutral.emphasis from neutral.8 → neutral.9 will further reduce contrast against fgColor.onEmphasis (which is explicitly white in dark mode). If the goal is to improve contrast, this should move to a darker step (or the dark neutral scale values need to be corrected).

Suggested change

dark: '{base.color.neutral.9}',

'dark-dimmed': '{base.color.neutral.9}',

dark: '{base.color.neutral.8}',

'dark-dimmed': '{base.color.neutral.8}',

Copilot · 2026-04-30T08:29:55Z

+
+## Visual Scale Comparison
+
+See `scale_comparison.html` for interactive side-by-side comparison with color swatches.


This file references scale_comparison.html, but the interactive comparison added in this PR is docs/scale-analysis/index.html. Please update the filename so readers can find the correct artifact.

This issue also appears on line 173 of the same file.

Suggested change

See `scale_comparison.html` for interactive side-by-side comparison with color swatches.

See `docs/scale-analysis/index.html` for interactive side-by-side comparison with color swatches.

Copilot · 2026-04-30T08:29:55Z

+# Neutral Scale Comparison: 16-Step Hybrid Approach vs PR #1340
+
+## 📋 What's in This Directory
+
+This analysis documents the **Hybrid Approach** to resolving Primer's neutral color scale transition (PR #1340), comparing it against the original blue-gray-to-green-gray mapping.


The PR title/description frames this as a docs-only change, but this PR also makes large, behavior-affecting token changes (base light/dark scales + functional tokens). Please either (1) split docs vs token changes into separate PRs, or (2) update the PR title/description to reflect that it changes shipped tokens.

This issue also appears on line 62 of the same file.

Copilot · 2026-04-30T08:29:55Z

+            <div class="step">
+              <div class="step-swatch" style="background: #F6F9F8;"></div>
+              <div class="step-info">
+                <div class="step-label">neutral.1</div>
+                <div class="step-hex">#F6F9F8</div>


The “Hybrid” swatch values here (e.g. neutral.1 #F6F9F8) don’t match the neutral values in src/tokens/base/color/light/light.json5 in this PR (neutral.1 is #f4f7f5). If this page is meant to represent the branch’s implementation, please derive these values from the actual token files (or clearly label them as illustrative).

Copilot · 2026-04-30T08:29:55Z

 {
  base: {
    color: {
      black: {


The header JSDoc describing the theme was removed from this base token file, but other base color theme files keep this header (e.g. src/tokens/base/color/dark/dark.dimmed.json5:1-4). Please restore the theme header so the intent/usage of this file remains documented.

This issue also appears in the following locations of the same file:

line 4

line 120

line 240

line 308

…yout - Use actual PR #1340 green-gray colors (not original blue-gray) - New side-by-side layout: labels on outside, swatches touching in middle - Larger color swatches (100px height) for better comparison - Direct visual comparison: left half is PR #1340, right half is hybrid - Hover effects for interactivity - Hex codes displayed below step labels on each side

- Remove separation line between colors (seamless swatch) - Replace 14+2 approach with 18-step monotonic scale - Insert steps BETWEEN existing ones instead of extending at ends - Maintains monotonic progression (never gets lighter) - Fixes emphasis color contrast issues - Shows mapping from PR #1340 (14 steps) to proposed (18 steps) - Highlights inserted steps that improve contrast flexibility Key insight: Scale should always darken, never lighten. Insert internal steps to smooth gradations and provide better emphasis color options. Emphasis mapping example: - bgColor-neutral-emphasis: step 8 → step 14 - Contrast: 1.64:1 → ~8:1 (WCAG AAA passed)

- Single unified view showing all 18 steps (0-17) - Clear badges: [FROM PR #1340] vs [INSERTED] - No confusing mapping sections or hidden steps - All 18 steps visible and comparable - Better explanation of why inserts between are better than extends at ends Fixes issue where steps appeared to be missing.

- Inserted steps (2,3,5,7,9,11,13,15) now grayed on left - FROM PR #1340 steps have normal blue labels - Makes it visually clear which steps are new vs preserved - Improves readability of scale composition

- Inserted steps now show light gray on left side - Right side shows actual color from 18-step scale - Makes it immediately clear which steps are new vs preserved

lukasoppermann and others added 3 commits April 29, 2026 15:03

Copilot AI review requested due to automatic review settings April 30, 2026 08:22

lukasoppermann requested a review from a team as a code owner April 30, 2026 08:22

lukasoppermann requested a review from TylerJDev April 30, 2026 08:22

Copilot started reviewing on behalf of lukasoppermann April 30, 2026 08:22 View session

lukasoppermann temporarily deployed to github-pages April 30, 2026 08:24 — with GitHub Actions Inactive

github-actions Bot temporarily deployed to Preview (Storybook) April 30, 2026 08:24 Inactive

Copilot AI reviewed Apr 30, 2026

View reviewed changes

lukasoppermann temporarily deployed to github-pages April 30, 2026 08:36 — with GitHub Actions Inactive

github-actions Bot temporarily deployed to Preview (Storybook) April 30, 2026 08:37 Inactive

lukasoppermann temporarily deployed to github-pages April 30, 2026 08:44 — with GitHub Actions Inactive

github-actions Bot temporarily deployed to Preview (Storybook) April 30, 2026 08:44 Inactive

lukasoppermann temporarily deployed to github-pages April 30, 2026 08:52 — with GitHub Actions Inactive

github-actions Bot temporarily deployed to Preview (Storybook) April 30, 2026 08:52 Inactive

design: Gray out inserted steps on left side for clarity

5369c55

- Inserted steps (2,3,5,7,9,11,13,15) now grayed on left - FROM PR #1340 steps have normal blue labels - Makes it visually clear which steps are new vs preserved - Improves readability of scale composition

lukasoppermann temporarily deployed to github-pages April 30, 2026 08:58 — with GitHub Actions Inactive

design: Gray out left swatch for inserted steps

4793c17

- Inserted steps now show light gray on left side - Right side shows actual color from 18-step scale - Makes it immediately clear which steps are new vs preserved

lukasoppermann deployed to github-pages April 30, 2026 09:01 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to Preview (Storybook) April 30, 2026 09:01 Inactive

lukasoppermann closed this Apr 30, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: 16-step hybrid approach comparison analysis#1364

docs: 16-step hybrid approach comparison analysis#1364
lukasoppermann wants to merge 8 commits into
mainfrom
docs/16-step-comparison-analysis

lukasoppermann commented Apr 30, 2026

Uh oh!

changeset-bot Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		dark: '{base.color.neutral.9}',
		'dark-dimmed': '{base.color.neutral.9}',


		## Visual Scale Comparison

		See `scale_comparison.html` for interactive side-by-side comparison with color swatches.

	See `scale_comparison.html` for interactive side-by-side comparison with color swatches.
	See `docs/scale-analysis/index.html` for interactive side-by-side comparison with color swatches.

Conversation

lukasoppermann commented Apr 30, 2026

Visual & Technical Comparison: 16-Step Hybrid Approach vs PR #1340

📊 What's Included

🎯 Key Findings

📈 Results

👀 View It

Related

Uh oh!

changeset-bot Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Design Token Diff (CSS)

Uh oh!

github-actions Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Design Token Diff (StyleLint)

Uh oh!

github-actions Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Design Token Diff (Figma)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Apr 30, 2026 •

edited

Loading

github-actions Bot commented Apr 30, 2026 •

edited

Loading

github-actions Bot commented Apr 30, 2026 •

edited

Loading

github-actions Bot commented Apr 30, 2026 •

edited

Loading