Skill: Padrões de Código HTML

Esta skill garante código HTML limpo, semântico, bem-estruturado e consistente em todo o projeto.

Quando Usar

• Ao criar novos arquivos HTML
• Ao modificar estrutura de páginas existentes
• Quando o usuário mencionar "HTML", "tags", "estrutura"
• Ao revisar ou refatorar código
• Ao corrigir problemas de formatação

Estrutura Básica Obrigatória

Toda página HTML deve seguir esta estrutura:

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>[Título Descritivo da Página]</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
</head>
<body class="bg-light">
    <!-- Conteúdo da página -->

    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html>

Regras de Formatação

1. Indentação

Padrão: 4 espaços

<!-- ✅ Correto -->
<div class="container">
    <div class="row">
        <div class="col-12">
            <p>Conteúdo</p>
        </div>
    </div>
</div>

<!-- ❌ Incorreto (2 espaços ou tabs) -->
<div class="container">
  <div class="row">
      <div class="col-12">
          <p>Conteúdo</p>
      </div>
  </div>
</div>

Regras:

• Use 4 espaços, nunca tabs
• Mantenha consistência em todo o arquivo
• Indente cada nível de aninhamento
• Elementos inline podem ficar na mesma linha quando curtos

2. Comentários HTML

Use comentários para separar seções principais:

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <!-- Head content -->
</head>
<body>
    <!-- Navigation -->
    <nav class="navbar">...</nav>

    <!-- Header Section -->
    <section class="bg-dark">...</section>

    <!-- Card Details -->
    <div class="container my-5">...</div>

    <!-- Footer -->
    <footer class="bg-dark">...</footer>

    <!-- Scripts -->
    <script src="..."></script>
</body>
</html>

Boas práticas:

• Comentários descritivos e concisos
• Em inglês para consistência
• Não comente código óbvio
• Use para delimitar seções grandes

3. Atributos

Ordem recomendada:

1. class
2. id
3. data-*
4. type
5. href / src
6. title
7. alt
8. aria-*
9. role

Exemplos:

<!-- ✅ Correto -->
<button class="btn btn-primary"
        id="submitBtn"
        type="button"
        data-bs-toggle="collapse"
        data-bs-target="#collapse1"
        aria-label="Abrir seção">

<img class="img-fluid rounded"
     src="image.jpg"
     alt="Descrição da imagem">

<!-- ❌ Incorreto (ordem aleatória) -->
<button type="button"
        aria-label="Abrir seção"
        class="btn btn-primary"
        data-bs-toggle="collapse"
        id="submitBtn">

Regras de atributos:

