HTML, CSS e JavaScript: do que é feita uma página web

O(a) senhor(a) pede ao agente para ajustar a página, e num projeto simples aparecem arquivos com nomes pouco claros: index.html, style.css, script.js. Ou eles já existiam, e no relatório do agente está escrito "mudei os estilos" - e por essa frase não dá para saber em que exatamente ele mexeu.

Vamos analisar três tecnologias básicas que o navegador recebe: HTML, CSS e JavaScript. Para simplificar, vamos usar uma página estática simples, sem build. Em um repositório de verdade os arquivos podem se chamar e ficar localizados de outro jeito, por isso antes de qualquer ajuste vale pedir ao agente para mostrar a estrutura do projeto e encontrar os arquivos responsáveis pelo elemento desejado. Este material não ensina a fazer a marcação à mão - para isso o(a) senhor(a) tem o agente.

A página é um texto que o navegador lê

Vamos começar com uma página estática simples: o código-fonte dela é feito de arquivos de texto comuns. Dá para abri-los num bloco de notas e ler com os próprios olhos. Nenhum build adicional é necessário aqui: o navegador lê o HTML, carrega os recursos ligados a ele e, a partir deles, desenha a página na tela.

O ponto de partida desse tipo de projeto costuma ser o arquivo index.html. O navegador o abre, interpreta a marcação e, pelos links, carrega estilos, scripts, imagens e fontes.

É assim que pode ser organizado um projeto estático simples: o navegador carrega três arquivos ligados entre si e exibe a página

Num projeto com build, o código-fonte pode ficar em componentes, e uma ferramenta específica gera o HTML, o CSS e o JavaScript finais. Os papéis a seguir continuam sendo um mapa útil, mas ali não faz sentido procurar exatamente três arquivos com esses nomes.

No nosso exemplo simples, vamos usar três arquivos com papéis diferentes:

HTML - o que existe na página: título, parágrafo, botão, imagem;
CSS - como isso fica visualmente: cores, fontes, espaçamentos, cantos arredondados, transições suaves;
JavaScript - o que acontece: ao clicar, ao digitar um texto, por temporizador.

Agora, um de cada vez.

HTML: do que é feita a marcação

HTML é marcação, não desenho. O(a) senhor(a) não descreve como o botão deve parecer. O(a) senhor(a) diz "aqui tem um botão" - e o navegador o desenha do jeito que sabe.

A unidade básica da marcação é a tag. Quase sempre são duas: a de abertura e a de fechamento, e entre elas fica o conteúdo.

Neste exemplo, as três partes juntas formam um elemento da página

Cada parte tem seu próprio nome, e o conjunto todo é chamado de elemento. A palavra vai ser útil: ao falar de uma página, costuma-se dizer "elemento", referindo-se à tag junto com o que está dentro dela.

Os nomes das tags são abreviações de palavras em inglês: p de paragraph, a de anchor, img de image. Não há necessidade de decorá-los, mas eles costumam ajudar a adivinhar para que serve uma tag desconhecida.

A tag de fechamento se distingue pela barra. Há também elementos sem tag de fechamento. Por exemplo, <img> não pode conter texto nem tags aninhadas, e recebe o endereço da imagem pelo atributo src.

As tags se aninham umas dentro das outras, como caixas dentro de caixas, e se fecham na ordem inversa - primeiro a interna, depois a externa. Se a ordem for quebrada, o navegador não dá erro, ele tenta adivinhar. Em geral, adivinha mal.

O segundo conceito é o atributo. É um complemento que fica dentro da tag de abertura e diz algo sobre ela: para onde o link leva, de onde vem a imagem, como esse elemento se chama.

<a href="https://example.com">Abrir site</a>
<img src="cover.png" alt="Capa">
<button id="play" class="btn">Jogar</button>

O atributo class da última linha vai ser útil daqui a dois minutos: por meio dele os estilos se aplicarão ao botão. O atributo id="play" dá a ele um nome único, pelo qual o script vai encontrar o botão.

Agora, a página inteira. Ela é mais curta do que se poderia pensar:

<!doctype html>
<html>
<head>
  <title>Minha página</title>
</head>
<body>
  <h1>Primeira página</h1>
  <p>Um parágrafo comum de texto.</p>
  <button id="play" class="btn">Jogar</button>
