feat(core): default palette reads the neutral scales, and add a --backdrop token

[wemra3]

Follow-up to #569. In the review, @interacsean asked whether the other rgba values in default.css should reference colour tokens. This PR does that for the neutral colours. Nothing changes on screen.

What this PR does

New primitives (internal, not bridged)

• --primitive-white
• --primitive-white-a1 to -a12 and --primitive-black-a1 to -a12. The values are Radix whiteA / blackA (0.05, 0.1, 0.15, 0.2, 0.3, then 0.1 steps to 0.9, and 0.95).

They are declared once next to the gray scale, because they are the same in both modes.

30 tokens in default.css now read a step

Token	Light	Dark
--background, --sidebar	gray-50	gray-950
--card	white	gray-900
--popover	white	gray-800
--muted, --secondary	gray-100	gray-800
--primary	gray-900	gray-200
--primary-foreground	gray-50	gray-900
--secondary-foreground	gray-900	gray-50
other -foreground tokens	gray-950	gray-50
--border	(already gray-200)	white-a2
--input	(already gray-200)	white-a3
--sidebar-border	gray-200	white-a2

White is its own step. The light page is gray-50 and cards are white, so putting cards on gray-50 would remove the difference.

New token --backdrop

--backdrop is var(--primitive-black-a7) (black at 50%) in both modes, bridged as bg-backdrop. Dialog, Sheet and the CsvImporter drawer use it instead of bg-black/50.

The name follows the CSS ::backdrop pseudo-element, the Base UI Backdrop part and the showBackdrop option of Sheet. I did not use overlay, because --z-overlay already names the modal layer, which holds both the backdrop and the popup.

What changes for consumers

• Nothing on screen. Every token resolves to the same colour as before in light and dark mode. I compared all 284 tokens before and after with a script.
• Code that reads these tokens with getComputedStyle(...).getPropertyValue() now gets the step's notation, for example #171717 instead of rgba(23, 23, 23, 1) for --card in dark mode. The colour is the same. The "Verifying" note in the 1.x migration guide is updated to match.
• New public token: --backdrop and bg-backdrop. Override --backdrop on :root to change every backdrop at once. Palettes inherit it.
• cream and bloom are not changed. They set their own values.

Not in this PR

• --accent, the shadows, the chart colours and --destructive stay literal. They have no matching step. (--destructive is feat(core): alias --destructive to the danger roles and move components off destructive utilities #583.)
• cream and bloom keep their own values. Their surfaces are tinted, so they do not map onto the neutral scale.
• The CsvImporter drawer backdrop uses z-50 instead of z-(--z-overlay). The value is the same. This is a separate small fix.
• This PR and feat(core): alias --destructive to the danger roles and move components off destructive utilities #583 both edit four files: the decision record, docs-manifest.json, and the inherited-token comments in theme.css and _template.css. The conflicts are small: keep both sides and run pnpm docs:sync. The PR that merges second will resolve them.

Checks

• fmt:check, lint, type-check, test (core: 2159 tests), docs:check and build pass.
• New tests: semantic-contrast.test.ts pins the resolved value of 19 neutral tokens in light and dark mode, so a step change that alters a colour fails. theme-bridge.test.ts checks that --backdrop is defined and bridged. I changed one value and removed the bridge line on purpose to confirm both tests fail.
• 5 snapshots updated. Each change is bg-black/50 to bg-backdrop only.
• The built CSS contains .astw\:bg-backdrop{background-color:var(--backdrop)}, and dist/themes/default.css defines --backdrop.
• Decision record: decisions/semantic-color-roles.md, section "Update 2026-10-12". Docs: the Surface & chrome table in the styling guide. Changeset: minor.

🤖 Generated with Claude Code

[github-actions]

Code Metrics Report

	main (403eebe)	#593 (33cf627)	+/-
Coverage	88.1%	88.1%	0.0%
Test Execution Time	2m18s	2m16s	-2s

Details

  |                     | main (403eebe) | #593 (33cf627) | +/-  |
  |---------------------|----------------|----------------|------|
  | Coverage            |          88.1% |          88.1% | 0.0% |
  |   Files             |            207 |            207 |    0 |
  |   Lines             |           6178 |           6178 |    0 |
  |   Covered           |           5448 |           5448 |    0 |
+ | Test Execution Time |          2m18s |          2m16s |  -2s |

Code coverage of files in pull request scope (21.8% → 21.8%)

Files	Coverage	+/-	Status
packages/core/src/components/csv-importer/CsvImporter.tsx	0.5%	0.0%	modified
packages/core/src/components/dialog/dialog.tsx	95.2%	0.0%	modified
packages/core/src/components/sheet/sheet.tsx	97.1%	0.0%	modified

---

Reported by octocov