# Spacing Token Consolidation — Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace ~183 hardcoded px values across 6 CSS files with design tokens, improving maintainability and theme consistency.

**Architecture:** Three sequential phases — border widths, spacing token adoption, border-radius scale. Each phase touches all affected files, gets verified via Playwright + tests, and is committed independently.

**Tech Stack:** Vanilla CSS custom properties (no build tools). Playwright MCP for visual verification.

**Spec:** `docs/superpowers/specs/2026-03-16-spacing-token-consolidation-design.md`

---

## Pre-flight

- [ ] **Step 0a: Run baseline tests**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

- [ ] **Step 0b: Capture baseline Playwright screenshots**

Use Playwright MCP to capture screenshots for pixel-diff comparison after each phase:
1. Navigate to `SVS-MSP-Calculator.html` at 1920x1080
2. Screenshot Dark theme (default) → save reference
3. Toggle to Light theme → screenshot → save reference
4. Toggle to Glass theme → screenshot → save reference
5. Resize to 375px width → screenshot mobile (Dark) → save reference

These are your "before" images. After each phase, re-capture and visually compare.

---

## Chunk 1: Phase 1 — Border Width Tokens

### Task 1: Add border width tokens to tokens.css

**Files:**
- Modify: `SVS-MSP-Calculator-tokens.css:66-68` (insert before `--radius-control`)

- [ ] **Step 1: Add new tokens**

Insert these 3 lines immediately before `--radius-control: 6px;` (line 67):

```css
    --border-thin: 1px;
    --border-medium: 2px;
    --border-thick: 3px;
```

The `:root` block at this point should read:
```css
    --space-4xl: 32px;
    --border-thin: 1px;
    --border-medium: 2px;
    --border-thick: 3px;
    --radius-control: 6px;
```

