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,347 4 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 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 内容生成。

描述

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.

主要语言
TypeScript
星标
6
派生
3
平均合并
5 小时 21 分钟
30 天内合并 PR
378

环境准备

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

codeatlasdev/ui 的其他 Issue

查看 codeatlasdev/ui 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。