Composição por tela: ver tudo sem rolar e nada cortado na dobra (regra do dono) + aprendizados do wi em painel, docs e landing
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 25/100
- Issue 类型
- 功能
- 描述清晰度
- 基本清楚
- 活跃度
- 活跃
- 技术栈
- typescript
调研方向
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.
由索引模型根据 Issue 内容生成。
描述
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.
- 主要语言
- TypeScript
- 星标
- 6
- 派生
- 3
- 平均合并
- 5 小时 21 分钟
- 30 天内合并 PR
- 378
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
codeatlasdev/ui 的其他 Issue
-
难度 2/5 1-3 小时 新手友好度 84/100
codeatlasdev/ui#1340 ·
维护者通常 1 天内回复
-
area:a11y area:components bug
难度 2/5 1-3 小时 新手友好度 76/100
codeatlasdev/ui#1336 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 77/100
codeatlasdev/ui#1329 ·
维护者通常 1 天内回复
-
good first issue
难度 2/5 1-3 小时 新手友好度 74/100
codeatlasdev/ui#1292 · 1 条评论 ·
维护者通常 1 天内回复
-
area:components enhancement good first issue
难度 2/5 1-3 小时 新手友好度 68/100
codeatlasdev/ui#1198 ·
维护者通常 1 天内回复
相似的 Issue
-
bug frontend
难度 2/5 1-3 小时 新手友好度 85/100
CivicTechWR/accessible-housing-portal#578 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 68/100
nekko-labs/nekko-agent#2998 ·
维护者通常 1 天内回复
-
难度 1/5 1 小时以内 新手友好度 86/100
sandbox-quantum/switch#2163 ·
维护者通常 1 天内回复
-
enhancement ux
难度 2/5 1-3 小时 新手友好度 72/100
lolimmlost/aidj#433 ·
维护者通常 1 天内回复
-
test: ipcShownDialogKeys.test.tsx can fail the unit run with 'window is not defined' after it ends未关闭
难度 2/5 1-3 小时 新手友好度 72/100
维护者通常 1 天内回复