</body>
</html>

Duas partes: <head> - a parte técnica, onde ficam o título da aba e os links para os estilos; <body> - tudo o que o leitor vê na tela. A primeira linha só avisa ao navegador que ele está diante de um HTML moderno.

Caixa dentro de caixa: head e body ficam dentro do html, e tudo o mais fica dentro deles

O esquema mostra a propriedade principal da marcação: na página tudo fica dentro de alguma coisa. <body> dentro de <html>, o botão dentro de <body>, o texto dentro do botão. Daí a escadinha de recuo no arquivo: ela não está ali por estética, mostra o que está aninhado dentro do quê.

A conclusão prática é simples. O título da aba do navegador e os links para os estilos ficam em <head>, e na tela eles não aparecem de jeito nenhum. Tudo o mais fica em <body>. Quando o agente escreve no relatório "adicionei um bloco no body", isso se refere exatamente à segunda caixa: algo novo apareceu na página, não na parte técnica.

Existem mais de cem tags na linguagem, mas numa página de verdade quase sempre aparecem as mesmas:

Tag	O que faz
`<h1>` ... `<h6>`	títulos, do principal ao mais discreto
`<p>`	parágrafo de texto
`<a>`	link, o endereço fica no atributo `href`
`<img>`	imagem, o caminho do arquivo fica no atributo `src`
`<button>`	botão
`<ul>` e `<li>`	lista e item de lista
`<div>`	bloco-contêiner, uma caixa para outros elementos
`<span>`	um pedaço de texto dentro da linha, para destacá-lo separadamente

Os dois últimos não significam nada por si só e não desenham nada. São caixas vazias, nas quais estilos e scripts se prendem com facilidade - e é exatamente por isso que são os mais numerosos em qualquer página.

CSS: como a página ganha aparência

A marcação pura parece pobre: texto preto em fundo branco, um botão cinza do sistema, tudo colado à esquerda. A maior parte da diferença entre isso e uma página estilizada é criada pelo CSS.

O CSS é feito de regras. Uma regra responde a duas perguntas: a que ela se aplica e o que muda.

.btn {
  background: #6c5ce7;    /* cor de fundo */
  color: #ffffff;         /* cor do texto */
  padding: 12px 24px;     /* espaçamento interno */
  border-radius: 12px;    /* cantos arredondados */
}

A primeira linha é o seletor: ele diz a quais elementos isso se aplica. Depois, entre chaves, vêm pares "propriedade: valor", cada um terminado com ponto e vírgula.

O ponto antes de btn indica uma classe. Lembra-se do atributo class="btn" no botão? Pois é ele que entrou em ação: na marcação o(a) senhor(a) coloca um rótulo no elemento, e nos estilos faz referência a ele. Um mesmo rótulo pode ser colocado em dez botões - e os dez ficam iguais graças a uma única regra.

Existem centenas de propriedades em CSS, mas para ler o arquivo de outra pessoa e entender o que está acontecendo ali, bastam algumas poucas:

color - cor do texto, background - cor ou imagem de fundo;
font-size e font-family - tamanho e família da fonte;
padding - espaçamento dentro do elemento, margin - fora dele, entre vizinhos;
border-radius - cantos arredondados, que também é metade da sensação de "caro";
transition - suavidade: não de repente, mas ao longo de 0,2 segundo.

Na maioria das vezes as regras ficam num arquivo separado, e a página fica sabendo dele por uma única linha na parte técnica:

<head>
  <link rel="stylesheet" href="style.css">
</head>

Se essa linha for removida, o arquivo de estilos não carrega. O texto e os elementos continuam na marcação, mas o layout e a aparência costumeiros podem desaparecer, e às vezes fica mais difícil usar a página.

Os elementos são os mesmos e na mesma ordem. Só mudaram a cor, os espaçamentos e a forma

No esquema, à esquerda e à direita está a mesma página: título, duas linhas de texto, um botão. Nenhum elemento foi adicionado ou removido - neste exemplo, só o arquivo de estilos foi alterado.

Isso é um mapa de busca, não uma parede técnica. Para um novo layout, às vezes o agente precisa mudar classes ou contêineres no HTML, e uma regra CSS malfeita pode encobrir um botão e atrapalhar o clique. Por isso, depois de um ajuste visual, confere-se o diff, abre-se a página e testam-se as ações afetadas.

