yg2224/app-shell-ui

App Shell UI

Você está implementando App Shell UI: um skill de design de frontend reutilizável com dois modos. Escolha a superfície antes de escolher os pixels. Não transforme toda solicitação em um shell de desktop, e não transforme todo aplicativo em uma página de marketing genérica.

Escolha a superfície primeiro

Modo	Uso para	Estrutura padrão	Não use para
Modo App	Ferramentas logadas, configurações, consoles, chat, e-mail, bancadas, fluxos operacionais	Navegação esquerda persistente + canvas de tarefa	Marketing público, leitura, comércio ou superfícies de portfólio
Modo Site	Sites de marketing, lançamentos de produtos, portfólios, páginas editoriais, catálogos, documentação, conteúdo público	Uma macroestrutura específica da página selecionada da jornada do usuário	Um template genérico de herói + três cartões + CTA, ou um shell de aplicativo falso

Se a solicitação tiver ambas as superfícies, projete-as separadamente: Modo Site para aquisição ou informação pública, Modo App para o produto logado. Compartilhe tokens de marca onde apropriado, mas não force o mesmo layout ou densidade em ambas.

Pré-voo (ambos os modos)

Antes de tomar decisões visuais em um projeto existente, inspecione a rota e sua fonte visual mais próxima de verdade: tokens atuais, tipografia, mecanismo de tema, ativos, framework, componentes primitivos e bibliotecas de ícones/movimento instaladas. Preserve um sistema estabelecido a menos que o usuário peça um redesign. Verifique package.json antes de adicionar dependência; não assuma que uma biblioteca existe ou misture dois sistemas de design não relacionados em uma única superfície.

Se o briefing for genuinamente ambíguo entre dois resultados materialmente diferentes, faça exatamente uma pergunta curta. Caso contrário, declare a inferência em uma frase e continue. Não transforme uma pequena solicitação de implementação em uma entrevista de requisitos.

Fluxo de trabalho do Modo App

1. Escolha um modelo de layout (obrigatório antes dos pixels):
   • 设置型 — navegação esquerda estreita + formulário / lista de alternância
   • 控制台型 — nav esquerda + grade de cartões / lista de status
   • 工作台型 — árvore de sessão + estado vazio centralizado + cartão de composição
   • IM / 三栏型 — trilho de ícones + lista + detalhes
2. Defina o orçamento do viewport — defina o viewport de desktop alvo (mínimo 1280×800) e a tarefa principal para a rota antes de adicionar conteúdo. Veja references/layouts.md → Viewport budget / 单页容量.
3. Bloqueie tokens de tema dual — use references/tokens.md (claro + escuro são ambos obrigatórios por padrão).
4. Componha a partir de receitas — use references/components.md (item de nav, cartão, linha de lista, alternância, pílula, vazio/compositor). Receitas são agnósticas ao tema; apenas variáveis mudam.
5. Implemente com variáveis CSS + data-theme="light"|"dark"; adicione um alternador de tema; mapeamento Tailwind/shadcn opcional.
6. Auto-verifique — execute a lista de verificação no final deste arquivo em ambos os temas e no viewport alvo antes da entrega.

Stack padrão quando livre para escolher:

Camada	Padrão
Marcação	HTML semântico ou React
Estilo	Variáveis CSS + utilidade leve/Tailwind
Componentes	shadcn / @coss style (New York + neutros tipo zinco)
Ícones	Estilo Lucide traço 1.5–2px, uma família apenas
Tema	Claro + Escuro (alternador + prefers-color-scheme opcional do SO)

Prefira um único HTML auto-contido para demonstrações a menos que o usuário queira integração com projeto.

Arquitetura do Modo App

L0  Chrome da janela (sinais de trânsito opcionais / barra de título / ferramentas superiores + alternador de tema)
L1  Barra lateral ou trilho de ícones
L2  Canvas de conteúdo (cinza suave claro / carvão suave escuro)
L3  Superfícies (cartões elevados, painéis, listas)

