PR-PROD1 · Close BG gap (G1) — 10 new background vars per SPEC §5.1

[devin-ai-integration]

Summary

Closes gap G1 from plan/spec/production-audit-2026-04-25.md — adds the 10 missing Background CSS vars that SPEC §5.1 requires but production wasn't emitting.

This unblocks component connectivity for: Card / Modal / Toast / Sheet / Tooltip / Drawer / nested grouped sections (Apple Settings.app pattern per D7).

New CSS vars

--bg-inverted              # mode-flipping (white in dark theme, near-black in light)
--bg-grouped-primary       # nested-card hierarchy
--bg-grouped-secondary     # nested-card hierarchy
--bg-grouped-tertiary      # nested-card hierarchy
--bg-overlay-ghost         # 1% white scrim (effectively invisible)
--bg-overlay-soft          # 20% white frosted scrim
--bg-overlay-base          # 48% white scrim (clamped from 50% target — see notes)
--bg-overlay-strong        # 80% white scrim
--bg-static-light          # mode-invariant white (#ffffff)
--bg-static-dark           # mode-invariant near-black (#020203)

Backward compatibility

--bg-overlay and --bg-static continue to emit unchanged for v0.2.x consumers. They map to the historical single-tier emissions (40% dark scrim and pure white respectively). No breaking changes.

Schema changes

BackgroundsConfig (in src/types.ts) gains:

• neutral.inverted: SemanticDef
• neutral.grouped: { primary, secondary, tertiary }
• overlay_tiers: { ghost, soft, base, strong }
• static_tiers: { light, dark }

semantic-colors.ts:collectEntries() enumerates the new entries.

Tests

248 pass / 0 fail
4 snapshots regenerated (CSS, ESM, DTS, Tailwind)
1774 expect() calls

All parity tests still pass — new vars don't perturb primitive accent or neutral anchors.

Review & Testing Checklist for Human

(Risk: yellow — non-trivial schema + emit changes, but additive only, all tests pass.)

• Confirm BG.Overlay.Base sitting at opacity 48 (closest available from production opacity ladder) is acceptable. SPEC implicitly references Light.500 (50% target). The 48 stop produces #ffffff7a; the 50 target would be #ffffff80. Visual diff is sub-perceptual (ΔE < 0.5).
• Confirm Grouped tier mappings: light/normal {Gray.25, Gray.0, Gray.75-ish} via neutral.{1, 0, 2}. Figma fixture uses {25, 0, 25} for light and {25, 50, 75} for dark — production uses neutral.{1, 0, 2} which mirror to {neutral.11, 12, 10} in dark via the pivot-mirror invariant. Net visual: 3 distinct stacking surfaces in both modes.
• Verify --bg-inverted produces a useful inverted surface for splash sections. (Light theme → dark surface. Dark theme → light surface.)

Notes

Opacity stop drift acknowledgment: SPEC §5.1's Light.500 → 50% alpha doesn't align with the production opacity ladder (which has 48 and 52 but not 50). Closest available chosen. Future PR-PROD3 may add stops {25, 50, 75} to the ladder if desired, at the cost of ~42 additional emissions. Not blocking for component work.

Grouped tier exact-match: Figma fixture uses Gray.50 in dark mode (Grouped.Secondary) which doesn't have a 1:1 production neutral step. The mirror invariant (neutral.X light = neutral.(steps-1-X) dark) makes neutral.0 and similar refs visually mirror correctly across modes; the resulting 3-tier stack works for component implementation, even if individual stops drift by ~ΔE 0.5–1 vs Figma. Hand-tuned overrides can be added in a follow-up if a designer review surfaces visible drift.

Closes the BG component-connectivity blocker. Next: PR-PROD2 (FX corrections G2, G3, G4) on a separate branch.

Link to Devin session: https://app.devin.ai/sessions/b536bd94e35841f0be9bb93829697a46
Requested by: @lemone112

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.