387 lines
12 KiB
Markdown
387 lines
12 KiB
Markdown
# 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).
|