depth-scroll (rolagem de profundidade)

Cria uma página de rolagem em profundidade, onde painéis (desenhos, cartões de uma ideia, estágios) são posicionados em estações ao longo de um eixo de profundidade, surgindo do fundo, parando nítidos no plano da tela e passando pelo visualizador, com um fluxo de cartões voando em direção ao visualizador atrás deles, inspirado no campo de aterrissagem do WhatTheFad (whatthefad.netlify.app). Ativado por 'uma interface que rola em direção ao usuário', 'como o whatthefad', 'faça isso voar em minha direção', 'rolagem de profundidade', 'role para dentro da tela', 'um túnel desses' ou qualquer pedido para transformar uma página plana de figuras em uma que o leitor percorre.

O que é depth-scroll (rolagem de profundidade)?

A habilidade 'depth-scroll' cria uma experiência imersiva de rolagem 3D para um conjunto de painéis (como desenhos, cartões de uma ideia ou estágios). O usuário rola verticalmente, e cada painel emerge do fundo, para nitidamente no centro da tela e depois desaparece ao passar, criando uma sensação de viagem. Ideal para 4 a 12 painéis autocontidos, não é adequada para textos longos ou comparações lado a lado. Inspirada na página de destino do WhatTheFad, a implementação usa perspectiva CSS e `requestAnimationFrame` para simular a profundidade, com um fluxo de cartões decorativos que se aceleram com a rolagem. A saída é um único arquivo HTML autocontido (sem WebGL ou scripts externos), personalizável via tokens CSS. Inclui fallback para JavaScript desabilitado ou movimento reduzido, mostrando a página plana. A habilidade fornece um modelo HTML, um script Python (`build.py`) para gerar a página a partir de uma especificação JSON, e um script `capture.mjs` para capturas de tela e testes de navegação via protocolo DevTools. Suporta entrada por roda, trackpad, toque, teclas de seta e barra de navegação, tudo sincronizado na mesma rolagem nativa. O processo de construção envolve criar o conteúdo em HTML plano, escrever uma especificação e executar o build. A especificação define saída, título, fonte opcional, estações, fluxo de cartões e CSS extra. O arquivo `capture.mjs` permite verificar o comportamento visual e a navegação em diferentes estados, garantindo que as estações parem nos pontos corretos, os cartões iluminem adequadamente e não haja rolagem lateral.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/rafaelcarlosabbariao/skills/tree/HEAD/agnostic/depth-scroll

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Se SKILL.local.md existir nesta pasta, leia-o primeiro; ele contém seus caminhos, dados e regras locais.

Rolagem de profundidade

Um formato de página para um conjunto de figuras que o leitor percorre, uma de cada vez. A primeira construção transformou um conjunto de desenhos explicativos em uma rolagem em direção ao visualizador, modelada na página de destino do WhatTheFad (whatthefad.netlify.app, código-fonte em github.com/rafaelcarlosabbariao/cultural-archaeology).

A habilidade contém quatro arquivos:

ArquivoO que é
template.htmlA página: a estrutura da estação, o fluxo, a barra e o script que os executa
build.pyPreenche o modelo a partir de uma especificação, como comando ou como módulo
capture.mjsCapturas headless em tempo real e verificações de navegação sobre o protocolo DevTools
SKILL.mdEste arquivo

Quando se aplica

  • Aplica-se a quatro a doze painéis autocontidos, lidos um de cada vez, cada um cabendo em uma tela: desenhos, cartões de uma ideia, os estágios de uma sequência.
  • Não se aplica a textos longos, tabelas ou qualquer coisa que o leitor compare lado a lado ou examine indo e voltar. Construa uma página plana para esses casos.
  • Saída. A página é um único arquivo .html autocontido, sem scripts externos e sem WebGL. O modelo vem com uma paleta de creme quente e tinta em tokens :root; reestilize-a a gosto.

Como funciona

O campo do WhatTheFad, a fonte

