Files
speaking-practice/docs/superpowers/specs/2026-06-02-speaking-lab-home-page-design.md
T
2026-06-03 00:34:42 +08:00

5.5 KiB

Speaking Lab Home Page v1 Design

Goal

Add a dedicated home page for browsing learning materials, so http://127.0.0.1:8000/ feels like a shareable product entry instead of opening directly inside the study workspace.

Current Context

Speaking Lab currently has:

  • index.html: the study page.
  • app.js: study-page logic for loading videos, search, tags, subtitles, recording, favorites, watch-later, and learning progress.
  • admin.html and admin.js: admin material management.
  • /api/videos: returns material metadata, tags, video URLs, subtitles, and source type.
  • Local user state in localStorage.

The current left-side material rail is useful inside the study page, but it is too narrow to work as the product home page.

Scope

Home Page v1 includes:

  • Make / open the new home page.
  • Move the current study experience to study.html.
  • Add home.html and home.js.
  • Home page supports searching materials.
  • Home page supports category filtering from material tags.
  • Home page shows material cards in a responsive grid.
  • Cards show an automatic preview cover when no real thumbnail exists.
  • Cards show title, speaker/source, tags, subtitle languages, and learning progress.
  • Clicking a card opens study.html?video=<id>.
  • The study page reads ?video=<id> and opens that material first.
  • Admin entry remains available for admin users.

Home Page v1 excludes:

  • Uploading custom thumbnails.
  • Automatically extracting thumbnails from video files.
  • Pagination.
  • Advanced sorting.
  • Multi-level category management.
  • Backend search endpoints.
  • Server-side user authentication.

Page Routing

Routes after this feature:

/

Shows the new home page.

/study.html

Shows the current learning workspace.

/study.html?video=<id>

Opens the learning workspace and selects the requested material.

/admin.html

Shows the existing admin page.

Home Page Layout

The home page uses a product-library layout:

  • Top bar:
    • Speaking Lab
    • Search input
    • Login/register or current user
    • Admin link shown only for admin users
  • Category row:
    • 全部
    • One chip per tag from loaded materials
  • Main content:
    • Responsive grid of material cards
    • Empty state when no materials match

The home page should be practical and product-like, not a marketing landing page. It should prioritize finding and opening materials.

Material Card

Each card displays:

  • Preview cover area.
  • Title.
  • Speaker/source.
  • Tags.
  • Subtitle language summary, for example 英文 / 中文.
  • Learning progress summary, for example 已练 2/15 · 13% or 看到 02:04.

Clicking anywhere on a card opens:

study.html?video=<id>

Preview Cover Strategy

Home Page v1 uses generated CSS preview covers instead of real video thumbnails.

Reason:

  • Local and remote videos may not be safe or easy to screenshot in the browser.
  • Cross-origin video URLs may block frame extraction.
  • A generated cover is reliable and fast for the prototype.

Generated cover contents:

  • Large short title or initials.
  • First tag as a category badge.
  • Subtle color variant based on material ID.

Future extension:

  • Add a backend thumbnail_url field.
  • Allow admin upload of cover images.
  • Show real thumbnail when available, generated cover as fallback.

Search And Category Behavior

Search matches:

  • Title.
  • Speaker/source.
  • Description.
  • Tags.

Category filtering:

  • 全部 shows all materials.
  • Clicking a tag chip filters cards whose tags include that tag.
  • Search and category filters combine.

Study Page Behavior

The current study page becomes study.html.

Changes:

  • It keeps existing playback, subtitles, recording, progress, favorites, and admin entry behavior.
  • On load, it checks URLSearchParams for video.
  • If the requested video exists, it selects that video.
  • If the requested video does not exist, it falls back to existing active-video behavior.

The study page may keep the left material rail for quick switching during learning.

State And Data

Home page uses:

  • GET /api/videos for materials.
  • The same speaking-lab-state-v1 localStorage key for users and progress.

No new database table is required.

No backend API change is required for Home Page v1.

Error Handling

If /api/videos fails:

  • Show a clear local error state.
  • Home page may show demo/sample materials only if the study page already uses those as fallback.

If no materials exist:

  • Show an empty state that points admin users to admin.html.
  • Non-admin users see a simple “暂无素材” state.

If study.html?video=<id> references a missing material:

  • Select the first available material.
  • Do not crash.

Testing

Automated checks:

  • node --check home.js
  • node --check app.js
  • Existing helper tests still pass.

Manual/browser verification:

  1. Open http://127.0.0.1:8000/.
  2. Confirm the home page appears, not the study workspace.
  3. Confirm materials render as cards.
  4. Confirm search filters by title/source/tag.
  5. Confirm category chips filter cards.
  6. Confirm each card has a generated preview cover.
  7. Click a card.
  8. Confirm study.html?video=<id> opens and selects that material.
  9. Confirm admin.html still works.
  10. Confirm logged-in admin users can see an admin entry on the home page.

Future Extensions

Good follow-up features:

  • Upload custom thumbnail in admin page.
  • Add 我的学习 section on the home page.
  • Add sorting by recently studied, newest, or most practiced.
  • Add collections or curated playlists.
  • Move search/filter to backend when the library becomes large.