Desarrollo de miniaplicaciones educativas + Despliegue automático v1.0

Filosofía

"Que cada docente pueda tener su propia herramienta de enseñanza, sin necesidad de saber programar."

Principios de diseño de herramientas interactivas

El problema central de una herramienta de aprendizaje interactivo no es "si es divertida", sino si el estudiante siente que aprendió.

Al diseñar, prioriza tres aspectos:

Autonomía: el estudiante puede elegir dificultad o tipo de ejercicio (en lugar de ser forzado a seguir una sola ruta).
Competencia: la dificultad de la tarea permite al estudiante intentar con éxito, no fracasar repetidamente y rendirse.
Conexión: la herramienta ofrece mecanismos para compartir, comparar o completar actividades en conjunto.

Principios de retroalimentación con puntuación:

Muestra "mejoraste X respuestas desde la última vez" o "respondiste correctamente X veces consecutivas".
No muestres solo la puntuación absoluta o la clasificación.
La sensación de progreso mantiene la motivación más que el ranking, especialmente en estudiantes con bases débiles.

Evitar recompensas puramente extrínsecas: Las recompensas externas como estrellas, insignias o tablas de clasificación reducen la motivación al eliminarse. Prioriza diseñar logros que hagan sentir al estudiante "realmente lo entiendo", en lugar de "obtuve puntos".

Sistema de diseño V2.0: Edu Warm

Basado en Claude Design (2026-04-17) + librería tipográfica canvas-design (Work Sans + Noto Sans TC)

Token CSS de 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;
}

Tipografías prohibidas: Inter, Roboto, Arial — usar Work Sans (títulos) + Noto Sans TC (cuerpo) Modos prohibidos: border-left accent callout (visualmente obsoleto), degradados excesivos, intentos de SVG illustration Extensión cromática: oklch(72% 0.13 50) puede derivar colores cálidos intermedios de Edu Warm

Especificación de componentes Edu Warm (librería compartida canvas-design)

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

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

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

/* Insignia de progreso */
.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; }

Maquetación: estándar de salida HTML artifact

Todas las miniaplicaciones se generan como HTML artifact (vista previa inmediata), garantizando:

Carga de Google Fonts: Work Sans + Noto Sans TC
Definición completa de tokens CSS (variables :root)
Diseño responsive (max-width: 720px centrado)
Soporte para ajustes: si el usuario dice "cambia el color principal", solo se actualiza la variable --primary
text-wrap: pretty aplicado a todos los párrafos para evitar huérfanas

Especificación técnica de React HTML artifact (versiones fijas)

Al usar React, las versiones CDN deben fijarse para evitar cambios externos:

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

Reglas de nomenclatura de objetos de estilo (evitar conflictos de ámbito con Babel):

// ❌ Incorrecto: const styles = {...} causará conflictos en múltiples scripts Babel
// ✅ Correcto: usar nombres únicos
const quizStyles = { container: {...}, question: {...} };
const timerStyles = { display: {...}, controls: {...} };
// Compartir componentes entre scripts
Object.assign(window, { QuizCard, TimerDisplay });

Persistencia de estado (LocalStorage)

Las herramientas que necesitan recordar el progreso (cuestionarios, tarjetas de estudio, configuraciones de temporizador) deben incluir LocalStorage:

// Guardar estado
localStorage.setItem('app_state', JSON.stringify({ score, currentQ, settings }));
// Restaurar estado (continuar después de recargar página)
const saved = JSON.parse(localStorage.getItem('app_state') || '{}');

Paso 0: Leer archivos necesarios

references/mini_app_types.md — Tipos y especificaciones comunes de miniaplicaciones educativas
../../shared/grade-adapter.md — Sistema de adaptación por grado
../../shared/guided-collection.md — Marco de recolección guiada
references/deployment_guide.md — Guía de despliegue en Vercel + GitHub Pages

Protocolo de alineación conceptual (paso previo obligatorio): ../../shared/concept-alignment.md → Antes de ejecutar cualquier tarea, completar la tarjeta de confirmación de alineación conceptual.

Paso 1: Detección de grado + Recolección guiada de información

Primera ronda de preguntas (máximo 3)

Q1: "¿Qué tipo de miniaplicación educativa deseas?
     Tipos comunes (puedes elegir varios o describir tu idea):
     🎯 A. Cuestionario interactivo (opción múltiple/verdadero-falso, con puntuación)
     🎲 B. Herramienta de sorteo/grupos aleatorios
     ⏱ C. Temporizador de clase (con cuenta atrás y sonido)
     🃏 D. Tarjetas de memoria de palabras/conceptos (juego de volteo)
     🎮 E. Juego de emparejar/completar crucigrama
     📊 F. Votación en tiempo real / termómetro emocional
     🔧 G. Otro (por favor describe)"

