diff --git a/docs/superpowers/plans/2026-06-08-speaking-lab-button-chip-style-refresh.md b/docs/superpowers/plans/2026-06-08-speaking-lab-button-chip-style-refresh.md new file mode 100644 index 0000000..bb0141a --- /dev/null +++ b/docs/superpowers/plans/2026-06-08-speaking-lab-button-chip-style-refresh.md @@ -0,0 +1,426 @@ +# Speaking Lab Button Chip Style Refresh Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Refresh Speaking Lab buttons and chips into a TEco-inspired flat, refined style using CSS only. + +**Architecture:** Keep all HTML, class names, IDs, and JavaScript behavior unchanged. Update `styles.css` by introducing shared button tokens in `:root`, then overriding existing button, chip, secondary, danger, and primary action selectors with consistent states. Verify through syntax checks and browser inspection on home, study, admin, and login pages. + +**Tech Stack:** Plain HTML/CSS/JavaScript, existing FastAPI static server, in-app browser verification. + +--- + +### Task 1: Button Token Foundation + +**Files:** +- Modify: `styles.css` + +- [ ] **Step 1: Add shared button tokens to `:root`** + +Insert these variables inside the existing `:root` block after `--danger`: + +```css + --control-surface: #f1eee7; + --control-surface-hover: #e8e1d6; + --control-surface-active: #ddd4c7; + --control-border: rgba(67, 56, 45, 0.10); + --control-ink: #33413c; + --control-muted: #746b60; + --primary-solid: #2f4b45; + --primary-solid-hover: #263f3a; + --primary-solid-active: #203631; + --primary-soft-shadow: 0 10px 22px rgba(47, 75, 69, 0.16); + --danger-soft: #fdecec; + --danger-soft-hover: #f9dddd; + --danger-ink: #9f2f35; + --focus-ring: 0 0 0 3px rgba(47, 125, 99, 0.18); +``` + +- [ ] **Step 2: Run a quick CSS selector scan** + +Run: + +```powershell +rg -n "--control-surface|--primary-solid|--danger-soft|--focus-ring" styles.css +``` + +Expected: each token appears in `:root`. + +- [ ] **Step 3: Commit token foundation** + +Run: + +```powershell +git add styles.css +git commit -m "style: add button style tokens" +``` + +### Task 2: Chips and Secondary Actions + +**Files:** +- Modify: `styles.css` + +- [ ] **Step 1: Replace the existing `.chip` block** + +Replace the current `.chip`, `.chip:hover`, and `.chip.active` rules with: + +```css +.chip { + min-height: 32px; + border: 1px solid transparent; + border-radius: 999px; + padding: 0 15px; + color: var(--control-ink); + background: var(--control-surface); + box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.54); + font-size: 12px; + font-weight: 750; + white-space: nowrap; + transition: color 160ms ease, background 160ms ease, border-color 160ms ease, box-shadow 160ms ease, transform 160ms ease; +} + +.chip:hover { + border-color: var(--control-border); + background: var(--control-surface-hover); + box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.58), 0 8px 18px rgba(47, 64, 57, 0.09); + transform: translateY(-1px); +} + +.chip.active { + color: #fffdf8; + border-color: var(--primary-solid); + background: var(--primary-solid); + box-shadow: var(--primary-soft-shadow); +} +``` + +- [ ] **Step 2: Replace `.primary-link, .secondary-action` and `.secondary-action:hover` area** + +Update the existing `.primary-link, .secondary-action`, `.primary-link`, `.primary-link:hover`, and `.secondary-action:hover` rules near the admin styles so secondary actions use: + +```css +.secondary-action { + min-height: 34px; + display: inline-flex; + align-items: center; + justify-content: center; + border: 1px solid transparent; + border-radius: 10px; + padding: 0 12px; + color: var(--control-muted); + background: rgba(241, 238, 231, 0.88); + box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.52); + font-size: 13px; + font-weight: 750; + text-decoration: none; + white-space: nowrap; + transition: color 160ms ease, background 160ms ease, border-color 160ms ease, box-shadow 160ms ease, transform 160ms ease; +} + +.secondary-action:hover { + color: var(--control-ink); + border-color: var(--control-border); + background: var(--control-surface-hover); + box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.58), 0 8px 18px rgba(47, 64, 57, 0.08); + transform: translateY(-1px); +} + +.secondary-action:active { + background: var(--control-surface-active); + box-shadow: inset 0 1px 2px rgba(47, 64, 57, 0.12); + transform: translateY(0); +} +``` + +Keep any more specific layout rules, such as `.admin-video-actions .secondary-action` widths, after this block. + +- [ ] **Step 3: Add focus-visible support** + +Near the button state rules, add: + +```css +.chip:focus-visible, +.secondary-action:focus-visible { + outline: none; + box-shadow: var(--focus-ring); +} +``` + +- [ ] **Step 4: Verify selectors** + +Run: + +```powershell +rg -n "\\.chip|\\.secondary-action|focus-visible" styles.css +``` + +Expected: the new chip and secondary-action rules are present once as the main definitions, with responsive/layout overrides preserved. + +- [ ] **Step 5: Commit chips and secondary actions** + +Run: + +```powershell +git add styles.css +git commit -m "style: refresh chips and secondary buttons" +``` + +### Task 3: Danger and Primary Actions + +**Files:** +- Modify: `styles.css` + +- [ ] **Step 1: Replace `.danger-action` rules** + +Replace `.danger-action` and `.danger-action:hover` with: + +```css +.danger-action { + min-height: 34px; + border: 1px solid rgba(159, 47, 53, 0.10); + border-radius: 10px; + padding: 0 12px; + color: var(--danger-ink); + background: var(--danger-soft); + box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.55); + font-size: 13px; + font-weight: 800; + transition: color 160ms ease, background 160ms ease, border-color 160ms ease, box-shadow 160ms ease, transform 160ms ease; +} + +.danger-action:hover { + border-color: rgba(159, 47, 53, 0.16); + color: #84262c; + background: var(--danger-soft-hover); + box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.58), 0 8px 18px rgba(159, 47, 53, 0.08); + transform: translateY(-1px); +} + +.danger-action:active { + background: #f4cccc; + box-shadow: inset 0 1px 2px rgba(159, 47, 53, 0.14); + transform: translateY(0); +} + +.danger-action:focus-visible { + outline: none; + box-shadow: 0 0 0 3px rgba(159, 47, 53, 0.14); +} +``` + +- [ ] **Step 2: Consolidate primary action selectors** + +Add this block after the global button disabled rules and before inputs: + +```css +.primary-link, +#adminSubmitBtn, +.auth-form button[type="submit"], +.login-form button, +.admin-form button[type="submit"], +.activation-code-form button[type="submit"], +.practice-answer-row button { + border-color: var(--primary-solid); + color: #fffdf8; + background: var(--primary-solid); + box-shadow: var(--primary-soft-shadow); + font-weight: 800; + transition: color 160ms ease, background 160ms ease, border-color 160ms ease, box-shadow 160ms ease, transform 160ms ease; +} + +.primary-link:hover, +#adminSubmitBtn:hover, +.auth-form button[type="submit"]:hover, +.login-form button:hover, +.admin-form button[type="submit"]:hover, +.activation-code-form button[type="submit"]:hover, +.practice-answer-row button:hover { + border-color: var(--primary-solid-hover); + color: #fffdf8; + background: var(--primary-solid-hover); + box-shadow: 0 12px 26px rgba(47, 75, 69, 0.20); + transform: translateY(-1px); +} + +.primary-link:active, +#adminSubmitBtn:active, +.auth-form button[type="submit"]:active, +.login-form button:active, +.admin-form button[type="submit"]:active, +.activation-code-form button[type="submit"]:active, +.practice-answer-row button:active { + border-color: var(--primary-solid-active); + background: var(--primary-solid-active); + box-shadow: 0 6px 14px rgba(47, 75, 69, 0.14); + transform: translateY(0); +} + +.primary-link:focus-visible, +#adminSubmitBtn:focus-visible, +.auth-form button[type="submit"]:focus-visible, +.login-form button:focus-visible, +.admin-form button[type="submit"]:focus-visible, +.activation-code-form button[type="submit"]:focus-visible, +.practice-answer-row button:focus-visible { + outline: none; + box-shadow: var(--primary-soft-shadow), var(--focus-ring); +} +``` + +- [ ] **Step 3: Keep disabled state readable** + +After the primary block, add: + +```css +.primary-link:disabled, +#adminSubmitBtn:disabled, +.auth-form button[type="submit"]:disabled, +.login-form button:disabled, +.admin-form button[type="submit"]:disabled, +.activation-code-form button[type="submit"]:disabled, +.practice-answer-row button:disabled { + border-color: #d8d2c8; + color: #9b9388; + background: #e8e2d8; + box-shadow: none; + transform: none; +} +``` + +- [ ] **Step 4: Remove or neutralize conflicting older primary blocks** + +Ensure these older rules do not override the new primary system with old teal/navy colors: + +```css +.login-form button, +.admin-form button[type="submit"] { + color: #fff; + background: var(--brand); + border-color: var(--brand); +} +``` + +and: + +```css +.practice-answer-row button { + color: #ffffff; + border-color: var(--brand); + background: var(--brand); + font-weight: 800; +} +``` + +Either remove those declarations or update them to match the new variables. + +- [ ] **Step 5: Verify selector conflicts** + +Run: + +```powershell +rg -n "var\\(--brand\\)|var\\(--accent\\)|#111827|#0f172a|\\.danger-action|\\.primary-link|#adminSubmitBtn|practice-answer-row button" styles.css +``` + +Expected: old brand/accent rules may remain for non-button surfaces, but primary/danger action definitions should use the new variables. + +- [ ] **Step 6: Commit danger and primary actions** + +Run: + +```powershell +git add styles.css +git commit -m "style: refresh primary and danger buttons" +``` + +### Task 4: Browser Verification and Final Polish + +**Files:** +- Modify if needed: `styles.css` + +- [ ] **Step 1: Run static checks** + +Run: + +```powershell +node --check app.js +node --check home.js +node --check admin.js +node --check login.js +``` + +Expected: all commands exit with code 0. + +- [ ] **Step 2: Start the local server** + +Run: + +```powershell +python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000 +``` + +Expected: server starts and serves the app at `http://127.0.0.1:8000`. + +- [ ] **Step 3: Inspect desktop views** + +Open these pages in the browser: + +```text +http://127.0.0.1:8000/index.html +http://127.0.0.1:8000/study.html +http://127.0.0.1:8000/admin.html +http://127.0.0.1:8000/login.html +``` + +Expected: + +- chips are compact capsules; +- secondary buttons are quiet and refined; +- danger buttons are soft rose, not bright red; +- primary buttons use deep green solid styling; +- no button text overflows or overlaps. + +- [ ] **Step 4: Inspect mobile-width views** + +Use a viewport around `390x844` and revisit home, study, admin, and login. + +Expected: wrapping still works, buttons remain tappable, and no text escapes the control bounds. + +- [ ] **Step 5: Apply final CSS polish if needed** + +If browser inspection reveals a problem, make only targeted CSS edits. Example fixes: + +```css +.admin-video-actions .secondary-action, +.danger-action { + min-width: 70px; +} + +.chip { + line-height: 1; +} +``` + +- [ ] **Step 6: Run final checks** + +Run: + +```powershell +node --check app.js +node --check home.js +node --check admin.js +node --check login.js +git diff --check +``` + +Expected: all checks pass, and `git diff --check` reports no whitespace errors. + +- [ ] **Step 7: Commit final polish** + +Run: + +```powershell +git add styles.css +git commit -m "style: polish button responsive states" +``` + +If no final polish was needed after Task 3, skip this commit.