JavaScript: o que acontece a partir de uma ação

HTML e CSS já sabem mostrar a página e dar a ela transições suaves ou animação. Mas o botão do nosso exemplo ainda não tem ação própria: clicamos - a contagem não muda.

Uma lógica arbitrária na página costuma ser adicionada pelo JavaScript. O botão já recebeu no HTML um nome único, id="play". Agora o esquema é simples: encontrar o elemento, esperar um evento, mudar alguma coisa.

// encontramos o botão pelo seu id
const button = document.getElementById("play");
let score = 0;

// escutamos o evento: o que fazer ao clicar
button.addEventListener("click", function () {
  score = score + 1;
  button.textContent = "Pontos: " + score;
});

O primeiro clique muda o texto para "Pontos: 1", o segundo, para "Pontos: 2". Se nada acontecer, verifique primeiro se no HTML está escrito id="play" e se no script está o mesmo nome play.

Aqui há três detalhes. const e let criam uma variável - uma caixa nomeada com um valor. addEventListener faz a página escutar um evento: clique, digitação de texto, passar o mouse por cima. E dentro das chaves fica uma função - um trecho de código que será executado quando o evento acontecer.

Repare na última linha: o script muda o texto do botão. Este é um ponto importante - o JavaScript sabe mudar tanto a marcação quanto os estilos com a página já em funcionamento. Ele pode adicionar um parágrafo, esconder um bloco, mudar a cor de um botão. Por isso a fronteira entre as camadas não é uma parede, e sim uma divisão de trabalho.

Na prática, comece a busca em JavaScript se o elemento reage a dados, processa um clique ou calcula alguma coisa. Um aparecimento suave, uma mudança de cor e um movimento simples costumam ser feitos pelo CSS. Isso é um ponto de partida, não um diagnóstico definitivo: depois do ajuste, abra a página e confira pessoalmente a aparência e as ações - uma única captura de tela não basta.

Um botão em três arquivos

Vamos juntar tudo em um único elemento. O botão "Jogar" vive ao mesmo tempo em três arquivos, e cada um responde pela sua parte.

<button id="play" class="btn">Jogar</button>

.btn {
  background: #6c5ce7;
  border-radius: 12px;
}

const playButton = document.getElementById("play");

playButton.addEventListener("click", function () {
  playButton.textContent = "Jogo iniciado";
});

Se os arquivos estiverem ligados, o clique muda o texto de "Jogar" para "Jogo iniciado". Agora dá para testar o exemplo sem precisar inventar uma função que falta.

E agora a parte mais útil - o que acontece se removermos uma linha de cada vez:

removeu o HTML - tudo desapareceu: não há mais nada para estilizar nem para dar vida;
removeu o CSS - o botão continua no lugar e funciona, só que parece um botão cinza de sistema dos anos noventa;
removeu o JS - o botão está bonito, mas morto. Clica, e nada acontece.

Daí um mapa simples para formular uma tarefa. Se o(a) senhor(a) não gosta da aparência, comece a busca pelos estilos. Se não gosta do que acontece, comece pelo script. Se o elemento nem existe, comece pela marcação. É "comece" mesmo: um ajuste de verdade pode afetar a camada vizinha, por isso o resultado do agente é conferido pelo diff e no navegador.

O que fica na pasta do projeto

O conjunto mais comum para uma página simples é assim:

index.html    marcação, ponto de entrada
style.css     estilos
script.js     comportamento

Eles se ligam por duas linhas na marcação. Os estilos são incluídos na parte técnica; o script, bem no final, antes do fechamento de </body>, para que, no momento de sua execução, todos os elementos já existam:

<head>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <!-- marcação da página -->
  <script src="script.js"></script>
</body>

Também pode ser diferente. Num projeto grande há dezenas de arquivos, distribuídos em pastas como css/ e js/, e ao lado ficam imagens e fontes. Também pode ser o contrário, quando existe um único arquivo - esse caso vem logo abaixo. Os papéis de marcação, estilos e lógica continuam os mesmos, mas os nomes dos arquivos e o jeito de incluí-los podem mudar.

Quando estilos e scripts ficam dentro da própria página

