Files
speaking-practice/docs/superpowers/plans/2026-06-02-speaking-lab-focused-learning-ui.md
T
2026-06-03 00:34:42 +08:00

6.5 KiB

Speaking Lab Focused Learning UI 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: Apply a clean English-learning UI direction with icon-led dashboard cards and a more focused study workspace.

Architecture: Keep the upgrade frontend-only. home.js adds icon metadata for metric cards, while styles.css changes visual treatment for the home dashboard, material cards, study video panel, subtitle prompt, toolbar, and transcript states. No backend, README, or data-model changes are required.

Tech Stack: Vanilla JavaScript, CSS, HTML, existing FastAPI server for browser verification.


Task 1: Add Metric Icon Metadata

Files:

  • Modify: F:\ooo\speaking-practice-local\home.js

  • Step 1: Update getMetricItems(metrics)

Replace each metric object with an icon and tone:

function getMetricItems(metrics) {
  return [
    { key: "all", label: "当前素材", value: metrics.total, hint: "持续更新中", icon: "::", tone: "blue" },
    { key: "studied", label: "已学习", value: metrics.studied, hint: "我的打卡", icon: "✓", tone: "green" },
    { key: "unstudied", label: "未学习", value: metrics.unstudied, hint: "未完成", icon: "○", tone: "slate" },
    { key: "favorites", label: "已收藏", value: metrics.favorites, hint: "收藏的视频", icon: "♡", tone: "rose" },
    { key: "difficult", label: "难句素材", value: metrics.difficult, hint: "重点复习", icon: "!", tone: "amber" },
  ];
}
  • Step 2: Update metric button markup in renderDashboard()

Use:

button.className = `home-metric tone-${item.tone}${activeStatus === item.key ? " active" : ""}`;
button.dataset.status = item.key;
button.innerHTML = `
  <span class="home-metric-icon" aria-hidden="true">${item.icon}</span>
  <span class="home-metric-copy">
    <span class="home-metric-label">${item.label}</span>
    <small>${item.hint}</small>
  </span>
  <strong>${item.value}</strong>
`;
  • Step 3: Run syntax check

Run:

node --check home.js

Expected: no output.

Task 2: Polish Home Dashboard And Cards

Files:

  • Modify: F:\ooo\speaking-practice-local\styles.css

  • Step 1: Update root colors

Use a calm learning palette:

:root {
  color-scheme: light;
  --bg: #f4f7fb;
  --panel: #ffffff;
  --panel-soft: #f7fafc;
  --ink: #172033;
  --muted: #667085;
  --line: #dfe6ef;
  --accent: #0f2742;
  --brand: #0f766e;
  --brand-soft: #e4f5f1;
  --gold: #c98a12;
  --danger: #b42318;
  --shadow: 0 12px 30px rgba(25, 37, 59, 0.08);
}
  • Step 2: Replace metric card CSS

Update .home-metric and related selectors to icon-card layout:

.home-metric {
  min-height: 76px;
  display: grid;
  grid-template-columns: 38px minmax(0, 1fr) auto;
  align-items: center;
  gap: 10px;
  padding: 12px;
  text-align: left;
  border-radius: 8px;
  background: var(--panel);
  box-shadow: var(--shadow);
}

.home-metric-icon {
  width: 34px;
  height: 34px;
  display: grid;
  place-items: center;
  border-radius: 10px;
  font-weight: 900;
}

.home-metric-copy,
.home-metric-label {
  display: block;
  min-width: 0;
}

.home-metric-label {
  font-weight: 800;
}

.home-metric small {
  color: var(--muted);
  font-size: 12px;
}

.home-metric strong {
  font-size: 24px;
  line-height: 1;
  font-variant-numeric: tabular-nums;
}

.home-metric.tone-blue .home-metric-icon {
  color: #087ea4;
  background: #e6f7fb;
}

.home-metric.tone-green .home-metric-icon {
  color: #047857;
  background: #e9f9f0;
}

.home-metric.tone-slate .home-metric-icon {
  color: #475467;
  background: #eef2f7;
}

.home-metric.tone-rose .home-metric-icon {
  color: #be123c;
  background: #fff1f4;
}

.home-metric.tone-amber .home-metric-icon {
  color: #9a5c00;
  background: #fff7df;
}

.home-metric.active {
  border-color: #b9dcd5;
  background: #f0fbf8;
}
  • Step 3: Lighten card covers

Update cover gradients to avoid heavy admin feel:

.home-cover.tone-1 { background: linear-gradient(135deg, #0f766e, #1d6f8f); }
.home-cover.tone-2 { background: linear-gradient(135deg, #2563eb, #0f766e); }
.home-cover.tone-3 { background: linear-gradient(135deg, #475569, #2563eb); }
.home-cover.tone-4 { background: linear-gradient(135deg, #9a5c00, #be6b21); }
.home-cover.tone-5 { background: linear-gradient(135deg, #334155, #0f766e); }

Task 3: Polish Study Workspace

Files:

  • Modify: F:\ooo\speaking-practice-local\styles.css

  • Step 1: Add focused study styling

Update existing study selectors:

.video-panel,
.transcript-panel,
.lesson-rail {
  border-color: #dce5ee;
}

.video-frame {
  background: #0b1220;
}

.tool-row {
  background: #ffffff;
}

.tool-row button {
  border-color: #d8e2ec;
  background: #f8fafc;
  font-weight: 650;
}

.tool-row button:hover {
  border-color: #b9dcd5;
  background: var(--brand-soft);
}

.subtitle-card {
  min-height: 116px;
  padding: 18px 28px;
  background: #f8fbfb;
}

#primarySubtitle {
  font-size: 22px;
  letter-spacing: 0;
}

#secondarySubtitle {
  color: #667085;
  font-size: 15px;
}

.line-button {
  border-radius: 8px;
}

.line-button.active {
  background: #f4fbf9;
  border-color: #b9dcd5;
  box-shadow: inset 4px 0 0 var(--brand);
}

.line-button.is-practiced {
  background: #f7fdf9;
}

.line-button.is-difficult {
  background: #fffaf0;
}
  • Step 2: Confirm mobile styles still exist

Run:

rg -n "@media \\(max-width: 860px\\)|@media \\(max-width: 720px\\)" styles.css

Expected: both media blocks still exist.

Task 4: Verify

Files:

  • Verify: F:\ooo\speaking-practice-local\home.js

  • Verify: F:\ooo\speaking-practice-local\app.js

  • Verify: F:\ooo\speaking-practice-local\admin.js

  • Verify: F:\ooo\speaking-practice-local\styles.css

  • Step 1: Run automated checks

Run:

node --check home.js
node --check app.js
node --check admin.js
python -m py_compile backend\main.py backend\db.py
node tests\progress-helpers.test.mjs
node tests\admin-file-input.test.mjs

Expected: all pass.

  • Step 2: Browser check home page

Open:

http://127.0.0.1:8000/

Confirm metric cards show icons and still filter.

  • Step 3: Browser check study page

Open:

http://127.0.0.1:8000/study.html

Confirm subtitle prompt, toolbar, and transcript feel more like a learning workspace and no text overlaps.