Développement de mini-applications pédagogiques + déploiement automatique v1.0

Positionnement philosophique

« Permettre à chaque enseignant de disposer de ses propres outils pédagogiques, sans avoir besoin de savoir coder. »

Principes de conception des outils interactifs

La question centrale d'un outil d'apprentissage interactif n'est pas « est-ce amusant ? », mais l'élève a-t-il eu le sentiment d'avoir appris quelque chose ?.

Lors de la conception, privilégiez trois aspects :

Autonomie : l'élève peut choisir la difficulté ou le type d'exercice (plutôt que d'être forcé à suivre un chemin unique).
Compétence : la difficulté de la tâche permet à l'élève de réussir après essai, sans échec répété menant à l'abandon.
Lien social : l'outil offre un mécanisme pour partager, comparer ou réaliser ensemble.

Principes de retour de score :

Afficher « Tu as progressé de X questions par rapport à la dernière fois » ou « Tu as répondu correctement X fois de suite ».
Ne pas afficher uniquement le score absolu ou le classement.
Le sentiment de progrès maintient mieux la motivation que le classement — surtout pour les élèves en difficulté.

Éviter les récompenses purement extrinsèques : Les récompenses externes (étoiles, badges, classements) diminuent la motivation une fois supprimées. Privilégiez les retours qui font ressentir à l'élève « J'ai vraiment compris » plutôt que « J'ai gagné des points ».

Système de design V2.0 : Edu Warm

Basé sur Claude Design (2026-04-17) + bibliothèque de polices canvas-design (Work Sans + Noto Sans TC)

Token CSS Edu Warm

: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;
}

Polices interdites : Inter, Roboto, Arial — utiliser Work Sans (titres) + Noto Sans TC (corps) Motifs interdits : border-left accent callout (visuellement obsolète), dégradés excessifs, tentatives d'illustrations SVG Extension de couleur : oklch(72% 0.13 50) peut générer des couleurs intermédiaires chaudes Edu Warm

Spécifications des composants Edu Warm (bibliothèque de composants partagés canvas-design)

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

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

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

/* Badge de progression */
.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; }

Mise en page : standard de sortie pour artefacts HTML

Toutes les mini-applications sont produites sous forme d'artefacts HTML (prévisualisation instantanée), en veillant à :

Charger Google Fonts : Work Sans + Noto Sans TC
Définir complètement les tokens CSS (variables :root)
Conception responsive (max-width: 720px centré)
Prise en charge du mode réglage fin : si l'utilisateur dit « change la couleur principale », seule la variable --primary est mise à jour
text-wrap: pretty appliqué à tous les textes de paragraphe, pour éviter les mots orphelins

Spécifications techniques des artefacts HTML avec React (version fixe)

Lors de l'utilisation de React, la version CDN doit être figée pour éviter les impacts de changements externes :

<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>

Règle de nommage des objets de style (pour éviter les conflits de portée Babel) :

// ❌ Erreur : const styles = {...} entre en conflit dans plusieurs scripts Babel
// ✅ Correct : utiliser un nom unique
const quizStyles = { container: {...}, question: {...} };
const timerStyles = { display: {...}, controls: {...} };
// Partage de composants entre scripts
Object.assign(window, { QuizCard, TimerDisplay });

Persistance d'état (LocalStorage)

Les outils nécessitant la mémorisation de la progression (quiz / cartes mémoire / paramètres de minuteur) doivent utiliser LocalStorage :

// Sauvegarder l'état
localStorage.setItem('app_state', JSON.stringify({ score, currentQ, settings }));
// Restaurer l'état (continuer après rechargement de la page)
const saved = JSON.parse(localStorage.getItem('app_state') || '{}');

Étape 0 : Lire les fichiers nécessaires

references/mini_app_types.md — Types et spécifications des mini-applications pédagogiques courantes
../../shared/grade-adapter.md — Système d'adaptation par niveau scolaire
../../shared/guided-collection.md — Cadre de collecte guidée
references/deployment_guide.md — Guide de déploiement Vercel + GitHub Pages

Protocole d'alignement conceptuel (étape préalable obligatoire) : ../../shared/concept-alignment.md → Avant d'exécuter toute tâche, remplir d'abord la fiche de confirmation d'alignement conceptuel.

Étape 1 : Détection du niveau scolaire + Collecte d'informations guidée

Première série de questions (3 maximum)

