karero/website-hero-carousel

Carrossel de herói do site: fotos que se alternam e os testes que as mantêm honestas

Um local de fotos no topo de uma página onde duas ou mais fotos se alternam a cada poucos segundos, com um ponto para cada. Parece fácil e não é: uma legenda em uma foto faz a página pular a cada mudança; pontos brancos desaparecem em uma foto clara; um telefone precisa de alvos maiores do que um mouse; e conteúdo em movimento tem sua própria regra de acessibilidade. Este skill entrega o componente e, mais importante, os testes que detectam todos esses problemas.

Por que foi construído assim (diga isso ao proprietário, com suas próprias palavras)

• A página nunca pula. Todas as fotos compartilham um único lugar, cortadas em uma forma, então a página tem a mesma altura para a primeira foto quanto para a última. Não há legendas ou créditos nas fotos: eles eram o que movia a página no site de onde isso veio. Créditos pertencem à página de créditos de imagem do site.
• Os pontos podem ser lidos em qualquer foto. Eles ficam em uma pequena pílula escura, então aparecem tanto em um céu claro quanto em uma parede escura. Um teste mede isso nos pixels de uma foto clara e uma escura.
• Funciona sem JavaScript. As fotos então ficam uma abaixo da outra e nenhum botão é exibido.
• É educado. Para quando o mouse está sobre ele, quando a aba está oculta, quando o foco do teclado entra nele, e desde o início para visitantes que pedem ao dispositivo menos movimento.
• Nada é armazenado ou enviado. Sem cookie, sem armazenamento, sem requisição para outro site.

E os pontos fracos honestos, para que o proprietário os ouça de você primeiro:

• Fotos rotativas nem sempre são o melhor design. Uma única foto forte é mais calma, carrega mais rápido e não pode irritar ninguém. Diga isso; o proprietário decide.
• Cada foto extra custa ao visitante tempo de download no telefone. Três fotos em quatro tamanhos cada estão bem; dez não. Mantenha em um punhado.
• O modo de pausa "pontos" troca um controle visível por uma foto mais limpa (a seção "Pausa" abaixo).

0. Esta é a ferramenta certa? (pergunte antes de instalar)

1. O proprietário tem certeza sobre a rotação? Uma foto não precisa de nada disso. Pergunte uma vez, claramente.
2. Quantas fotos, e elas têm a mesma forma? Duas a cinco. Qualquer forma funciona (cada uma é cortada para a forma do carrossel), mas uma foto com seu assunto na borda o perde no corte: olhe para cada uma na forma do carrossel (16 / 9 por padrão) e no de um telefone.
3. As fotos linkam para algum lugar? Qualquer slide pode linkar para uma página (um projeto, por exemplo); misturar slides com e sem link é aceitável (a página de CI faz isso).
4. Qual modo de pausa? Leia "Pausa" abaixo para o proprietário e deixe-o escolher. Padrão: o botão.

1. O que ele adiciona ao site

Arquivo	Deste skill templates/	O que é
src/components/HeroCarousel.astro	HeroCarousel.astro	a marcação, os pontos, os estilos
src/components/hero-carousel-text.ts	hero-carousel-text.ts	as palavras que ele diz, em inglês e alemão
public/js/hero-carousel.js	hero-carousel.js	o script: coloca os slides em um lugar, rotaciona, manipula os controles
tests/hero-carousel.spec.ts	hero-carousel.spec.ts	o carrossel como um visitante o encontra (lista abaixo)

Instale todos os quatro. Os templates não contêm nenhum arquivo de imagem: as fotos são do próprio site, passadas como props.

Como funciona, em um parágrafo. O servidor envia todos os slides, um abaixo do outro, e os controles ocultos. O script, um arquivo próprio do site em public/js/ em vez de um script inline (para que um script-src 'self' restritivo permita sua execução), então coloca os slides em uma única célula de grade, mostra os controles e marca o slide em exibição. Qual slide está em exibição é um atributo de dados; o CSS faz o resto, incluindo o fade de um segundo. Um slide é mostrado apenas quando sua imagem está completa, então uma foto tardia ou com falha nunca deixa um espaço em branco.

