Carrossel em anel 3D

Oito cards de foto pousados sobre um cilindro visto de frente. O anel gira sozinho, muito devagar, e o olho segue o card que está chegando ao centro: ele cresce até ficar de frente, nítido e cheio, enquanto os vizinhos se inclinam para dentro como portas entreabertas e escurecem conforme recuam. A metade de trás não existe — o card virado some, e o cilindro lê como um punhado de fotos em volta de um eixo, não como uma parede curva. Arrastar o anel com o mouse ou com o dedo o gira com inércia; ao soltar, ele encaixa no card mais próximo da frente. As setas do teclado e os dois botões do rodapé fazem o mesmo passo a passo. Abaixo do palco, uma legenda diz o título e a categoria do card da frente, e troca com blur e subida a cada volta de casa.

Resolve a dobra de "o que já fizemos" quando os casos são muitos, cada um cabe numa foto e num título curto, e uma grade os transformaria em inventário. Uma fileira que rola para o lado mostra tudo com o mesmo peso; o anel elege um card por vez e diz, pela forma, que há mais girando atrás dele. É a dobra que dá presença a uma lista que, em grade, seria só um catálogo — e é por isso que o conteúdo aqui é curto de propósito: o anel não é para ler, é para percorrer até parar em alguma coisa.

Quando usar

• Casos atendidos, tipos de estrutura, linhas de serviço, capítulos de uma história — de 6 a 10 itens, cada um com uma foto forte e um título de uma linha.
• Quando a dobra precisa de um momento de presença no meio de uma página de texto, e a página aguenta uma seção de ~980px em desktop.
• Quando os itens não levam a lugar nenhum: aqui o card não é link. Ele existe para ser olhado e nomeado.

Quando não usar

• Se cada item precisa abrir uma página: use midia/galeria-scroll-horizontal, onde o card é um <a> de verdade, o encaixe é nativo do navegador e o Tab passa por todos.
• Se cada item tem texto de verdade para ler (bio, descrição, número): midia/carrossel-perfis tem card com rodapé e painel de texto; aqui o card é foto e três palavras.
• Menos de seis itens: o anel fica com vão grande demais entre vizinhos e a volta se fecha rápido demais para valer o 3D. Com quatro ou cinco fotos, midia/galeria-pasta ou listas/leque-paineis contam a mesma coisa com menos maquinário.
• Mais de doze: a volta fica longa e o card da frente demora a mudar. Uma esteira contínua serve melhor — midia/colunas-cascata para parede de fotos, prova/carrossel-depoimentos para fila que atravessa sem parar.
• Se o clique tem de abrir o item em tela cheia: overlay/card-expansivel-fullscreen.
• Se a dobra é o assunto principal da página e precisa de título, número e frase em cada item: conteudo/pilares-texto-na-foto é a grade que já faz isso, parada.

Padrão editorial

O que mantém o anel coeso é o paralelismo dos títulos: todos frases, ou todos rótulos. Misturar "Três irmãos, um acordo" com "Previdência corporativa" faz o anel parecer duas listas girando juntas. E o par categoria + título tem de funcionar lido em voz alta na ordem em que o leitor de tela lê: título, categoria, posição.

Especificação dos assets

• Formato e dimensão mínima: 900×1200 (retrato 3:4), WebP. O card é exatamente 3:4 — foto nessa proporção não sofre corte nenhum.
• Peso alvo: até 150 KB por foto. São 6 a 10 imagens simultâneas na mesma dobra.
• Enquadramento: assunto no terço superior ou central. O quinto inferior da foto fica sob o véu da legenda e não deve carregar informação.
• Coerência: mesma temperatura de cor e mesma densidade nas 8. O anel mostra três fotos lado a lado o tempo todo, e uma clara no meio de escuras salta como erro.
• O que não pode ter: rosto encostado na borda inferior (some sob a legenda), texto na imagem, logo de terceiro, e foto de proporção muito diferente de 3:4 sem ajustar --ring-focus.

Como usar

<link rel="stylesheet" href="componentes/midia/carrossel-anel-3d/estilo.css">
<script src="componentes/midia/carrossel-anel-3d/script.js"></script>

Ganchos

Variações