Q1 : « Quel type de mini-application pédagogique souhaitez-vous ?
    Types courants (sélection multiple ou description de votre idée) :
    🎯 A. Quiz interactif (QCM, vrai/faux, avec score)
    🎲 B. Outil de tirage au sort / répartition en groupe
    ⏱ C. Minuteur pédagogique (avec son de décompte)
    🃏 D. Cartes mémoire de mots / concepts (jeu de retournement)
    🎮 E. Jeu de mots croisés / d'association
    📊 F. Vote instantané / thermomètre émotionnel
    🔧 G. Autre (veuillez décrire) »

Q2 : « Pour quel niveau d'élèves ? » (si non détecté)
Q3 : « Les élèves doivent-ils saisir des données / noms ? (Si oui, je concevrai une zone de saisie) »

Deuxième série de questions (facultative)

Q4 : « Avez-vous des questions, mots ou contenus spécifiques à inclure ?
    (Vous pouvez les coller directement, ou me donner le thème et je conçois un exemple) »

Q5 : « Préférence de déploiement ?
    A. Vercel (recommandé, plus rapide et stable, nécessite un compte Vercel)
    B. GitHub Pages (gratuit, nécessite un compte GitHub)
    C. Uniquement le fichier HTML, je déploie moi-même »

Résumé de confirmation

✅ Type de mini-application : {type}
🎓 Niveau scolaire : {niveau}
📝 Contenu : {thème / description des questions}
🚀 Mode de déploiement : {Vercel / GitHub Pages / Local}
🔗 Une fois terminé : génération d'un lien permanent partageable

Étape 2 : Spécifications architecturales techniques

Principes de choix technique

Outils interactifs simples (quiz / jeux / minuteurs) :
  → HTML pur + CSS + Vanilla JS (fichier .html unique)
  → Pas de npm, pas de framework, facilement utilisable par les enseignants

Outils interactifs complexes (multi-pages / backend de données) :
  → React + Tailwind CSS
  → Déploiement sur Vercel

Outils de persistance de données (besoin de stocker les résultats) :
  → React + localStorage (pas besoin de backend)
  → Ou Vercel + KV store (backend nécessaire)

