svsmspcalc/docs/SESSION-HANDOFF.md

Session Handoff — SVS MSP CALC

Last updated: 2026-03-16 Session: Spacing Token Consolidation + Docs Cleanup + Phase 4-6 Research Status: COMMITTED — token consolidation + docs cleanup merged. Phase 4-6 research complete, design not started. Tests: 254/254 passing

What Was Done This Session

Spacing Token Consolidation (Phases 1-3) — COMMITTED

Commit 786a850: css: tokenize borders, spacing, and radii — spacing audit pass 4

• Phase 1: border widths (76 replacements), Phase 2: spacing tokens (18), Phase 3: border-radius (16)
• 110 replacements + 7 new tokens across 7 CSS files
• Playwright verified: 9 screenshots (3 themes x 3 viewports) — zero regressions

Docs Cleanup — COMMITTED

Commit a42ce66: removed 11 outdated files (1,480 lines)

• 8 STAGE*-SESSION-PROMPT.md files, ai-session-brief.md, code-verification.md, phase-roadmap.md
• Updated QUICK-REF.md directory listing

Phase 4-6 Research — NOT COMMITTED (findings below)

Deep exploration of remaining token consolidation + sidebar UX issues. Ready to brainstorm into design.

Research Findings: Remaining Token Consolidation (Phases 4-6)

Phase 4: Icon/Button Sizing (~12 locations)

Hardcoded icon/button sizes scattered across components.css:

• 14px (export icon), 15px (sidebar icon), 16px (nudge nav), 18px (addon checkbox)
• 20px (HST toggle), 22px (M365 icon), 28px (mobile pill), 34px (chevron/toggle buttons)
• Missing tokens: --icon-size-xs through --icon-size-xl, --control-icon-size

Phase 5: Typography Scale (~36 locations)

Letter-spacing (26+ occurrences, no tokens):

• 0.02em (price values), 0.04em (meta labels), 0.06em (waive labels)
• 0.07em (badges/floor notes), 0.08em (buttons/badges), 0.1em (section titles)
• 0.12em (labels/headings), 0.14em (nav), 0.18em (uppercase kickers), -0.02em (MRR hero)
• Missing tokens: --text-spacing-tight/compact/normal/loose etc.

Font-size (hardcoded, not using tokens):

• 8px (best value badge), 10px (mobile pill label), 12px (various labels)
• 13px (sublabels), 14px (addon name, fee table), 15px (section meta)
• 16px (input label), 18px (sidebar hero responsive), 20px (modal icon)

Sidebar typography tokens defined in components.css (should be in tokens.css):

• --sidebar-copy-size, --sidebar-copy-line, --sidebar-note-size, --sidebar-mono-size, --sidebar-mrr-size (components.css lines 1019-1023)

Phase 6: Responsive Breakpoints (optional)

Hardcoded responsive font-sizes in @media rules:

• 1.375rem, 1.125rem, 1.1rem (mobile text), 2.25rem/1.875rem (sidebar MRR at breakpoints)
• Could benefit from --text-size-responsive-* tokens

Research Findings: Sidebar UX Issues

Divider/Line Inconsistency Across Themes

Sidebar divider tokens exist but values differ per theme:

• Dark: color-mix(in srgb, var(--border) 88%, transparent) — dashed
• Light: color-mix(in srgb, var(--border) 70%, transparent) — lighter
• Glass: rgba(143, 183, 221, 0.12) — very light
• Risk: Extra/mismatched horizontal lines visible on some themes. Needs Playwright visual audit.

Price Value Letter-Spacing

• Current: letter-spacing: 0.02em on .sidebar-line .val (components.css ~line 1211)
• User feedback: prices ($x.xx) look "bunched" — needs more breathing room
• font-variant-numeric: tabular-nums IS applied globally (good)
• Consider bumping to 0.04em-0.06em and tokenizing as --text-spacing-money

Sidebar Line Variants

Element	Style	Notes
.sidebar-line	dashed bottom border	Uses --sidebar-line-rule-style
.sidebar-line-opportunity	dotted	No token for line-style
.sidebar-line-discount	dashed, opacity 0.8	Hardcoded opacity
.sidebar-line-hst	double top border	Uses token
.sidebar-line-total	solid top border	Uses --sidebar-total-rule (good)

Files Modified (this session)

File	Change
7 CSS files	Token consolidation (committed)
11 docs files	Deleted (committed)
docs/QUICK-REF.md	Updated directory listing (committed)
docs/SESSION-HANDOFF.md	Updated (committed)

Test Status

254/254 tests passing
node tests/test-quote-engine.js

What's Next

Priority 1 (next session): Sidebar UX fine-tune + Phase 4-6 token consolidation

• Brainstorm into design (was about to start — visual companion offered, user paused)
• Use superpowers:brainstorming → design spec → superpowers:writing-plans
• Dispatch UI/UX designer (Opus + ui-ux-pro-max) for sidebar line/spacing decisions
• Use Playwright MCP for visual comparison across themes

Priority 2: Sections IV-VI activation Priority 3: Mobile panel UX enhancements Priority 4: Beta readiness audit

Continuation Prompt

Read docs/SESSION-HANDOFF.md then docs/QUICK-REF.md.
3 themes: Dark, Light, Glass.
254 tests must pass: node tests/test-quote-engine.js

## Resume Point: Sidebar UX Fine-Tune + Token Consolidation (Phases 4-6)

Research is DONE (see SESSION-HANDOFF.md "Research Findings" sections).
Design has NOT started yet. Pick up at brainstorming.

### Two workstreams to combine into one design:

**1. Sidebar UX fine-tune (user-reported issues):**
- Extra horizontal lines in sidebar that don't match across Dark/Light/Glass themes
- Price values ($x.xx) look "bunched" — need more letter-spacing
- Divider opacity/color differs per theme (Dark 88%, Light 70%, Glass 12% rgba)
- Use Playwright MCP to screenshot sidebar across all 3 themes for visual comparison
- Dispatch UI/UX designer (Opus + ui-ux-pro-max skill) for design decisions

**2. Token consolidation Phases 4-6:**
- Phase 4: icon/button sizing (~12 hardcoded values → --icon-size-* tokens)
- Phase 5: typography scale (~36 locations — letter-spacing + font-size + move sidebar tokens to tokens.css)
- Phase 6: responsive breakpoints (optional — hardcoded rem values in @media)

### Action: Start with superpowers:brainstorming
- Project context: ALREADY EXPLORED (skip step 1 of brainstorming checklist)
- Offer visual companion (Playwright) — user was offered, hadn't accepted yet
- Then clarifying questions → approaches → design → spec → plan

## Key References
- Token file: SVS-MSP-Calculator-tokens.css
- Sidebar styles: SVS-MSP-Calculator-components.css (lines 1019-1023 sidebar tokens, 1183-1250 sidebar lines)
- Theme overrides: SVS-MSP-Calculator-light.css (lines 122-123), SVS-MSP-Calculator-glass.css (lines 194-195)

## Plugins Available — USE THEM
- **superpowers** — planning, subagent-driven development, parallel agents, TDD, debugging
- **ui-ux-pro-max** — design intelligence (palettes, typography, styles)
- **playwright** — visual verification in real browser
- **frontend-design**, **code-review**, **code-simplifier**

 ## Clear up DOCS folder
 - clean up docs, remove old phases no longer under considertation, old instructions that no longer apply

Budget: stay under 60% context. Checkpoint before ending.