TeachBox100
給台灣孩子的免費互動教材 —— 認識新臺幣、看懂時鐘、算找零，還有老師上課用得到的小遊戲。
純前端、可離線、不用註冊。學齡前到國小、特教班都適合。
線上試玩 → · 單元一覽 · 快速開始 · 參與貢獻
這是什麼
老師在課堂上要教「50 元可以換幾個 10 元」，得自己準備教具；家長想讓孩子練習看時鐘，找到的 App 不是要註冊就是塞滿廣告。TeachBox100 把這些單元做成打開就能玩的網頁：沒有帳號、沒有廣告。
單元
| 單元 | 路徑 | 在教什麼 |
|---|
| 認識新臺幣 | /coin/introduction | 每種硬幣、鈔票長什麼樣子，哪些組合價值一樣 |
| 金錢等值換算 | /coin/equivalent | 用不同的錢湊出一樣的金額 |
| 計算金錢價值 | /coin/value | 把一堆硬幣鈔票加起來 |
| 付款 | /coin/pay | 看商品價格，挑出剛好的錢 |
| 購物 | /coin/buy | 挑商品 → 算總價 → 付款，走完整流程 |
| 找零 | /coin/change | 算出該找多少，再把零錢湊出來 |
| 學習讀時鐘 | /clock/current-time | 分清時針分針，讀出幾點幾分 |
| 翻牌配對 | /memory | 記憶配對，可自訂卡片主題 |
| 大富翁 | /monopoly | 全班共用一台電腦輪流玩，題庫可匯入 |
| 抽籤（轉盤 / 扭蛋機 / 一番賞） | /draw、/draw/wheel、/draw/gacha、/draw/ichiban | 課堂點名、分組、抽題與獎勵用的抽籤工具 |
| 九九乘法練習 | /multiplication | 自選段數與題數，四選一練乘法表 |
| 計時器 | /timer | 大字倒數，時間到響鈴，可全螢幕投影 |
| 噪音計 | /noise | 麥克風即時顯示音量，太吵變紅色 |
| 計分板 | /scoreboard | 老師手動加減分，最高分那組會亮起來 |
快速開始
git clone https://github.com/<your-org>/teachbox100.git
cd teachbox100
pnpm install
pnpm dev # http://localhost:3000
需要 Node.js 20+。環境變數只有 NEXT_PUBLIC_*（站台網址與分析工具 ID），已在 .env 內附預設值，開發時不必另外設定。
常用指令
| 指令 | 說明 |
|---|
pnpm dev | 開發伺服器 |
pnpm build / pnpm start | 產出並啟動 production build |
pnpm lint | oxlint（含 type-aware 規則） |
pnpm test / pnpm test:coverage | Vitest 單元測試 |
pnpm seo:snapshot | 抓 Lighthouse／SEO 數據寫進 docs/seo/history.md |
設計原則
兩種使用者，需求不同，都要顧。
- 孩子（4–12 歲，含特教生） —— 真正在操作的人。點擊目標要大、文字要少、失敗不能有懲罰感、動效要慢而溫和。不識字的孩子也要能靠圖示猜出怎麼玩。
- 老師／家長 —— 決定要不要用的人。需要一眼看懂單元在教什麼、能自己調難度、大富翁能匯入自己的題庫。
不能違反的限制：
| 限制 | 為什麼 |
|---|
| 純前端、可離線 | 教室網路不穩。PWA（@serwist/next），狀態進 localStorage |
| 不需要帳號 | 孩子沒有 email，老師不想幫全班開帳號 |
| 大富翁是單一螢幕 | 老師電腦／投影幕上全班共用，玩家輪流上前操作。不做多裝置連線 |
| 動效要克制 | 前庭敏感的孩子會不舒服。一定要接 prefers-reduced-motion |
| 繁體中文台灣用語 | 「新臺幣」不是「人民幣」，「鈔票」不是「紙幣」 |
技術架構
| 層 | 選用 |
|---|
| 框架 | Next.js 15 App Router、React 19、TypeScript 5.9 |
| 樣式 | Tailwind CSS 4、shadcn/ui（Radix）、設計 token 集中在 styles/globals.css |
| 動效 | motion（Framer Motion）、canvas-confetti；大富翁物理用 matter-js |
| 狀態 | Zustand（僅遊戲單元），規則邏輯抽成純函式 |
| 音效 | Howler.js |
| 離線 | @serwist/next service worker |
| 分析 | PostHog、Umami（皆為 public key） |
| 測試 | Vitest |
目錄結構
app/ Next.js App Router；pages.config.ts 是首頁的唯一資料來源
components/ atoms / molecules / organisms / templates 分層
lib/ 純邏輯：monopoly 規則、memory、gacha、hooks、helpers
public/images/ 單元封面、硬幣、吉祥物（一律 webp）
docs/ 設計 spec、SEO 紀錄
scripts/ SEO snapshot、IndexNow、GSC 排名查詢
開發慣例
- 首頁是 server component。
app/page.tsx、PageDecor、ImageCard 都沒有 "use client"。唯一的 client component 是 ParallaxFallback（無 markup，只掛 effect）。加東西前先想能不能維持
app/pages.config.ts 是首頁的唯一資料來源。 新增單元 = 加一筆 + 放封面圖，格線與 sitemap 會自己接上- 大富翁規則是純函式（
lib/monopoly/rules.ts），由 Zustand store 呼叫。測邏輯測那裡，不要測 store
- 設計 token 全在
styles/globals.css，不要在元件裡寫死顏色
components/atoms/shadcn/ 的元件被改過，不要用 CLI 直接覆蓋- 圖片一律 webp、用
next/image 並帶 blurDataURL
- 換圖要換檔名破 Next 圖片快取，不要砍
.next（dev server 跑著的時候砍會白畫面）
- 只在客戶端能跑的套件（matter-js 等）要用
next/dynamic + ssr: false，否則 build 會噴不相干的 prerender 錯誤
- commit message 走 Conventional Commits
參與貢獻
歡迎 issue 與 PR。送 PR 前請確認：
pnpm lint 與 pnpm test 都過- 新增的互動有接
prefers-reduced-motion
- 文案是繁體中文台灣用語
- 動 UI 之前先讀
.claude/memo/ui-style-guide.md
回報問題時請附上瀏覽器、裝置，以及是哪個單元的哪一步。
延伸文件
授權
素材可自由用於教學與其他非商業用途，需標示來源，改作須沿用相同授權。商業使用請先聯絡。
© 2026 Eno Huang
