Composição por tela: ver tudo sem rolar e nada cortado na dobra (regra do dono) + aprendizados do wi em painel, docs e landing

Aperta
#1,347 4 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
typescript

Direzione di ricerca

Start with styles/tokens.css, docs/css-api.md, testing/layout-audit.ts, and the existing PageShell and Section implementations; read the related issues #1003, #1044, and #1290 to understand existing constraints. The issue proposes changes across tokens, layout primitives, audit detectors, linting, and guides, with acceptance criteria listed at the end. Done means those criteria are implemented and the new behavior is tested against the short viewport heights and screen types described.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

ai-report documentation enhancement

Contexto

Relato do wi (codeatlasdev/wi, SvelteKit + @codeatlasdev/ui 4.6.0: painel apps/web, docs apps/docs, landing). Em 16/11/2026 o dono revisou o produto inteiro no desktop e no iPhone e refizemos telas do painel, a leitura das docs no celular e começamos a landing e as docs ilustradas. Esta issue junta o que quebrou, a regra que resolveu e o que o núcleo deveria garantir para a lib produzir esse nível sem depender de revisão manual. Os defeitos pontuais já têm issue própria (lista em cada seção); aqui ficam a regra nova e o mapa.

Origem dos números: "medido" é medição direta em build ou produção; "relato" é contagem do agente que implementou, não refeita.


1. Regra do dono: composição por tela

Nas palavras dele: pensar sempre na UX de 100dvh, em que o usuário vê tudo na cara, sem precisar rolar e sem conteúdo quebrado na vertical, no desktop e no celular. É o ponto em que ele é mais exigente, e hoje a lib não tem esse conceito escrito nem verificável.

O que a lib tem hoje (verificado no main)
  • --ca-vh (100vh, e 100dvh sob @supports) e --ca-vh-min (100vh, e 100svh sob @supports; "minimum height for full-screen sections") em styles/tokens.css:121-124 e :250-253. AGENTS.md regra 10 manda usar var(--ca-vh) e nunca 100vh/100dvh, e não cita --ca-vh-min: o token da viewport pequena existe, mas não está no guia nem em docs/css-api.md. (Correção: a primeira versão desta issue dizia que --ca-vh era a única altura; estava errado.)
  • Um precedente de tipografia por altura: o título editorial "capped by viewport height so it fits one screen" (tokens.css:27).
  • #1084 proíbe vazio sem função e "altura mínima de uma tela" para reservar espaço. #1055 e #1080 tratam largura e área morta.
  • O mais próximo que já existe: #1003 R10 ("a informação primária aparece sem rolar": reprova quando ela começa abaixo de uma tela no desktop ou a página passa de 2,5 telas) e #1044 (orçamento de altura do cabeçalho). #1054 já cita as fontes sobre svh/lvh/dvh (S13, S14). Esta issue não repete essas regras; ela acrescenta o que falta nelas: a tela composta cabe inteira (não só a informação primária), nada é cortado na dobra, vale no celular e em alturas curtas, e há token, primitivo e detector para isso.
  • auditLayout (testing/layout-audit.ts) verifica rolagem lateral, sobreposição, texto cortado pela própria caixa e alvo de toque. Não tem detector de altura: não sabe se a tela cabe nem se algo cruza a dobra.
Tipos de tela
Tipo Exemplos Regra
Tela composta cockpit/home do painel, passo de wizard, login, consentimento, seção de landing, home das docs Cabe inteira no viewport de referência, sem rolar
Tela de coleção lista, tabela, conversa A moldura cabe (título, filtros, ações, paginação visíveis); só a coleção rola, dentro da própria região
Leitura longa página de docs, changelog, termos Rola por natureza; a primeira tela é completa e nenhuma figura é cortada pela dobra; toda ilustração cabe em uma tela
Regras mensuráveis
  1. Cabe: numa tela composta, scrollHeight do documento e da região de conteúdo ≤ altura do viewport, em toda a matriz de referência.
  2. Nada cortado na dobra: com a tela (ou a seção) no topo, nenhum texto, controle, imagem ou moldura cruza a borda inferior. O que não cabe começa inteiro na tela seguinte.
  3. Uma seção, uma tela: em páginas de seções (landing), rolar uma tela traz a próxima seção inteira, do título ao último elemento.
  4. Cabe por composição, não por miniatura: tipografia e espaçamento escalam com largura e altura; mídia é dimensionada pela altura disponível. Pisos: texto corrido 16px, alvo de toque 44px, contraste igual.
  5. Nunca recortar para caber: min-block-size, nunca height + overflow: hidden. Com zoom de 200%, texto ampliado ou celular deitado, a tela cresce e rola normalmente, sem sobreposição.
  6. Cheia, não esticada: caber não é preencher com vazio. Uma seção curta esticada até uma tela viola o #1084; ou ganha conteúdo real, ou divide a tela com a vizinha.
  7. Matriz de referência tem alturas, não só larguras: 1920×1080, 1440×900, 1366×768, 1280×720, 430×932, 390×844, 360×640. As alturas curtas (768, 720, 640) são onde a composição quebra, e hoje ninguém testa nelas.
  8. Barras do navegador móvel: uma seção de altura cheia baseada em dvh muda de tamanho quando a barra de URL recolhe. Seção estável pede a viewport pequena (svh); conteúdo que deve chegar até a borda pede a dinâmica.