Q2: "¿Para qué grado de estudiantes?" (si no se detectó)
Q3: "¿Los estudiantes necesitan ingresar datos/nombres? (Si es así, diseñaré campos de entrada)"

Segunda ronda de preguntas (opcional)

Q4: "¿Tienes preguntas, palabras o contenido específico para incluir?
    (Puedes pegarlos directamente, o dime el tema y yo diseño contenido de ejemplo)"
    
Q5: "¿Preferencia de despliegue?
    A. Vercel (recomendado, más rápido y estable, requiere cuenta Vercel)
    B. GitHub Pages (gratuito, requiere cuenta GitHub)
    C. Solo necesito el archivo HTML, yo mismo lo despliego"

Resumen de confirmación

✅ Tipo de miniaplicación: {tipo}
🎓 Grado: {grado}
📝 Contenido: {tema/descripción de preguntas}
🚀 Método de despliegue: {Vercel/GitHub Pages/Local}
🔗 Al finalizar: se generará un enlace permanente compartible

Paso 2: Especificación de arquitectura técnica

Principios de selección técnica

Herramientas interactivas de una sola página (cuestionarios/juegos/temporizadores):
  → HTML puro + CSS + Vanilla JS (archivo .html único)
  → Sin npm, sin frameworks, fácil de usar para el docente

Herramientas interactivas complejas (múltiples páginas/datos en backend):
  → React + Tailwind CSS
  → Despliegue en Vercel

Herramientas con persistencia de datos (necesitan guardar resultados):
  → React + localStorage (sin backend)
  → O Vercel + KV store (con backend)

Sistema de diseño (educativo)

/* Colores principales */
--edu-blue:   #1A5276;   /* Botones de acción principal */
--edu-green:  #1E8449;   /* Correcto/completado */
--edu-orange: #CA6F1E;   /* Advertencia/en progreso */
--edu-gold:   #D4AC0D;   /* Recompensa/destacado */

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

/* Tamaños de texto según grado */
Primaria baja:   Título 2.5rem / Cuerpo 1.5rem / Botón 1.3rem
Primaria media-alta: Título 2rem   / Cuerpo 1.3rem / Botón 1.1rem
Secundaria:     Título 1.8rem / Cuerpo 1.1rem / Botón 1rem
Preparatoria:   Título 1.5rem / Cuerpo 1rem   / Botón 0.9rem

Paso 3: Especificaciones por tipo de miniaplicación

A. Cuestionario interactivo (más común)

Especificaciones funcionales:
- Las preguntas se muestran una por una, con retroalimentación inmediata (correcto/incorrecto + explicación)
- Barra de progreso (pregunta X de Y)
- Sistema de puntuación (+10 por acierto, se puede configurar bonus por tiempo)
- Al finalizar, muestra puntuación total + comentario
- Botón para reintentar
- Soporte para modificar directamente preguntas/opciones (modo docente)

Formato de datos (Claude lo completa automáticamente o según lo proporcionado por el usuario):
const questions = [
  {
    id: 1,
    question: "Texto de la pregunta",
    options: ["Opción A", "Opción B", "Opción C", "Opción D"],
    answer: 0, // índice de la respuesta
    explanation: "Explicación",
    difficulty: 1 // 1=★☆☆ 2=★★☆ 3=★★★
  }
];

B. Sorteo/grupos aleatorios

Especificaciones funcionales:
- Ingresar lista de estudiantes (un nombre por línea)
- Configurar número de grupos o tamaño de grupo
-Animación de asignación aleatoria
- Botón para reagrupar con un clic
- Botón para copiar resultados

Funcionalidades adicionales:
- Modo de enfriamiento (los ya sorteados no se repiten temporalmente)
- Efecto visual de ruleta (opcional)

C. Temporizador de clase

Especificaciones funcionales:
- Modo de cuenta atrás por fases (pensar 1 min/discutir 3 min/presentar 2 min)
- Visualización en letra grande del tiempo restante
- Últimos 10 segundos con cambio de color de advertencia
- Señal sonora al finalizar
- Preajustes por situación de clase:
  * Discusión grupal, reflexión individual, presentación, repaso previo, examen