Leia do index.html do WhatTheFad (CSS #landing-trendfield e a função renderTrendField).

  • Projeção. O campo é um contêiner com perspective: 900px, e cada chip é posicionado com translate3d(x, y, z). O navegador desenha um chip na escala 900 / (900 − z): 0,24 em z = −2800, 1 no plano da tela e 1,3 em z = 220.
  • Um relógio impulsiona o movimento. Um loop requestAnimationFrame move cada chip em direção ao visualizador a 150 px/s vezes um fator por chip de 0,75 a 1,25. Após z = 220, ele reaparece em um anel elíptico em z = −2800.
  • Fades e ordem de pintura. Um chip aparece gradualmente no primeiro quarto de sua profundidade e desaparece entre z = 60 e 220. O campo nunca usa preserve-3d, então o z-index de cada chip é definido a partir de sua profundidade para que o mais próximo pinte por cima.
  • O centro silencioso. Uma mask-image radial esconde o meio, onde chips distantes se acumulam no ponto de fuga.
  • Pegando um chip. O navegador verifica novamente :hover apenas quando o ponteiro se move, então um chip derivando sob um cursor parado nunca acende. O WhatTheFad testa o ponteiro contra o retângulo projetado de cada chip a cada quadro, e um chip pego reduz a velocidade do campo para 8%.

O que este formato adiciona

  • A rolagem é a câmera.
    • Uma trilha alta (main.depth) contém uma parada por estação, um altura de estágio de distância, com scroll-snap-type: y proximity.
    • Um estágio fixo sob o cabeçalho fixo contém a cena.
    • A posição de rolagem se torna um índice de estação, inteiro em cada parada. Uma câmera se aproxima suavemente (taxa 9 por segundo), e a estação i é desenhada em z = (câmera − i) × 1400.
  • A passagem de uma estação.
    • A estação que espera atrás está escura e um pouco baixa, então ela sobe para o lugar conforme avança.
    • Em repouso, ela está em z = 0 e escala 1, em pixels inteiros, então seu texto é tão nítido quanto uma página plana.
    • Ao passar pelo visualizador, ela desaparece em z = 300, com 1,5×.
    • Uma estação mais alta que o estágio é escalada para caber.
  • O fluxo. O campo do WhatTheFad, máscara incluída. A velocidade dos cartões é uma base de 46 mais 0,9 da velocidade da câmera, então rolar para frente os acelera e rolar para trás os afasta. Uma estação nomeia os grupos de cartões que ela ilumina (lit), e esses cartões acendem enquanto ela estiver na frente.
  • Entrada.
    • Roda, trackpad, toque, as teclas de seta, a barra e o conteúdo do cabeçalho movem a mesma rolagem nativa, então toda entrada chega nas mesmas paradas.
    • O foco entrando em uma estação que não está na frente rola até ela.
    • O fluxo é decorativo, e apenas a estação em repouso recebe eventos de ponteiro, então nenhum teste de impacto por quadro é necessário.
  • Fallback. Sem JavaScript, ou com prefers-reduced-motion: reduce, a página são as estações empilhadas planas. A profundidade é ativada por uma classe deep que o script adiciona. No modo plano, as âncoras do conteúdo se movem para as estações.

Construindo uma

SK abaixo é onde você instalou esta habilidade, por exemplo ~/.claude/skills/depth-scroll.

  1. Conteúdo primeiro. Coloque cada painel em uma página plana como <figure class="fig"> contendo um .plate (o desenho) e um figcaption. A página plana também é a cópia de leitura. Uma estação pode, alternativamente, conter html bruto.
  2. Escreva uma especificação (abaixo), como um arquivo JSON ou como um dict no próprio script de construção do projeto quando os valores são computados (por exemplo, nomes de cartões lidos de um arquivo de dados).
  3. Construa-a.
    python3 -I $SK/build.py spec.json
    
    ou, a partir de um script:
    sys.path.insert(0, str(Path.home() / '.claude/skills/depth-scroll'))
    import build
    build.write(spec, base=AQUI)
    
  4. Cabeçalho opcional. O modelo deixa espaço para um cabeçalho fixo (--pin-h, header.pin, nav.pin-toc). Sem um, o estágio começa no topo da janela.
  5. Verifique-a com capture.mjs (abaixo), então faça o commit.

A especificação

Os caminhos são relativos a base: a pasta do arquivo de especificação ou a pasta passada para write. Os caminhos das imagens são escritos na página como fornecidos, então forneça-os relativos à página de saída.

CampoO que contém
outA página a ser escrita
titleO <title>, nomeado por tipo (<Assunto> <substantivo do tipo>)
sourcePágina plana opcional. Seus blocos figure.fig se tornam fig: n, e seus blocos de estilo (não os do cabeçalho) são copiados para que os desenhos mantenham suas classes
kickerO pequeno rótulo sobre uma estação de nível de seção; o kicker de uma subseção é o nome de sua seção
doorHTML da primeira estação: um resumo, uma nota, um link para a página plana
stations[]id; sec e/ou sub (as linhas de conteúdo; sec sozinho é uma seção, sub sozinho uma subseção, ambos abre uma seção nesta estação); title (padrão para sub, depois sec); lead (HTML, uma ou duas frases); fig ou html; cards ([{img, label}], uma pequena fileira de imagens); lit (grupos do fluxo para iluminar)
cards_labelO rótulo no final da fileira de imagens de uma estação
close{title, kicker, html} para a última estação, geralmente as fontes
stream[]{label, img, group} por cartão. Quarenta a oitenta é lido como um fluxo
cssCSS extra opcional, anexado por último

Verificando

K=$SK/capture.mjs
node $K file:///caminho/pagina.html em-repouso.png 2                  # uma estação em repouso
node $K file:///caminho/pagina.html em-transito.png 4.4 --wait=900  # entre duas estações, saindo do encaixe
node $K file:///caminho/pagina.html ultima.png 9                  # a última parada é alcançável
node $K file:///caminho/pagina.html luz.png 5 --light               # o fundo claro
node $K file:///caminho/pagina.html celular.png 3 375 700          # largura de celular
node $K file:///caminho/pagina.html plano.png 0 --reduce            # a página com movimento reduzido
node $K "file:///caminho/pagina.html#st-modelo" hash.png -          # um link para uma parada, ao carregar
node $K file:///caminho/pagina.html navegacao.png 0 --nav           # setas, o último link do conteúdo, a barra

Cada execução imprime as paradas e, por etapa, y, front (a estação que recebe eventos de ponteiro), rail, cardsShown, cardsLit, deep e pageWidth. Uma estação em repouso tem front igual ao seu índice; pageWidth deve ler a largura da janela de visualização (sem rolagem lateral da página). Olhe cada imagem, em ambos os fundos e na largura de celular, antes de considerar concluído. Para páginas cujas imagens estão fora da pasta, copie a página para o scratchpad com caminhos de imagem absolutos primeiro.

Não verifique com chrome --headless --screenshot. Sob --virtual-time-budget, os quadros de animação mal avançam, então a câmera suavizada nunca chega, e uma captura de tela de uma janela rolada pode voltar em branco. capture.mjs dirige um Chrome headless em tempo real, onde os quadros são executados em sua taxa real.

Ajuste

As constantes estão no início do script em template.html.

ConstanteValorO que move
PERSP900Deve corresponder ao perspective CSS em .stations e .field
GAP1400Profundidade mundial entre duas estações
AHEAD2,2 × GAPQuão à frente uma estação é desenhada
PASS300Onde uma estação passando desapareceu (escala 1,5)
LIFT36Pixels que uma estação em espera fica baixa por GAP de distância
DEPTH, NEAR2800, 220A profundidade de surgimento do fluxo e a profundidade onde um cartão passou
BASE46A velocidade do fluxo em repouso, px/s
suavização da câmera9 por segundoA rapidez com que a câmera alcança a rolagem

O que deu errado na primeira construção

Cada um desses foi encontrado olhando, e cada um está corrigido no modelo.

  • A margem de rolagem do cabeçalho. O cabeçalho fixo dá a cada [id] um scroll-margin-top, para que as âncoras caiam abaixo dele. Os saltos caíam 126px antes de cada parada até que as paradas fossem ajustadas para zero.
  • A trilha estava um cabeçalho mais curta. A página terminava antes que a última parada pudesse chegar ao topo. A altura da trilha usa a altura da janela, não a do estágio.
  • Cartões voavam atrás da coluna de conteúdo. Essa coluna é fixa e transparente, então os cartões apareciam através de seu texto. Quando a coluna está fixa, o estágio começa à sua direita.
  • Cartões distantes se acumulavam no ponto de fuga. A máscara do WhatTheFad corrigiu isso.
  • A estação passando persistia como um grande borrão. A correção foi um PASS mais curto e um fade ao quadrado.
  • A estação em espera aparecia sob estações curtas. Ela é desenhada escurecida (ao quadrado).
  • Os âncoras do modo plano apontavam para paradas ocultas. As paradas se movem para as estações.
  • Uma rolagem que chegava antes do evento de carga atingia uma página curta. A trilha é disposta assim que o documento é analisado, e novamente quando as fontes e imagens se estabilizam, então uma rolagem restaurada e um link #st-<id> ambos pousam.
  • Em um celular, os desenhos largos deslizam lateralmente dentro de sua placa, a fileira de imagens fica oculta e a estação é estreitada para que a barra mantenha a borda direita.

Em aberto

  • Pegar um cartão. No WhatTheFad, um chip pego abre uma escavação. Aqui, um cartão poderia abrir seu registro, o que requer que a página de destino receba um id em sua URL e o teste de impacto projetado acima.
  • Um controle de pausa. O fluxo se move enquanto a página estiver aberta. Movimento reduzido o para, mas não há botão de pausa, o que a WCAG 2.2.2 exige para movimento que dura mais de cinco segundos junto com outro conteúdo.
  • A sensação em um trackpad e celular reais, e a taxa de quadros, não foram julgados por uma pessoa.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas