Textbooks are mid. Master the bridge from HSK 4 to real-world talk.
The perfect fusion of academic precision and colloquial soul.
In traditional Chinese learning, there has always been a disconnect.
- The Red: Represents the formal, structured HSK curriculum—essential for exams but often sounding "robotic" in real life.
- The Gold: Represents the colloquial, native rhythm—the way people actually talk in the streets of Beijing or Shanghai.
RedGold bridges this gap. We transform the HSK 4 Standard Course into a premium, interactive experience that teaches you not just what to say, but how to say it like a native.
Our intelligent Scroll Engine in the TextSection component provides a seamless reading experience.
- Forward-Only Logic: The viewport only moves forward with the audio, preventing distracting "snaps" back to previous lines.
- Timing Heuristics: Calculates line changes based on character weight and audio duration for frame-perfect synchronization.
Unlike standard HSK tools, RedGold explicitly identifies and styles Proper Nouns — names, places, brands — with pinyin AND English meaning right there, no lookup needed. Styled in the signature Modern Han Elegant gold theme.
Zero-latency transitions. The app predicts your learning path and pre-warms audio assets and lesson data as you browse, ensuring the next chapter is ready before you even click.
A premium "glassmorphic" interface designed for focus:
- Responsive Layout: Tailored for high-aspect-ratio mobile displays (Galaxy S26 / iPhone Pro Max).
- Sticky Navigation: Smooth tab switching between Vocab, Grammar, and Texts.
- Visual Selection: Browse lessons via high-resolution 3D-styled textbook covers.
The app header now shows the current version and last build date in real time — no more guessing what's deployed.
Every lesson can now be opened directly with https://heroyik.github.io/redgold/?lesson=N, so external apps can send learners straight to the right chapter.
Lesson data generation now uses a compact plan/auto_json rule pack:
- Execution Context: Load only
0.rules_common.mdthrough3.rules_mastery.mdfor lesson work. - Schema Alignment: Use
data/lesson1.jsonas the practical data-shape baseline, withplan/lesson-schema-canonical.mdas a reference. - Locale Safety: Keep source fields such as
proper_nounsandkey_sentencesaligned with translation-pack fields such asproperNounsandkeySentences. - Translation Matching: Require
texts,grammar, andkeySentencestranslations to match source array counts and order.
Built for performance, scalability, and the Google Cloud ecosystem:
- Frontend: Vite + TypeScript
- Architecture: Vanilla Web Components (Shadow DOM, 0-dependency runtime)
- Styling: Vanilla CSS with a centralized token system (Modern Han Elegant)
- Backend: Firebase (Hosting, Auth, Firestore ready)
- CI/CD: GitHub Actions deploys
mainto GitHub Pages. Local git hooks bump the patch version (+0.0.1) before each commit and stamp that version into the commit message.
redgold/
├── data/ # HSK 4 Lesson JSONs (Vocab, Grammar, Texts)
├── plan/ # Technical specs, auto JSON rules, and design documentation
├── public/ # Assets (Audio, Images, Logos)
├── scripts/ # Python automation for data processing
└── src/
├── components/ # Custom Web Components (TextSection, VocabCard, etc.)
├── styles/ # Global design tokens and CSS
├── utils/ # Security (XSS Sanitizer) and Helpers
└── web/ # Main App container and routing# Clone the repo
git clone https://github.com/heroyik/redgold.git
# Install dependencies
npm install# Start the dev server
npm run dev# Build for deployment
npm run build| Phase | Milestone | Status |
|---|---|---|
| UI/UX | Landing Page Refresh (Book Covers + Hip Tagline) | ✅ Done |
| Logic | Forward-only Scroll Sync Engine | ✅ Done |
| Pedagogy | Proper Nouns with Pinyin + English Meaning | ✅ Done |
| Versioning | Pre-commit patch bump + versioned commit messages + header badge | ✅ Done |
| Auth | Firebase Authentication Implementation | ✅ Done |
| Data | Lesson 5 Textbook Data Build-Out | ✅ Done |
| Data | Lesson 11 Textbook Data Build-Out | ✅ Done |
| Data | Lesson 12 Textbook Data Build-Out | ✅ Done |
| Data | Lesson 1-20 Complete Textbook JSON Coverage | ✅ Done |
| Pipeline | Auto JSON Rule Pack Optimization | ✅ Done |
| Data | Mastery Quiz System & Progress Tracking | ⏳ Next |
Every local commit bumps the patch version by 0.0.1, and the commit message is auto-stamped with that exact version. Here's the human-readable tea:
Lesson deep links. RedGold now supports direct lesson URLs for cross-app navigation from QingVoca and other tools.
- 🔗 Lesson URL Routing — Added
?lesson=Nsupport sohttps://heroyik.github.io/redgold/?lesson=7opens Lesson 7 directly instead of landing on the chapter picker. - 🧭 History-Aware Navigation — Internal lesson changes now update the address bar, home navigation clears the lesson parameter, and browser back/forward follows the URL state.
- 🧩 Shadow DOM Compatible — Deep links route through the existing app state and lesson loading flow instead of depending on clickable DOM cards.
- 🖼️ Favicon 404 Fixed — Added an explicit favicon link using the existing RedGold logo asset, eliminating the browser's default
/favicon.ico404. - ✅ Validation — Confirmed production build, direct
?lesson=7entry, lesson switching URL updates, home URL cleanup, and zero 4xx favicon responses.
Full textbook run complete. RedGold now has complete HSK 4 textbook JSON coverage from Lesson 1 through Lesson 20.
- 📚 Lessons 1-20 Complete — Completed and validated all lesson JSON data across textbook texts, vocabulary, grammar/notes, mastery sentences, and locale translation packs.
- 🏆 Lesson 20 Finalized — Added Lesson 20 notes and mastery sentences, including repeated-progressive verb patterns, immediate-sequence structures, emphasis adverbs, directional complements, and same-character vocab notes.
- 🌐 Locale Packs Completed — Backfilled missing
translations.vocabulary,properNouns,lessonTitle,textTitles, grammar examples, and mastery fields where needed. - 🧱 Auto JSON Rules Hardened — Updated
plan/auto_jsonrules to prevent recurring schema gaps around optionalproper_nouns, grammar translation wrappers, and mastery base fields. - ✅ Full Validation Pass — Revalidated Lessons 1-20 with optional proper nouns excluded correctly:
checked: 20,passed: 20,failed: 0.
Auto JSON Rules Hardened. The lesson-generation prompts are now smaller, stricter, and safer for locale data.
- 🧱 Auto JSON Rule Pack — Added
plan/auto_jsonas the execution-ready rule set for Lesson JSON generation, split into common, Kewen, Notes, and Mastery files. - 🚫 Spec Excluded from Runtime Context — Marked
rules-optimization-spec.mdas design/history only, so future Lesson work loads only0~3.rules_*.md. - 🌐 Locale Mapping Guardrails — Documented the source-vs-translation naming split for
proper_nouns/properNounsandkey_sentences/keySentences. - ✅ Translation Count Checks — Required text-line, grammar-example, and mastery-sentence translations to match the source arrays by count and order.
Lesson 12 Complete. The textbook data pipeline now covers the careful-observation and methods chapter.
- 📚 Lesson 12 Textbook Data Complete — Added
data/lesson12.jsonfor the attentive-world-discovery chapter, covering Text 1-5, 33 vocabulary items, 6 grammar/notes entries, 5 mastery sentences, and 3 same-character word examples. - 🧩 Grammar Notes Preserved — Added the full set of Lesson 12 conjunction, comparison, noun-measure reduplication, and contrast notes with complete formal examples.
- 🏆 Mastery Expansion — Added 5 Golden Sentences with Living Language equivalents for problem solving, praise, education methods, giving advice, and choosing methods.
- 🌐 Locale Sync — Filled KO/JA/EN translations for vocabulary, proper nouns, text titles, text lines, grammar explanations/examples, same-character examples, and mastery sentences.
- ✅ Validation — Confirmed Lesson 12 JSON parses successfully, locale mapping reports zero missing fields, and text line indexes are 0-based.
Lesson 11 Complete. The textbook data pipeline now covers the reading-methods chapter.
- 📚 Lesson 11 Textbook Data Complete — Added
data/lesson11.jsonfor the self-study-methods chapter, covering Text 1-5, 30 vocabulary items, 7 grammar/notes entries, 5 mastery sentences, and complete locale data. - 🧩 Grammar Notes Preserved — Added the full set of Lesson 11 emphasis, condition, no-matter, contrast, simultaneity, and same-character notes with full formal and colloquial examples.
- 🌐 Locale Sync — Filled KO/JA/EN translations for vocabulary, proper nouns, text titles, text lines, grammar explanations/examples, and mastery sentences.
- ✅ Validation — Confirmed Lesson 11 JSON parses successfully and locale mapping reports zero issues.
Lessons 1-5 Grammar Image Review Complete. The textbook grammar notes were rechecked against the source images.
- 📚 Lesson 1-5 Grammar Review — Rechecked grammar sections in
data/lesson1.jsonthroughdata/lesson5.jsonagainst the provided textbook images. - 🧩 Compare & Expansion Notes Preserved — Stored comparison pages as explicit grammar items and preserved same-character expansion pages as dedicated notes.
- 🈶 Chinese Examples Complete — Ensured every Chinese example shown in the grammar images is represented in the JSON data.
- 🌐 Locale Sync — Aligned
translations.grammarkeys and example counts with the updated grammar entries, including Korean, Japanese, and English translations. - 🛠️ Recognition Rules Hardened — Updated
plan/image_recognition/2.rules_notes.mdso future grammar image passes preserve comparison/expansion pages instead of collapsing or inventing structure. - ✅ Validation — Verified lesson 1-5 grammar translation keys/counts and ran
npm run buildsuccessfully.
Lesson 5 Complete. The textbook data pipeline now covers Lesson 5.
- 📚 Lesson 5 Textbook Data Complete — Added
data/lesson5.jsonfor the furniture-store sofa-buying chapter, covering Text 1-5, vocabulary, grammar notes, comparison content, same-character word notes, mastery sentences, and locale data. - ✅ Validation — Confirmed
data/lesson5.jsonparses as valid JSON.
Lesson 4 Image Recognition Pass, Canonical Schema Rules & Fixed Lesson Header. Today's work tightened the data pipeline and made lesson navigation stay put.
- 📌 Always-Fixed Lesson Selector Header — The top lesson chip bar (
Home,L1..., language picker, pinyin toggle) now uses viewport-level fixed positioning, so it remains visible while scrolling anywhere inside a lesson page. - 🧭 Sticky Lesson Toolbar — The lesson title and tab row are grouped into a dedicated sticky toolbar below the fixed lesson selector. This keeps the current lesson context and tab controls accessible without covering the content.
- 📚 Lesson 4 Textbook Data Build-Out — Expanded
data/lesson4.jsonfrom the provided textbook images: 5 text sections, 36 vocabulary items, 6 grammar points, 5 mastery sentences, and complete text-line translations. - 🌐 Missing Translation Fixes — Filled the previously missing translations for Lesson 4 text 1 line 0, text 4, and text 5. The translation map now covers all 20 Lesson 4 text lines with KO, JA, and EN entries.
- 🧩 0-Based Text Translation Rule — Updated localization rules so
translations.texts[{textId}].linesmust use JavaScript array indices (0,1,2...) instead of textbook-style line numbers. This prevents app-visible “missing translation” cases for one-line monologues. - 🧱 Canonical Lesson Schema Added — Added
plan/lesson-schema-canonical.mdas the official schema reference based on the currentlesson1.jsonstructure, includingformal_examples[],colloquial_examples[],lessonTitle,textTitles, and KO/JA/EN translation objects. - 📸 Image Recognition Pipeline v2 Docs — Added
plan/image-recognition-spec.mdandplan/image_recognition_status.mdto document the textbook-image-to-JSON workflow, current lesson progress, and schema expectations. - 🛠️ Rule Files Hardened — Updated
1.rules_kewen.md,2.rules_notes.md,3.rules_mastery.md, and4.rules_locale.mdto reference the canonical schema, require complete locale data, preserve proper pinyin such asü, and use array-based grammar examples. - ✅ Validation — Ran
npm run buildsuccessfully after the data and UI changes.
Textbook-Sourced Vocab, Lesson Title i18n & Pinyin Toggle Polish. Precision over assumptions.
- 📝 Pinyin Toggle Fix for Text Titles — Extracted pinyin from text titles into a separate
.pinyindiv via thetitlePinyinfield inlessonTranslations.ts, so the global pinyin toggle CSS properly hides/shows it. - 🎯 Vocab & Review Tabs Now Sourced from Textbook New-Words Sections — Both tabs now collect unique vocabulary items from each text's new-words section instead of the top-level
lesson.vocabularyarray. This ensures only words actually introduced in the textbook pages appear. - 🔧
getTextVocab()Extracted — Deduplicated vocab collection logic into a reusable exported function inlessonTranslations.ts, used by both the vocab tab and review tab. - 🛡️ Meaning Fallback Fix — Added
pickLocalized(...) || item.meaningso text vocabulary items without a translation pack entry still display their original English meaning. - 🌏 Lesson Title Korean/Japanese i18n — Filled in
lessonTitleandtextTitlestranslations (ko/ja) for Lessons 1–4. Now the lesson header properly displays the locale-specific subtitle below the pinyin line.
Firebase Authentication & User Profile. Identity is now live.
- 🔐 Firebase Authentication — Implemented Google Sign-In with a custom
UserMenuWeb Component. - 👤 User Profile UI — Added a sleek, glassmorphic profile menu to both the landing page and lesson view header, showing user name, email, and photo.
- 🛠 Auth Utility — Created a centralized
auth.tsutility for handling user state and authentication logic. - 🔢 Version Bump — Updated to v0.9.49 as part of the automated versioning workflow.
Mobile-First UX Optimization & Cloud Sync. The Review Tab gets a massive glow-up.
- ☁️ Firestore Integration — Migrated local
lesson1.jsondata to Firebase Firestore, laying the groundwork for a true backend architecture. - 📱 Mobile UI/UX Polish — Complete overhaul of the Review tab for modern, high-aspect-ratio screens (Galaxy S26 / iPhone Pro). Eliminated rogue left-margins and packed the top header icons perfectly into a single responsive row.
- 🔄 Click-to-Flip Refined — Resolved PC vs Mobile interaction conflicts. Cards now flip flawlessly on a simple click or tap through a centralized
InteractionManager. - 📐 Perfect Card Boundaries — Leveraged
dvhcalculations (calc(100dvh - 380px)) to aggressively subtract header real estate. Flashcard outlines now fit perfectly on-screen without clipping, and long texts (like complex meanings or examples) are neatly scrollable inside the card itself. - 🎯 Absolute Center Alignment — Chinese characters on the front face are perfectly centered vertically and horizontally. Fixed descender drifts by applying
line-height: 1alongside precise flexbox layouts. - 🎧 Visual Audio Triggers — Replaced text-based audio buttons with sleek, static PNG icons for better intuition.
- 📝 App Manifesto Update — Rewrote the intro messaging to sound more colloquial and explicitly highlight the "HSK4 learners" target audience, while strictly preserving the GitHub footer link.
- ⬅️ Navigation Enhancements — Added tactile left/right arrows flanking the progress counter (
< 1/31 >) for immediate visual navigation cues. - 🧹 Layout Compaction — Reduced unnecessary padding between the version badge and the logo to grant more breathing room to core content.
The version system drops. Things just got official.
- 🔢 Version badge is live — header now shows
vX.X.X+ last build date on both the landing page and the lesson view - ⚙️ Automatic patch bump — local git hooks patch
0.0.1before every commit and make sure the commit message includes the bumped version - 🏷️ Proper Nouns Overhaul — corrected all proper noun entries to match the actual textbook pages (images > assumptions, always)
- 📖 Dialogue 2 Data Fix — cleaned up the proper noun list so it follows the textbook instead of guesswork.
- ➕ Missing Vocab Added — added the missing "happy" vocab item from Dialogue 2 because the textbook had it and the data needed to catch up.
- 📏 Vocabulary meanings tightened up — part-of-speech labels (
adj.,v.,adv.) now match the textbook format exactly
Redgold is an educational tool designed to complement the HSK Standard Course 4 textbook series authorized by Hanban and published by BLCUP.
Built with ❤️ by the RedGold Team.
Speak the Language, Not Just the Grammar.