O que o spec verifica (visão do visitante, na página como construída): a marcação e o nome de cada ponto; o intervalo ao milissegundo em um relógio congelado; o botão Pausa ou o ponto parando-o, com os rótulos e a região ao vivo; foco do teclado (para, permanece parado, Retomar); o ponteiro segurando-o e um novo intervalo após sair; movimento reduzido; uma aba oculta; uma segunda imagem tardia e com falha; a página sem JavaScript; nenhum salto de altura em 1280, 768 e 390 px; que um slide não em exibição não pode ser alcançado pelo teclado ou na árvore de acessibilidade; que o link de uma foto funciona e um ponto nunca o abre; alvos de 32 px (44 em telas sensíveis ao toque); os pontos contra a pílula sobre cada foto, lidos a partir de pixels renderizados; cores forçadas; axe em ambos os temas; nada armazenado ou enviado; o script é um arquivo, não inline; o fade executa em um quadro parcial e se estabiliza, e não executa sob movimento reduzido.

2. Instale (em uma branch, como um pull request: AGENTS.md §2)

1. Copie os quatro arquivos para os lugares em §1 (mkdir -p public/js primeiro).
2. Coloque o carrossel em uma página, dentro do <Base> dessa página, próximo ao topo:

   ---
   import HeroCarousel from '../components/HeroCarousel.astro';
   import first from '../assets/hero-1.jpg';
   import second from '../assets/hero-2.jpg';
   ---
   <HeroCarousel label="Fotos do nosso trabalho" slides={[
     { image: first,  alt: 'O que a primeira foto mostra', label: 'Nome curto', href: '/projetos/um' },
     { image: second, alt: 'O que a segunda mostra',        label: 'Outro nome' },
   ]} />
   

   • label: o que o carrossel é, para um leitor de tela. Obrigatório.
   • cada slide: image (uma foto importada), alt (uma frase que diz o que está nela, pelo menos 10 caracteres: a build para se for menor), label (o nome curto do ponto), href (opcional).
   • pause: "button" (padrão) ou "dots". swap: "instant" (padrão) ou "fade". intervalMs: padrão 6000, nunca abaixo de 2000. ratio: padrão "16 / 9". lang: o idioma da própria página. Fotos: JPEG ou PNG, cerca de 2.400 px de largura, mantidas ao que a página precisa (a build faz quatro tamanhos de cada, AVIF com fallback WebP). A primeira foto carrega primeiro (alta prioridade); as outras carregam em baixa prioridade e mantêm seu lugar.
3. Idioma. Inglês e alemão são embutidos, e o componente aceita o idioma da própria página (Base.astro o repassa como Astro.locals.lang). Qualquer outro: "Adicione um idioma" abaixo, primeiro.
4. Em tests/hero-carousel.spec.ts defina PAGE (a página com o carrossel), PAUSE e SWAP para o que a página passa (os padrões do componente são button e instant; o spec precisa deles escritos). O spec falha enquanto um estiver vazio. LANG apenas se a página passar lang. Fotos para o teste de contraste: o spec lê as fotos reais do carrossel, então encontra as do próprio proprietário. Se todas forem escuras, o teste de "pontos brancos na pílula" não pode falhar; para vê-lo falhar, verifique uma clara manualmente (a verificação de mutação em §3 faz isso).
5. npm run check && npm test.

Pausa (leia para o proprietário antes de ele escolher)

Conteúdo em movimento que começa por si mesmo, dura mais de cinco segundos e fica ao lado de outro conteúdo cai sob WCAG 2.2.2, Nível A, que pede "um mecanismo para o usuário pausar, parar ou ocultá-lo" (leia em https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html). A mesma página define pausa como "parado por solicitação do usuário e não retomado até que seja solicitado pelo usuário", e não diz que o mecanismo deve ser visível. Ela não discute indicadores de slide.

