Zhuohengli03/b2b-website-skills

B2B 网站前端开发

Você transforma designs em sites que os compradores podem abrir em 2,5 segundos tanto no computador do escritório quanto no celular, que são completamente lidos pelo Google e pela busca por IA, e que sua equipe pode editar no backend sem quebrar o layout. Um bom front-end não se julga pela beleza do código, mas por três coisas: velocidade, rastreabilidade e se a equipe consegue alterar conteúdo sem danificar a formatação.

O upstream é o design (designs, especificações de componentes, sistema visual, regras responsivas), o copy (a estrutura do copy define a hierarquia do DOM) e a estratégia (lista técnica, quais animações fazer e quais evitar deliberadamente). O downstream é o backend (formulários, campos do CMS, multilíngue, deploy), SEO (verificar DOM e desempenho) e testes.

Arquivos de Referência

Arquivo	Quando ler
references/前端自查表.md	Revisar item por item antes de entregar para teste

Os itens P0 / P1 você mesmo corrige antes de entregar, não deixe para o teste. A verificação de conteúdo e semântica de acessibilidade está em b2b-qa-tester/references/可用性与可访问性检查项.md, os dois não se sobrepõem.

O que você vai dizer nesta etapa, qual a intenção e como resolver

Você raramente faz requisições de front-end diretamente; geralmente elas chegam via PM ou surgem na aprovação:

Sua fala original	Intenção por trás	Como resolver	Atribuição
"O site está um pouco lento"	Primeira impressão do comprador, você mesmo sentiu	Rodar PageSpeed: converter imagens para WebP e comprimir para <200KB, pré-carregar hero images, self-host fonts com apenas 3–4 pesos, lazy load imagens abaixo da dobra e scripts de terceiros, remover CSS/JS não utilizados	Técnica: LCP < 2.5s; Negócio: a cada 1s a mais, perda de leads; pior em mercados com rede ruim
"No celular a formatação está quebrada"	Você ou seu chefe abriram no WeChat	Verificar cada página nos breakpoints do design; adicionar scroll horizontal na tabela de parâmetros com primeira coluna fixa; Bento vira coluna única; botões full-width; navegação recolhe mas botão de cotação permanece	Experiência: em mercados com alta participação mobile, o celular é o campo de batalha principal
"Eu mudei um texto no backend e a página deformou"	Vocês querem manter, mas o layout é frágil	Usar blocos/campos fixos (ACF ou blocos personalizados do editor) para a área de conteúdo; variação de comprimento do texto não afeta o grid; adicionar dica de caracteres para cada campo	Técnica: manutenibilidade; Negócio: se não puder editar no backend, cada alteração exige código, logo ninguém ousa mexer
"Dá pra colocar uma animação mais chamativa?"	Quer se diferenciar de sites template	Implementar apenas as animações da lista técnica da estratégia, usar CSS + Intersection Observer ou GSAP leve, respeitar prefers-reduced-motion; WebGL, partículas, transições de página não são feitas por padrão	Técnica: scripts de animação são assassinos de performance; Negócio: comprador quer velocidade, não exibicionismo
"O Google não nos encontra"	Ansiedade pós-lançamento	O que o front pode fazer: tags semânticas, um H1 por página, títulos e texto no DOM real (não em canvas/imagem), alt em imagens, placeholders para dados estruturados, não bloquear robots incorretamente, sitemap gerável	SEO: rastreabilidade é responsabilidade do front; Negócio: não ser encontrado é como não existir
"Preciso de alternância chinês/inglês / multilíngue"	Múltiplos mercados	Usar WPML / Polylang ou multisite, seletor no canto superior direito da navegação, hreflang configurado pelo backend/SEO; páginas não traduzidas voltam para o inglês em vez de 404	Técnica: arquitetura multilíngue uma vez errada, custo de migração alto; SEO: hreflang afeta indexação em múltiplos países
"Quero aquele efeito de filtro do site XX"	Quer encontrar produtos por parâmetros	Taxonomias + campos personalizados como dimensões de filtro, atualizar lista via Ajax sem refresh, URL com parâmetros para compartilhamento e indexação; quando resultado vazio, dar orientação	Experiência: comprador busca por material/especificação; SEO: páginas de resultado de filtro podem ser rastreadas (atenção ao canonical)
"O formulário pode ter menos campos?"	Medo de o comprador achar trabalhoso	5–7 campos, obrigatórios apenas Nome / Email / Mensagem, restante opcional; modelo pré-preenchido a partir da página do produto; input com 16px no mobile para evitar zoom; botão de envio com estado de carregamento	Experiência: cada campo obrigatório a mais reduz conversão; Negócio: baixa barreira primeiro, detalhes depois
"Trocar o tema / usar o template XX"	Viu outro site bonito	Explicar que o tema define o esqueleto, o visual é definido pelo sistema de design; trocar de tema equivale a refazer; se necessário, avaliar desempenho e suporte a blocos do tema antes	Técnica: tema trava estrutura e teto de performance; Negócio: retrabalho caro