Visual:
- Pantalla completa (ideal para proyector)
- Modo oscuro (sin fatiga visual)

D. Juego de volteo de tarjetas de memoria

Especificaciones funcionales:
- Emparejamiento por volteo (palabra+definición, pregunta+respuesta, imagen+texto)
- Registro de tiempo + número de intentos
- Animación al completar
- Contenido de tarjetas personalizable

Apto para: aprendizaje de vocabulario, memorización de fórmulas, emparejamiento de eventos históricos

E. Votación en tiempo real / Termómetro emocional

Especificaciones funcionales:
- Lado del docente: muestra pregunta + código QR
- Lado del estudiante (escanea con móvil): selecciona respuesta
- Gráficos estadísticos en tiempo real
Nota: esta función requiere backend, se recomienda usar Vercel + Upstash Redis

Paso 4: Proceso de desarrollo + despliegue

Opción A: Archivo HTML único (más simple)

# Generar un solo archivo HTML
python scripts/generate_mini_app.py \
  --type "[quiz/lottery/timer/flashcard]" \
  --grade "[grado]" \
  --content "[preguntas/contenido JSON]" \
  --output "/mnt/user-data/outputs/[nombre].html"

# El usuario puede abrirlo directamente en el navegador o subirlo a cualquier servidor estático

Opción B: Despliegue automático en Vercel (recomendado)

MCP requerido: Vercel MCP

Flujo si Vercel MCP está disponible:

1. Claude genera el código fuente del proyecto React (/tmp/mini-app-[nombre]/)
2. Llama a Vercel MCP para desplegar:
   deploy_to_vercel(project_dir="/tmp/mini-app-[nombre]")
3. Vercel MCP devuelve el enlace permanente (https://xxx.vercel.app)
4. Claude entrega el enlace al usuario

⚠️ Requiere que el usuario haya conectado Vercel MCP en Claude Code

Si Vercel MCP no está disponible:

# Generar proyecto React + vercel.json
python scripts/generate_mini_app_react.py \
  --type "[tipo]" --grade "[grado]" \
  --output_dir "/mnt/user-data/outputs/mini-app-[nombre]/"

# Imprimir instrucciones de despliegue para el usuario
echo "Ejecuta los siguientes comandos para desplegar:
cd mini-app-[nombre]
npx vercel --prod"

Opción C: GitHub Pages

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

# Imprimir instrucciones de despliegue:
echo "Sube la carpeta a GitHub y habilita el despliegue en Settings > Pages"

Paso 5: Lista de verificación de calidad

Conectores MCP (diferencias por plataforma, funcionalidad central)

Claude Code (soporte completo)

Vercel MCP (si está conectado):
  Uso: desplegar miniaplicaciones en Vercel con un clic, generar enlace compartible
  Habilitar: claude mcp add vercel
  
  Cuándo usarlo: cuando el usuario dice "desplegar en Vercel" o "generar enlace compartible"
  Llamada MCP: deploy_to_vercel(project_path, project_name)
  Valor de retorno: { url: "https://xxx.vercel.app", deployment_id: "..." }

GitHub MCP / Filesystem (si está conectado):
  Uso: crear repositorio GitHub y habilitar Pages
  Cuándo usarlo: cuando el usuario dice "ponerlo en GitHub Pages"

Claude.ai (habilitar en página de configuración)

Actualmente Vercel MCP solo funciona en entorno Claude Code.
Para usuarios de Claude.ai se recomienda:
1. Claude genera un archivo HTML completo
2. El usuario lo sube manualmente a Vercel / Netlify / GitHub Pages

Plataforma Codex

Soporta generación de scripts de despliegue para Vercel CLI y GitHub Pages. Con Vercel MCP configurado en ~/.codex/config.toml, puede desplegar automáticamente. Sin Vercel MCP configurado, Claude genera un script deploy.sh completo que el usuario ejecuta manualmente.

Plataforma Antigravity (Google AI IDE)

MCP se configura a través de MCP Server Hub con Vercel Connector para despliegue automático. Sin configurar, Claude genera un script deploy.sh que el usuario ejecuta manualmente.

Ejemplo de llamada MCP de despliegue (Claude Code)

# Si Vercel MCP está conectado
[Claude genera el código]
[Llama a Vercel MCP para desplegar]
→ Devuelve https://edu-quiz-xxxxx.vercel.app
→ Claude muestra: "✅ ¡Desplegado! Enlace compartible: https://edu-quiz-xxxxx.vercel.app"

Preguntar en tu IA favorita

Documentación