diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..a153a67 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,19 @@ +{ + "permissions": { + "allow": [ + "Bash(ls -lh *.css)", + "Bash(node tests/*)", + "Bash(python3 .claude/skills/*)", + "Bash(git status*)", + "Bash(git add*)", + "Bash(git commit*)", + "Bash(git log*)", + "Bash(git diff*)", + "Bash(git branch*)", + "Bash(git checkout*)", + "Read(//c/Users/JohnOReilly/OneDrive - Silicon Valley Services/Documents/Projects VS CODE/SVS MSP Calculator/**)", + "mcp__plugin_playwright_playwright__browser_evaluate", + "mcp__plugin_playwright_playwright__browser_run_code" + ] + } +} diff --git a/.playwright-mcp/console-2026-03-16T20-42-35-139Z.log b/.playwright-mcp/console-2026-03-16T20-42-35-139Z.log new file mode 100644 index 0000000..3fad8c1 --- /dev/null +++ b/.playwright-mcp/console-2026-03-16T20-42-35-139Z.log @@ -0,0 +1 @@ +[ 245ms] [ERROR] Failed to load resource: the server responded with a status of 404 (File not found) @ http://localhost:8765/favicon.ico:0 diff --git a/docs/superpowers/plans/2026-03-16-spacing-token-consolidation.md b/docs/superpowers/plans/2026-03-16-spacing-token-consolidation.md new file mode 100644 index 0000000..55c7efe --- /dev/null +++ b/docs/superpowers/plans/2026-03-16-spacing-token-consolidation.md @@ -0,0 +1,386 @@ +# 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). diff --git a/docs/superpowers/specs/2026-03-16-spacing-token-consolidation-design.md b/docs/superpowers/specs/2026-03-16-spacing-token-consolidation-design.md new file mode 100644 index 0000000..dcc6004 --- /dev/null +++ b/docs/superpowers/specs/2026-03-16-spacing-token-consolidation-design.md @@ -0,0 +1,202 @@ +# Spacing Token Consolidation — Design Spec + +**Date:** 2026-03-16 +**Status:** Approved +**Scope:** Phases 1-3 (~183 instances across 5 CSS files) +**Approach:** Phase-by-phase across all files, one commit per phase + +--- + +## Context + +The SVS MSP Calculator CSS has ~420 hardcoded px values across 75+ unique values. About half already have tokens defined in `SVS-MSP-Calculator-tokens.css` but aren't being used. This consolidation pass addresses the highest-ROI phases: border widths, existing token adoption, and border-radius scale. + +**Why now:** The project is moving from alpha to beta. Consolidating magic numbers improves maintainability, makes theme adjustments easier, and reduces regression risk from future CSS changes. + +**What's NOT in scope:** Icon/button sizing tokens (Phase 4), typography scale (Phase 5), breakpoint tokens (Phase 6 — CSS vars can't be used in `@media` queries anyway). + +--- + +## Phase 1: Border Width Tokens (~124 instances) + +### New tokens (add to `SVS-MSP-Calculator-tokens.css`) + +```css +--border-thin: 1px; /* structural borders */ +--border-medium: 2px; /* accent borders, summary badges */ +--border-thick: 3px; /* sidebar decorators, group strips */ +``` + +### Replacement rules + +| Pattern | Replacement | +|---------|-------------| +| `border: 1px solid ...` | `border: var(--border-thin) solid ...` | +| `border-top: 1px solid ...` | `border-top: var(--border-thin) solid ...` | +| `border-bottom: 1px solid ...` | `border-bottom: var(--border-thin) solid ...` | +| `border-left: 1px solid ...` | `border-left: var(--border-thin) solid ...` | +| `border-right: 1px solid ...` | `border-right: var(--border-thin) solid ...` | +| `border-width: 1px` | `border-width: var(--border-thin)` | +| Same patterns for `2px` | Use `var(--border-medium)` | +| `border: 1px dashed ...` | `border: var(--border-thin) dashed ...` | +| `border: 1px dotted ...` | `border: var(--border-thin) dotted ...` | +| `border-*-width: 1px` | `border-*-width: var(--border-thin)` | +| Same patterns for `2px` | Use `var(--border-medium)` | +| Same patterns for `3px` | Use `var(--border-thick)` | + +### Files affected + +1. `SVS-MSP-Calculator-components.css` (~86 instances) +2. `SVS-MSP-Calculator-responsive.css` (~19 instances) +3. `SVS-MSP-Calculator-layout.css` (~12 instances) +4. `SVS-MSP-Calculator-print.css` (~7 instances) +5. `SVS-MSP-Calculator-base.css` (~2 instances) +6. `SVS-MSP-Calculator-glass.css` (~1 instance) + +### Global exclusions + +- `pre-alpha/` directory — archived reference, do not modify +- `1px` in `calc()` expressions — visual micro-adjustments +- `1px` in `box-shadow` offsets — shadow geometry, not borders +- `1px` in `outline` — separate concern +- `2px` in non-border contexts (e.g., `padding: 2px`) — that's spacing, not border width + +### Commit message + +`css: tokenize border widths — consolidate 1px/2px/3px to --border-thin/medium/thick` + +--- + +## Phase 2: Adopt Existing Spacing Tokens (~37 instances) + +### No new tokens — use what already exists + +| Hardcoded | Token | Count | +|-----------|-------|-------| +| `4px` (spacing) | `var(--space-xs)` | ~12 | +| `8px` (spacing) | `var(--space-sm)` | ~11 | +| `10px` (spacing) | `var(--space-stack-tight)` | ~5 | +| `12px` (spacing) | `var(--space-md)` | ~2 | +| `16px` (spacing) | `var(--space-stack-roomy)` | ~2 | +| `18px` (spacing) | `var(--space-lg)` | ~2 | +| `20px` (spacing) | `var(--space-xl)` | ~3 | + +### Replacement rules + +Only replace `margin`, `padding`, and `gap` properties. Do NOT replace: +- `border-radius` values (Phase 3) +- `font-size` values (out of scope) +- `width`/`height` values (out of scope) +- Values in `clamp()` or `calc()` expressions +- Intentional off-grid values (`5px`, `9px`, `7px`) — these are deliberate tweaks + +### Files affected + +1. `SVS-MSP-Calculator-components.css` (~30 instances) +2. `SVS-MSP-Calculator-layout.css` (~4 instances) +3. `SVS-MSP-Calculator-responsive.css` (~2 instances) +4. `SVS-MSP-Calculator-print.css` (~1 instance) + +### Commit message + +`css: adopt existing spacing tokens — replace hardcoded 4-20px with var(--space-*)` + +--- + +## Phase 3: Border-Radius Scale (~20 instances) + +### New tokens (add to `SVS-MSP-Calculator-tokens.css`) + +```css +--radius-sm: 4px; /* small corners: pills, badges, small buttons */ +--radius-md: 8px; /* medium corners: cards, modals, containers */ +--radius-lg: 10px; /* large corners: pill buttons, modal dialogs */ +--radius-pill: 999px; /* perfect pill shape */ +``` + +Existing tokens remain unchanged: +- `--radius-control: 6px` — input controls +- `--radius-card: 12px` — section cards + +### Replacement rules + +| Hardcoded | Token | Count | +|-----------|-------|-------| +| `border-radius: 4px` | `var(--radius-sm)` | ~12 | +| `border-radius: 8px` | `var(--radius-md)` | ~8 | +| `border-radius: 10px` | `var(--radius-lg)` | ~4 | +| `border-radius: 999px` | `var(--radius-pill)` | ~1 | + +### Exclusions + +- `border-radius` values inside `clamp()` or `calc()` +- Outlier values (`2px`, `3px`, `7px`) — keep as hardcoded, too unique to tokenize + +### Files affected + +1. `SVS-MSP-Calculator-components.css` (~18 instances) +2. `SVS-MSP-Calculator-responsive.css` (~2 instances) +3. `SVS-MSP-Calculator-base.css` (~1 instance) + +### Commit message + +`css: tokenize border-radius — consolidate to --radius-sm/md/lg/pill scale` + +--- + +## Verification (per phase) + +1. **Tests:** `node tests/test-quote-engine.js` — 254/254 must pass +2. **Visual:** Playwright screenshots at 1920px — Dark, Light, Glass themes +3. **Mobile:** Playwright at 375px — floating MRR pill, bottom sheet, sync +4. **Print:** Playwright print media emulation — no regressions +5. **Diff:** Pixel-compare screenshots before/after — changes should be zero (pure refactor) + +--- + +## Risk Assessment + +| Risk | Mitigation | +|------|------------| +| Accidental visual change | Playwright pixel-diff before/after each phase | +| Theme-specific breakage | Light/Glass only override colors/shadows, not border-widths or spacing — low risk | +| Mobile sync breakage | No DOM ID changes — zero risk | +| Print regression | Print CSS uses same tokens — verify with print emulation | +| Token name collision | Checked: no existing `--border-thin/medium/thick` or `--radius-sm/md/lg/pill` tokens | +| `!important` in theme overrides | Tokenizing `1px !important` in glass.css is valid CSS; border widths don't vary by theme so low risk | + +--- + +## Token Summary (final state after all 3 phases) + +### New tokens added to `SVS-MSP-Calculator-tokens.css` + +```css +/* Border widths */ +--border-thin: 1px; +--border-medium: 2px; +--border-thick: 3px; + +/* Border radius (additions to existing scale) */ +--radius-sm: 4px; +--radius-md: 8px; +--radius-lg: 10px; +--radius-pill: 999px; +``` + +### Existing tokens (no changes) + +```css +/* Spacing (already defined, now actually used) */ +--space-xs: 4px; +--space-sm: 8px; +--space-stack-tight: 10px; +--space-md: 12px; +--space-stack-roomy: 16px; +--space-lg: 18px; +--space-xl: 20px; + +/* Radius (already defined, unchanged) */ +--radius-control: 6px; +--radius-card: 12px; +```