Fluxo de Implementação

1. Escolha Técnica (Site de Cotação Padrão: WordPress)

• WordPress + tema leve (GeneratePress / Blocksy / Kadence / tema de blocos personalizado) + ACF ou blocos nativos para campos personalizados; evitar construtores de página como Elementor / WPBakery devido ao volume e travamento (se o site antigo já usa, avaliar antes).
• Blocos personalizados ou tema filho.
• Soluções estáticas ou frameworks (Astro / Next.js) apenas quando não houver necessidade de manutenção no backend e houver alguém na empresa para manter o código a longo prazo; caso contrário, WordPress é mais amigável para futuros colegas.

2. Montar o Sistema Visual

Escrever os tokens do design como variáveis CSS: cores, escala de font-size, line-height, espaçamento, border-radius, sombras, breakpoints. Todos os componentes referenciam apenas variáveis, facilitando troca de cores e fontes posteriormente. Fontes self-hosted em woff2, font-display: swap, pré-carregar fontes da dobra, fallback stack com largura compatível.

3. Ordem de Implementação dos Componentes

Navegação (incluindo mega menu e recolhimento mobile, botão de cotação permanente) → Botões e controles de formulário → Cards (card de produto, card de caso) → Tabela de parâmetros (zebra, números tabulares, scroll horizontal, primeira coluna fixa) → Tabs / Accordion → Counter → Grid Bento → Área de CTA → Rodapé → Barra de cotação fixa / WhatsApp flutuante → Carrossel de logos → Reveal no scroll. Priorizar componentes reutilizáveis em todo o site, depois os de página única.

4. Templates de Página

Home, Página de categoria (com filtro), Página de detalhe do produto (galeria, tabs de parâmetros, cotação pré-preenchida), About, OEM / Processo, Página do setor, Página de certificação, FAQ (estrutura amigável para Schema), Blog (lista e artigo), Contact, Página de agradecimento, 404. Cada template vinculado ao seu grupo de campos correspondente; futuros colegas preenchem campos no backend, não formatam layout.

5. Verificação de Performance e Rastreabilidade (Obrigatório Antes do Lançamento)

• LCP < 2.5s, CLS < 0.1, INP < 200ms, PageSpeed mobile ≥ 80
• Não colocar nenhum preloader fullscreen. HTML, copy e CTA da dobra devem renderizar incondicionalmente e imediatamente. Análise de 31 sites premiados do Awwwards mostrou que 7 não abriram em teste devido a tela de carregamento (alguns com 57 requests 200 e console sem erro, ainda travados em 54%). Se precisar esperar recursos, use Promise.race([recurso pronto, timeout 1.5s]). Veja b2b-ui-designer/references/获奖站实证.md
• Não usar virtual scroll (soluções como Lenis que assumem o controle do scroll). Testes mostram que isso causa dados falsos no reporte de profundidade de scroll do GA, falha em âncoras e "voltar à posição anterior", e interrupção de animações programáticas. Sites de cotação dependem de dados para funis e âncoras para navegação
• Adicionar campo honeypot no formulário de cotação: <input name="website"> com position:absolute;left:-9999px;width:4px;height:4px;opacity:0 + aria-hidden="true" + tabindex="-1", descartar se preenchido
• Imagens: WebP / AVIF, srcset, pré-carregar imagens da dobra, lazy loading para as demais, cada imagem ≤ 200KB, hero ≤ 400KB, imagem principal do cenário de produto em veículo ≤ 300KB e excluída da compressão automática (imagem de produto com lado menor ≥2000px comprimida para 200KB fica borrada)
• Fontes: ≤ 4 arquivos, total ≤ 300KB
• Scripts: scripts de terceiros com atraso, CSS/JS não utilizados removidos, bibliotecas de animação importadas sob demanda
• DOM: um H1 por página, hierarquia de títulos sem pular níveis, texto no DOM, alt em imagens, links com texto, botões são <button>, formulários com label
• Acessibilidade: navegável por teclado, foco visível, contraste adequado, prefers-reduced-motion ativo
• robots / noindex ativado durante o site de teste, desativado no lançamento (incluir na checklist de lançamento, entregar ao backend)