• pause="button" (o padrão). Um botão Pausa ao lado dos pontos (Retomar enquanto parado). Visível, nomeado, a leitura que ninguém contesta, e a que um visitante encontra. Seu preço: uma pequena palavra na foto.
• pause="dots". Nenhum botão. Escolher um ponto mostra aquela foto e para a rotação até o visitante recarregar; o foco entrando nele pelo teclado também o para, e movimento reduzido o inicia parado. Isso é provavelmente um mecanismo no sentido de 2.2.2, mas nada informa um visitante que um ponto o para, e não há maneira de retomar. O primeiro site a usar este modo o escolheu pela foto mais limpa, sabendo disso.

Este skill não tira conclusões de conformidade: se "pontos" é aceito é para o próprio auditor do site. Se o proprietário escolher, escreva uma linha na documentação do site dizendo isso, com a data.

Adicione um idioma

Em um novo site nesse idioma, ou quando um site o ganhar depois.

1. Leia primeiro a voz do site (CONTENT_GUIDE.md; em alemão o registro, "du" ou "Sie"). Os textos são algumas palavras: onde o idioma permitir, não se dirija a ninguém.
2. Em src/components/hero-carousel-text.ts, copie a entrada en de TEXT sob o código de duas letras do idioma (fr, não fr-CA) e traduza cada valor; npm run check falha enquanto um estiver faltando.
3. A página e seu teste, como nos passos 3 e 4 de §2.

3. Teste uma vez (o proprietário), e as verificações por trás deste skill

Após npm run build && npm run preview, ou no endereço de preview do pull request, o proprietário:

1. Espera: as fotos mudam sozinhas, o ponto em exibição as segue.
2. Move o mouse sobre ele: ele segura. Tira: continua, após um intervalo completo.
3. Em um telefone: toca um ponto (ele mostra sua foto); sem rolagem lateral; os pontos são fáceis de acertar.
4. No modo de botão: pressiona Pausa, vê dizer Retomar, pressiona novamente.

As verificações com as quais este skill foi construído, para que uma alteração em um template possa ser julgada: o spec carrega um teste para cada uma delas, e cada um falha quando a coisa que protege é removida. Execute uma vez manualmente quando os templates mudarem (o job de CI os instala em um site novo e executa o spec, em todas as três combinações das configurações que usa):

Remova isto de HeroCarousel.astro	Este teste falha
as regras de grade (display: grid, grid-area)	"os slides compartilham um lugar …"
aspect-ratio na foto	o mesmo teste (uma foto 4:3 é mais alta)
o background da pílula	"renderizado sobre cada foto …" (branco em uma foto clara é cerca de 1:1)
border-width: 5px no ponto em exibição	o teste de cores forçadas
as regras transition	o teste de fade ("um quadro parcial")
pointer-events: none em slides não em exibição	"o link da foto para sua página …" (um slide esmaecendo captura o clique)
o inert e aria-hidden que o script define em slides não em exibição (hero-carousel.js)	os testes de tecla Tab e árvore de acessibilidade (o link do slide que está saindo permanece acessível e legível enquanto esmaece)
o recover() do script (uma foto com falha em exibição é substituída pela primeira outra foto que está lá, agora ou quando chegar)	"uma primeira imagem que falha …"

4. A página de privacidade, e o caminho de volta

O carrossel não armazena nada e não envia nada: nada a adicionar à página de privacidade.

Para removê-lo: exclua os quatro arquivos, o bloco <HeroCarousel> e a linha import HeroCarousel (com as importações de foto que apenas ele usava) da página; coloque uma foto de volta. Nada mais se refere a ele, exceto suites dirigidas por PAGES que veem apenas a página.

5. Não neste skill (para que ninguém assuma)

Setas de anterior/próximo, gestos de deslizar, legendas nas fotos, créditos nas fotos, slides de vídeo, mais de um carrossel em uma página (seus ids são fixos), carregamento preguiçoso das fotos posteriores. Cada um pode ser adicionado depois; nenhum é necessário para a primeira versão.