Três arquivos é o arranjo mais comum, mas não o único. O mesmo CSS pode ser colocado em três lugares diferentes, e os três, mais cedo ou mais tarde, vão aparecer para o(a) senhor(a).

O primeiro o(a) senhor(a) já viu: um arquivo separado mais uma linha <link>. O segundo é um bloco <style> direto na marcação, sem arquivo separado:

<head>
  <style>
    .btn {
      background: #6c5ce7;
      border-radius: 12px;
    }
  </style>
</head>

Por dentro é tudo igual: seletor, chaves, pares "propriedade: valor". Só mudou o lugar. Escreve-se assim quando só existe uma página e não faz sentido criar um arquivo separado para ela.

O terceiro lugar são os estilos em linha, também chamados de inline styles. As propriedades ficam direto no elemento, no atributo style:

<button class="btn" style="background: #e17055; font-size: 20px">Jogar</button>

Aqui não é preciso seletor: já fica claro a que a regra se aplica - ao elemento no qual ela está escrita. Por isso, nem chaves, nem ponto antes da classe, só pares "propriedade: valor" separados por ponto e vírgula, tudo numa única linha.

Isso é conveniente exatamente uma vez. Depois disso começam as desvantagens. A regra vale para um único elemento: dez botões, dez cópias, e depois será preciso mudar todas as dez. Um estilo em linha comum costuma ter prioridade sobre uma regra comum vinda de arquivo. O(a) senhor(a) pinta o botão pelo style, depois ajusta a mesma propriedade em style.css e não entende por que a cor não muda. Por isso o atributo style é um dos primeiros a ser conferido; regras detalhadas de prioridade ainda não são necessárias.

Com o script é a mesma história, só que com dois lugares. Um arquivo separado é incluído por <script src="...">, ou dá para escrever o código direto entre as tags:

<script>
  document.getElementById("play").addEventListener("click", function () {
    alert("Jogo iniciado");
  });
</script>

Vamos reunir tudo numa tabela, para ter onde consultar:

O quê	Onde fica	Como fica no HTML
estilos	arquivo separado	`<link rel="stylesheet" href="style.css">`
estilos	bloco na própria página	`<style>` ... `</style>`
estilos	direto no elemento	`style="color: red"`
script	arquivo separado	`<script src="script.js"></script>`
script	bloco na própria página	`<script>` ... `</script>`

O caso extremo é quando está tudo junto: marcação, bloco <style> e bloco <script> vivem num único index.html. Não há nada de errado nisso, para uma página pequena até fica mais simples: um único arquivo, abriu no navegador e funciona, nada se perde pelo caminho. As dificuldades começam depois, quando a página cresce e é preciso encontrar algo dentro desse emaranhado. Aí o conteúdo costuma ser distribuído em arquivos, e surge exatamente aquele trio.

Antes de pedir ao agente para "mudar os estilos", descubra onde eles ficam. Se o projeto tem um único index.html, pode não existir um arquivo style.css, e o ajuste vai acabar acontecendo dentro da marcação. Se o elemento não muda, peça para conferir três coisas: se o arquivo de estilos necessário está incluído, se o seletor é adequado e se não há um style em linha ou uma regra mais forte. Assim a busca se estreita sem chutar o culpado.

Como isso funciona junto com o Claude Code

Agora está claro o que acontece quando o agente mexe numa página:

num projeto estático simples, o agente pode escrever e ligar sozinho o HTML, o CSS e o JavaScript. Em outro projeto, primeiro peça a ele para mostrar a estrutura e nomear os arquivos responsáveis pelo elemento desejado;
o que exatamente fica visível antes de gravar depende das configurações e do modo de trabalho. Se o agente mostra a proposta com antecedência, revise-a; depois de gravar, de qualquer forma, examine o diff e os arquivos finais. O nome style.css sugere o papel do arquivo, mas ainda não garante nada;
confira um ajuste visual com os olhos e clicando nos elementos afetados, e um ajuste de comportamento, com ações reais. Uma captura de tela não mostra que o contador parou de contar;
se algo quebrou, descreva o sintoma observado, não a camada suposta: "depois do ajuste, o botão aparece, mas o clique não faz nada". Assim o agente vai conferir as ligações entre HTML, CSS e JavaScript.