Composição por tela: ver tudo sem rolar e nada cortado na dobra (regra do dono) + aprendizados do wi em painel, docs e landing
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
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, e100dvhsob@supports) e--ca-vh-min(100vh, e100svhsob@supports; "minimum height for full-screen sections") emstyles/tokens.css:121-124e:250-253.AGENTS.mdregra 10 manda usarvar(--ca-vh)e nunca100vh/100dvh, e não cita--ca-vh-min: o token da viewport pequena existe, mas não está no guia nem emdocs/css-api.md. (Correção: a primeira versão desta issue dizia que--ca-vhera 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
- Cabe: numa tela composta,
scrollHeightdo documento e da região de conteúdo ≤ altura do viewport, em toda a matriz de referência. - 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.
- 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.
- 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.
- Nunca recortar para caber:
min-block-size, nuncaheight+overflow: hidden. Com zoom de 200%, texto ampliado ou celular deitado, a tela cresce e rola normalmente, sem sobreposição. - 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.
- 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.
- Barras do navegador móvel: uma seção de altura cheia baseada em
dvhmuda 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-mincomo 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-minmenos a altura da barra, à mão. - Primitivo de tela:
PageShell fit(ouScreen) para tela composta:min-block-sizena altura útil, grade que distribui o conteúdo, e a região de coleção como único ponto de rolagem. Para sites:Section fitcom a mesma regra por seção. - Tipografia e espaço por altura: estender o precedente do título editorial para uma escala
clamp()que consideravh, 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: hiddenem contêiner de conteúdo; uso devhcru em vez do token. Coerente com o aviso demin-heightemvhproposto no #1084. - Guia "Composição por tela" no
guides.json(servido peloca-ui-mcp), com a tabela de tipos, a matriz e antes/depois, e uma linha noAGENTS.mddo 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
textContentdo 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 comaria-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):
- Declarar o tipo de tela (seção 1) e a matriz de estados antes de desenhar.
- Construir, capturar cada estado × viewport (com alturas curtas) × tema, criticar olhando a imagem, repetir pelo menos duas vezes.
- 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. - Detectores automáticos no CI (rolagem lateral, corte na dobra, caber na tela, vazio, alvo de toque), não só revisão visual.
- 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-mindocumentado no guia e nocss-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/100dvhcru e paraheightde viewport +overflow: hiddenem 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
- Nessun Dockerfile né file Docker Compose
- Ha un modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di codeatlasdev/ui
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
codeatlasdev/ui#1340 ·
I maintainer di solito rispondono entro 1 giorno
-
area:a11y area:components bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
codeatlasdev/ui#1336 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 77/100
codeatlasdev/ui#1329 ·
I maintainer di solito rispondono entro 1 giorno
-
good first issue
Difficoltà 2/5 1-3 ore Idoneità per principianti 74/100
codeatlasdev/ui#1292 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
area:components enhancement good first issue
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
codeatlasdev/ui#1198 ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di codeatlasdev/ui
Issue simili
-
Console writes URL credentials to the local log, though AGENTS.md says secrets never reach diskAperta
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 86/100
sandbox-quantum/switch#2163 ·
I maintainer di solito rispondono entro 1 giorno
-
automated issue report
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 78/100
I maintainer di solito rispondono entro 1 giorno
-
area/dashboard kind/bug QA/dev-automation
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 75/100
I maintainer di solito rispondono entro 1 giorno
-
bug pydanty:is-working
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
pydantic/pydantic-ai#13939 ·
I maintainer di solito rispondono entro 1 giorno
-
self-host
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
funmusicplace/mirlo#2625 ·
I maintainer di solito rispondono entro 1 giorno