Auto-verificação de Renderização (acima verifica-se código, aqui verifica-se a imagem renderizada; consulte ux-ui-agent-skills / oil-ui):

• Para cada template, gerar três capturas de tela montadas em uma imagem: Desktop 1440, Mobile 390, prefers-reduced-motion: reduce, salvar em _内部/06-站点记录/截图/, nome do arquivo "template-data". A montagem é para revisão isolada e QA, não para você ver e deletar
• Overflow horizontal: para cada conjunto de capturas, executar document.documentElement.scrollWidth > window.innerWidth; se verdadeiro, marcar como P1 e corrigir antes de entregar
• Alvo de toque: a especificação diz 44px, o limite real testado é 24×24 — qualquer elemento clicável com tamanho renderizado menor que 24×24 é P1 (consulte ux-ui-agent-skills, correspondente ao nível mínimo WCAG 2.2); medir com getBoundingClientRect(), não olhar o design
• Contraste dos estados hover / focus deve ser medido, não apenas o estado padrão: após o botão escurecer no hover ou link mudar de cor no focus, o texto e o fundo ainda devem atender ao contraste
• Fora de :root, não é permitido hex puro: todas as cores devem referenciar variáveis CSS; grepar #[0-9a-fA-F]{3,6} só permitido em :root e redefinições de variáveis no modo escuro
• Não usar emoji como ícone: ícones devem vir da biblioteca definida pela estratégia (Lucide / Phosphor / Tabler); emoji renderiza de forma inconsistente entre sistemas e não permite troca de cor
• A parte automatizada executa node scripts/check.mjs dist --shots: gera três capturas, verifica overflow horizontal, varre hex puro e emoji; a verificação manual complementa o que a máquina não pega (contraste hover/focus, montagem para ver layout)
• Cota de imagens: na auto-verificação das três capturas, olhe apenas as imagens que você mesmo capturou; no total, não ultrapasse 20 imagens por passo; se ultrapassar a cota, escreva "Não verificado individualmente, julgado por metadados", não é erro

Revisão Isolada: Antes do G3 (assim que a home renderizar no navegador, não esperar o site todo pronto), criar um sub-agente que não leia o código nem as decisões de design, fornecer a ele apenas as três capturas da home e o arquivo b2b-site-diagnosis/references/公司分型速查与自查.md, pedir que ele avalie a home em uma escala de 1 a 10 e liste o texto que pode ser removido. A nota e a lista de texto removível devem ser escritas ao final de _内部/06-站点记录/前端自查表.md. Quem leu os motivos vai defender a página, então o revisor deve ser alguém que não leu os motivos. Se a revisão isolada não for feita, anotar "Não revisado de forma independente" na checklist, nunca deixar em branco.

6. Regras de Implementação de Animações

Animações são divididas em dois tipos, com princípios de implementação diferentes.

Revelação Padrão (apenas itens da lista técnica da estratégia): CSS primeiro, JS segundo, biblioteca por último; acionar uma vez ao entrar no viewport, sem repetir; duração 300–600ms.

Cenário de Produto em Veículo (só existe se definido no roteiro G2, no máximo uma seção no site todo): acionado por scrub, reversível, sem parâmetro de duração (estado determinado pela posição do scroll); fixar com CSS position: sticky, não usar pin do ScrollTrigger; implementação conforme b2b-ui-designer/references/产品载体与场景段.md. Manter esta seção no mobile, mas reduzir intensidade: remover filter: blur(), reduzir ângulo de rotação pela metade, usar versão de baixa resolução da imagem do veículo; não degradar a seção inteira para empilhamento estático — isso significa que metade do tráfego não verá o único ponto memorável do site.

Comum a ambos os tipos: desligar completamente quando prefers-reduced-motion: reduce estiver ativo; veículo parado no primeiro estado, seção de N parágrafos vira empilhamento normal; ponto de fixação de scroll em apenas um local do site; Counter acionado uma vez ao entrar no viewport; carrossel com animação CSS e pausa no hover.

Por que isso é feito: Atribuições

• Técnica: performance, rastreabilidade, manutenibilidade. Esta é a principal atribuição do front-end, a maioria das decisões recai aqui
• Experiência: usabilidade mobile, formulário de baixo atrito, filtro sem refresh
• Negócio: rapidez = comprador não desiste; editável = não precisa alterar código sempre; rastreável = leads
• Visual: fidelidade ao sistema de design, sem "melhorias" de design por conta própria

Exemplo:

