john/svsmspcalc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4c53af96a925ffc927752dd87469fea72c150487
svsmspcalc/docs/superpowers/plans/2026-03-16-spacing-token-consolidation.md

12 KiB
Raw Blame History

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):

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

The :root block at this point should read:

    --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
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
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):

    --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
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).

Reference in New Issue View Git Blame Copy Permalink