Landing build
Transforme o copy aprovado, a direção visual e os tokens de design em uma
página estática que funcione completamente com o JavaScript desligado.
Completo significa que um visitante pode ler cada seção, alcançar cada seção
a partir do cabeçalho e enviar o formulário. Movimento e 3D vêm depois,
através de landing-skills:landing-motion, e se baseiam em uma página que já
funciona.
Dois bugs apareceram em mais de uma build de teste feita sem este skill, e ele é moldado para tornar ambos impossíveis:
- Uma classe container com um shorthand
paddingsobrescreveu o padding vertical da seção, fazendo com que cada seção ficasse grudada na seguinte. A correção é estrutural: a seção controla o eixo de bloco, o container controla o eixo inline, e nenhum usa o shorthand (etapa 5). - Um formulário morto:
action="#",onsubmit="return false", ou um script que mostrava "Obrigado" e descartava os dados. A correção: umactionreal, ummethodreal, uma página de sucesso apoiada pelo servidor e nenhuma mensagem de sucesso que a página não possa confirmar (etapa 8).
Entradas
Leia estes itens do projeto do usuário antes de escrever código.
| Arquivo | O que você obtém dele |
|---|---|
landing/brief.md | os campos que landing-skills:landing-page escreve. Você usa: Idioma (para lang); Ação de conversão (um formulário com seus campos e endpoint ou nenhum ainda, ou uma URL externa); Stack (conforme nomeado, ou detectar); Domínio (o domínio de produção, ou desconhecido); Rotas de contato (para o rodapé e /form-error/); Assets disponíveis |
landing/copy.md | um H2 por seção da página na ordem da página; o último H2, Placeholders, lista cada lacuna |
landing/direction.md | tipografias com fonte e licença, a linha de layout para cada seção, imagens com proporções, superfícies, e o H2 final Intenção de movimento e 3D |
landing/tokens.css | as propriedades customizadas: --color-*, --font-*, --text-*, --space-*, --radius-* |
Quando uma entrada estiver ausente:
- Sem
copy.md: não escreva copy de marketing você mesmo. Peça ao usuário o texto ou sugiralanding-skills:landing-copy. Se o usuário fornecer o texto, use-o como escrito. Nunca invente prova: nenhum depoimento, logotipos, contagens ou avaliações. Uma peça ausente se torna[PLACEHOLDER: o que é necessário]. - Sem
direction.mdoutokens.css: sugiralanding-skills:landing-art-directionprimeiro. Se o usuário quiser continuar sem eles, escrevalanding/tokens.cssvocê mesmo com os cinco prefixos, derive os valores das restrições de marca que o usuário fornecer, e informe ao usuário que esses tokens são provisórios. - Sem
brief.md: pergunte pelo idioma, a ação de conversão (um formulário e para onde deve enviar, ou uma URL externa), o domínio de produção e uma rota de contato. - Um campo do brief que diz
desconhecidoounenhum aindaé uma lacuna, não um erro: construa com a regra que este skill fornece para ele (sem tags de URL sem um domínio, o placeholder/api/leadsem um endpoint, uma linha de contato placeholder sem rotas de contato) e liste-o na entrega. Detecte o stack a partir dos arquivos do projeto (veja "Detecção de stack") em vez de perguntar quando puder.
Processo
1. Detecte o stack
Use a tabela em "Detecção de stack". Leia a seção correspondente de
references/adapters.md antes de escrever arquivos; ela cobre apenas o que
difere das receitas simples nas outras referências.
2. Faça um inventário
Antes de qualquer marcação, anote:
- Cada H2 de
copy.mde o<section>que ele se torna, com seuid. - Cada nome de token em
tokens.css. Você usará esses nomes e nenhum outro para cor, tipo, espaçamento e raio. - Cada imagem que a direção pede, sua proporção e se o arquivo existe.
- A ação de conversão do brief: uma URL externa (um link, sem formulário),
ou um formulário com seus campos e endpoint. Com o endpoint
nenhum ainda, o formulário envia para/api/leade essa lacuna vai para a entrega (etapa 11). - O Domínio (
conhecidooudesconhecido) e as Rotas de contato, que o head, o rodapé e/form-error/precisam.
3. Escreva o head
Título, descrição, canônico, Open Graph e cartão social, conjunto de favicons,
theme-color, lang, dados estruturados. Modelos e regras estão em
references/seo-meta.md. Escreva o título e a descrição a partir de
copy.md; um título padrão como o título inicial do framework é um indicativo.
4. Carregue as fontes
Auto-hospede os arquivos WOFF2 nomeados na direção, declare @font-face com
nomes de família que correspondam exatamente aos stacks em tokens.css,
adicione um fallback com métrica correspondente e pré-carregue apenas um ou
dois arquivos usados acima da dobra. references/performance.md tem a receita
e um script testado que calcula os valores de fallback. Uma página que nomeia
uma fonte e nunca a carrega, ou cai para system-ui, renderiza de forma
diferente em cada máquina.
5. Construa o esqueleto do layout
Cada faixa da página é um <section class="section"> com um
<div class="container"> dentro dele. Os dois nunca compartilham uma função:
/* A seção controla o ritmo vertical, o container controla a largura e as gutters. */
.section { padding-block: var(--space-section-open); }
.container {
inline-size: min(100% - 2 * var(--space-gutter), var(--space-content-max));
margin-inline: auto;
}
Os nomes de token acima são exemplos; use os nomes do seu tokens.css.
references/css.md lista cada papel de token que as receitas assumem e o que
fazer quando seu arquivo não tem um token para ele.
O container não define padding algum, então nenhuma ordem de regra ou
especificidade pode apagar o espaçamento da seção. Nunca escreva o shorthand
padding ou margin em uma classe de seção ou container: um shorthand define
ambos os eixos e substitui silenciosamente aquele que a outra classe definiu.
Esta é a regra que elimina o bug 1. references/css.md mostra a versão
quebrada ao lado desta, mais os casos de full-bleed e hairline.
6. Construa as seções
- Use elementos semânticos:
header,nav,main,section,footer,olpara etapas,dloutablepara especificações,figurepara mídia com legenda. - Um
h1, no hero. Cada seção abre com umh2extraído decopy.md. Não pule níveis. - Disponha cada seção conforme sua linha em
direction.mddiz. Quando a direção deixar a forma aberta, escolha entre as receitas emreferences/css.md; o número e a forma dos blocos seguem o conteúdo, então três cards iguais aparecem apenas quando o conteúdo são três coisas iguais. - Use os tokens para cada cor, fonte, tamanho, espaço e raio. Nunca
redefina um token no CSS da página. Se um valor que você precisa não tiver
token, componha-o a partir de tokens (
calc(),color-mix()) e liste-o na entrega para que a direção possa adicioná-lo. - Use tamanhos fluidos com
clamp(), propriedades lógicas, coroklch()com os fallbacks emreferences/css.md, e consultas de container para componentes que mudam de forma com sua própria largura.
7. Posicione a mídia
Imagens reais recebem width e height, texto alt que diz o que há nelas,
formatos modernos com um fallback, e fetchpriority="high" apenas na imagem
do hero (references/performance.md). Um asset que ainda não existe se torna
uma caixa placeholder visível e rotulada na proporção final, com texto como
[PLACEHOLDER: foto, a bancada da oficina de cima, 3:2]. Não dê à caixa
role="img": isso anunciaria uma fotografia que não existe. Dê a cada
placeholder a proporção, largura e fundo que a direção dá àquela imagem, para
que os quadros mostrem o layout planejado em vez de uma fileira de caixas
tracejadas idênticas (references/css.md, Placeholders de mídia). Nunca
desenhe uma tela de produto falsa e a apresente como o produto.
8. Construa a ação de conversão
A ação de Conversão do brief decide o que você constrói:
- Uma URL externa (checkout, página de reserva, app store): a ação é um
link,
<a class="button" href="https://...">com o rótulo decopy.md. Não há formulário,form.jsou página/thanks/ou/form-error/; pule o resto desta etapa. Se o brief disser que o clique deve ser contado,landing-skills:landing-launchadiciona o beacon. - Um formulário com um endpoint que o usuário já tem: o formulário envia
para essa URL e o placeholder
/api/leadnão é usado. Construa as páginas de resultado apenas se esse endpoint redirecionar para elas; caso contrário, diga na entrega para onde o endpoint envia o visitante. - Um formulário com o endpoint
nenhum ainda: o formulário envia para o placeholder/api/lead, quelanding-skills:landing-launchconstrói como um Worker.
Para um formulário, leia references/forms-a11y.md. As partes não negociáveis:
<form action="..." method="post">com o endpoint do brief, ouaction="/api/lead"com um comentário HTML ao lado dizendo que o endpoint ainda não existe, listado na entrega.- Cada campo tem um
name, um<label>visível, otypeeautocompletecorretos, e uma dica vinculada comaria-describedbyquando o formato precisar de explicação. - Sem JavaScript, o navegador envia o formulário e o endpoint responde com
um redirecionamento
303para uma de duas páginas estáticas que você constrói agora:/thanks/e/form-error/. Assim quelanding-skills:landing-launchadicionar Turnstile, um visitante sem JavaScript não terá token e sempre cairá em/form-error/, então essa página deve oferecer outra forma de entrar em contato, tirada das Rotas de contato do brief. - Sempre envie
form.jsdereferences/forms-a11y.mdcomo aprimoramento progressivo. O formulário funciona sem ele; o arquivo ainda faz parte da build, porquelanding-skills:landing-motionestende os estados que ele define elanding-skills:landing-launchos verifica. Ele mostra sucesso apenas quando a resposta é um 2xx e seu corpo JSON dizok: true. Um 2xx sozinho prova apenas que algo respondeu:fetchsegue um redirecionamento e relata a página em que cai como 200, e um host estático pode responder a um POST com uma página HTML comum. Ambos aconteceram em testes, e ambos são falhas. Em caso de falha, o script diz isso e mantém o que o visitante digitou. Nunca redefina o formulário ou mostre "Obrigado" antes de o servidor confirmar.
9. Atenda ao piso de acessibilidade
Link de pular, landmarks, um nav cujos links apontam para ids de seção
reais, o logotipo linkando para /, um estilo de foco visível em cada
elemento interativo, alvos de pelo menos 44 por 44 px, e uma verificação de
contraste de cada par de texto e fundo que a página realmente renderiza: texto
corporal em cada superfície, legendas, dicas, texto de placeholder, texto no
destaque. Detalhes e números estão em references/forms-a11y.md. Uma
navegação que esconde seus links em celulares sem substituição falha neste
piso; deixe os links quebrarem em vez disso.
10. Deixe o movimento de fora
Sob movimento reduzido, é o movimento que é reduzido, nunca o feedback,
portanto não escreva nenhuma regra global que zere transições. Construa cada
elemento em seu estado final e visível. Sem animações de entrada, sem
opacity: 0 esperando um script, sem bibliotecas de scroll.
Para cada momento nomeado na Intenção de movimento e 3D da direção, deixe
um substituto: uma imagem de pôster estática, ou um placeholder rotulado, no
tamanho final e proporção do momento, para que o layout não mude quando
landing-skills:landing-motion montar a coisa real. Marque-o com
data-moment="<nome>", usando o nome curto que a direção dá àquele momento;
o movimento encontra seu alvo por esse atributo. O substituto é completo sem
movimento: uma imagem real com texto alt, ou texto placeholder que diz o
que o momento mostra.
<div class="hero__media" data-moment="exploded-view">
<img src="/img/exploded-poster.jpg" width="1600" height="1000" alt="As camadas do dispositivo separadas: gabinete, placa, bateria, lente">
</div>
Quando a intenção for nenhuma, não adicione elementos data-moment.
11. Verifique e entregue
Execute "Definição de pronto". Em seguida, informe ao usuário, em uma lista curta:
- o que foi construído e onde (arquivos, pasta de saída), e o stack resolvido
escrito no campo Stack do brief se disser
detectar, - cada
[PLACEHOLDER: ...]ainda na página e cada asset a fornecer, - a ação de conversão como construída: um link para uma URL externa, um
formulário enviando para o endpoint do usuário, ou um formulário enviando
para
/api/lead, que ainda não existe, - cada campo que o formulário submete, uma linha cada: seu
name, seu tipo (email,tel,text,textarea), se érequired, e seumaxlengthda marcação.landing-skills:landing-launchconfigura a validação, limites de comprimento, armazenamento e limite de tamanho de requisição do seu Worker a partir desta lista, e recusa um campo sobre o qual não foi informado, - valores compostos porque nenhum token existia, e cada token opcional que
tokens.cssnão tinha com o fallback que as receitas usaram para ele, - o domínio de produção se o brief disser
desconhecido, e as tags de URL omitidas por causa disso (canônico,og:url,og:image, sitemap), - rotas de contato que o brief deixou
desconhecidas, que o rodapé e/form-error/mostram como placeholders, - cada arquivo de fonte que não foi subdividido, com seu tamanho em bytes,
- cada verificação da Definição de pronto que não foi executada, marcada como "não executada" com o motivo,
- cada momento da
Intenção de movimento e 3D: seu nomedata-momente onde seu substituto está (seção e elemento), ou "nenhum" quando a intenção fornenhuma, - o próximo skill:
landing-skills:landing-motionquando aIntenção de movimento e 3Dda direção nomeia um momento, depoislanding-skills:landing-review, depoislanding-skills:landing-launchpara hospedagem e o endpoint do formulário.
Detecção de stack
Verifique a raiz do projeto nesta ordem e pare na primeira correspondência. O
campo Stack em brief.md decide quando a pasta do projeto está vazia.
Assim que o stack for resolvido, escreva-o de volta: se o campo Stack do
brief disser detectar, substitua essa única palavra pelo stack resolvido
(por exemplo Astro, ou HTML e CSS simples) e não mude nada mais em
landing/brief.md. Skills posteriores leem o campo e não devem encontrar uma
palavra não resolvida. Um stack nomeado pelo usuário permanece como escrito.
Quando não houver landing/brief.md, não crie um.
| Sinal no projeto | Stack | Seção do adapter |
|---|---|---|
astro.config.mjs (ou .ts, .js), ou astro em dependências do package.json | Astro | Astro |
…
[truncado para tradução]