Largura da barra lateral: 220–260px (nav textual) ou 48–56px (trilho de ícones). Padding do conteúdo: 20–28px. Espaçamento em grade de 4px.

Orçamento de página padrão: o estado inicial do desktop deve completar sua tarefa principal em um viewport após a inclusão do chrome do shell. Mantenha um pequeno espaço respiratório inferior; não faça a página inteira rolar verticalmente apenas para revelar conteúdo secundário rotineiro. Coleções longas podem usar uma região de rolagem interna limitada quando o produto genuinamente precisar. 中文偏好：每个页面尽量一屏完成，内容达到首屏容量就停止继续堆叠。

Modo App Inegociáveis

1. Dois temas: envie conjuntos de tokens claro e escuro a menos que o usuário queira explicitamente apenas um.
2. Um primário de marca para: botões primários, alternância ON, preenchimento de progresso, borda/fundo selecionados, links. O primário escuro pode ser um gêmeo ligeiramente mais brilhante (ex. #007AFF → #0A84FF).
3. Escada de superfície (ambos os temas): fundo do app → fundo da barra lateral → superfície elevada (contraste fraco). Claro: cinza suave + cartões brancos. Escuro: carvão suave + cartões cinza elevados — não página pura #000 + cartões puros #fff.
4. Escada de texto: primário / secundário / terciário (valores diferem por tema).
5. Hierarquia via bordas de 1px primeiro; sombra opcional e específica ao tema.
6. Escada de raio: 8 / 12 / 16 / 999 (compartilhado entre temas).
7. Padrão de cópia: título + uma linha de subtítulo suave.
8. Movimento: 150–200ms cor/fundo apenas; sem teatro de bounce.
9. Troca de tema: data-theme na raiz + alternador visível; persista com localStorage quando possível.
10. Restrição de ícones (conteúdo): conteúdo direito padrão para texto + ícones traço + pílulas de status. Emoji/ilustração são acentos opcionais apenas — nunca o padrão para cada linha de lista ou cartão. Prefira zero emoji em listas densas; no máximo uma marca decorativa em um banner ou estado vazio.
11. Pares de mesma altura: qualquer par de conteúdo lado a lado (lista + compositor, painel + painel, irmãos de estatísticas que formam um par de cartões em uma linha) deve compartilhar a mesma borda inferior externa. Use grid/flex stretch + coluna flex + flex: 1 nas superfícies — nunca align-items: start que deixa um cartão curto. Veja references/layouts.md → Equal-height side-by-side columns.
12. Orçamento de conteúdo de viewport único: no desktop, a rota padrão não deve exigir rolagem vertical no nível da página. Preencha o canvas utilizável com conteúdo priorizado, mas pare antes que o primeiro viewport seja excedido. Se o conteúdo não couber, remova, encurte, pagine, divulgue, tabule ou divida em outra rota; nunca recorte controles ou encolha texto abaixo da legibilidade. Em mobile, mantenha a ação principal e o status no primeiro viewport; rolagem natural é reservada para conteúdo genuinamente longo.

Modo App Faça / Não Faça

Faça	Não Faça
Nav esquerda + conteúdo direito	Arte herói full-bleed como todo o app
Canvas suave + cartões elevados em ambos os temas	Escuro cyber neon ou preto OLED puro por padrão
Acento único (par claro/escuro)	Ícones de nav arco-íris como múltiplos primários
Ícones traço (estilo Lucide) na nav + conteúdo	Conjuntos de ícones misturados preenchidos + traço
Cartões/listas focados em texto; pílula para status	Emoji em cada linha / cartão / cabeçalho de seção
Status como pequenas pílulas/texto suave	Banners de alerta largos e barulhentos para estados normais
Alternador de tema no chrome	Modo escuro via filter: invert()
Separação de borda por tokens	Cores de chrome #fff / #000 codificadas
Espaçamento arejado	Empacotamento denso de planilha
≤1 acento de emoji por região principal (ou nenhum)	Banner + cartões + listas todos pesados em emoji
Cartões lado a lado de mesma altura (stretch)	Um par alto / um baixo (align-items: start)
Rota de uma tela com blocos priorizados	Rolagem de página ilimitada para conteúdo rotineiro
Rolagem interna limitada para coleções longas	Esconder ou recortar conteúdo com alturas fixas

Ordem de Montagem de Página do Modo App

1. Shell (janela + barra lateral + principal)
2. Bloco de marca na barra lateral
3. Grupos de nav + item ativo
4. Cabeçalho da página (H1 + subtítulo suave + ações)
5. Alternador de tema na barra de título ou configurações (obrigatório para demos)
6. Barra de ferramentas opcional (busca + filtro segmentado)
7. Blocos de conteúdo por prioridade: banner → estatísticas → grade/lista primária → duas colunas secundária. Pare quando o orçamento do viewport estiver cheio; mova blocos de menor prioridade para abas, divulgação, paginação ou outra rota.
8. Para cada linha de pares de duas colunas: aplique receita de mesma altura (stretch + superfícies flex) sem forçar overflow.
9. Conecte interação: troca de nav, seleção, alternâncias, filtros, alternador de tema

Notas de Implementação do Modo App

• Coloque tokens claro em :root, :root[data-theme="light"] e escuro em :root[data-theme="dark"] (veja references/tokens.md).
• Componentes consomem apenas variáveis — nenhum hex de marca/superfície codificado em regras de componente.
• Nav selecionada: wash primário suave + texto primário, raio 8px (wash mix difere por tema).
• Cartões: --bg-surface + 1px --border + raio 12; selecionado: anel/borda primária. Marca principal = ícone traço em placa suave ou nenhuma marca — não emoji por padrão.
• Linhas de configurações / feed: ícone traço 16–18px (placa suave opcional) + título + descrição suave + controle direito. Evite ícones de lista com emoji.
• Vazio / nova sessão: título centralizado + compositor redondo grande; chips + CTA primário. Marca d'água vazia pode ser um ícone traço fraco ou um único glifo discreto — não uma pilha de emoji.
• Banner: prioridade a texto; opcional no máximo um pequeno azulejo de acento (frequentemente nenhum).
• Zona de adição tracejada para "coleção vazia + criar" (sinal de mais, não emoji).
• Botões secundários, trilhas de segmento, trilhas OFF de alternância devem usar tokens de tema (--secondary-btn-bg, --seg-track, --toggle-off) — rgba cinza claro não funciona no escuro.
• Mantenha o shell da página fixo (min-height: 0; overflow: hidden) por padrão. Se uma lista, log, tabela ou histórico de mensagens for inerentemente longo, coloque a rolagem em uma região filha limitada com um orçamento de altura claro; não faça do corpo do documento ou de todo o canvas de conteúdo o contêiner de rolagem padrão.
• Valide o estado de primeiro carregamento em um viewport de desktop de pelo menos 1280×800 (e em um viewport móvel estreito). Verifique se a tarefa principal, controles e status estão visíveis sem rolagem de página e se nenhum texto ou controle está recortado.

API do Tema (canônico)

// data-theme = "light" | "dark"
// chave localStorage: "app-shell-theme"
// toggle alterna atributo; init lê storage então prefers-color-scheme

Bloco mínimo de tokens CSS

Copie o bloco dual-tema de references/tokens.md.

Esqueleto HTML mínimo

<html data-theme="light">
…
<div class="window">
  <header class="titlebar">
    …
    <button type="button" data-theme-toggle aria-label="Trocar tema claro/escuro">…</button>
  </header>
  <div class="shell">
    <aside class="sidebar">…</aside>
    <main class="main">…</main>
  </div>
</div>

Semente de Prompt do Modo App

Claro

Interface de utilidade desktop macOS clara: barra lateral cinza suave de 240px (ícones traço + rótulo, selecionado = wash primário claro + raio 8px), canvas principal cinza suave com cartões brancos arredondados; primário único #007AFF para botões, alternâncias, progresso, anel de seleção; três cinzas de texto; raio 8–16px; quase sem sombra, bordas claras de 1px; linhas de configurações/lista com pequenos ícones traço (não emoji) + título/desc + alternância direita ou pílula de status; área de conteúdo prioridade a texto, mínimo ou sem emoji; estado vazio = título centralizado + compositor redondo grande.

Escuro

Mesmo shell em modo escuro: canvas carvão suave #1C1C1E, barra lateral #161617, cartões elevados #2C2C2E, bordas branco 8% alfa, texto #F5F5F7 / #A1A1A6 / #6C6C70, primário #0A84FF, nav selecionada = primário 22% misturado na superfície do cartão; sem página preta pura; sem filtro invert; inclua alternador de tema.

Troque apenas substantivos de negócio; mantenha shell + regras dual-tema.

Fluxo de trabalho do Modo Site

O Modo Site é para trabalho web voltado ao público. Pode usar rolagem de documento normal e não deve herdar o canvas fixo, barra lateral, chrome de janela artificial ou limite de conteúdo de um viewport do Modo App. Leia references/web-frontend.md antes de implementar o Modo Site.

1. Faça uma leitura de design — declare o tipo de página, público, trabalho principal e um tom concreto. "Limpo e moderno" não é uma direção. Infira a partir do briefing e da marca existente; faça uma pergunta curta apenas quando duas direções produziriam trabalho materialmente diferente.
2. Escolha o modo de superfície — Persuadir para uma página de conversão ou lançamento, Ler para docs ou conteúdo editorial, Experiência para trabalho de portfólio/galeria/evento, ou Catálogo para navegar e comprar. O produto logado permanece no Modo App.
3. Escolha uma macroestrutura antes dos componentes — escolha uma forma de página que se encaixe no trabalho, como revelação de produto, história liderada por evidências, narrativa editorial, índice de trabalho, catálogo, guia de leitura ou pôster de campanha. Não use padrão de herói centralizada -> três cartões iguais -> CTA.
4. Comprometa-se com um sistema visual — bloqueie uma paleta, papéis de tipo, regras de espaçamento/raio, tratamento de imagem e um diferenciador visível. Reutilize tokens de marca existentes; caso contrário, defina variáveis CSS semânticas e consuma-as em vez de improvisar cores ou fontes por seção.
5. Planeje verdade e mídia — use fatos fornecidos, capturas de tela reais/estados de produto, ativos licenciados ou mapas de bitmap gerados apropriados ao briefing. Não invente clientes, métricas, depoimentos, logotipos, dashboards falsos, chrome de navegador ou dados de placeholder que pareçam reais. Alegações desconhecidas permanecem visivelmente marcadas como placeholders ou são omitidas.
6. Construa a jornada de informação — use landmarks semânticos e uma hierarquia que torne a próxima ação óbvia. Deixe seções variarem em composição quando seus trabalhos diferirem; cartões são para itens repetidos e limitados, em vez de um wrapper de seção de página padrão.
7. Implemente comportamento completo — use controles e links nativos, foco visível, estados de carregamento, vazio, erro, desabilitado e sucesso quando relevante. Movimento deve explicar feedback ou mudança espacial, use transform/opacity, respeite prefers-reduced-motione fique fora de fluxos de alta frequência a menos que seja efetivamente instantâneo.
8. Inspecione a saída renderizada — valide capturas de tela de desktop e mobile, extremos de conteúdo real, contraste, navegação por teclado, dimensões de imagem de carregamento, overflow e o primeiro viewport. A proposta do herói, ação principal e ponto focal visual devem caber em 1280x800; rolagem de página abaixo disso é normal para um site.

Inegociáveis do Modo Site

1. Não envolva um site público no chrome do Modo App a menos que o usuário peça explicitamente uma prévia de produto ou rota de aplicativo logado.
2. Dê a cada página pública um título de documento semântico (<title>) e uma descrição meta (<meta name="description">) que encapsule o conteúdo da página, não o nome do produto.
3. Use landmarks de navegação (<nav>, <main>, <header>, <footer>, <article>, <section>) e garanta que a estrutura de cabeçalhos (h1–h6) seja lógica e escalonada.
4. Os botões de CTA devem usar texto de ação real ("Inscreva-se", "Compre agora", "Baixe", "Explore") em vez de rótulos genéricos como "Saiba mais" a menos que seja apropriado ao contexto.
5. Imagens devem ter alt descritivo, dimensões explícitas (width/height em HTML ou CSS) e ser otimizadas para a largura de exibição; imagens decorativas devem ter alt="".
6. Animações devem ser usadas com moderação e devem parar ou reduzir com prefers-reduced-motion. Evite animações de loop de página inteira, fogos de artifício de cursor ou rolagem parallax pesada.
7. Prefira HTTP seguro e recursos auto-hospedados; não incorra em custos de licenciamento ou limites de taxa de chamadas de API de terceiros para assets de site que devem ser estáticos.
8. A página inicial do site deve carregar em <3s em uma conexão 3G simulada (ou o usuário deve ser avisado se mídia pesada for necessária).

Notas de Implementação do Modo Site

• Use tipografia fluida (unidades clamp()) para escalar texto entre viewports de mobile estreito e amplo desktop.
• Defina uma paleta de cores baseada em tokens --color-* semânticos em vez de hex inventado por seção.
• Use consultas de mídia CSS para layout (incluindo prefers-color-scheme para tema escuro se o modo escuro for implementado).
• Para sites de múltiplas páginas, use um sistema de roteamento adequado (arquivos HTML estáticos vinculados, ou um framework como Next.js / Remix / Astro).

Dicas de Layout do Modo Site

• Persuadir: estrutura de página de uma coluna, grande herói com valor claro, seção de como funciona, prova social (logotipos ou depoimentos), e um CTA forte no final.
• Ler: largura máxima de coluna de texto de ~680px, margens generosas, divisões suaves de seção, imagens podem ser maior que a largura do texto para destaque.
• Experiência: grid de portfólio com hover/efeitos, espaçamento vertical ousado, tipografia expressiva, uso de cor para definir tom em vez de moldar grade.
• Catálogo: grade de cartões com filtros, sidebar para navegação de categoria (ou top nav para mobile), prioridade à imagem com texto de apoio.

Lista de Verificação de Qualidade (ambos os modos, após implementação)

• 1. Estado de primeiro carregamento: tarefa principal visível, controles acessíveis, sem rolagem desnecessária (Modo App) ou rolagem natural começa abaixo do herói (Modo Site).
• 2. Tema dual verificado: alternador de tema funciona, ambos os temas têm contraste suficiente, sem cores não definidas.
• 3. Layout responsivo verificado em desktop (1280×800) e mobile (375×667).
• 4. Navegação por teclado: foco visível, Tab ordena logicamente, atalhos de tecla (se aplicável) funcionam.
• 5. Acessibilidade: landmarks semânticas, textos de link/alt descritivos, estrutura de cabeçalhos correta, contraste mínimo de 4.5:1 para texto normal.
• 6. Estados: vazio, carregamento, erro (se relevante) e sucesso de interação.
• 7. Sem dependências de bibliotecas externas não verificadas; pacotes conhecidos e seus tamanhos são aceitáveis.
• 8. Código segue guia de estilo do projeto (se existente) e não introduz regras CSS conflitantes.
• 9. (Modo App) Cor, raio e espaçamento usam tokens CSS personalizados, não valores codificados.
• 10. (Modo App) Cartões lado a lado têm mesma altura; listas de uma coluna podem ter alturas variadas.
• 11. (Modo Site) Meta tags de SEO definidas; página tem título descritivo e descrição.
• 12. (Modo Site) Imagens têm dimensões e alt; mídia carregada de forma eficiente.