- [ ] **Step 2: Verify no syntax errors**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing` (CSS-only change, tests should still pass)

---

### Task 2: Tokenize border widths in components.css

**Files:**
- Modify: `SVS-MSP-Calculator-components.css`

- [ ] **Step 1: Replace all `1px` border values**

Search for these patterns and replace. Apply ONLY to border properties (`border`, `border-top`, `border-bottom`, `border-left`, `border-right`, `border-width`, `border-*-width`). Include `solid`, `dashed`, and `dotted` styles.

**DO NOT replace** `1px` in:
- `calc()` expressions
- `box-shadow` values
- `outline` properties
- `pre-alpha/` directory

Replace pattern: `1px solid` → `var(--border-thin) solid`, `1px dashed` → `var(--border-thin) dashed`, `border-width: 1px` → `border-width: var(--border-thin)`, etc.

- [ ] **Step 2: Replace all `2px` border values**

Same pattern as Step 1 but for `2px` → `var(--border-medium)`. Only border properties — skip `padding: 2px` or `margin: 2px` (those are spacing).

- [ ] **Step 3: Replace all `3px` border values**

Same pattern for `3px` → `var(--border-thick)`. Only border properties.

- [ ] **Step 4: Verify — run tests**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

---

### Task 3: Tokenize border widths in remaining files

**Files:**
- Modify: `SVS-MSP-Calculator-responsive.css`
- Modify: `SVS-MSP-Calculator-layout.css`
- Modify: `SVS-MSP-Calculator-print.css`
- Modify: `SVS-MSP-Calculator-base.css`
- Modify: `SVS-MSP-Calculator-glass.css`

- [ ] **Step 1: Replace border widths in responsive.css**

Same rules as Task 2. Replace `1px`/`2px`/`3px` in border properties only. Respect all exclusions (calc, box-shadow, outline).

- [ ] **Step 2: Replace border widths in layout.css**

Same rules.

- [ ] **Step 3: Replace border widths in print.css**

Same rules.

- [ ] **Step 4: Replace border widths in base.css**

Known instances:
- `border-bottom: 2px solid var(--top-bar-border)` → `border-bottom: var(--border-medium) solid var(--top-bar-border)`
- `border: 1px solid var(--theme-chip-border)` → `border: var(--border-thin) solid var(--theme-chip-border)`

- [ ] **Step 5: Replace border widths in glass.css**

Known instance:
- `border-bottom-width: 1px !important` → `border-bottom-width: var(--border-thin) !important`

- [ ] **Step 6: Verify — run tests**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

---

### Task 4: Phase 1 visual verification

- [ ] **Step 1: Playwright screenshots — all 3 themes at 1920px**

Navigate to calculator. Screenshot Dark, Light, Glass at 1920x1080. Compare against baseline from Step 0b. Changes should be zero — this is a pure refactor.

- [ ] **Step 2: Playwright screenshots — mobile at 375px**

Resize to 375px. Verify floating MRR pill visible, mobile panel opens, values sync.

- [ ] **Step 3: Playwright — print emulation**

Enable print media emulation. Verify all sections expand, interactive controls hidden, no visual regressions.

- [ ] **Step 4: Commit Phase 1**

```bash
git add SVS-MSP-Calculator-tokens.css SVS-MSP-Calculator-components.css SVS-MSP-Calculator-responsive.css SVS-MSP-Calculator-layout.css SVS-MSP-Calculator-print.css SVS-MSP-Calculator-base.css SVS-MSP-Calculator-glass.css
git commit -m "css: tokenize border widths — consolidate 1px/2px/3px to --border-thin/medium/thick"
```

---

## Chunk 2: Phase 2 — Adopt Existing Spacing Tokens

### Task 5: Replace hardcoded spacing values in components.css

**Files:**
- Modify: `SVS-MSP-Calculator-components.css`

- [ ] **Step 1: Replace `4px` spacing → `var(--space-xs)`**

Search for `margin`, `padding`, and `gap` properties using hardcoded `4px`. Replace with `var(--space-xs)`.

**DO NOT replace** `4px` when used as:
- `border-radius` (Phase 3)
- `font-size`, `width`, `height`
- Inside `clamp()` or `calc()`
- Values that are already `var(--space-xs)`

- [ ] **Step 2: Replace `8px` spacing → `var(--space-sm)`**

Same rules — only `margin`, `padding`, `gap`. Skip `border-radius: 8px` (Phase 3).

- [ ] **Step 3: Replace `10px` spacing → `var(--space-stack-tight)`**

Same rules. Only spacing properties.

- [ ] **Step 4: Replace `12px` spacing → `var(--space-md)`**

Only spacing properties. Skip `border-radius: 12px` (already uses `--radius-card`).

- [ ] **Step 5: Replace `16px` spacing → `var(--space-stack-roomy)`**

Only spacing properties. Skip font-size and width/height uses.

- [ ] **Step 6: Replace `18px` spacing → `var(--space-lg)`**

Only spacing properties. Skip icon sizing.

- [ ] **Step 7: Replace `20px` spacing → `var(--space-xl)`**

Only spacing properties.

- [ ] **Step 8: Verify — run tests**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

---

### Task 6: Replace hardcoded spacing in remaining files

**Files:**
- Modify: `SVS-MSP-Calculator-layout.css`
- Modify: `SVS-MSP-Calculator-responsive.css`
- Modify: `SVS-MSP-Calculator-print.css`
- Modify: `SVS-MSP-Calculator-base.css`

- [ ] **Step 1: Replace spacing values in layout.css**

Same rules as Task 5. Only `margin`, `padding`, `gap` properties. Skip values in `clamp()`.

- [ ] **Step 2: Replace spacing values in responsive.css**

Same rules.

- [ ] **Step 3: Replace spacing values in print.css**

Same rules.

- [ ] **Step 4: Replace spacing values in base.css**

Known instance: `gap: 16px` → `gap: var(--space-stack-roomy)`. Same exclusion rules apply.

- [ ] **Step 5: Verify — run tests**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

---

### Task 7: Phase 2 visual verification

- [ ] **Step 1: Playwright screenshots — all 3 themes at 1920px**

Compare against Phase 1 screenshots. Changes should be zero.

- [ ] **Step 2: Playwright screenshots — mobile at 375px**

Verify pill, panel, sync all working.

- [ ] **Step 3: Playwright — print emulation**

Enable print media emulation. Verify no regressions from print.css spacing changes.

- [ ] **Step 4: Commit Phase 2**

```bash
git add SVS-MSP-Calculator-components.css SVS-MSP-Calculator-layout.css SVS-MSP-Calculator-responsive.css SVS-MSP-Calculator-print.css SVS-MSP-Calculator-base.css
git commit -m "css: adopt existing spacing tokens — replace hardcoded 4-20px with var(--space-*)"
```

---

## Chunk 3: Phase 3 — Border-Radius Scale

### Task 8: Add border-radius tokens to tokens.css

**Files:**
- Modify: `SVS-MSP-Calculator-tokens.css` (insert after `--border-thick`, before `--radius-control`)

- [ ] **Step 1: Add new radius tokens**

Insert into the radius section in **ascending px order**, interleaving with existing `--radius-control` (6px) and `--radius-card` (12px):

```css
    --border-thick: 3px;
    --radius-sm: 4px;        /* NEW */
    --radius-control: 6px;   /* existing */
    --radius-md: 8px;        /* NEW */
    --radius-lg: 10px;       /* NEW */
    --radius-card: 12px;     /* existing */
    --radius-pill: 999px;    /* NEW */
