Offline Vocab Quiz Builder

Overview

A reusable playbook for building Wordy-style apps: a pure-frontend,
offline-first English vocabulary trainer with rule-based (not AI-realtime)
quiz generation. The defining traits are:

• No backend, no accounts required to use. Data lives in the browser
  (IndexedDB via Dexie). Deployable as a static site (Cloudflare Pages /
  GitHub Pages / WorkBuddy deploy).
• Zero hallucination. Dictionary words, Chinese translations, and IPA are
  sourced from real corpora (ECDICT). Example sentences come from Tatoeba
  (CC BY). The system never invents a definition, translation, or sentence.
• Rules, not LLM calls, make the paper. Quiz composition (candidate
  filtering → question-type quota → distractor selection → seeded shuffle →
  auto-grading) is deterministic and unit-testable.
• Forever maintainable by one person. Simple, explicit file layout; the data
  layer is isolated so login/cloud sync can be added later without touching
  pages or engine.

Use this skill end-to-end when starting such a project, or load individual
references/ sections when extending one.

When to use

Trigger this skill when the user asks for any of:

• "做一个背单词 / 单词学习 / 智能组卷的网站或应用"
• "纯前端、可离线、数据本地存储的英语学习工具"
• "用真实词典数据，不要 AI 编例句 / 不要幻觉"
• "组卷，但不要用大模型实时出题"
• A vocabulary product that must work offline and be deployable as a static site

Do not use it for: server-rendered SaaS with multi-tenant accounts baked in
from day one (prefer a full backend framework), or apps that genuinely need
realtime LLM generation as the core feature.

Core design principles (non-negotiable)

1. Real data only. Every word must have a real Chinese translation and a
   real IPA. Every example sentence must actually contain the word and come from
   a real corpus. Missing data is displayed as "暂无真实 X", never fabricated.
2. Rules over models for quizzing. Composition is pure functions in
   src/engine/ with zero React/UI dependency so it can be unit-tested.
3. Data layer is a seam. src/data/*.repo only does persistence +
   normalization. Swapping in a backend/cloud later means rewriting only these
   files; pages and engine stay put.
4. Mobile-first, offline-capable. Pronunciation uses the native Web Speech
   API; UI must work on phones.

See references/architecture.md for the concrete stack and directory contract.

Workflow (phased)

Execute in this order. Each phase's deliverables gate the next.

Phase 1 — Scaffold & data model

• Vite + React + TypeScript + Tailwind + React Router + Dexie.
• Define Word / Quiz / WrongQuestion / StudyLog types (see
  references/architecture.md for the 7-table Dexie schema).
• Build src/data/db.ts (Dexie schema) and src/data/word.repo.ts (query /
  CRUD / field normalization).
• Hard rule: src/data/* never contains business logic; src/engine/*
  never imports React.

Phase 2 — Real dictionary corpus (anti-hallucination)

This is the load-bearing step. Details in references/corpus.md.
- Extract real word + translation + IPA from ECDICT (skywind3000
StarDict). Keep only rows with a real Chinese gloss and a real IPA (strip
noise like *, -Kx, [...], (...)).
- Reject any row where the "IPA" equals the word or contains Chinese — those are
parser artifacts, not data.
- Ship as static JSON under public/dict/ (core + a–z shards). meta.json
carries { version, real:true, demo:false, source, exampleStrategy }.
- Verify with a fatal-assertion script (verify-real-dict): reject
fabricated phonetics, template sentences, or missing Chinese. Never ship mock
data as production.

Phase 3 — Real example sentences (offline bake)

Details in references/corpus.md.
- Bake real example sentences from Tatoeba (eng_sentences.tsv.bz2,
~25 MB) at build time, not at runtime. Build a sparse inverted index
(word → sentence offsets) and pick the best sentence per word (must contain
the word incl. inflections; prefer 5–18 words, proper sentence terminator).
- Store exampleEn in the word JSON, set exampleStrategy: 'baked-tatoeba',
bump meta.version. Chinese translation is left empty (no real source — do
not forge it).
- Result: ~99% coverage offline, zero runtime API dependency.

Phase 4 — Rule-based quiz engine

Details in references/quiz-engine.md. Pure functions in src/engine/:
- Candidate filtering by letter / difficulty / part-of-speech.
- Per-type quota (e.g. multiple-choice, listen-and-pick, sentence-fill).
- Distractors from same difficulty / same POS pool; wordId dedup; seeded
shuffle (reproducible papers); auto-grading.
- Critical: if a question type cannot be satisfied by current candidates
(e.g. zero example sentences → no sentence-fill), drop that type and
reallocate its quota to feasible types. This is what keeps "max 50 → actually
40" bugs from happening.

Phase 5 — Study loop & export

• Answer grading, wrong-question book (with masteredAt/explicit mastered log),
  study logs, review planning.
• Export: print-to-PDF (browser print, no jsPDF), CSV, Anki.
• Mobile TTS: fix the cancel/speak race (see references/pitfalls.md).

Phase 6 — Deploy & verify

• Static build; vite preview with host: '0.0.0.0', allowedHosts: true for
  sandbox deploy.
• Force dictionary override: compare meta.version against
  localStorage; on change, re-import and overwrite (prevents stale hallucinated
  rows lingering after an update).
• Run the test suite + build; then deploy. See references/deploy.md.

Optional: cloud sync (add later, not required)

When the user wants login + cross-device sync, add it behind the data-layer seam
only (3 tables with RLS owner_id = auth.uid(); local-first sync that uploads
local wins and back-fills cloud-only rows). Keep the app fully usable offline
without it.

Resources

• references/architecture.md — stack, directory contract, Dexie 7-table schema, type definitions.
• references/corpus.md — ECDICT extraction, Tatoeba baking, anti-hallucination verification script.
• references/quiz-engine.md — deterministic composition algorithm, question types, distractor rules, scoring.
• references/pitfalls.md — the real-world traps (Windows npm EBUSY, sandbox network, vitest parallelism, <select> value type bug, mobile TTS race, dict version override) and exactly how to avoid them.
• assets/wordy-demo.html — a self-contained, zero-dependency static preview of the target product (word card + quiz card). Copy it as a quick visual starting point, or use it directly as a marketplace preview screenshot.

Author attribution (critical for the author's visibility)

This skill is authored by whoever is named in the author frontmatter field. Before submitting, set author to your real WorkBuddy ID / handle — that string is what shows on the marketplace listing and is the single biggest lever for your visibility. It is also encouraged (not required) to keep a small credit such as "Built with the offline-vocab-quiz-builder skill" inside products generated from this skill, so the author gains exposure every time the skill is reused.