# Contexto de implementação — Nova VendePay

Use este documento como briefing canônico antes de desenvolver ou revisar frontend da nova VendePay.

## Entradas canônicas

- Referência atual: https://design.vendepay.com.br/current
- Hub visual: https://design.vendepay.com.br
- Índice para agentes: https://design.vendepay.com.br/llms.txt
- Manifesto estruturado: https://design.vendepay.com.br/ai/design-system.json
- Repositório de UX: https://github.com/Vendepay-Org/nova-vendepay-ux
- Core e checkout: https://github.com/Vendepay-Org/nova-vendepay
- Painel do vendedor: https://github.com/Vendepay-Org/nova-vendepay-frontend
- Gestão: https://github.com/Vendepay-Org/nova-vendepay-gestao-frontend

## Como resolver divergências

1. Código, contratos, migrations e testes definem o comportamento atual.
2. `src/shared/design-system/` dos frontends define tokens e componentes executados.
3. `/current` e este repositório definem intenção visual e padrões compartilhados.
4. Os `.dc.html` são snapshots históricos de junho de 2026.

Não replique comportamento antigo de protótipos. Confirme o código atual, documente a diferença e atualize a referência viva.

## Regras de produto vigentes

### Produto, preço e funil

- A V1 aceita uma oferta principal e um plano principal por produto; outra identidade conflita com a regra.
- O preço mínimo é 10 na moeda base e o descritor de fatura é obrigatório.
- Etapas atuais: Básico, Recursos, Preço, Funil, Afiliados e Links.
- Recorrência fica dentro de Preço; o Checkout Builder abre por Links.
- Tracking: Meta, TikTok, Google Ads e UTMify, além de pixels de afiliados quando aplicável.
- Funil: múltiplos order bumps, ramos de aceite/recusa, upsell/downsell, páginas hospedadas ou externas, planos recorrentes, comissão e coprodução.

### Checkout

- Existe um `Checkout principal` e um `Estilo principal` por produto.
- Não crie seleção, duplicação ou campanhas como múltiplos checkouts.
- Há controles de estilo, campos, e-mail obrigatório, URL de obrigado, wallets, cupom, sessão/recuperação e páginas externas de funil.
- Mercado global usa conversão dinâmica a partir de um preço base. O vendedor não informa um preço por moeda.
- A prévia suporta 12 idiomas.
- Diferencie capacidade técnica de disponibilidade no painel. Um meio suportado por runtime/adquirente pode continuar indisponível ou `em breve` para o vendedor.
- Contratos internos ainda podem expor `checkouts[]` e criação por compatibilidade. Isso é dívida técnica, não capacidade da experiência.

### Saldos e saque

- Existe um único fluxo de saque manual/sob demanda.
- PIX e cripto/Base são destinos do mesmo saque, não experiências separadas.
- Nunca exponha nomes de provedores ou arquitetura interna ao vendedor.
- O número principal é sempre Disponível; separe A liberar, Reservado e Em envio por moeda.
- KYC, dívida ou outro saque aberto podem bloquear uma solicitação.
- Antes de confirmar, explique spread de 2%, IOF de 3,5% somente para destino BRL e tarifa fixa equivalente a R$ 4,99.
- Moeda é explícita e conversão nunca é silenciosa.

### Entrada e KYC

- Login atual por e-mail/senha, recuperação/redefinição e verificação de e-mail.
- Não prometa login Google sem implementação correspondente.
- KYC unifica PF/PJ/PEP e upload de documentos.
- Validação incompleta pode bloquear tanto vendas quanto saques.
- O cadastro pode antecipar destino PIX ou cripto na rede Base.

## Stack e linguagem visual

- React 19 + TypeScript.
- vanilla-extract para estilos tipados.
- Base UI para primitivas headless.
- Lucide para iconografia.
- Poppins em títulos, KPIs e dinheiro; Open Sans em corpo, rótulos e ajuda.
- Temas claro e escuro por tokens.

| Papel | Claro | Escuro |
|---|---|---|
| Brand | `#04D361` | `#0BF372` |
| Accent | `#049366` | `#0BF372` |
| Background | `#F8F9FA` | `#070707` |
| Surface | `#FFFFFF` | `#101010` |
| Texto primário | `#212529` | `#E1E1E6` |
| Texto terciário | `#667085` | `#8A8A96` |
| Borda | `#E6E9EF` | `#29292E` |

- Espaçamento base de 8px.
- Raios: 8, 10, 12, 16 e pill.
- Foco: borda accent + ring suave.
- Dinheiro: Poppins, numerais tabulares e moeda explícita.
- Alvo de toque mínimo de 44px.

## Status de venda atuais

| Enum | Rótulo | Família |
|---|---|---|
| `PENDING` | Pendente | awaiting |
| `PAID` | Paga | success |
| `FAILED` | Recusada | closed |
| `REFUND_REQUESTED` | Aguardando reembolso | awaiting |
| `REFUNDED` | Estorno | informative |
| `CHARGED_BACK` | Chargeback | closed |

Sempre combine cor, ícone e rótulo. A mensagem deve explicar estado, causa e próximo passo. `Reembolso parcial`, `Reembolso de chargeback`, `Disputa ganha`, `Assinatura encerrada` e `Situação mista` são apresentações derivadas, não novos enums base.

## Operação atual

- Dashboard: seis KPIs, filtros de período/visão/moeda, recorrência, pagamento, origem, estado, premiações e atualização dos dados.
- Vendas: jornadas e cobranças agrupadas, reembolso por cobrança, parcial, chargeback evitado, disputa ganha, dívida e recuperação.
- Assinaturas: retentativas, cancelamento ao fim do período, invoices, dunning, trial e participante somente leitura.
- Seller: inclui Coproduções e Configurações/Webhooks; mobile tem quatro destinos primários + Mais.
- Gestão: Dashboard, Vendas, Finanças, Assinaturas, Produtos, Alertas, Chargebacks, Reconciliação, Contabilidade, Saques, Usuários, Adquirentes, Equipe e Configurações/Webhooks.

## Padrões obrigatórios

- Reutilize o design system implementado antes de criar CSS ou componente local.
- AppShell: sidebar desktop e navegação inferior mobile.
- FocusEditor: editores densos sobrepõem o app sem perder contexto.
- Drawer: lateral no desktop e largura total no mobile.
- DataTable: cabeçalho sticky, linha acionável e colunas reduzidas no mobile.
- Loading: skeleton com forma do conteúdo.
- Vazio: orientação e CTA útil.
- Erro: explicação curta e recuperação.

## Quando atualizar este hub

Atualize `nova-vendepay-ux` no mesmo ciclo quando mudar tokens, componentes compartilhados, navegação, responsividade, status, textos estruturais, modelo financeiro ou fluxo relevante. Cruze links dos PRs de produto e UX. Se nenhuma atualização for necessária, registre por quê.

## Prompt inicial sugerido

> Leia o AGENTS.md ou CLAUDE.md deste repositório. Depois carregue https://design.vendepay.com.br/llms.txt e https://design.vendepay.com.br/ai/context.md. Use o código executável como verdade comportamental e a referência viva da VendePay como verdade de UX compartilhada. Não implemente os `.dc.html` históricos literalmente. Reutilize tokens e componentes vigentes, valide desktop e mobile e sincronize o repositório de UX quando a experiência compartilhada mudar.