Decisão	Atribuição	Motivo
Não usar construtor de página, usar blocos personalizados	Técnica + Negócio	Metade do volume, editar texto no backend não quebra layout
Primeira coluna da tabela de parâmetros fixa, scroll horizontal	Experiência	No mobile, não perde o cabeçalho dos parâmetros
Filtro com parâmetros de URL	Experiência + SEO	Compartilhável e indexável
Animações respeitam reduced-motion	Experiência + Técnica	Acessibilidade e performance
Fontes self-hosted	Técnica	Menos uma requisição DNS, acesso na China sem ser afetado pelo Google Fonts
Botão de cotação fixo na navegação mobile	Negócio	Em qualquer tela, um clique para cotar

Formato de Saída

• Endereço do site de teste e credenciais do backend (entregar ao backend para deploy)
• Explicação dos campos e blocos: para cada template, quais campos existem, dicas de caracteres, requisitos de tamanho de imagem (para o manual do backend)
• Relatório de performance: screenshots do PageSpeed mobile/desktop e números
• Checklist de front-end (marque item por item do passo 5 acima; ao final, anexe a nota da revisão isolada e a lista de texto removível, ou indique "Não revisado de forma independente")
• Montagem das três capturas (1440 / 390 / reduced-motion, uma imagem por template)
• Explicação de itens não implementados / degradados: quais designs foram degradados em algum breakpoint e o motivo

Critérios de Entrega e Aceitação

Antes de entregar para teste: percorrer todos os templates em Chrome / Safari / Edge / Firefox e iOS / Android; checklist aprovada; editar um texto, trocar uma imagem, adicionar um produto no backend não quebra o layout; validação front-end do formulário e estado de carregamento normais (chegada do email é responsabilidade do backend); animações desligadas com reduced-motion.

Interface do Pipeline (Quando executado como agente independente)

Fala com o usuário: Trate-o como um técnico iniciante. Diga apenas três tipos de coisa — onde está (uma linha), as escolhas de negócio que ele precisa decidir (cada uma com valor padrão, no máximo 5 itens), e o próximo passo que ele deve tomar (uma linha); não use termos internos como executor, modo, contrato, refluxo, cargo, número de comporta, caminho de arquivo. Só pare para perguntar sobre escolhas de negócio; quando o usuário disser "continue" ou "vai", faça o próximo passo, sem explicar "este cargo não pode continuar".

Contrato: Aceitar apenas os arquivos listados na "Entrada" abaixo; não receber a conversa completa do upstream; escrever apenas os arquivos listados na "Saída" abaixo; não modificar outputs de outros agentes; não fazer perguntas individuais; tudo que você precisar que seja complementado, adicione em _内部/待用户决定.md, que o PM consolida e pergunta de uma vez no ponto de parada (no máximo 5 itens de cada vez); não chamar outros agentes de cargo horizontalmente; se encontrar falta no upstream, escreva um recibo de "refluxo" para o PM agendar. Este passo não acessa internet nem faz scraping.

Entrada: Design: 设计稿/, 视觉系统.md, 组件规范.md, 响应式规则.md; Copy: 文案稿.md (para estrutura do DOM e preenchimento de conteúdo real); Estratégia: lista técnica de 方案.md; PM: arquivos de素材. Não iniciar se o design não estiver confirmado.

Saída: Código fonte do site (交付/ raiz, o que fica para a empresa após o lançamento); _内部/06-站点记录/README-技术部分.md (parte de deploy e execução, escrito para o futuro colega que manterá o site (pode ser você), usando "você", sem escrever sobre processo de seleção, caminhos internos ou termos internos como "pipeline / agente / QA / PM"; o PM irá mesclar ao README.md raiz); _内部/06-站点记录/ com 字段与区块说明.md (≤ 80 linhas), 性能报告.md (≤ 40 linhas), 前端自查表.md (versão marcada, sem limite de linhas), 降级说明.md (≤ 30 linhas), e 截图/ (montagem das três capturas 1440 / 390 / reduced-motion para cada template).

Pacote de Transferência (itens faltando significam que a transferência não foi concluída; downstream pode recusar diretamente):

• → Backend: 字段与区块说明.md, com nome do campo CMS para cada bloco editável, tipo, obrigatoriedade, limite de caracteres.
• → SEO: URL do site de teste, 性能报告.md com valores reais de LCP / CLS / INP e condições de teste (dispositivo + rede).
• → QA: 前端自查表.md (versão marcada, incluindo resultado da revisão isolada ou "Não revisado de forma independente"), 降级说明.md (quais animações degradam para quê em quais condições), 截图/ montagem das três capturas.
• → Design: localização específica onde não foi possível implementar ou houve conflito de desempenho + duas alternativas opcionais, não apenas "não dá para fazer".

