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