Plano de melhoria do layout da home (index.md) com foco na experiência dos alunos. Criado em 2026-09-23 e aprovado pelo usuário com escopo completo (4 etapas).

• Branch: feat/home-ui-ux
• Mockup aprovado: https://claude.ai/artifact/1japwa9Ed9aRgtegtUAcDy
• Situação em 2026-09-24: código das 4 etapas commitado como wip (1c6ed388), ajustes visuais feitos depois do mockup e build local no Docker concluído. Teste visual feito em 375, 768 e 1280 px nos dois temas. Falta commitar os ajustes e abrir o PR (seção 5).
• Histórico: em 2026-09-23 o computador travou antes do build. Os arquivos sobreviveram, mas a nota de fim de linha em docs/DECISOES_TECNICAS.md não está no disco e precisa ser refeita, se ainda for desejada.

---

1. Diagnóstico da home antiga

#	Problema	Evidência
1	O menu do topo recebia as 40 entradas da sidebar (navigation.main), com títulos longos e quase tudo no menu de excesso	_data/navigation.yml (40 itens, ~800 subitens)
2	Não havia ponto de partida: nada dizia “comece pelo Mod 01”	index.md (Central de Navegação Rápida)
3	A Fase 5 misturava módulos obrigatórios (09–14) com 8 especializações opcionais	index.md
4	Os cards mostravam só o título, sem descrição, nível, pré-requisito nem tipo (Módulo/Especialização)	.course-card em style.scss
5	A sequência Fase 1 → Fase 5 não aparecia visualmente, e o Mod 06 estava na Fase 1, antes do 03	index.md
6	“Projetos Full Stack” aparecia duas vezes e o Guia de Linguagens não aparecia	HTML gerado
7	Conteúdo de mantenedor (Governança, Auditoria, De-Para, Changelog, Testes) ocupava o fim da home	index.md
8	QR Code solto no meio da página, com fundo branco fixo no modo escuro	index.md
9	A busca só era citada via Ctrl+K, que não existe no celular	index.md
10	Estilos inline e cores fixas fora dos tokens claro/escuro	index.md, style.scss

2. Decisões tomadas

• Escopo: aplicar as 4 etapas.
• Mod 06 (Git): movido para a Fase 2, depois do Mod 05.
• Menu curto: fica em _data/masthead.yml, e não em _data/navigation.yml, porque o navigation.yml é regerado por script e sobrescrito inteiro.
• Validador de Liquid: o index.md foi acusado a princípio. O validador procura Liquid “didático” dentro das aulas, mas na home o Liquid é real. A versão atual passa.

3. Etapas e status

Etapa 1 — Arquitetura da informação ✅ validado

1. Topo da página (hero) com “🚀 Começar pelo Mod 01”, “🗺️ Ver grade completa” e campo de busca visível que abre o mesmo modal do Ctrl+K.
2. Bloco “Como estudar aqui” com 3 passos (Tópico → Exemplos → Exercícios/Quiz).
3. Trilha principal (Mod 01–14 em 5 fases) separada das especializações (Backend / Frontend / Mobile / Sistemas / Segurança, cada uma com pré-requisito).
4. Link duplicado de Projetos removido e Guia de Linguagens incluído.
5. Links de mantenedor movidos para docs/index.md (seção “🧰 Recursos de Manutenção”).

Etapa 2 — Navegação global ✅ validado

1. Menu curto (Trilha · Especializações · Projetos · Guias · Grade) em _data/masthead.yml, renderizado pelo override _includes/masthead.html. O navigation.main continua alimentando a sidebar das páginas internas.

Etapa 3 — Componentes visuais ✅ validado

1. Card rico em _includes/portal-card.html, alimentado por _data/cursos.yml (ícone, título curto, descrição e selos).
2. Linha do tempo das fases (.ph-timeline) em CSS puro.
3. Cores em variáveis CSS com versões clara e escura em assets/css/portal-home.css, carregado só na home.
4. QR Code numa seção própria perto do rodapé (.ph-qr), com fundo que se adapta ao tema.

Etapa 4 — Acessibilidade e qualidade ✅ validado

1. aria-hidden nos emojis e :focus-visible nos cards. Contraste AA conferido por script (texto real, não emoji) em 375, 768 e 1280 px, nos temas claro e escuro: nenhuma falha.
2. validate_liquid.py ✅. Build no Docker ✅ (cerca de 160 s). Sem rolagem horizontal nas 3 larguras, sem imagens quebradas e os 50 links internos da home funcionam.

Ajustes depois do wip (2026-09-24)

• Tokens de cor, largura (1120 px) e base de 16 px alinhados ao mockup, com fundo próprio na home e o rodapé do tema escondido nela.
• Barra do topo compacta, com masthead_title curto no _config.yml e botão “🔍 Buscar Ctrl K”.
• Busca no celular: a lupa voltou ao botão, e o campo do modal, que ficava espremido a ~8 px por causa do .search-icon { width: 100% } do tema, agora tem ~220 px.
• Rodapé com “Portal ADS” e linha de ©.
• Recuo lateral de 16 px abaixo de 1160 px, porque o texto encostava a 4 px da borda no celular e no tablet.
• O rodapé da home reserva embaixo o espaço do botão fixo “voltar ao topo”, que antes cobria o QR Code no fim da página.
• Na home, o botão “voltar ao topo” usa as cores de destaque dela e uma seta de texto no lugar do emoji ⬆️. As outras páginas não mudaram.

Observações fora do escopo

• Os resultados da busca mostram código Mermaid cru nos resumos, e “git” também casa com palavras como “Digital”. O problema é do índice de busca, não da home.
• O docker_build.sh falha no rm -rf _site_local quando existem caminhos longos (obj/Debug/net8.0/... em proj_aplicacoes_full_stack). Uma segunda execução ou um docker cp manual do container resolve.

4. Próximos passos

1. ✅ python _scripts/test_links.py no build de 2026-09-24: 4513 páginas, nenhum link quebrado.
2. Commitar os ajustes pendentes (_config.yml, _includes/head/custom.html, _layouts/portal-home.html, assets/css/portal-home.css, este plano).
3. Abrir o PR de feat/home-ui-ux para main.

---

📚 Voltar à Documentação