Système de design (pour l'éducation)

/* Couleurs principales */
--edu-blue:   #1A5276;   /* Boutons d'action principaux */
--edu-green:  #1E8449;   /* Correct / Terminé */
--edu-orange: #CA6F1E;   /* Alerte / En cours */
--edu-gold:   #D4AC0D;   /* Récompense / Mise en évidence */

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

/* Tailles de police par niveau */
Primaire début :   Titre 2.5rem  / Corps 1.5rem  / Bouton 1.3rem
Primaire moyen/avancé : Titre 2rem / Corps 1.3rem / Bouton 1.1rem
Collège :          Titre 1.8rem   / Corps 1.1rem  / Bouton 1rem
Lycée :            Titre 1.5rem   / Corps 1rem    / Bouton 0.9rem

Étape 3 : Spécifications par type de mini-application

A. Quiz interactif (le plus courant)

Spécifications fonctionnelles :
- Affichage des questions une par une, retour immédiat après sélection (correct / incorrect + explication)
- Barre de progression (Question X / Total Y)
- Système de score (+10 points par bonne réponse, bonus de temps possible)
- Affichage du score total + appréciation après terminaison
- Bouton pour recommencer
- Questions / options modifiables directement (mode enseignant)

Format des données (rempli automatiquement par Claude ou selon les informations fournies) :
const questions = [
  {
    id: 1,
    question: "Texte de la question",
    options: ["Option A", "Option B", "Option C", "Option D"],
    answer: 0, // index de la bonne réponse
    explanation: "Explication",
    difficulty: 1 // 1=★☆☆ 2=★★☆ 3=★★★
  }
];

B. Tirage au sort / Répartition en groupe

Spécifications fonctionnelles :
- Saisie de la liste des élèves (un nom par ligne)
- Définition du nombre de groupes ou du nombre d'élèves par groupe
- Animation de répartition aléatoire
- Bouton pour refaire la répartition en un clic
- Bouton pour copier le résultat

Fonctionnalités supplémentaires :
- Mode « refroidissement » (les élèves déjà tirés sont temporairement exclus)
- Effet visuel de roue de loterie (optionnel)

C. Minuteur pédagogique

Spécifications fonctionnelles :
- Mode chronomètre multi-segments (réflexion 1 min / discussion 3 min / présentation 2 min)
- Affichage du décompte en grands caractères
- Changement de couleur les 10 dernières secondes
- Alerte sonore (à la fin)
- Préréglages de scénarios pédagogiques :
  * Discussion en groupe, réflexion individuelle, présentation orale, révision avant cours, examen

Visuel :
- Affichage plein écran (pratique pour la projection)
- Mode sombre (peu agressif pour les yeux)

D. Jeu de cartes mémoire à retourner

Spécifications fonctionnelles :
- Appariement de cartes (mot + définition, question + réponse, image + mot)
- Chronomètre + compteur d'essais d'appariement
- Animation de fin
- Contenu des cartes personnalisable

Utilisations : apprentissage de mots, mémorisation de formules, appariement d'événements historiques

E. Vote instantané / Thermomètre émotionnel

Spécifications fonctionnelles :
- Côté enseignant : affichage de la question + QR Code
- Côté élève (scan du code avec un téléphone) : sélection de la réponse
- Affichage immédiat des statistiques sous forme de graphiques
Remarque : cette fonction nécessite un backend ; Vercel + Upstash Redis recommandé

Étape 4 : Processus de développement + déploiement

Option A : Fichier HTML unique (le plus simple)

# Générer un fichier HTML unique
python scripts/generate_mini_app.py \
  --type "[quiz/lottery/timer/flashcard]" \
  --grade "[niveau]" \
  --content "[questions / contenu JSON]" \
  --output "/mnt/user-data/outputs/[nom].html"

# L'utilisateur peut l'ouvrir directement dans un navigateur ou le téléverser sur n'importe quel serveur statique

Option B : Déploiement automatique Vercel (recommandé)

MCP nécessaire : Vercel MCP

Procédure si Vercel MCP est disponible :

1. Claude génère le code source du projet React (/tmp/mini-app-[nom]/)
2. Appel du Vercel MCP pour déployer :
   deploy_to_vercel(project_dir="/tmp/mini-app-[nom]")
3. Le Vercel MCP retourne un lien permanent (https://xxx.vercel.app)
4. Claude affiche le lien à l'utilisateur

⚠️ L'utilisateur doit avoir connecté Vercel MCP dans Claude Code

Si Vercel MCP n'est pas disponible :

# Générer un projet React + vercel.json
python scripts/generate_mini_app_react.py \
  --type "[type]" --grade "[niveau]" \
  --output_dir "/mnt/user-data/outputs/mini-app-[nom]/"

# Afficher les instructions de déploiement à l'utilisateur
echo "Veuillez exécuter les commandes suivantes pour déployer :
cd mini-app-[nom]
npx vercel --prod"

Option C : GitHub Pages

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

# Afficher les instructions de déploiement :
echo "Poussez le dossier sur GitHub, puis activez le déploiement dans Settings > Pages"

Étape 5 : Liste de contrôle qualité

Connecteurs MCP (différences entre plateformes, fonctionnalités de base)

Claude Code (support complet)

Vercel MCP (si connecté) :
  Utilisation : déployer la mini-application sur Vercel en un clic, générer un lien partageable
  Activation : claude mcp add vercel

  Quand l'utiliser : lorsque l'utilisateur dit « déployer sur Vercel » ou « générer un lien partageable »
  Appel MCP : deploy_to_vercel(project_path, project_name)
  Valeur de retour : { url: "https://xxx.vercel.app", deployment_id: "..." }

GitHub MCP / Filesystem (si connecté) :
  Utilisation : créer un dépôt GitHub et activer Pages
  Quand l'utiliser : lorsque l'utilisateur dit « mettre sur GitHub Pages »

Claude.ai (activer dans la page des paramètres)

Actuellement, Vercel MCP nécessite l'environnement Claude Code.
Recommandation pour les utilisateurs Claude.ai :
1. Claude génère un fichier HTML complet unique
2. L'utilisateur le téléverse manuellement sur Vercel / Netlify / GitHub Pages

Plateforme Codex

Prend en charge la génération de scripts de déploiement pour Vercel CLI et GitHub Pages. Vercel MCP, configuré via ~/.codex/config.toml, peut automatiser le déploiement. Si Vercel MCP n'est pas configuré, Claude génère un script deploy.sh complet que l'utilisateur exécute manuellement.

Plateforme Antigravity (Google AI IDE)

MCP peut automatiser le déploiement après configuration du connecteur Vercel via MCP Server Hub. Sinon, Claude génère un script deploy.sh que l'utilisateur exécute manuellement.

Exemple d'appel MCP de déploiement (Claude Code)

# Si Vercel MCP est connecté
[Après génération du code par Claude]
[Appel du Vercel MCP pour déployer]
→ Retourne https://edu-quiz-xxxxx.vercel.app
→ Claude affiche : « ✅ Déployé ! Lien de partage : https://edu-quiz-xxxxx.vercel.app »

Demander à votre IA préférée

Documentation