Verge — Papel de superfície `sunken` (recesso), aditivo à elevação

ratified

Resumo

Propõe adicionar ao Verge um papel de superfície sunken (recesso/"well") como peer ortogonal da elevação — não um substituto. O sunken modela uma superfície escavada na sua moldura (mais escura no dark; cinza suave no light), para casos como telas de auth emolduradas, input wells, blocos de código e painéis embutidos.

A pergunta que originou este RFC foi: *"trocar o Verge para um modelo recuado, em vez de compor de níveis existentes?"* (sequência do id#190 auth recuada + design-gen#173). A recomendação é NÃO inverter o modelo de elevação — isso quebra o sistema (ver R2) — e SIM promover o recuo a um papel aditivo de 1ª classe quando o limiar de reúso for atingido (R5). Este RFC é a forma estruturalmente correta de ter o visual recuado sem regredir o Verge.

R1 — Contexto

  • id#190 quis a estética recuada no auth dark (página mais clara = moldura;

    card mais escuro = recesso), inspirada no fluxo do Google.

  • design-gen#173 (ratificado pelo owner 2026-05-29) concluiu: o look recuado

    compõe-se de níveis Verge existentes (page=--card-high, card=--surface), sem mudar o Verge — e adiou por YAGNI um token --well/--sunken dedicado até "≥3 consumidores" surgirem.

  • Este RFC reabre só a parte aditiva (o papel sunken), porque o limiar de

    reúso está próximo/atingido (R5). Não reabre a inversão do modelo.

R2 — Por que NÃO inverter o modelo de elevação do Verge

