Teaching Mini-App Development + Automatic Deployment v1.0

Philosophical Positioning

"Empower every teacher to create their own teaching tools, no programming background required."

Interactive Tool Design Principles

The core question for interactive learning tools is not "is it fun," but rather does the student feel like they've learned something.

When designing, prioritize three things:

Autonomy: Students can choose difficulty or question type (instead of being forced along the same path)
Competence: Task difficulty allows students to try and succeed, not repeatedly fail and give up
Relatedness: The tool has a mechanism for students to share, compare, or work together

Score Feedback Design Principles:

Show "You improved by X questions compared to last time" or "You answered X questions in a row correctly"
Don't just show absolute scores or rankings
Progress is more motivating than rankings—especially for struggling students

Avoid Pure External Rewards: External rewards based only on stars, badges, and leaderboards reduce learning motivation once removed. Prioritize designing achievement feedback that makes students feel "I really understand this," rather than exchange feedback where they "got points."

Design System V2.0: Edu Warm

Based on Claude Design (2026-04-17) + canvas-design Font Library (Work Sans + Noto Sans TC)

Edu Warm CSS Token

:root {
  --bg: #fffbf5;      --surface: #f5f0e8;
  --text: #141413;    --text-muted: #6B6B6B;
  --primary: #d97757; --primary-hover: #c4664a;
  --secondary: #6a9bcc; --accent: #788c5d;
  --radius: 12px;     --shadow: 0 4px 24px rgba(0,0,0,0.08);
  --font-heading: 'Work Sans', 'Noto Sans TC', sans-serif;
  --font-body: 'Noto Sans TC', sans-serif;
}

Forbidden Fonts: Inter, Roboto, Arial — use Work Sans (headings) + Noto Sans TC (body) Forbidden Patterns: border-left accent callout (visually stale), gradient overload, SVG illustration attempts Color Extension: oklch(72% 0.13 50) can derive Edu Warm warm-tone mid-colors

Edu Warm Component Specs (canvas-design Shared Component Library)

/* Buttons */
.btn-primary { background: #d97757; color: white; border-radius: 8px; 
               padding: 12px 24px; font: Work Sans Bold 16px; }

/* Cards */
.card { background: white; border-radius: 12px; padding: 24px;
        box-shadow: 0 4px 24px rgba(0,0,0,0.08); }

/* Callout Boxes */
.callout { border-left: 4px solid #d97757; background: rgba(217,119,87,0.08);
           padding: 16px 20px; border-radius: 0 8px 8px 0; }

/* Progress Badges */
.badge { background: #d97757; color: white; border-radius: 50%;
         width: 32px; height: 32px; display: flex; align-items: center; 
         justify-content: center; font: Work Sans Bold 14px; }

Layout: HTML Artifact Output Standard

All mini-apps should be output as HTML artifacts (with instant preview capability), ensuring:

Google Fonts loaded: Work Sans + Noto Sans TC
CSS tokens fully defined (:root variables)
Responsive design (centered, max-width: 720px)
Fine-tuning mode support: user says "change primary color" only updates --primary variable
text-wrap: pretty applied to all paragraph text to prevent widows

React HTML Artifact Technical Specs (Fixed Versions)

When using React, CDN versions must be pinned to avoid external changes affecting functionality:

<script crossorigin src="https://unpkg.com/[email protected]/umd/react.development.js"></script>
<script crossorigin src="https://unpkg.com/[email protected]/umd/react-dom.development.js"></script>
<script src="https://unpkg.com/@babel/[email protected]/babel.min.js"></script>

Style Object Naming Rules (to avoid Babel scope conflicts):

// ❌ Wrong: const styles = {...} conflicts across multiple Babel scripts
// ✅ Correct: Use unique names
const quizStyles = { container: {...}, question: {...} };
const timerStyles = { display: {...}, controls: {...} };
// Share components across scripts
Object.assign(window, { QuizCard, TimerDisplay });

State Persistence (LocalStorage)

Tools that need to remember progress (quizzes/study cards/timer settings) must use localStorage:

// Save state
localStorage.setItem('app_state', JSON.stringify({ score, currentQ, settings }));
// Restore state (continue after page reload)
const saved = JSON.parse(localStorage.getItem('app_state') || '{}');

