Entwicklung von Lehr-Mini-Programmen + Automatische Bereitstellung v1.0
Philosophische Ausrichtung
„Jede Lehrkraft soll ihr eigenes Unterrichtswerkzeug haben können – ohne Programmierkenntnisse."
Gestaltungsprinzipien für interaktive Werkzeuge
Die Kernfrage interaktiver Lernwerkzeuge ist nicht „ob sie Spaß machen", sondern ob die Schüler das Gefühl haben, etwas gelernt zu haben.
Bei der Gestaltung steht Folgendes im Vordergrund:
- Autonomie: Schüler können Schwierigkeitsgrad oder Aufgabentyp wählen (statt gezwungen zu werden, denselben Weg zu gehen)
- Kompetenz: Die Aufgabenschwierigkeit ermöglicht es den Schülern, erfolgreich zu sein, anstatt wiederholt zu scheitern und aufzugeben
- Verbundenheit: Das Werkzeug bietet Mechanismen zum Teilen, Vergleichen oder gemeinsamen Bearbeiten
Grundsätze für Punkte-Feedback:
- Anzeige: „Du hast X Aufgaben mehr richtig als beim letzten Mal" oder „Du hast X Aufgaben in Folge richtig beantwortet"
- Keine reine Anzeige von absoluten Punktzahlen oder Ranglistenplätzen
- Fortschrittsgefühl erhält die Lernmotivation besser als Ranglisten – insbesondere bei leistungsschwächeren Schülern
Vermeide rein extrinsische Belohnungen: Extrinsische Belohnungen wie Sterne, Abzeichen oder Ranglisten senken die Lernbereitschaft, wenn sie entfernt werden. Gestalte stattdessen Erfolgsrückmeldungen, die den Schülern das Gefühl geben: „Ich habe es wirklich verstanden", nicht „Ich habe Punkte gesammelt".
Designsystem V2.0: Edu Warm
Basierend auf Claude Design (2026-04-17) + canvas-design Schriftbibliothek (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;
}
Verbotene Schriften: Inter, Roboto, Arial – stattdessen Work Sans (Überschriften) + Noto Sans TC (Fließtext) Verbotene Muster: border-left accent callout (optisch veraltet), Verlaufsüberladung, SVG-Illustrationsversuche Farbverlängerung:
oklch(72% 0.13 50)kann warme Edu-Zwischenfarben ableiten
Edu Warm Komponentenspezifikation (canvas-design gemeinsam genutzte Komponentenbibliothek)
/* Schaltflächen */
.btn-primary { background: #d97757; color: white; border-radius: 8px;
padding: 12px 24px; font: Work Sans Bold 16px; }
/* Karten */
.card { background: white; border-radius: 12px; padding: 24px;
box-shadow: 0 4px 24px rgba(0,0,0,0.08); }
/* Hervorhebungsrahmen */
.callout { border-left: 4px solid #d97757; background: rgba(217,119,87,0.08);
padding: 16px 20px; border-radius: 0 8px 8px 0; }
/* Fortschrittsabzeichen */
.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 Ausgabestandard
Alle Miniprogramme werden als HTML artifact ausgegeben (sofortige Vorschau), die Folgendes gewährleisten:
- Laden von Google Fonts: Work Sans + Noto Sans TC
- Vollständige Definition der CSS-Token (:root Variablen)
- Responsive Design (max-width: 720px zentriert)
- Unterstützung des Feinabstimmungsmodus: Wenn der Benutzer „ändere Primärfarbe" sagt, wird nur die Variable --primary aktualisiert
text-wrap: prettyfür alle Absatztexte, um einzelne Schriftzeichen zu vermeiden
React HTML artifact Technische Spezifikation (feste Versionen)
Bei Verwendung von React müssen die CDN-Versionen fest sein, um externe Änderungen zu vermeiden:
<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>
Namensregelung für Stilobjekte (um Babel-Scope-Konflikte zu vermeiden):
// ❌ Falsch: const styles = {...} führt in mehreren Babel-Skripten zu Konflikten
// ✅ Richtig: Verwende eindeutige Namen
const quizStyles = { container: {...}, question: {...} };
const timerStyles = { display: {...}, controls: {...} };
// Komponenten über Skripte hinweg teilen
Object.assign(window, { QuizCard, TimerDisplay });
Zustandspersistenz (LocalStorage)
Werkzeuge, die Fortschritte merken müssen (Tests/Lernkarten/Timer-Einstellungen), MÜSSEN LocalStorage verwenden:
// Zustand speichern
localStorage.setItem('app_state', JSON.stringify({ score, currentQ, settings }));
// Zustand wiederherstellen (nach Seitenneuladen fortsetzen)
const saved = JSON.parse(localStorage.getItem('app_state') || '{}');
Schritt 0: Notwendige Dokumente lesen
references/mini_app_types.md– Häufige Arten von Lehr-Miniprogrammen und deren Spezifikationen../../shared/grade-adapter.md– System zur Klassenstufenanpassung../../shared/guided-collection.md– Geführtes Sammelframeworkreferences/deployment_guide.md– Vercel + GitHub Pages Bereitstellungsanleitung
Konzeptabstimmungsprotokoll (notwendiger vorbereitender Schritt):
../../shared/concept-alignment.md
→ Vor der Ausführung jeglicher Arbeit das Konzeptabstimmungsblatt ausfüllen.
Schritt 1: Klassenstufenerkennung + Geführte Informationssammlung
Erste Fragerunde (maximal 3)
F1: „Welche Art von Lehr-Miniprogramm möchten Sie?
Häufige Typen (Mehrfachauswahl oder Beschreibung Ihrer Idee):
🎯 A. Interaktiver Test (Multiple-Choice/Richtig-Falsch, mit Bewertung)
🎲 B. Zufallsauslosung/Gruppierungswerkzeug
⏱ C. Unterrichts-Timer (mit Countdown-Ton)
🃏 D. Wort-/Konzept-Lernkarten (Kartenspiel)
🎮 E. Kreuzwort-/Zuordnungsspiel
📊 F. Live-Abstimmung/Gefühlsthermometer
🔧 G. Sonstiges (bitte beschreiben)"
F2: „Für welche Klassenstufe sind die Schüler?" (falls nicht erkannt)
F3: „Müssen Schüler Daten/Namen eingeben? (Wenn ja, werde ich ein Eingabefeld entwerfen)"
Zweite Fragerunde (optional)
F4: „Haben Sie konkrete Fragen, Wörter oder Inhalte, die eingefügt werden sollen?
(Sie können sie direkt einfügen oder mir das Thema nennen, ich entwerfe Beispielinhalte)"
F5: „Bereitstellungspräferenz?
A. Vercel (empfohlen, schneller und stabiler, erfordert Vercel-Konto)
B. GitHub Pages (kostenlos, erfordert GitHub-Konto)
C. Nur HTML-Datei, ich stelle selbst bereit"
Zusammenfassungsbestätigung
✅ Miniprogramm-Typ: {Typ}
🎓 Geeignete Klassenstufe: {Klassenstufe}
📝 Inhalt: {Thema/Fragenbeschreibung}
🚀 Bereitstellungsmethode: {Vercel/GitHub Pages/Lokal}
🔗 Nach Abschluss: Erstelle einen permanent teilbaren Link
Schritt 2: Technische Architekturspezifikation
Prinzipien der Technologieauswahl
Einseitige interaktive Werkzeuge (Tests/Spiele/Timer):
→ Reines HTML + CSS + Vanilla JS (einzelne .html-Datei)
→ Kein npm, kein Framework nötig, für Lehrer einfach zu verwenden
Komplexe interaktive Werkzeuge (mehrere Seiten/Backend-Daten):
→ React + Tailwind CSS
→ Bereitstellung auf Vercel
Werkzeuge mit Datenpersistenz (müssen Ergebnisse speichern):
→ React + localStorage (kein Backend nötig)
→ Oder Vercel + KV Store (benötigt Backend)
Designsystem (für den Bildungsbereich)
/* Primärfarben */
--edu-blue: #1A5276; /* Primäre Aktionsschaltflächen */
--edu-green: #1E8449; /* Richtig/Abgeschlossen */
--edu-orange: #CA6F1E; /* Warnung/Laufend */
--edu-gold: #D4AC0D; /* Belohnung/Hervorhebung */
/* Schriften */
--font-main: 'Noto Sans TC', 'Microsoft JhengHei', sans-serif;
/* Schriftgrößen nach Klassenstufe */
Grundschule Unterstufe: Überschrift 2.5rem / Fließtext 1.5rem / Schaltfläche 1.3rem
Grundschule Mittel-/Oberstufe: Überschrift 2rem / Fließtext 1.3rem / Schaltfläche 1.1rem
Mittelstufe: Überschrift 1.8rem / Fließtext 1.1rem / Schaltfläche 1rem
Oberstufe: Überschrift 1.5rem / Fließtext 1rem / Schaltfläche 0.9rem
Schritt 3: Spezifikationen der einzelnen Miniprogramm-Typen
A. Interaktiver Test (am häufigsten verwendet)
Funktionsspezifikation:
- Fragen werden einzeln angezeigt, nach Auswahl sofortiges Feedback (richtig/falsch + Erklärung)
- Fortschrittsbalken (Frage X / insgesamt Y)
- Bewertungssystem (+10 Punkte pro richtiger Antwort, Zeitbonus konfigurierbar)
- Nach Abschluss: Gesamtpunktzahl + Leistungsbeurteilung
- Wiederholungs-Schaltfläche
- Direkte Bearbeitung von Fragen/Optionen (Lehrermodus)
Datenformat (Claude füllt automatisch aus oder basierend auf Benutzerangaben):
const questions = [
{
id: 1,
question: "Fragentext",
options: ["Option A", "Option B", "Option C", "Option D"],
answer: 0, // Index der richtigen Antwort
explanation: "Erklärung",
difficulty: 1 // 1=★☆☆ 2=★★☆ 3=★★★
}
];
B. Zufallsauslosung/Gruppierung
Funktionsspezifikation:
- Schülernamen eingeben (ein Name pro Zeile)
- Anzahl der Gruppen oder Gruppengröße einstellen
- Animierte zufällige Gruppierung
- Ein-Klick-Neugruppierung
- „Ergebnisse kopieren"-Schaltfläche
Zusatzfunktion:
- Kühlmodus (bereits ausgewählte werden vorübergehend nicht erneut ausgewählt)
- Visueller Dreh-Effekt (optional)
C. Unterrichts-Timer
Funktionsspezifikation:
- Mehrere Zeitabschnitte (Nachdenken 1 Min/Diskussion 3 Min/Präsentation 2 Min)
- Große Countdown-Anzeige
- Farbänderung in den letzten 10 Sekunden
- Tonhinweis (bei Abschluss)
- Voreinstellungen für Unterrichtssituationen:
* Gruppendiskussion, Einzelarbeit, Präsentation, Unterrichtswiederholung, Prüfung
Visuell:
- Vollbildanzeige (für Projektion geeignet)
- Dunkelmodus (nicht blendend)
D. Gedächtniskarten-Kartenspiel
Funktionsspezifikation:
- Kartenpaare finden (Wort+Definition, Frage+Antwort, Bild+Wort)
- Zeitmessung + Anzahl der Versuche aufzeichnen
- Abschlussanimation
- Anpassbare Karteninhalte
Geeignet für: Wortschatzlernen, Formelmemorierung, Zuordnung historischer Ereignisse
E. Live-Abstimmung/Gefühlsthermometer
Funktionsspezifikation:
- Lehreransicht: Frage + QR-Code anzeigen
- Schüleransicht (Handy-Scan): Antwort auswählen
- Echtzeit-Statistikdiagramme anzeigen
Hinweis: Diese Funktion benötigt Backend-Unterstützung, empfohlen wird Vercel + Upstash Redis
Schritt 4: Entwicklungs- + Bereitstellungsprozess
Option A: Reine HTML-Einzeldatei (am einfachsten)
# Einzelne HTML-Datei generieren
python scripts/generate_mini_app.py \
--type "[quiz/lottery/timer/flashcard]" \
--grade "[Klassenstufe]" \
--content "[Fragen/Inhalt JSON]" \
--output "/mnt/user-data/outputs/[Name].html"
# Benutzer kann sie direkt im Browser öffnen oder auf einen statischen Server hochladen
Option B: Automatische Bereitstellung auf Vercel (empfohlen)
Benötigter MCP: Vercel MCP
Ablauf, wenn Vercel MCP verfügbar ist:
1. Claude generiert React-Projektquellcode (/tmp/mini-app-[Name]/)
2. Vercel MCP zur Bereitstellung aufrufen:
deploy_to_vercel(project_dir="/tmp/mini-app-[Name]")
3. Vercel MCP gibt permanenten Link zurück (https://xxx.vercel.app)
4. Claude gibt den Link an den Benutzer aus
⚠️ Der Benutzer muss Vercel MCP in Claude Code verbunden haben
Wenn Vercel MCP nicht verfügbar ist:
# React-Projekt + vercel.json generieren
python scripts/generate_mini_app_react.py \
--type "[Typ]" --grade "[Klassenstufe]" \
--output_dir "/mnt/user-data/outputs/mini-app-[Name]/"
# Bereitstellungsanleitung für den Benutzer ausgeben
echo "Führen Sie die folgenden Befehle aus, um bereitzustellen:
cd mini-app-[Name]
npx vercel --prod"
Option C: GitHub Pages
python scripts/generate_github_pages.py \
--type "[Typ]" --grade "[Klassenstufe]" \
--output_dir "/mnt/user-data/outputs/mini-app-[Name]/"
# Bereitstellungsanleitung ausgeben:
echo "Schieben Sie den Ordner auf GitHub und aktivieren Sie die Bereitstellung unter Settings > Pages"
Schritt 5: Qualitätssicherungs-Checkliste
- Mobilgerätefreundlich (funktioniert auf Smartphone/Tablet)
- Schriftgröße entspricht der Klassenstufenspezifikation
- Touch-Bedienung unterstützt
- Farbkontrast entspricht den Barrierefreiheitsstandards (WCAG AA)
- Zurück-/Zurücksetzungsfunktion vorhanden
- Kein Konto erforderlich (Schülerseite)
- Chinesische Anzeige korrekt (Schriftarten eingebettet oder Fallback-Schriftarten angegeben)
- Bereitstellung erfolgreich und Testlink erreichbar
- React-Version festgelegt (18.3.1 + Babel 7.29.0)?
- Stilobjektnamen eindeutig (nicht
const styles)? - Werkzeuge, die Fortschritte speichern müssen, haben LocalStorage hinzugefügt?
- Keine Verlaufsüberladung, keine SVG-Illustrationsversuche, kein border-left accent callout?
-
text-wrap: prettyangewendet?
MCP-Connectors (Plattformunterschiede, Kernfunktionen)
Claude Code (vollständige Unterstützung)
Vercel MCP (falls verbunden):
Zweck: Mit einem Klick Miniprogramm auf Vercel bereitstellen, teilbaren Link generieren
Aktivierung: claude mcp add vercel
Verwendungszeitpunkt: Benutzer sagt „Auf Vercel bereitstellen" oder „Teilbaren Link generieren"
MCP-Aufruf: deploy_to_vercel(project_path, project_name)
Rückgabewert: { url: "https://xxx.vercel.app", deployment_id: "..." }
GitHub MCP / Filesystem (falls verbunden):
Zweck: GitHub-Repository erstellen und Pages aktivieren
Verwendungszeitpunkt: Benutzer sagt „Auf GitHub Pages stellen"
Claude.ai (in den Einstellungen aktivieren)
Derzeit kann Vercel MCP nur in der Claude Code-Umgebung verwendet werden.
Empfehlung für Claude.ai-Benutzer:
1. Claude generiert vollständige HTML-Einzeldatei
2. Benutzer lädt sie manuell auf Vercel / Netlify / GitHub Pages hoch
Codex-Plattform
Unterstützt Vercel CLI und GitHub Pages Bereitstellungsskript-Generierung. Vercel MCP kann nach Konfiguration in ~/.codex/config.toml automatisch bereitstellen.
Wenn Vercel MCP nicht konfiguriert ist, generiert Claude ein vollständiges deploy.sh-Skript, das der Benutzer manuell ausführt.
Antigravity-Plattform (Google AI IDE)
MCP kann nach der Konfiguration des Vercel-Connectors über den MCP Server Hub automatisch bereitstellen.
Wenn nicht konfiguriert, generiert Claude ein deploy.sh-Skript, das der Benutzer manuell ausführt.
Beispiel für den Aufruf des Bereitstellungs-MCP (Claude Code)
# Wenn Vercel MCP verbunden ist
[Claude generiert Code]
[Ruft Vercel MCP zur Bereitstellung auf]
→ Rückgabe https://edu-quiz-xxxxx.vercel.app
→ Claude Ausgabe: „✅ Bereitgestellt! Teilen-Link: https://edu-quiz-xxxxx.vercel.app"