# VendePay Design System — full agent context Canonical URL: https://design.vendepay.com.br Current reference: https://design.vendepay.com.br/current Structured manifest: https://design.vendepay.com.br/ai/design-system.json Repository: https://github.com/Vendepay-Org/nova-vendepay-ux Last verified: 2026-08-26 ## Purpose Use this document when planning, implementing or reviewing user-facing work in the new VendePay. It covers the seller frontend, admin frontend, checkout and shared product language. ## Source priority 1. Executable code, contracts, migrations and tests define current behavior. 2. `src/shared/design-system` in each frontend defines the tokens and components currently executed. 3. `/current` and `nova-vendepay-ux` define shared UX intent and living documentation. 4. `public/artifacts` and `/viewer` preserve the June 2026 handoff as history. If sources diverge, verify the product code, follow the current implementation and update the living reference. Never copy obsolete prototype behavior silently. ## Current frontend baseline - React 19 and TypeScript. - vanilla-extract for typed, zero-runtime styles. - Base UI for headless primitives. - Lucide for icons. - Poppins for titles, KPIs and monetary values. - Open Sans for body, labels and descriptions. ## Essential tokens - Brand green: #04D361. - Bright green on dark: #0BF372. - Action green on light: #049366. - Deep teal: #00454C. - Light canvas/surface/border: #F8F9FA / #FFFFFF / #E6E9EF. - Dark canvas/surface/border: #070707 / #101010 / #29292E. - Tertiary text: #667085 light and #8A8A96 dark. - Base spacing: 8px; practical scale 4, 8, 12, 16, 24, 32, 48, 64. - Radius: 8px small, 10px control, 12px card, 16px large and 999px pill. - Motion: 150ms fast, 250ms base and 350ms slow. ## Current sale statuses Use color, icon and label together. Color alone is never sufficient. - PENDING: `Pendente`; awaiting family. - PAID: `Paga`; success family. - FAILED: `Recusada`; closed family. - REFUND_REQUESTED: `Aguardando reembolso`; awaiting family. - REFUNDED: `Estorno`; informative family. - CHARGED_BACK: `Chargeback`; closed family. Derived presentations may include `Reembolso parcial`, `Reembolso de chargeback`, `Disputa ganha`, `Assinatura encerrada` and `Situação mista`. These are UI interpretations, not additional base enums. ## Product and pricing - V1 supports one primary offer and one primary plan per product. Creating another identity conflicts with the invariant. - Minimum price is 10 in the base currency and statement descriptor is required. - Current editor steps are Básico, Recursos, Preço, Funil, Afiliados and Links. - Recurrence is configured inside Price. Checkout Builder is opened from Links. - Tracking has Meta, TikTok, Google Ads and UTMify, plus affiliate pixels where applicable. - Funnel supports multiple order bumps, accept/reject branches, upsell/downsell, hosted or external pages, recurring target plans, commission and co-production rules. ## Checkout - One `Checkout principal` and one `Estilo principal` per product. - Do not create UI for multiple checkouts, campaign checkouts or a checkout selector. - The current experience includes style controls, fields, mandatory email, thank-you URL, wallets, coupons, session/recovery and external funnel pages. - Global pricing is always dynamic conversion from one base price. Sellers do not maintain a price table per currency. - Preview supports 12 languages. - Separate capability from availability: runtime/acquirer contracts may support methods that the seller UI still shows as unavailable or `em breve`. - Compatibility debt: internal contracts still expose `checkouts[]` and a create endpoint. Treat this as technical compatibility, not a user capability. ## Financial UX - One manual/on-request withdrawal flow. - PIX and crypto/Base are payout destinations of that same flow. - Never expose provider or internal architecture names such as Stripe, Connect or Legacy to sellers. - The large balance number is always Available. Also distinguish To release, Reserved and In transit, per currency. - KYC, debt or another open withdrawal can block a request; explain cause and next step. - Conversion display includes 2% spread, 3.5% IOF only for BRL destinations and a fixed fee equivalent to R$ 4.99. - Currency is explicit and conversion is never silent. ## Entry and KYC - Current authentication uses email/password, forgot/reset password and email verification. - Do not promise Google login without matching implementation. - KYC is a unified PF/PJ/PEP and document-upload journey. - Incomplete KYC may block both selling and payout. - Registration may configure PIX or crypto/Base payout information. ## Operations - Dashboard: six KPIs; date, view and currency filters; recurrence, payment, origin and state analytics; awards and freshness. - Sales: grouped journeys and charges, per-charge refunds, partial refund, prevented chargeback, dispute won, debt and recovery states. - Subscriptions: retry, cancel at period end, invoices, dunning, trial and read-only participant states. - Seller navigation includes Co-productions and Settings/Webhooks. Mobile exposes four primary destinations plus More. - Separate admin frontend includes Dashboard, Sales, Finance, Subscriptions, Products, Alerts, Chargebacks, Reconciliation, Accounting, Withdrawals, Users, Acquirers, Team and Settings/Webhooks. ## Shared patterns - AppShell: desktop sidebar and mobile bottom navigation. - FocusEditor: dense editors overlay the app and restore the prior context on exit. - Drawer: side panel on desktop and full-width panel on mobile. - DataTable: sticky headers, actionable rows and collapsed mobile columns. - MoneyValue: Poppins, tabular numerals and explicit currency. - StatusBadge: semantic family plus icon and label. - Loading: shape-matched skeletons. - Empty: orientation and useful action. - Error: clear explanation and recovery action. - Minimum touch target: 44px. ## Agent change policy Before implementation, read repository instructions, load `/llms.txt` and `/ai/context.md`, inspect shared design-system exports, and confirm contracts for business rules. Update `nova-vendepay-ux` in the same cycle when changing tokens, components, navigation, responsive behavior, status presentation, structural copy, financial mental models or a major flow. Cross-link product and UX pull requests; if no docs change is needed, record why. ## Historical prototypes Historical viewers remain available only for origin and visual study: - https://design.vendepay.com.br/#biblioteca - https://design.vendepay.com.br/viewer?artifact=checkout-builder - https://design.vendepay.com.br/viewer?artifact=saldos-saque Every viewer and standalone artifact is marked as historical. Do not treat it as the current specification.