themes/elevation.kmd §R2 define profundidade tonal: no dark, a elevação é comunicada por tonal overlay que empurra a superfície para "mais clara / mais perto" — i.e. mais alto = mais claro (rampa de 6 níveis 0–5; drawer/overlay nível 5 é o mais claro). themes/depth.kmd formaliza o mesmo como eixo-z único. Inverter para "recuado canônico" (mais fundo = mais escuro) falha em quatro pontos estruturais, não estéticos:

  1. Não recursa — acaba o preto. Empilhar dialog ▸ card ▸ página no modelo

    recuado esgota o preto em ~2 passos (#1F → #0F → #00 → nada). A rampa elevada continua clareando; a recuada bate no fundo do poço.

  2. Overlays teriam que ser os mais escuros, contradizendo o eixo único de

    themes/depth.kmd ("mais perto = mais claro", projetado até XR em cm).

  3. É estética de uma superfície, não de um sistema. O recuo é lindo numa

    moldura de profundidade 1 (login/hero); um design system precisa de aninhamento arbitrário, que só a elevação tonal resolve.

  4. Blast radius desproporcional. Verge v2 recuado tocaria toda UI Koder

    (mobiledesktopweb/TV), todos os tokens de elevação, koder_web_kit, koder_kit, presets e re-auditorias — por um modelo pior no trabalho central de empilhar superfícies.

Conclusão R2: a elevação tonal permanece o modelo canônico (elevation.kmd/depth.kmd inalterados).

R3 — Modelo: sunken é ortogonal à elevação

  • Elevação responde "quão acima da página esta superfície está?" →

    recursiva, tonal (dark: mais alto = mais claro), níveis 0–5.

  • sunken responde "esta superfície é um recesso escavado na sua

    moldura?" → profundidade 1, não-recursiva por contrato.

Os dois eixos coexistem: um card elevado (nível 2) pode conter um input well sunken; o well não é uma nova base de empilhamento (nada "elevado" nasce dentro dele). Isso preserva a recursão da elevação e dá o recuo onde ele faz sentido.

R4 — Tokens propostos (valores recomendados, pendentes de ratificação)

Adiciona um token semântico, em ambos os temas, alinhado ao OLED-aware dark do verge.kmd §R4.3:

Token Dark Light Papel
--surface-sunken #0A0A0B #ECEEF0 recesso escavado na moldura

Referência das superfícies existentes (inalteradas):

Token existente Dark Light
--bg (base da página) #0A0A0B #FAFAFA
--surface #0F0F0F #FFFFFF
--card-high (mat/elevado) #1F1F22 #F1F3F5

Nota: no dark o valor recomendado de --surface-sunken coincide hoje com --bg, mas é semanticamente distinto (recesso vs base de página) e pode divergir em ajuste futuro do owner. No light é um cinza-inset suave.

R4.1 — Regras do token

  • R4.1.1 — --surface-sunken é sempre ≥1 passo mais escuro que a sua

    moldura no dark (um cinza-inset no light). Nunca mais claro que o container.

  • R4.1.2 — Não-recursivo: proibido usar --surface-sunken como container de

    componentes elevados (menusdialogscards). Quem precisa de filhos elevados usa a rampa de elevação.

  • R4.1.3 — Definição/separação por borda + tom, não por sombra de elevação

    (um recesso não "flutua"). Hairline --border opcional.

  • R4.1.4 — Contraste (a11y): texto/ícone sobre --surface-sunken mantém AA

    (≥4.5 corpo / ≥3.0 large); separação tonal recesso↔moldura ≥1.15× (mesmo budget de themes/light-dark.kmd).

R5 — Quando usar (e o gate de adoção)

Usar sunken:

  • Tela de auth emoldurada (id#190): página--card-high, card--surface

    (caso de profundidade-1 já conformante); o token entra quando há recesso dentro de uma superfície já escura.

  • Input wells (campos/áreas de entrada rebaixadas).
  • Blocos de código / <pre> embutidos.
  • Painéis inset / "poços" de conteúdo dentro de um card.

NÃO usar sunken (usar elevação): qualquer coisa que empilhe ou aninhe superfícies acima da página (cards, sheets, dialogs, menus, drawers).

Gate de adoção (resolve o YAGNI do #173): promover o token quando houver ≥3 consumidores reais confirmados. Candidatos hoje: (1) auth id#190, (2) input wells do koder_kitkoder_web_kit, (3) blocos de código do KDSdocs. Se ratificado, esses três são a primeira leva.

R6 — Impacto e migração (aditivo, baixo risco)

  • Sem mudança na rampa de elevação (elevation.kmd) nem no eixo de

    profundidade (depth.kmd). Nenhum componente elevado existente muda.

  • koder_web_kit e koder_kit adicionam um token (--surface-sunken) em

    light/dark; demais tokens intactos (verge.kmd = fonte de verdade dos tokens).

  • O KDS (tools/design-gen) documenta o papel na página verge/elevation.
  • id#190 passa a referenciar o papel sunken onde aplicável (o CSS recuado já

    shipado continua válido; vira uso nomeado do papel em vez de composição ad-hoc).

R7 — Acceptance

  • [ ] Token --surface-sunken (dark+light) em themes/verge.kmd + elevation.kmd

    (§ novo "Recesso / sunken"), com R4.1.1–R4.1.4.

  • [ ] koder_web_kit + koder_kit expõem o token (paridade com verge.kmd).
  • [ ] Página KDS documenta elevação vs sunken (eixos ortogonais).
  • [ ] ≥3 consumidores adotam (gate R5).
  • [ ] koder-spec-audit / regressão estrutural cobre R4.1.2 (não-recursivo) e

    R4.1.4 (contraste).

R8 — Decisão (owner)

Status ratified (owner rodrigo@koder.dev, 2026-05-30). Implementação: verge.kmd §R4.1/§R4.3 ganhou --surface-sunken (light #ECEEF0 / dark #0A0A0B); elevation.kmd documenta o eixo ortogonal; koder_web_kit expõe o token. koder_kit (Flutter) = follow-up (estava locado por KKIT-019 nesta janela). Recomendação confirmada (Quality > Speed, stack-principles.kmd §2): aditivo sunken, sem inverter o modelo.

Questões abertas

  • Valor exato de --surface-sunken no light (#ECEEF0 vs #F1F3F5) e se no

    dark diverge de --bg (#0A0A0B).

  • O papel ganha borda inset própria (ex.: inset 0 1px 0 rgba(0,0,0,.4))

    como cue de recesso, ou só tom+hairline?