Desenvolvimento de Miniaplicativos Educacionais + Implantação Automática v1.0
Filosofia
"Que cada professor possa ter suas próprias ferramentas de ensino, sem necessidade de conhecimento em programação."
Princípios de Design de Ferramentas Interativas
A questão central de uma ferramenta de aprendizagem interativa não é "é divertida?", mas sim se o aluno sentiu que aprendeu.
Ao projetar, priorize três coisas:
- Autonomia: o aluno pode escolher a dificuldade ou o tipo de questão (em vez de ser forçado a seguir o mesmo caminho).
- Competência: a dificuldade da tarefa permite que o aluno tente e tenha sucesso, em vez de falhar repetidamente e desistir.
- Conexão: a ferramenta oferece mecanismos para compartilhar, comparar ou trabalhar em conjunto.
Princípios de feedback com pontuação:
- Mostre "você melhorou X questões em relação à última vez" ou "você acertou X questões consecutivas".
- Não exiba apenas a pontuação absoluta ou o ranking.
- A sensação de progresso mantém a motivação para aprender mais do que o ranking – especialmente para alunos com dificuldades.
Evite recompensas puramente extrínsecas: Recompensas externas como estrelas, medalhas e rankings diminuem a vontade de aprender quando removidas. Priorize feedback de realização que faça o aluno sentir "eu realmente entendi", em vez de feedback de troca do tipo "eu ganhei pontos".
Sistema de Design V2.0: Edu Warm
Baseado em Claude Design (2026-04-17) + biblioteca de fontes 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;
}
Fontes proibidas: Inter, Roboto, Arial — usar Work Sans (títulos) + Noto Sans TC (corpo) Modos proibidos: border-left accent callout (visual desatualizado), gradiente excessivo, tentativas de SVG ilustrativo Extensão de cor:
oklch(72% 0.13 50)pode derivar tons intermediários quentes Edu Warm
Especificações de Componentes Edu Warm (biblioteca de componentes compartilhada canvas-design)
/* Botão */
.btn-primary { background: #d97757; color: white; border-radius: 8px;
padding: 12px 24px; font: Work Sans Bold 16px; }
/* Cartão */
.card { background: white; border-radius: 12px; padding: 24px;
box-shadow: 0 4px 24px rgba(0,0,0,0.08); }
/* Bloco de destaque */
.callout { border-left: 4px solid #d97757; background: rgba(217,119,87,0.08);
padding: 16px 20px; border-radius: 0 8px 8px 0; }
/* Emblema de progresso */
.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: Padrão de saída de artefato HTML
Todos os miniaplicativos devem ser gerados como artefatos HTML (visualização instantânea), garantindo:
- Carregamento de Google Fonts: Work Sans + Noto Sans TC
- Definição completa dos tokens CSS (variáveis :root)
- Design responsivo (max-width: 720px centralizado)
- Suporte a modo de ajuste fino: usuário diz "mudar cor primária" e apenas a variável --primary é atualizada
text-wrap: prettypara todos os parágrafos de texto, evitando órfãos
Especificações Técnicas para Artefato HTML React (versão fixa)
Ao usar React, a versão CDN deve ser fixa para evitar alterações externas:
<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>
Regras de nomenclatura para objetos de estilo (evitar conflitos de escopo do Babel):
// ❌ Errado: const styles = {...} conflita em múltiplos scripts Babel
// ✅ Correto: use nomes únicos
const quizStyles = { container: {...}, question: {...} };
const timerStyles = { display: {...}, controls: {...} };
// Compartilhar componentes entre scripts
Object.assign(window, { QuizCard, TimerDisplay });
Persistência de Estado (LocalStorage)
Ferramentas que precisam lembrar o progresso (questionários, cartões de estudo, configurações de temporizador) devem usar LocalStorage:
// Salvar estado
localStorage.setItem('app_state', JSON.stringify({ score, currentQ, settings }));
// Restaurar estado (continuar após recarregar a página)
const saved = JSON.parse(localStorage.getItem('app_state') || '{}');
Passo 0: Ler Documentos Necessários
references/mini_app_types.md— Tipos comuns de miniaplicativos educacionais e suas especificações../../shared/grade-adapter.md— Sistema de adaptação por série escolar../../shared/guided-collection.md— Estrutura de coleta guiadareferences/deployment_guide.md— Guia de implantação no Vercel + GitHub Pages
Protocolo de Alinhamento Conceitual (etapa obrigatória antes de qualquer trabalho):
../../shared/concept-alignment.md
→ Antes de executar qualquer tarefa, complete o cartão de verificação de alinhamento conceitual.
Passo 1: Detecção de Série + Coleta Guiada de Informações
Primeira Rodada de Perguntas (máximo 3)
P1: "Que tipo de miniaplicativo educacional você deseja?
Tipos comuns (pode selecionar múltiplos ou descrever sua ideia):
🎯 A. Questionário interativo (múltipla escolha/verdadeiro-falso, com pontuação)
🎲 B. Ferramenta de sorteio/formação de grupos
⏱ C. Cronômetro de sala de aula (com contagem regressiva e som)
🃏 D. Cartões de memória para palavras/conceitos (jogo de virar cartas)
🎮 E. Jogo de palavras cruzadas/combinação
📊 F. Votação em tempo real/termômetro de emoções
🔧 G. Outro (descreva)"
P2: "Para qual série os alunos usam?" (se não detectado)
P3: "Os alunos precisam inserir dados/nomes? (Se sim, projetarei campos de entrada)"
Segunda Rodada de Perguntas (opcional)
P4: "Você tem perguntas, palavras ou conteúdo específico para incluir?
(Pode colar diretamente ou me informar o tema para eu criar conteúdo de exemplo)"
P5: "Preferência de implantação?
A. Vercel (recomendado, mais rápido e estável, requer conta Vercel)
B. GitHub Pages (gratuito, requer conta GitHub)
C. Preciso apenas do arquivo HTML, eu mesmo implanto"
Resumo de Confirmação
✅ Tipo de miniaplicativo: {tipo}
🎓 Série aplicável: {série}
📝 Conteúdo: {tema/descrição das perguntas}
🚀 Método de implantação: {Vercel/GitHub Pages/Local}
🔗 Após conclusão: link permanente compartilhável gerado
Passo 2: Especificações da Arquitetura Técnica
Princípios de Escolha Técnica
Ferramentas interativas de página única (questionários/jogos/cronômetros):
→ HTML puro + CSS + Vanilla JS (arquivo .html único)
→ Sem npm, sem frameworks, fácil de usar para professores
Ferramentas interativas complexas (várias páginas/dados de backend):
→ React + Tailwind CSS
→ Implantar no Vercel
Ferramentas com persistência de dados (precisam salvar resultados):
→ React + localStorage (sem backend)
→ Ou Vercel + KV store (com backend)
Sistema de Design (para fins educacionais)
/* Cores principais */
--edu-blue: #1A5276; /* Botões de ação principal */
--edu-green: #1E8449; /* Correto/concluído */
--edu-orange: #CA6F1E; /* Alerta/em andamento */
--edu-gold: #D4AC0D; /* Recompensa/destaque */
/* Fontes */
--font-main: 'Noto Sans TC', 'Microsoft JhengHei', sans-serif;
/* Tamanhos de fonte por série */
Ensino Fundamental I (1º-4º ano): Título 2.5rem / Corpo 1.5rem / Botão 1.3rem
Ensino Fundamental II (5º-9º ano): Título 2rem / Corpo 1.3rem / Botão 1.1rem
Ensino Médio (10º-12º ano): Título 1.8rem / Corpo 1.1rem / Botão 1rem
Ensino Superior: Título 1.5rem / Corpo 1rem / Botão 0.9rem
Passo 3: Especificações por Tipo de Miniaplicativo
A. Questionário Interativo (mais comum)
Especificações funcionais:
- Perguntas exibidas uma a uma, feedback imediato após seleção (correto/errado + explicação)
- Barra de progresso (Questão X / Total Y)
- Sistema de pontuação (+10 por acerto, bônus de tempo configurável)
- Exibição da pontuação final + comentário de desempenho
- Botão para refazer o questionário
- Perguntas/opções podem ser editadas diretamente (modo professor)
Formato de dados (Claude preenche automaticamente ou conforme fornecido pelo usuário):
const questions = [
{
id: 1,
question: "Texto da pergunta",
options: ["Opção A", "Opção B", "Opção C", "Opção D"],
answer: 0, // índice da resposta correta
explanation: "Explicação",
difficulty: 1 // 1=★☆☆ 2=★★☆ 3=★★★
}
];
B. Sorteio/Formação de Grupos
Especificações funcionais:
- Inserir lista de alunos (um nome por linha)
- Definir número de grupos ou tamanho de cada grupo
- Animação de divisão aleatória
- Botão para reagrupar com um clique
- Botão para copiar resultado
Funcionalidades extras:
- Modo de resfriamento (alunos já sorteados não são sorteados novamente temporariamente)
- Efeito visual de roleta de sorteio (opcional)
C. Cronômetro de Sala de Aula
Especificações funcionais:
- Modo de temporizador com múltiplos estágios (reflexão 1 min/discussão 3 min/apresentação 2 min)
- Exibição da contagem regressiva em letras grandes
- Alerta de mudança de cor nos últimos 10 segundos
- Alerta sonoro (ao finalizar)
- Predefinições para contextos de aula:
* Discussão em grupo, reflexão individual, apresentação, revisão pré-aula, prova
Visual:
- Exibição em tela cheia (ideal para projetor)
- Modo escuro (não ofuscante)
D. Jogo de Virar Cartas de Memória
Especificações funcionais:
- Combinar cartas viradas (palavra + definição, pergunta + resposta, imagem + palavra)
- Registro de tempo + número de tentativas de combinação
- Animação de conclusão
- Conteúdo dos cartões personalizável
Aplicações: aprendizagem de vocabulário, memorização de fórmulas, combinação de eventos históricos
E. Votação em Tempo Real/Termômetro de Emoções
Especificações funcionais:
- Lado do professor: exibe pergunta + QR Code
- Lado do aluno (escaneia com celular): clica na resposta
- Gráficos estatísticos em tempo real
Atenção: esta funcionalidade requer suporte de backend, recomendado usar Vercel + Upstash Redis
Passo 4: Fluxo de Desenvolvimento + Implantação
Opção A: Arquivo HTML Único (mais simples)
# Gerar arquivo HTML único
python scripts/generate_mini_app.py \
--type "[quiz/lottery/timer/flashcard]" \
--grade "[série]" \
--content "[perguntas/conteúdo JSON]" \
--output "/mnt/user-data/outputs/[nome].html"
# O usuário pode abrir diretamente no navegador ou enviar para qualquer servidor estático
Opção B: Implantação Automática no Vercel (recomendado)
MCP necessário: Vercel MCP
Fluxo quando o Vercel MCP está disponível:
1. Claude gera o código-fonte do projeto React (/tmp/mini-app-[nome]/)
2. Chama o Vercel MCP para implantar:
deploy_to_vercel(project_dir="/tmp/mini-app-[nome]")
3. Vercel MCP retorna o link permanente (https://xxx.vercel.app)
4. Claude exibe o link para o usuário
⚠️ Necessário que o usuário já tenha conectado o Vercel MCP no Claude Code
Se o Vercel MCP não estiver disponível:
# Gerar projeto React + vercel.json
python scripts/generate_mini_app_react.py \
--type "[tipo]" --grade "[série]" \
--output_dir "/mnt/user-data/outputs/mini-app-[nome]/"
# Exibir instruções de implantação para o usuário
echo "Execute os comandos abaixo para implantar:
cd mini-app-[nome]
npx vercel --prod"
Opção C: GitHub Pages
python scripts/generate_github_pages.py \
--type "[tipo]" --grade "[série]" \
--output_dir "/mnt/user-data/outputs/mini-app-[nome]/"
# Exibir instruções de implantação:
echo "Envie a pasta para o GitHub e ative a implantação em Settings > Pages"
Passo 5: Lista de Verificação de Qualidade
- Compatível com dispositivos móveis (funciona normalmente em celular/tablet)
- Tamanho da fonte adequado para a série escolar
- Suporte a operações por toque
- Contraste de cores atende aos padrões de acessibilidade (WCAG AA)
- Botão de retorno/redefinição disponível
- Não requer conta para uso (lado do aluno)
- Exibição correta em chinês (fonte incorporada ou especificada como fallback)
- Implantação bem-sucedida e link de teste acessível
- Versão do React fixada (18.3.1 + Babel 7.29.0)?
- Nome do objeto de estilo único (não
const styles)? - Ferramentas que precisam lembrar progresso usam LocalStorage?
- Sem gradiente excessivo, sem tentativas de SVG ilustrativo, sem border-left accent callout?
-
text-wrap: prettyaplicado?
Conectores MCP (variações por plataforma, funcionalidade principal)
Claude Code (suporte completo)
Vercel MCP (se conectado):
Uso: implantar miniaplicativo no Vercel com um clique, gerar link compartilhável
Ativação: claude mcp add vercel
Quando usar: usuário diz "implantar no Vercel" ou "gerar link compartilhável"
Chamada MCP: deploy_to_vercel(project_path, project_name)
Retorno: { url: "https://xxx.vercel.app", deployment_id: "..." }
GitHub MCP / Filesystem (se conectado):
Uso: criar repositório GitHub e ativar Pages
Quando usar: usuário diz "colocar no GitHub Pages"
Claude.ai (ativar na página de configurações)
Atualmente, o Vercel MCP só pode ser usado no ambiente Claude Code.
Para usuários do Claude.ai, recomenda-se:
1. Claude gera um arquivo HTML único completo
2. O usuário faz upload manualmente para Vercel / Netlify / GitHub Pages
Plataforma Codex
Suporta geração de scripts de implantação para Vercel CLI e GitHub Pages. Com o Vercel MCP configurado via ~/.codex/config.toml, a implantação pode ser automática.
Sem o Vercel MCP configurado, o Claude gera um script deploy.sh completo para execução manual.
Plataforma Antigravity (Google AI IDE)
O MCP pode ser configurado via MCP Server Hub com Vercel Connector para implantação automática.
Sem configuração, o Claude gera um script deploy.sh para execução manual.
Exemplo de Chamada MCP para Implantação (Claude Code)
# Se o Vercel MCP estiver conectado
[Claude gera o código]
[Chama Vercel MCP para implantar]
→ Retorna https://edu-quiz-xxxxx.vercel.app
→ Claude exibe: "✅ Implantado! Link compartilhável: https://edu-quiz-xxxxx.vercel.app"