Imported from ben1009/super-minds (AGENTS.md). Install upstream with npx skills add ben1009/super-minds. Copyright stays with the author.

Super Minds - Agent Guide

Project Overview

Super Minds 是一个面向儿童的互动式英语学习网站，涵盖 Super Minds 2 和 Super Minds 3 的语法、词汇、阅读、故事和作业练习。项目是纯静态站点，托管在 GitHub Pages 上，无需后端服务器。

• 在线访问: https://ben1009.github.io/super-minds/
• 源码仓库: https://github.com/ben1009/super-minds
• 目标用户: 儿童英语学习者
• 课程来源: Super Minds 2 / Super Minds 3 教材与 PDF 资料

Technology Stack

• HTML5 + CSS3 + 原生 JavaScript
• Tailwind CSS CDN
• Lucide Icons CDN
• Font Awesome CDN on baseball-themed pages
• Google Fonts
• Google Analytics via shared ga.js
• GitHub Pages

Project Structure

<project-root>/
├── index.html
├── ga.js
├── favicon.svg
├── css/
│   ├── common.css
│   ├── baseball-theme.css
│   └── baseball-unit7.css
├── js/
│   └── common.js
├── scripts/
│   ├── generate-baseball.py
│   ├── test_generate_baseball.py
│   ├── test_review_unit5_lecture2.py
│   └── test_sm3_pages.py
├── sm2/
│   ├── unit7/
│   ├── unit8/
│   ├── unit9/
│   ├── review/
│   └── baseball/
├── sm3/
│   ├── unit0/
│   ├── unit1/
│   ├── unit2/
│   └── unit3/
├── README.md
├── TESTING.md
├── todo.md
└── AGENTS.md

Page Inventory

Shared Architecture

CSS

• Shared styles live in css/common.css.
• Baseball-themed shared styles live in css/baseball-theme.css.
• Baseball Unit 7 shared styles live in css/baseball-unit7.css.
• Page-specific styles may remain inline when they are tightly coupled to one page.

JavaScript

js/common.js owns shared behavior:

• renderNav(config) renders shared nav when window.NAV_CONFIG and <nav id="site-nav"></nav> are present.
• toggleMobileMenu() opens/closes the generated mobile menu.
• buildNavPatternA() and buildNavPatternB() generate desktop dropdown nav and compact mobile nav.
• Mobile nav uses native <details> sections for SM2 and SM3; the active course family is open by default.
• Desktop SM2 and SM3 dropdowns open on hover or keyboard focus.
• data-action is reserved for shared nav actions such as toggle-mobile-menu.
• Page-specific delegated actions should use a separate attribute, such as data-lesson-action, to avoid nav conflicts.
• Shared lesson helpers include translation toggles, answer reveals, todo progress, copy helpers, speech, keyboard binding, and progress restore.

Navigation Patterns

• Pattern A: SM2 Unit 7 pages with blue styling.
• Pattern B: SM2 Unit 8/9 and SM3 pages with green/baseball-themed styling.
• Pattern C: Baseball Unit 7 flat navigation.
• Pattern D: Baseball Unit 8 generated page.

When adding a page, prefer window.NAV_CONFIG plus <nav id="site-nav"></nav> instead of copying nav HTML.

SM3 Unit 2 Notes

sm3/unit2/there-is-there-are-picnic.html was generated from the newly added Unit 2 PDF.

Required content:

• Two source pictures at the top of the lesson:
  • sm3/unit2/assets/unit2-source-000.jpg
  • sm3/unit2/assets/unit2-source-001.jpg
• Food vocabulary for countable and uncountable nouns.
• There is, There are, question, and negative grammar cards.
• Picnic song with clickable translations.
• Reading comprehension with correct/wrong feedback.
• Picnic basket cloze and Chinese-to-English translation practice.
• Supermarket story reading and comprehension cards.
• Todo list using localStorage key sm3Unit2ThereBeTodos.

Implementation rule:

• Lesson controls on this page use data-lesson-action.
• Do not use data-action for lesson controls because data-action is used by shared mobile navigation.

SM3 Unit 2 Breakfast Notes

sm3/unit2/breakfast-foods-simple-present.html was generated from the Unit 2 breakfast PDF before source cleanup.

Required content:

• Breakfast vocabulary for Britain, Brazil, Mexico, special breakfasts, and common food words.
• Pizza ordering dialogue using I'd like..., Have you got any...?, We haven't got any..., and How about...?.
• Required reading passage A Busy Saturday at Home with comprehension feedback.
• Extension reading A Helping Hand at Home with simple-present comprehension cards.
• Simple present grammar notes and cloze practice.
• Todo list using localStorage key sm3Unit2BreakfastTodos.

Implementation rule:

• Lesson controls on this page use data-lesson-action.
• Do not use data-action for lesson controls because data-action is used by shared mobile navigation.

SM3 Unit 3 Daily Routines Notes

sm3/unit3/daily-routines-frequency-adverbs.html was generated from the Unit 3 PDF.

Required content:

• Frequency adverbs from always through never, including placement rules and time expressions.
• My Weekday Routine reading with clickable Chinese translations and true/false feedback.
• Page 38 story vocabulary and Our Daily Search reading with a cloze exercise.
• Frequency-adverb grammar practice and a Helping Hands story preview.
• Todo list using localStorage key sm3Unit3RoutinesTodos.

Implementation rule:

• Lesson controls on this page use data-lesson-action.
• Do not use data-action for lesson controls because data-action is used by shared mobile navigation.

Baseball Generation

sm2/baseball/unit8/baseball-gerunds-ball-sports.html is generated from sm2/unit8/gerunds-ball-sports.html.

Run after changing the source page:

python3 scripts/generate-baseball.py
python3 scripts/test_generate_baseball.py

Do not directly edit the generated baseball Unit 8 page unless changing the generator or tests at the same time.

Adding A New Lesson

1. Add the page under the right product folder, for example sm3/unit3/.
2. Reuse the closest existing lesson page as the template.
3. Use window.NAV_CONFIG and shared nav rendering.
4. Add homepage links in index.html.
5. Add or update focused tests, especially in scripts/test_sm3_pages.py for SM3 pages.
6. Update README.md, TESTING.md, AGENTS.md, and todo.md when the course inventory or workflow changes.
7. Run local checks before committing.

Development Guidelines

• Use semantic HTML (header, main, section, footer).
• Keep class names kebab-case.
• Use Tailwind utility classes where practical.
• Keep custom CSS local unless it is clearly shared.
• Prefer event listeners and delegated handlers over inline onclick.
• Add role="button" and keyboard activation support for clickable non-button elements.
• Keep localStorage keys page-specific when progress state should not overlap.
• Preserve the bilingual English/Chinese lesson format.
• Avoid direct pushes to master; use feature branches and PRs.

Local Testing

PYTHONDONTWRITEBYTECODE=1 ./test.sh
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest scripts/test_sm3_pages.py
python3 scripts/test_generate_baseball.py
node --check js/common.js

For browser preview:

python3 -m http.server 8000

Then visit http://localhost:8000.

Deployment

GitHub Pages deploys from the protected branch after PR merge. Do not push directly to master.