Step 0: Read Required Files

references/mini_app_types.md — Common teaching mini-app types and specifications
../../shared/grade-adapter.md — Grade adaptation system
../../shared/guided-collection.md — Guided information collection framework
references/deployment_guide.md — Vercel + GitHub Pages deployment guide

Concept Alignment Protocol (Required Pre-Step): ../../shared/concept-alignment.md → Before executing any work, complete the concept alignment confirmation card.

Step 1: Grade Detection + Guided Information Collection

First Round Questions (Max 3)

Q1: "What type of teaching mini-app do you want?
     Common types (select multiple or describe your idea):
    🎯 A. Interactive Quiz (multiple choice/true-false, with scoring)
    🎲 B. Random Pick/Group Sorter
    ⏱ C. Classroom Timer (with countdown sound)
    🃏 D. Word/Concept Memory Cards (flip game)
    🎮 E. Crossword/Matching Game
    📊 F. Instant Poll/Mood Thermometer
    🔧 G. Other (please describe)"

Q2: "Which grade level is this for?" (if not already detected)
Q3: "Do students need to enter data/names? (If so, I'll design input fields)"

Second Round Questions (Optional)

Q4: "Do you have specific questions, vocabulary, or content to include?
    (You can paste them directly, or tell me the topic and I'll design sample content)"
    
Q5: "Deployment preference?
    A. Vercel (Recommended, faster and more stable, requires a Vercel account)
    B. GitHub Pages (Free, requires a GitHub account)
    C. Only need an HTML file, I'll deploy it myself"

Confirmation Summary

✅ Mini-App Type: {type}
🎓 Grade Level: {grade}
📝 Content: {topic/question description}
🚀 Deployment Method: {Vercel/GitHub Pages/Local}
🔗 Upon Completion: Generate a shareable permanent link

Step 2: Technical Architecture Specifications

Technology Selection Principles

Single-page interactive tools (quiz/game/timer):
  → Pure HTML + CSS + Vanilla JS (single .html file)
  → No npm, no frameworks needed, easy for teachers to use directly

Complex interactive tools (multi-page/backend data):
  → React + Tailwind CSS
  → Deploy to Vercel

Data-persistent tools (need to store results):
  → React + localStorage (no backend needed)
  → Or Vercel + KV store (backend needed)

Design System (Educational Use)

/* Primary Colors */
--edu-blue:   #1A5276;   /* Primary action buttons */
--edu-green:  #1E8449;   /* Correct/Complete */
--edu-orange: #CA6F1E;   /* Warning/In Progress */
--edu-gold:   #D4AC0D;   /* Reward/Highlight */

/* Fonts */
--font-main: 'Noto Sans TC', 'Microsoft JhengHei', sans-serif;

/* Grade-Specific Font Sizes */
Early Elementary (Grades 1-2):   Heading 2.5rem / Body 1.5rem / Button 1.3rem
Upper Elementary (Grades 3-6):    Heading 2rem   / Body 1.3rem / Button 1.1rem
Middle School (Grades 7-9):       Heading 1.8rem / Body 1.1rem / Button 1rem
High School (Grades 10-12):       Heading 1.5rem / Body 1rem   / Button 0.9rem

Step 3: Mini-App Type Specifications

A. Interactive Quiz (Most Common)

Functional Specifications:
- Display questions one at a time, with instant feedback after selection (Correct/Wrong + Explanation)
- Progress bar showing (Question X of Y)
- Scoring system (+10 points for correct, optional time bonus)
- Display total score + grade commentary upon completion
- Retry button
- Questions/options support direct editing (Teacher Mode)

Data Format (Auto-populated by Claude or based on user input):
const questions = [
  {
    id: 1,
    question: "Question text",
    options: ["Option A", "Option B", "Option C", "Option D"],
    answer: 0, // Answer index
    explanation: "Explanation text",
    difficulty: 1 // 1=★☆☆ 2=★★☆ 3=★★★
  }
];

B. Random Pick / Group Sorter

Functional Specifications:
- Input student list (one name per line)
- Set number of groups or members per group
- Random grouping animation effect
- One-click regroup
- Copy results button

Additional Features:
- Cooldown mode (picked students temporarily not re-picked)
- Spinner wheel visual effect (optional)

C. Classroom Timer

Functional Specifications:
- Multi-segment timing mode (Think 1 min / Discuss 3 min / Present 2 min)
- Large display countdown
- Color change hint in the last 10 seconds
- Sound hint upon completion
- Classroom scenario presets:
  * Group discussion, individual thinking, presentation, pre-class review, exam

Visual:
- Full-screen display (projector-friendly)
- Dark mode (less harsh on eyes)

D. Memory Card Flip Game

Functional Specifications:
- Card matching (word + definition, question + answer, image + text)
- Timer + number of attempts recorded
- Completion animation
- Custom card content

Use Cases: Vocabulary learning, formula memorization, historical event matching

E. Instant Poll / Mood Thermometer

Functional Specifications:
- Teacher side: Show question + QR Code
- Student side (scan code on phone): Select answer
- Real-time statistical chart display
Note: This feature requires backend support; Vercel + Upstash Redis is recommended

Step 4: Development + Deployment Process

Plan A: Single HTML File (Simplest)

# Generate a single HTML file
python scripts/generate_mini_app.py \
  --type "[quiz/lottery/timer/flashcard]" \
  --grade "[grade]" \
  --content "[question/content JSON]" \
  --output "/mnt/user-data/outputs/[name].html"

# User can open directly in browser, or upload to any static server

Plan B: Vercel Automatic Deployment (Recommended)

Required MCP: Vercel MCP

Flow when Vercel MCP is available:

1. Claude generates React project source code (/tmp/mini-app-[name]/)
2. Call Vercel MCP to deploy:
   deploy_to_vercel(project_dir="/tmp/mini-app-[name]")
3. Vercel MCP returns a permanent URL (https://xxx.vercel.app)
4. Claude outputs the URL to the user

⚠️ Requires the user to have connected Vercel MCP in Claude Code

If Vercel MCP is not available:

# Generate React project + vercel.json
python scripts/generate_mini_app_react.py \
  --type "[type]" --grade "[grade]" \
  --output_dir "/mnt/user-data/outputs/mini-app-[name]/"

# Output deployment instructions to the user
echo "Please run the following commands to deploy:
cd mini-app-[name]
npx vercel --prod"

Plan C: GitHub Pages

python scripts/generate_github_pages.py \
  --type "[type]" --grade "[grade]" \
  --output_dir "/mnt/user-data/outputs/mini-app-[name]/"

# Output deployment instructions:
echo "Push the folder to GitHub, then enable deployment in Settings > Pages"

Step 5: Quality Confirmation Checklist

MCP Connectors (Platform Differences, Core Features)

Claude Code (Full Support)

Vercel MCP (if connected):
  Purpose: Deploy the mini-app to Vercel with one click, generating a shareable link
  Activation: claude mcp add vercel
  
  When to Use: User says "deploy to Vercel" or "generate a shareable link"
  MCP Call: deploy_to_vercel(project_path, project_name)
  Return Value: { url: "https://xxx.vercel.app", deployment_id: "..." }

GitHub MCP / Filesystem (if connected):
  Purpose: Create a GitHub repository and enable Pages
  When to Use: User says "put it on GitHub Pages"

Claude.ai (Enable in Settings)

Currently, Vercel MCP requires the Claude Code environment.
Recommendation for Claude.ai users:
1. Claude generates a complete, single HTML file
2. User manually uploads to Vercel / Netlify / GitHub Pages

Codex Platform

Supports Vercel CLI and GitHub Pages deployment script generation. With Vercel MCP configured via ~/.codex/config.toml, automatic deployment is possible. When Vercel MCP is not configured, Claude generates a complete deploy.sh script for the user to execute manually.

Antigravity Platform (Google AI IDE)

MCP can be configured via MCP Server Hub with the Vercel Connector for automatic deployment. When not configured, Claude generates a deploy.sh script for the user to run manually.

Example MCP Invocation (Claude Code)

# If Vercel MCP is connected
[Claude generates code]
[Call Vercel MCP to deploy]
→ Returns https://edu-quiz-xxxxx.vercel.app
→ Claude outputs: "✅ Deployed! Shareable link: https://edu-quiz-xxxxx.vercel.app"

Ask in your favorite AI

Documentation