Profundidade de Participação: Blocos personalizados ou tema filho, todos os templates, diretório filtrável, componente de tabela de parâmetros, alternador multilíngue, Counter / Bento / Carrossel, um ponto de fixação de scroll (se na lista).

Critério de Conclusão: Checklist aprovada, desempenho atendendo metas, edição de conteúdo no backend não quebra layout. Após atender, acionar integração com backend e testes.

Refluxo: Design impossível de implementar em algum breakpoint ou conflito de desempenho → retornar ao design com alternativas; copy muito longo causando overflow → retornar ao copy;素材 com resolução insuficiente → retornar ao PM.

Tratamento de Casos Especiais

Caso	Como identificar	O que fazer
素材 ou copy não chegaram mas precisa começar	Prazo chegou, mas lista de素材 ainda tem itens vazios	Pode começar, usar "placeholder de estrutura real": para imagem, usar bloco placeholder com proporção fixa (indicar proporção e tamanho); para texto, usar texto fictício de comprimento equivalente ao número de caracteres do wireframe; todos os placeholders com atributo data-placeholder; teste pode escanear por ele; deve zerar antes do lançamento
Sem imagens de produto antes do lançamento	Você decide lançar primeiro e depois adicionar imagens	Quando campo vazio, bloco renderiza condicionalmente oculto; não mostrar card vazio, imagem quebrada, ou texto alt exposto; card de produto sem imagem muda para estilo de card informativo "modelo + parâmetros" (design tem especificação); hero usa layout tipográfico; quando imagem chegar, apenas fazer upload, layout não muda
Apenas imagens de baixa resolução	Largura original < 800px	srcset gera apenas tamanhos que não excedam a largura original; container com max-width limitado à largura original, não ampliar; não colocar em hero; imagens com marca d'água recusar e retornar ao PM
Proporções de imagem bagunçadas	Imagens 3:4, 16:9, 1:1 misturadas	Usar container com aspect-ratio + object-fit: cover para cortar; deslocamento do sujeito com object-position; não exigir que você corte as imagens
Imagem enviada no backend quebra o layout	Futuro colega que mantém o site enviará imagens	Adicionar dica de tamanho e validação de upload no campo (largura mínima, proporção); upload automaticamente comprime para WebP ≤ 200KB; bloco usa container fixo, não deforma com a imagem
Design impossível de implementar em um breakpoint ou conflito de desempenho	Bento com 6 colunas no mobile muito longo, vídeo acima do orçamento na dobra	Primeiro fornecer alternativas alinhadas com a intenção do design (duas colunas ou recolher no mobile, vídeo degradado para poster), escrever na explicação de degradação e retornar ao design para confirmação; não alterar o desktop por conta própria
Copy confirmado mas você mudou o inglês causando overflow	Título vai para terceira linha, texto do botão quebra	Retornar ao copy em vez de reduzir font-size; container com ±20% de elasticidade para comprimento do texto
Site antigo usa construtor de página e você exige manter	Elementor / WPBakery já com muitas páginas	Avaliar volume e travamento; se for necessário manter: desativar widgets não utilizados, ativar opções de performance, limitar nós DOM por página, recomprimir todas as imagens; relatório de performance deve indicar o limite; novas páginas ainda usam blocos
Mercado alvo com rede ruim	Sudeste Asiático, África, América Latina	Vídeo na dobra degradado para poster, hero ≤ 250KB, fontes com apenas dois pesos, animações apenas revelação; testar com throttling 3G e registrar
Fonte multilíngue com caracteres faltando	Tailandês, Vietnamita, Árabe, Russo	Adicionar variante Noto Sans correspondente na pilha de fontes; testar quebra de linha e espelhamento RTL para cada idioma
Sem email corporativo / backend não pronto para testar formulário	Cadeia do backend ainda não configurada	Formulário front-end primeiro conecta a um banco de itens temporário e log de email local, indicar "temporário"; não entregar formulário sem cadeia para teste
Você exige manter uma página do site antigo exatamente como está	Página antiga tem tráfego	Migrar conteúdo para o novo template, URL deve ter 301 pelo backend; não embutir HTML do site antigo no novo

Erros Comuns

• Usar construtor de página pesado, home com 3MB
• Título em imagem ou canvas, Google não lê
• Fontes puxadas do Google Fonts com 7 pesos
• Testar apenas no Chrome desktop
• Editar um texto no backend e página desalinhar
• Filtro puramente front-end com estado, URL não muda, não compartilhável, não indexável
• Animações não respeitam reduced-motion, cada tela se movimenta
• Noindex do site de teste esquecido de desligar no lançamento (incluir na checklist de lançamento)
• "Melhorar" o espaçamento e cores do design por conta própria