• seis ou dez cards — acrescente ou remova <li> e renumere --ring-i. Passo e raio saem da conta do script; nada mais muda.
• anel parado — --ring-speed:0. Gira só no gesto.
• anel mais fechado — --ring-slack:1.0 encosta um card no outro e o anel vira tambor contínuo.
• cards maiores — --ring-card:clamp(220px,21vw,320px). Confira que 2 × raio ainda cabe na coluna.
• em seção clara — .sec-paper no lugar de .sec-dark. O véu de profundidade continua escuro de propósito: é sombra, não fundo.
• sem legenda dentro da foto — apague os .ring-cap, mantendo .ring-cap-name e .ring-cap-cat num <span hidden>: é de lá que o script lê o texto da legenda do rodapé.

Gotchas

Tudo abaixo foi medido no preview.html com Chrome headless (node bin/medir.js), em 1440×900 e em 390×844.

• O recorte não pode ficar no <ul> — e você não descobre isso lendo estilo computado. overflow:hidden, clip-path, filter:blur(0px) e até opacity:.99 no .ring-list achatam o 3D: a assinatura das larguras projetadas cai de 137,245,137,38,138,166,138,38 para 140,121,0,121,140,83,0,83 — o card a 90° perde a fatia de perspectiva (38px → 0) e o da frente encolhe de 245px para 121px, com o espalhamento indo de 539px para 385px. São as grouping properties do spec: qualquer uma delas força transform-style:flat no elemento. E o getComputedStyle(lista).transformStyle continua dizendo preserve-3d nos dois casos — a única forma de detectar é medir a geometria. As mesmas propriedades no .ring-scene (que carrega o transform) e no .ring-stage (que carrega a perspectiva) não achataram nada. Por isso o recorte que vai no ar está na <section>, fora da cadeia de perspectiva, e o palco tem overflow visível.

• A perspectiva fica no pai, não em cada card. Trocar perspective:1400px no palco por transform:perspective(1400px) rotateY(…) translateZ(…) em cada card parece equivalente e não é: cada card ganha a própria câmera, plantada bem à frente dele, e o anel perde o ponto de fuga único. Medido: card da frente vai de 245×326 para 319×427, e o espalhamento do conjunto de 553px para 687px. De quebra, o recuo da cena fica inerte — sem perspectiva no ancestral não há projeção onde aplicá-lo.

• A cena recua o raio ANTES de girar, e é isso que deixa o texto nítido. translateZ(calc(var(--ring-radius) * -1)) rotateY(var(--ring-angle)), nessa ordem: o eixo do anel vai para trás da tela na medida exata do raio e o card da frente pousa em z=0. Medido: layout 245×326, projetado 245×326 — escala 1,00. Sem o recuo, o anel fica centrado em z=0, o card da frente vai para z=+331 e a perspectiva o amplia: 318×431, ou 1,30×. Texto ampliado em 3D é texto reamostrado, e nenhum will-change conserta isso. Invertida a ordem das duas funções, o rotateY passa a girar um anel já deslocado e o resultado é uma órbita torta.

• --ring-speed é graus por SEGUNDO, e parseFloat(...) || 6 seria um bug. --ring-speed:0 é uma variação documentada (o anel parado), e o || a engoliria, devolvendo o padrão justamente para quem pediu zero. O script usa isNaN. A conta é por dt com teto de 50ms: 60Hz e 120Hz giram igual, e voltar de uma aba em segundo plano não dá meia volta de uma vez.

• O % do JavaScript devolve negativo, e o encaixe depende disso. -3 % 8 é -3, não 5. O índice do card da frente é ((k % n) + n) % n, onde k = Math.round(-ângulo / passo) é a casa contínua — quantos passos o anel andou desde a origem, podendo passar de n e ficar negativo. Sem o módulo duplo, a primeira volta para trás faz a legenda ler undefined.

• Dois cliques seguidos no mesmo botão andavam um card só. Medido antes do conserto: três cliques rápidos em "próximo" paravam em 03 em vez de 04. A causa é que Math.round(-ângulo/passo) lê a posição de agora, e o segundo clique chega antes de o anel sair do lugar. O comando parte da casa de destino quando há encaixe em curso (casaBase()). Depois: três cliques → -135°, card 04; cinco ArrowRight em rajada → -270°, card 07. Vale igual para o auto-repeat de tecla segurada.

