# SVS MSP CALC — STAGE 10: UI & THEME POLISH
# Generated: 2026-03-15

---

## WHERE WE ARE

**Stages 1–9: COMPLETE.** Beta build is production-quality for Sections I–III.
**Tests:** 254/254 passing.
**Spacing tokens:** Consolidated (150+ magic numbers → CSS custom properties).
**Retro theme visual QA:** Passed at all viewports (375/1100/1400/2500/2800px).
**Pricing:** Single source in `package-prices-data.js`, addon labels sync dynamically.

---

## STAGE 10 FOCUS: UI / THEME / COLOR CONSISTENCY

This stage is about visual polish, color consistency, and interface usability across all 4 themes.

### Known Issues to Investigate
- **Too many similar-but-slightly-off colors** within individual themes — need audit and consolidation
- **Color consistency per theme** — some elements use raw hex where they should use tokens
- **Usability polish** — any controls, labels, or interactions that could feel tighter or more intuitive
- **Cross-theme consistency** — ensure the same UI elements feel equivalent across Dark/Light/Glass/Retro

### Approach

1. **Color Audit** — For each theme, extract all unique colors actually used. Group by purpose (text, surface, border, accent). Flag duplicates that are close but not identical (e.g., two slightly different grays serving the same role).

2. **Token Consolidation** — Where colors are inconsistent, consolidate to existing tokens or define new ones. Goal: fewer unique colors, each with a clear semantic role.

3. **Per-Theme Walkthrough** — User provides screenshots. AI audits for:
   - Color contrast issues (text readability)
   - Inconsistent element styling across themes
   - Visual weight imbalances
   - Elements that "don't belong" visually

4. **Surgical Fixes** — Each fix is small, tested, and verified across all 4 themes.

---

## SESSION WORKFLOW

1. **Start with a color audit** — Use Explore agent to scan all theme CSS files for unique color values, group by semantic role
2. **User provides screenshots** of specific areas that feel "off"
3. **AI proposes fixes** with before/after reasoning
4. **Apply fixes surgically** — one logical change at a time
5. **User verifies visually** — confirms or adjusts
6. **Run tests** after any render/engine changes

---

## HARD CONSTRAINTS

1. DOM IDs are a contract — renaming breaks mobile sync (100+ pairs)
2. 254 tests must pass: `node svsmspcalc/tests/test-quote-engine.js`
3. All 4 themes must work after every change
4. No frameworks, no npm — vanilla only
5. Surgical changes only — read before editing
6. Sections IV–VI are placeholders — do not activate

---

## THEME FILES

| Theme | File | Base |
|-------|------|------|
| Dark (default) | `SVS-MSP-Calculator-tokens.css` | All colors defined here |
| Light | `SVS-MSP-Calculator-light.css` | Overrides dark tokens |
| Glass | `SVS-MSP-Calculator-glass.css` | Glassmorphism overrides |
| Retro | `SVS-MSP-Calculator-70retro.css` | Cyberpunk overrides |

---

## VERIFICATION

```
node svsmspcalc/tests/test-quote-engine.js
```

254 tests, zero dependencies. Run after any pricing/engine/render changes.

---

## CONTEXT MANAGEMENT

After completing work:
- Update `docs/CHECKPOINT.md` with results
- If context is heavy, create `docs/STAGE11-SESSION-PROMPT.md` for the next chat