```

This requires inserting at 3 positions:
1. `--radius-sm: 4px;` before `--radius-control`
2. `--radius-md: 8px;` and `--radius-lg: 10px;` between `--radius-control` and `--radius-card`
3. `--radius-pill: 999px;` after `--radius-card`

- [ ] **Step 2: Verify — run tests**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

---

### Task 9: Tokenize border-radius in components.css

**Files:**
- Modify: `SVS-MSP-Calculator-components.css`

- [ ] **Step 1: Replace `border-radius: 4px` → `var(--radius-sm)`**

Search for all `border-radius` properties using `4px`. Replace with `var(--radius-sm)`. Skip values inside `calc()`.

- [ ] **Step 2: Replace `border-radius: 8px` → `var(--radius-md)`**

Same pattern.

- [ ] **Step 3: Replace `border-radius: 10px` → `var(--radius-lg)`**

Same pattern.

- [ ] **Step 4: Replace `border-radius: 999px` → `var(--radius-pill)`**

Same pattern.

- [ ] **Step 5: Verify — run tests**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

---

### Task 10: Tokenize border-radius in remaining files

**Files:**
- Modify: `SVS-MSP-Calculator-responsive.css`
- Modify: `SVS-MSP-Calculator-base.css`

- [ ] **Step 1: Replace border-radius values in responsive.css**

Same rules as Task 9.

- [ ] **Step 2: Replace border-radius values in base.css**

Known instance: `border-radius: 8px` → `var(--radius-md)`

- [ ] **Step 3: Verify — run tests**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

---

### Task 11: Phase 3 visual verification + final commit

- [ ] **Step 1: Playwright screenshots — all 3 themes at 1920px**

Compare against Phase 2 screenshots. Changes should be zero.

- [ ] **Step 2: Playwright screenshots — mobile at 375px**

Verify pill, panel, sync.

- [ ] **Step 3: Playwright — print emulation**

Final print check.

- [ ] **Step 4: Commit Phase 3**

```bash
git add SVS-MSP-Calculator-tokens.css SVS-MSP-Calculator-components.css SVS-MSP-Calculator-responsive.css SVS-MSP-Calculator-base.css
git commit -m "css: tokenize border-radius — consolidate to --radius-sm/md/lg/pill scale"
```

---

## Post-flight

- [ ] **Step final-a: Run full test suite**

Run: `node tests/test-quote-engine.js`
Expected: `254/254 tests passing`

- [ ] **Step final-b: Final Playwright verification — all themes, all viewports**

Full sweep: Dark/Light/Glass at 1920px + 375px mobile + print. Compare against original baseline screenshots.

- [ ] **Step final-c: Update SESSION-HANDOFF.md**

Record what was done, files modified, test status, and next steps.

- [ ] **Step final-d: Update KNOWN-ISSUES.md**

Mark "Spacing token consolidation — 150+ magic px values" as partially resolved (Phases 1-3 complete, Phases 4-6 remain).