• O parafuso da inércia é a soma da progressão, não o multiplicador. Com decaimento de .94 por quadro, o arremesso anda vel/(1−.94) = 16,7 vezes a velocidade inicial. O .9 do midia/carrossel-perfis daria ~100° num arremesso rápido — duas casas e meia de anel só de escorregar. Com .5, dá ~57°, pouco mais de uma casa. Medido: arrasto de −300px em 1440 pousa exatamente em -135,00° (3 cards); de −140px em 390, em -90,00° (2 cards). A inércia é cortada em .35°/quadro e passa a bola ao encaixe: esperar ela morrer de verdade custaria mais 45 quadros para andar 1° somado.

• A legenda visível é aria-hidden; quem anuncia é outra, fora da tela. A 6°/s o card da frente troca a cada 360/8/6 = 7,5 segundos. Um aria-live preso ao texto visível anunciaria oito vezes por minuto, para sempre, em qualquer página que tivesse esta dobra. Por isso são dois elementos: .ring-caption acompanha o anel quadro a quadro e é aria-hidden (o texto já está no card correspondente do <ul>, então nada se perde), e .ring-live só recebe texto quando a troca foi pedida — seta, botão, clique ou fim de arrasto. Se alguém "simplificar" juntando os dois, o componente vira uma máquina de interromper leitor de tela.

• O véu de profundidade é opacidade, não filter:brightness. São oito elementos reescritos a cada quadro: opacidade é mudança de composição, filtro é repintura. E o véu não tem transition de propósito — o valor já anda quadro a quadro, e uma transição por cima transformaria cada escrita numa animação nova, com a sombra chegando atrasada em relação ao card. O véu fica acima da legenda (z-index:3) para o card recuar inteiro, texto junto.

• backface-visibility:hidden já tira o card de trás do clique — no Chrome. Medido: com e sem .is-back, elementFromPoint no ponto em que a caixa projetada de um card virado cobre a de um card de frente devolve sempre o de frente. A regra .is-back{pointer-events:none} fica como guarda porque os motores já divergiram nisso, e o custo é uma troca de classe quando o estado vira — não por quadro. É também o gancho para quem quiser estilizar a metade de trás.

• O foco mora no palco, não na lista. Tudo que está dentro da cena gira com ela, e um anel de foco desenhado ali giraria junto, como uma porta. O palco fica fora do contexto 3D e o retângulo dele é estável — daí tabindex, role="group" e aria-roledescription="carrossel" estarem nele, e não no <ul>. O outline-offset é negativo (-2px): o core desenha 3px para fora, e em tela estreita isso cairia no recorte da seção. O max-width do palco é 2 × raio justamente para o anel de foco não atravessar a tela inteira para cercar um anel de 620px — medido, a meia-largura visível do anel chega a 291px contra os 331px do raio.

• A folga não é o parafuso de "caber". Afastar o card do eixo aumenta a meia-largura do anel na tela, porque o recuo em z que a folga também provoca encolhe menos do que o afastamento em x cresce. Medido em 390px: --ring-slack:1.12 chega a 219px de borda; 1.28 chega a 250px. Quem faz caber é --ring-card. Em 390px, com min(44vw,200px), o anel tem 205px de meia-largura contra 195px de meia-tela: os laterais são cortados por 10 a 45px conforme o ângulo, e isso é a sangria — o motivo de o palco ser irmão do .wrap e o recorte ser da seção.

• --ring-focus é inerte no preview, e existe mesmo assim. Os placeholders são exatamente 3:4 e o card também, então object-fit:cover não corta nada e mudar o object-position não faz diferença nenhuma. O gancho existe para a foto do cliente, que nunca chega em 3:4 exato. O padrão é 50% 42%, que privilegia o terço de cima.

• Math.round no raio não é cosmético. translateZ fracionário faz o navegador reamostrar a textura do card, e o texto sai borrado mesmo com o anel parado. O raio é arredondado para inteiro antes de virar --ring-radius.

• offsetWidth e não getBoundingClientRect para medir o card. O card está transformado em 3D: o rect devolve a caixa projetada — menor, e diferente a cada ângulo. Medir por ele faria o raio encolher a cada resize até o anel implodir. offsetWidth ignora transform e devolve a largura de layout, que é a que a conta pede.