O que a lib deveria oferecer
  • Tokens: documentar --ca-vh-min como a base de seção estável (hoje só aparece no CSS), acrescentar a viewport grande se houver uso, e um token de altura útil (viewport menos cabeçalho, barra inferior e áreas seguras do shell), para a tela não refazer a conta à mão. A landing do wi derivou a altura de tela de --ca-vh-min menos a altura da barra, à mão.
  • Primitivo de tela: PageShell fit (ou Screen) para tela composta: min-block-size na altura útil, grade que distribui o conteúdo, e a região de coleção como único ponto de rolagem. Para sites: Section fit com a mesma regra por seção.
  • Tipografia e espaço por altura: estender o precedente do título editorial para uma escala clamp() que considera vh, usada por hero, KPI e títulos de seção.
  • Detectores no auditLayout (#1290): screen-fit (telas declaradas como compostas), fold-slice (elemento cruzando a dobra na primeira tela e no topo de cada seção), figure-taller-than-viewport (ilustração maior que uma tela) e a matriz de viewports com alturas curtas como padrão.
  • Lint: height: 100vh|100dvh + overflow: hidden em contêiner de conteúdo; uso de vh cru em vez do token. Coerente com o aviso de min-height em vh proposto no #1084.
  • Guia "Composição por tela" no guides.json (servido pelo ca-ui-mcp), com a tabela de tipos, a matriz e antes/depois, e uma linha no AGENTS.md do pacote: declarar o tipo de tela antes de desenhar.
Evidência no wi
  • Home do painel refeita como tela composta (commit 0f9bd486): console da sessão com 24 h de tráfego, fila de pendências e frota. Medido em produção a 1296×712: rolagem do documento 0 e da região de conteúdo 0. No celular a fila mostra o item mais urgente e "+N" em vez de crescer.
  • Estado "sessão não conectada" da mesma tela tinha ~700px vazios; a correção preencheu com causa, quando caiu e como resolver.
  • Landing atual: 9.230px a 1440×900 (10,3 telas), 401 palavras, nenhuma tela do produto (medido). A nova está sendo feita com as regras acima e um spec que verifica cada seção em cada viewport da matriz.

2. Painel: o que quebrou e onde está

Defeito visto pelo dono Regra que resolveu Issue
Aviso global fora da coluna da página (título, aviso e corpo em eixos diferentes) Uma coluna para tudo que a página mostra #1337, #673
Estado vazio com botão virando barra de 360px Ação com largura do conteúdo, centrada #1338
Abas inferiores com legendas de tamanhos aparentes diferentes Legenda curta por aba #1339
Cartões de sessão com anatomias diferentes Uma anatomia por tipo de registro (commit 5963c426) sem issue própria; relacionado ao #1331
Lista em modo cards no celular: chips um por linha, linha "AÇÕES" Campo de vários valores ocupa a largura; ações no cabeçalho do cartão #1341
Chip com rótulo longo quebrando em duas linhas Chip é uma linha, com reticências e title #1340
Gráfico de atividade exigiria echarts Faixa de 24 colunas em CSS #1342
Abas coladas no toque; controle segmentado truncando Espaçamento de toque #1292, #1293
Botão de fechar do Alert com 28px Alvo de 44px #1336

Números: sem o workaround do #1340 falham 5 testes e sem o do #1341 falham 8 (relato). O menor BarChart do charts mede 175 KB gzip (relato); a rota da home ficou em 34,8 kB, 11,7 kB gzip, sem echarts no build (medido).

Lição que não é de um componente: toda tela foi revisada por matriz de estados (conectada, desvinculada, offline, criada, sem sessão, muitas sessões) × viewport × tema, em screenshots. Os defeitos apareceram nos estados que ninguém abre no desenvolvimento.

3. Docs: leitura no celular

Defeito Regra Issue
code em linha quebrando no meio do identificador Token inteiro; só quebra depois de / . _ - : acima de 24 caracteres #1343
Tabela que rola sem mostrar que rola; região sem nome Degradê e seta na borda; região focalizável e nomeada #1344
Tabela de definição espremida Empilha linhas por regra determinística (2 a 4 colunas, primeira só com código, até 16 linhas) #1345
td { min-width: 7rem } no pacote publicado Contrato do #788 #741
Barra Anterior/Próxima fixa sobre o texto Pager no fluxo, último bloco #1346

A varredura automática de todas as páginas (104 páginas, 390 e 1440px, claro e escuro) saiu de 769 achados para zero (relato) e roda no CI do wi. Ela existe só no app; é o tipo de coisa que deveria vir da lib (#1290, #929).

Em andamento: componentes de ilustração para docs (Flow, Sequence, Screen com tela do produto em HTML/CSS, grade de escolhas por intenção), todos com a regra da seção 1 (ilustração cabe em uma tela). Quando terminar, comento aqui o contrato de cada um (props, tokens, alternativa em texto) como proposta para area:docs.

4. Landing e páginas de produto

Em andamento. O que já está decidido e vale como diretriz:

  • A imagem principal é o produto funcionando (composição de interface em HTML/CSS com tokens), não foto de banco nem ilustração genérica. Pede blocos que a lib não tem: moldura de aparelho, conversa, nota de voz com transcrição, estado de ligação, painel de código. Relacionado: #753 (blocos de marketing), #754 (cabeçalho estático).
  • Menos texto: um título, uma linha de apoio e três provas visuais. Título diz o que a coisa é; sem slogan, sem rótulo em maiúsculas, sem "A · B · C", sem numeração decorativa.
  • Texto animado acessível: a landing antiga dividia o título em spans e deixava uma segunda cópia no DOM; o textContent do h1 era "MANDA.MANDA. CHEGA.CHEGA." (medido). Um primitivo de texto dividido em ./motion (#1097) deveria expor a frase uma vez e marcar os spans animados com aria-hidden.
  • Segue o tema do visitante (claro e escuro), com os mesmos tokens do produto.
  • Toda afirmação da página aponta para uma fonte (código, plano, doc); o que não tem fonte sai.
  • Formulário de entrada em passos curtos, cada passo uma tela (seção 1), com finalidade declarada e consentimento explícito.

5. Processo que funcionou

Proposta de "pronto" para qualquer tela, para entrar no guia do agente (cli/agent-guide.ts):

  1. Declarar o tipo de tela (seção 1) e a matriz de estados antes de desenhar.
  2. Construir, capturar cada estado × viewport (com alturas curtas) × tema, criticar olhando a imagem, repetir pelo menos duas vezes.
  3. Defeito da lib: issue com a causa medida, comentário ca-ui-workaround(#N) no código, um teste que falha sem o workaround e uma linha na tabela do app. Sem teste, o workaround nunca sai.
  4. Detectores automáticos no CI (rolagem lateral, corte na dobra, caber na tela, vazio, alvo de toque), não só revisão visual.
  5. Conferir em produção com dados reais e dizer o que foi medido e o que não foi (aparelho real, por exemplo).

Critério de aceite

  • Guia "Composição por tela" publicado (tipos de tela, regras 1 a 8, matriz de referência com alturas).
  • --ca-vh-min documentado no guia e no css-api.md; token de altura útil do shell.
  • PageShell fit / Section fit (ou equivalente) com teste nas alturas 640, 720 e 768.
  • auditLayout: screen-fit, fold-slice, figure-taller-than-viewport; matriz com alturas curtas por padrão.
  • Lint para 100vh/100dvh cru e para height de viewport + overflow: hidden em conteúdo.
  • Guia do agente com o "pronto" da seção 5.
  • Seções 3 e 4 atualizadas com o contrato dos componentes de ilustração e dos blocos de produto quando o wi terminar.

Relacionados

#1003 (R10 e R2: esta issue aperta o R10 para telas compostas), #1084 (sem vazio, sem altura mínima de uma tela), #1044 (orçamento de altura), #1054 (lista de verificação do painel e fontes de unidades de viewport), #1055 (página sem área morta), #1080 (largura por receita), #922 (princípios de layout), #1290 e #929 (detectores como pacote), #1330 e #1331 (aprendizados do Atlas), #753, #754, #1097 (sites), #1333 (Sheet e viewport visual).

As seções 2 e 3 são um mapa: os defeitos listados continuam nas issues próprias e nenhum foi reaberto aqui.

Lingua principale
TypeScript
Stelle
6
Fork
3
Merge medio
5h 21m
PR unite (30g)
378

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di codeatlasdev/ui

Tutte le issue di codeatlasdev/ui

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.