• Sempre use aspas duplas (")
• Um atributo por linha se muitos atributos
• Valores booleanos explícitos quando necessário
• Sem espaços extras ao redor do =

4. Semântica HTML5

Use tags apropriadas:

<!-- ✅ Correto - Tags semânticas -->
<nav>Navegação</nav>
<header>Cabeçalho</header>
<main>Conteúdo principal</main>
<section>Seção</section>
<article>Artigo independente</article>
<aside>Conteúdo lateral</aside>
<footer>Rodapé</footer>

<!-- ❌ Incorreto - Divs para tudo -->
<div class="navigation">...</div>
<div class="header">...</div>
<div class="main-content">...</div>

Hierarquia de Headings:

<!-- ✅ Correto -->
<h1>Título Principal</h1>
    <h2>Seção</h2>
        <h3>Subseção</h3>
    <h2>Outra Seção</h2>
        <h3>Subseção</h3>

<!-- ❌ Incorreto - Pula níveis -->
<h1>Título</h1>
    <h3>Subseção</h3>  ❌

Lista de tags semânticas:

• <nav> - Navegação principal
• <header> - Cabeçalho de página ou seção
• <main> - Conteúdo principal (se aplicável)
• <section> - Seção temática de conteúdo
• <article> - Conteúdo independente
• <aside> - Conteúdo complementar/lateral
• <footer> - Rodapé de página ou seção
• <figure> - Conteúdo referenciado (imagens com legenda)
• <figcaption> - Legenda de figure
• <time> - Datas e horários

5. Links e Navegação

Links relativos:

<!-- ✅ Correto - Caminho relativo correto -->
<a href="../index.html">Voltar</a>
<img src="../assets/image.jpg">

<!-- ❌ Incorreto - Caminho absoluto desnecessário -->
<a href="/home/user/projeto/index.html">Voltar</a>

Texto descritivo:

<!-- ✅ Correto -->
<a href="charizard.html">Ver detalhes do Charizard</a>
<a href="index.html">Voltar ao Portfólio</a>

<!-- ❌ Incorreto -->
<a href="charizard.html">Clique aqui</a>
<a href="index.html">Voltar</a>

Target e rel:

<!-- Links externos -->
<a href="https://exemplo.com" target="_blank" rel="noopener noreferrer">
    Link externo
</a>

<!-- Links internos -->
<a href="../index.html">Link interno</a>

6. Imagens

Atributo alt obrigatório:

<!-- ✅ Correto - Alt descritivo -->
<img src="carta.jpg" alt="Carta Charizard Base Set graduada nota 9">

<!-- ✅ Correto - Imagem decorativa -->
<img src="decoration.png" alt="">

<!-- ❌ Incorreto - Sem alt -->
<img src="carta.jpg">

Classes e estilos:

<!-- ✅ Correto -->
<img src="carta.jpg"
     alt="Carta Pikachu"
     class="w-100 rounded border"
     style="height: 400px; object-fit: contain;">

<!-- ❌ Incorreto - Estilo inline desnecessário -->
<img src="carta.jpg"
     alt="Carta Pikachu"
     style="width: 100%; border-radius: 5px; border: 1px solid #ccc;">

7. Formulários (Se Aplicável)

Labels obrigatórios:

<!-- ✅ Correto -->
<label for="nome">Nome:</label>
<input type="text" id="nome" name="nome" class="form-control">

<!-- ❌ Incorreto - Sem label -->
<input type="text" name="nome" placeholder="Nome">

Estrutura de formulário:

<form action="/submit" method="POST">
    <div class="mb-3">
        <label for="email" class="form-label">Email:</label>
        <input type="email"
               id="email"
               name="email"
               class="form-control"
               required>
    </div>
    <button type="submit" class="btn btn-primary">Enviar</button>
</form>

Padrões Específicos do Projeto

Navbar Padrão

<!-- Navigation -->
<nav class="navbar navbar-expand-lg navbar-dark bg-dark">
    <div class="container">
        <a class="navbar-brand fw-bold" href="../index.html">Cartas Graduadas</a>
        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav">
            <span class="navbar-toggler-icon"></span>
        </button>
        <div class="collapse navbar-collapse" id="navbarNav">
            <ul class="navbar-nav ms-auto">
                <li class="nav-item">
                    <a class="nav-link" href="../index.html">Voltar ao Portfólio</a>
                </li>
            </ul>
        </div>
    </div>
</nav>

Footer Padrão

<!-- Footer -->
<footer class="bg-dark text-white py-4 mt-5 border-top border-secondary">
    <div class="container">
        <div class="row">
            <div class="col-md-6">
                <p class="mb-0 text-secondary">&copy; 2025 Cartas Pokémon TCG Graduadas</p>
            </div>
            <div class="col-md-6 text-md-end">
                <p class="mb-0 text-secondary">Laudo gerado em: DD/MM/YYYY</p>
            </div>
        </div>
    </div>
</footer>

Modal Padrão

<!-- Modal -->
<div class="modal fade" id="modalId" tabindex="-1" aria-labelledby="modalLabel" aria-hidden="true">
    <div class="modal-dialog modal-dialog-centered modal-lg">
        <div class="modal-content bg-dark">
            <div class="modal-header border-secondary">
                <h5 class="modal-title text-white" id="modalLabel">Título</h5>
                <button type="button" class="btn-close btn-close-white" data-bs-dismiss="modal" aria-label="Fechar"></button>
            </div>
            <div class="modal-body text-center p-0">
                <img src="image.jpg" alt="Descrição" class="img-fluid">
            </div>
        </div>
    </div>
</div>

O Que Evitar

❌ CSS Inline ou Tags Style

<!-- ❌ Incorreto -->
<style>
    .custom-class {
        color: red;
    }
</style>

<div style="margin: 10px; padding: 20px; background: blue;">

Exceções permitidas:

• Width de progress bars: style="width: 85%;"
• Height de progress bars: style="height: 25px;"
• Object-fit de imagens: style="object-fit: contain;"

❌ JavaScript Inline

<!-- ❌ Incorreto -->
<button onclick="alert('Hello')">Clique</button>

<!-- ✅ Correto -->
<button class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#myModal">
    Clique
</button>

Exceção: Atributos data-bs-* do Bootstrap são permitidos.

❌ Tabelas para Layout

<!-- ❌ Incorreto -->
<table>
    <tr>
        <td>Menu</td>
        <td>Conteúdo</td>
    </tr>
</table>

<!-- ✅ Correto -->
<div class="row">
    <div class="col-md-3">Menu</div>
    <div class="col-md-9">Conteúdo</div>
</div>

Exceção: Tabelas são OK para dados tabulares reais.

❌ Divs Desnecessárias

<!-- ❌ Incorreto -->
<div>
    <div>
        <div>
            <p>Texto</p>
        </div>
    </div>
</div>

<!-- ✅ Correto -->
<p>Texto</p>

❌ IDs Duplicados

<!-- ❌ Incorreto -->
<div id="item">Item 1</div>
<div id="item">Item 2</div>

<!-- ✅ Correto -->
<div id="item1">Item 1</div>
<div id="item2">Item 2</div>

❌ Mistura de Idiomas

<!-- ❌ Incorreto -->
<h1>Pokemon Cards</h1>
<p>Bem-vindo ao portfólio</p>

<!-- ✅ Correto -->
<h1>Cartas Pokémon</h1>
<p>Bem-vindo ao portfólio</p>

Exceções: Nomes próprios e termos técnicos (ex: "Base Set", "Gem Mint").

Checklist de Código HTML

Ao criar ou modificar HTML:

Estrutura:

• ✅ <!DOCTYPE html> no início
• ✅ <html lang="pt-BR">
• ✅ Meta charset e viewport no <head>
• ✅ Título descritivo
• ✅ CDN do Bootstrap (CSS e JS)

Formatação:

• ✅ Indentação de 4 espaços consistente
• ✅ Comentários para seções principais
• ✅ Ordem de atributos padronizada
• ✅ Aspas duplas em todos os atributos

Semântica:

• ✅ Tags HTML5 semânticas (<nav>, <section>, <footer>)
• ✅ Hierarquia de headings correta
• ✅ Alt em todas as imagens
• ✅ Labels em inputs (se houver)

Boas Práticas:

• ✅ Links relativos corretos
• ✅ Texto descritivo em links
• ✅ Sem CSS inline (exceto exceções)
• ✅ Sem JavaScript inline
• ✅ Sem divs desnecessárias
• ✅ IDs únicos
• ✅ Idioma consistente (português)

Validação

Ferramentas:

• W3C HTML Validator
• Nu Html Checker
• Extensão "HTMLHint" para VS Code

Validação mínima:

• Sem erros críticos
• Sem warnings importantes
• Estrutura bem-formada

Integração com Outras Skills

Esta skill trabalha em conjunto com:

• bootstrap-guidelines: Para classes e componentes Bootstrap
• acessibilidade: Para HTML acessível
• estrutura-paginas: Para layout consistente

Código HTML limpo é a base para um projeto de qualidade. Mantenha os padrões!