• O backdrop-filter da legenda não custou nada de medível. Oito legendas com blur(3px) dentro de uma cena que gira: 4,17 ms/quadro contra 4,20 ms sem — razão 0,99, dentro do ruído (Chrome headless, rasterização por software; o número absoluto não vale, a razão vale). O custo do anel está no compositor da cena, não no véu. O mesmo teste com o filter:blur(0px) que o reveal do core deixaria no palco deu 1% de diferença — o motivo de removê-lo com .ring .ring-stage.in{filter:none} não é desempenho, é que filter é uma grouping property e não convém deixar uma dentro da cadeia de perspectiva esperando alguém movê-la para o lugar errado.

Histórico

Origem. É um componente autoral (contrato §11): um padrão de interação que aparece em muitos sites premium — vitrines de estúdio premiadas no Awwwards, os componentes de galeria em anel dos templates de Framer, as prateleiras de produto em perspectiva das páginas de produto da Apple — construído aqui do zero, sem referência única e sem uma linha copiada. Não há URL a creditar porque não há original: a forma é do repertório, o arquivo é da casa. Nada foi copiado: reescrito do zero dentro do contrato desta biblioteca. O primeiro projeto que usar promove, e esta ficha registra qual foi. O registro consolidado está em projetos/autorais.md.

Decisões de tradução para o contrato.

• A geometria virou conta, não tabela. Cada card declara só --ring-i. O passo (360/n) e o raio saem do script a partir da largura medida do card: o raio de um polígono regular de n lados de largura W é (W/2)/tan(π/n) — nesse raio os cards fecham como um tambor, encostados um no outro — e --ring-slack afasta na proporção dada. Com 1.12, o vão entre vizinhos é 12% da largura do card, o suficiente para o olho ler cards em volta de um eixo e não uma parede curva. Consequência prática: trocar oito cards por seis ou dez é renumerar a lista, e mudar --ring-card reajusta tudo sozinho. A implementação comum desse padrão crava raio e passo no CSS e obriga a recalcular à mão a cada mudança.
• Cor, fonte, curva e raio, só token. Nenhuma cor crua: o véu de profundidade é --dark com opacidade variável, o gradiente da legenda é rgba(var(--dark-rgb),…), o texto sobre a foto é --light (ilha escura, não escopo de tom), e o que está fora da foto — legenda do rodapé, contador, botões — lê --fg, --fg-2, --fg-muted e --rule-2 do escopo da seção.
• Ajuste por variável do prefixo. --ring-card, --ring-h, --ring-air, --ring-perspective, --ring-slack e --ring-speed, todas com unidade e padrão documentados no cabeçalho do CSS. A velocidade é em graus por segundo, com a conta por dt — a versão comum desse padrão anda por quadro e roda o dobro numa tela de 120Hz.
• Entrada pelos ganchos do core. data-rv/data-d e .ttl; nenhum observer próprio para "aparecer". O único observer do componente é o que faz o rAF dormir quando a dobra sai da tela — medido: com a seção acima da janela, o --ring-angle para de mudar.
• Sangria pela regra da casa. O palco é irmão do .wrap e filho direto da seção; o recorte é overflow:hidden na seção. Nenhuma margem negativa, nenhum 100vw.

• Acessibilidade que o padrão comum não tem. O palco é role="group" focável com aria-roledescription="carrossel"; setas giram um card, Home/End vão ao primeiro e ao último pelo caminho curto (do card 3 ao 8 o anel anda três passos para trás, não cinco para a frente); os dois botões são <button> de verdade com aria-label; o <ul> tem role="list" para o leitor de tela anunciar "8 itens" — a informação que um anel esconde de quem não vê a metade de trás; e a região aria-live só fala quando a pessoa pediu. Movimento reduzido desliga a rotação livre e a inércia, e encurta o encaixe para .5 por quadro (~8 quadros): o gesto pedido continua funcionando, e nada anda sozinho — medido, --ring-angle fica em 0.00deg depois de 120 quadros.

• Os dois botões são a primitiva .btn-disc do core, e o markup traz as duas classes (class="btn-disc ring-btn"). A regra do disco estava copiada ao caractere em cinco pastas — midia/galeria-scroll-horizontal, midia/carrossel-anel-3d, midia/carrossel-foco-central, midia/pilha-swipe e midia/roda-de-cards — e foi promovida ao core/base.css em 2026-09-03, como o §6 do contrato manda fazer já na terceira. Forma, cor, hover e o estado desabilitado vêm de lá; o parafuso é --disc-size. Não é .btn: aquela é pílula de texto, com padding horizontal fixo.