OBJETIVO DO USUARIO
"O que essa pessoa quer realmente?"
(nao o que ela pediu — o que ela precisa)

OBSTACULO PSICOLOGICO
"O que faz ela hesitar, confundir, ou abandonar?"
(cognitivo: too many choices, nao confiar, nao saber o proximo passo)
(emocional: ansiedade, vergonha, preguica, impaciencia)
(tecnico: lento, quebrado, incompativel)

MOMENTO DE DECISAO
"Qual e o ponto critico onde ela decide ficar ou sair?"
(geralmente nos primeiros 30 segundos ou no primeiro obstáculo real)

RECOMPENSA
"O que ela ganha ao completar a acao?"
(imediata: feedback visual/sonoro/haptico)
(acumulada: progresso, status, dados proprios)
(social: reputacao, compartilhamento, pertencimento)

PROXIMO PASSO INEVITAVEL
"Qual acao ela naturalmente vai querer fazer depois?"
(design o fluxo para que esse passo seja a opcao mais facil)

TOKENS FUNDAMENTAIS
├── Colors
│   ├── brand (primary, secondary, accent)
│   ├── neutral (50, 100, 200, ..., 900)
│   ├── semantic (success, warning, error, info)
│   └── surface (background, card, overlay, border)
├── Typography
│   ├── families (display, body, mono)
│   ├── scale (xs, sm, base, lg, xl, 2xl, 3xl, 4xl)
│   ├── weights (regular, medium, semibold, bold)
│   └── line-heights (tight, normal, relaxed)
├── Spacing (4px base: 1, 2, 3, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48)
├── Radius (none, sm, md, lg, xl, full)
├── Shadows (sm, md, lg, xl — com cor contextual)
└── Motion (durations: fast 150ms, normal 250ms, slow 400ms)
         (easings: ease-out para entrada, ease-in para saida, spring para fisica)

COMPONENTES BASE
├── Button (variant: primary, secondary, ghost, danger | size: sm, md, lg | state: idle, loading, success, disabled)
├── Input (variant: default, filled | state: idle, focus, error, success | tipos: text, search, password)
├── Card (variant: default, interactive, elevated | com header, body, footer opcionais)
├── Modal / Drawer (com overlay, foco trap, escape to close, animacao)
├── Toast / Notification (types: success, warning, error, info | auto-dismiss)
├── Badge / Tag (status, labels, categorias)
├── Avatar (sizes, fallback, group)
├── Tabs (horizontal, vertical, com badge)
├── Select / Combobox (searchable, multi-select, virtualized)
└── DataTable (sort, filter, pagination, row actions, empty state)

ESTADOS OBRIGATORIOS (PARA TUDO)
├── Loading (skeleton screens > spinners; nunca tela em branco)
├── Error (mensagem humana + acao de recuperacao)
├── Empty (zero-state que convida a acao, nao so "sem dados")
└── Success (feedback positivo claro antes de continuar)

1. Qual e a promessa central do produto?
   (em 1 frase que um nao-tecnico entende)

2. Qual e o maior atrito?
   (o momento onde mais usuarios abandonam ou ficam confusos)

3. O que e "feio", "confuso", "lento"?
   (seja especifico: "este modal tem 3 acoes sem hierarquia clara")

4. Onde a experiencia morre?
   (o bottleneck de conversao, retencao ou satisfacao)

5. Qual acao deve virar habito?
   (o comportamento que, se o usuario repetir 3x, ele esta "viciado")

NOME DO CONCEITO (metaforico, nao descritivo)
"Por que e novo?" (1-2 frases — o que nenhum produto faz hoje)
Interacao assinatura (a Killer Interaction deste conceito)
Flow principal (3-7 telas em bullets — nomes e descricao de cada uma)
Risco e tradeoff (o que pode nao funcionar; honestidade e inteligencia)

SITEMAP / ROTAS
├── / (home/dashboard)
├── /[entidade] (lista/grid)
├── /[entidade]/[id] (detalhe)
└── /settings, /onboarding, /auth etc.

COMPONENTES NECESSARIOS
(lista com variantes e estados)

FLUXOS CRITICOS
(passo-a-passo de cada fluxo principal com estado de cada tela)

MICROINTERACOES
(hover states, focus rings, transitions entre telas, loading skeletons)

ANIMACOES
(quais elementos animam, como, quando, por que)

ACESSIBILIDADE
(foco visivel, aria-labels, contraste, keyboard nav, reduced-motion)

src/
├── app/                    # Next.js App Router ou Vite pages
│   ├── layout.tsx
│   ├── page.tsx
│   └── [rota]/page.tsx
├── components/
│   ├── ui/                 # Design system base (atoms)
│   │   ├── button.tsx
│   │   ├── input.tsx
│   │   ├── card.tsx
│   │   └── ...
│   ├── features/           # Componentes de dominio (molecules/organisms)
│   │   ├── [feature]/
│   │   └── ...
│   └── layouts/            # Shells, sidebars, headers
├── lib/
│   ├── utils.ts            # cn(), formatters, helpers
│   ├── hooks/              # Custom hooks
│   ├── api/                # TanStack Query hooks / fetch wrappers
│   └── validations/        # Zod schemas
├── styles/
│   ├── globals.css         # Tailwind base + CSS variables (tokens)
│   └── animations.css      # Keyframes customizados
├── types/                  # TypeScript interfaces/types
└── data/                   # Mock data (quando sem backend)

TIPOGRAFIA
[ ] Scale clara: 1 fonte display, 1 body, 1 mono (maximo)
[ ] Hierarquia: H1 > H2 > H3 > body > caption — nenhum nivel igual
[ ] Line-height adequado para leitura (1.5-1.7 para body)
[ ] Letter-spacing ajustado em headings grandes (tracking-tight)

ESPACAMENTO
[ ] Breathing room: conteudo nao cola nas bordas (min 16px mobile, 24px desktop)
[ ] Agrupamento: elementos relacionados proximos, grupos distantes entre si
[ ] Consistencia: multiplos de 4px em tudo

INTERATIVIDADE
[ ] Todos os estados: idle, hover, focus, active, disabled, loading
[ ] Focus ring visivel e elegante (nao outline feio padrao)
[ ] Cursor correto (pointer em clicavel, text em texto, grab em arrastaveis)
[ ] Haptico equivalente digital: feedback imediato em toda acao

ANIMACOES
[ ] Entraram suave (ease-out, 200-300ms)
[ ] Saem rapido (ease-in, 150-200ms)
[ ] Sem animacoes longas que atrasam o usuario
[ ] prefers-reduced-motion respeitado

PERFORMANCE
[ ] LCP < 2.5s (Largest Contentful Paint)
[ ] CLS < 0.1 (Cumulative Layout Shift — sem pulos de layout)
[ ] TTI < 3.8s (Time to Interactive)
[ ] Imagens com width/height declarados (evita CLS)
[ ] Fonts com font-display: swap

ESTADOS DE DADOS
[ ] Loading: skeleton screen (nao spinner em tela cheia)
[ ] Error: mensagem humana + botao "Tentar novamente"
[ ] Empty: ilustracao/icone + texto convidativo + CTA primario
[ ] Success: feedback claro antes de continuar o fluxo

ACESSIBILIDADE
[ ] Contraste WCAG AA (4.5:1 texto normal, 3:1 texto grande)
[ ] Toda acao com teclado (Tab, Enter, Escape, Arrow keys)
[ ] aria-label em icones sem texto
[ ] Imagens com alt descritivo
[ ] Forms com label associado (nao placeholder como unico label)
[ ] Role correto em componentes customizados (combobox, dialog, etc.)

MOBILE
[ ] Touch targets minimo 44x44px
[ ] Sem hover states como unica indicacao de estado
[ ] Scroll suave (overscroll-behavior)
[ ] Safe areas (env(safe-area-inset-*) para notch/home i

## 4.1 Stack Base

## 4.2 Quando Usar Cada Abordagem

**Use shadcn/ui como base quando:**
- Velocidade e prioridade (MVP, prototipo, produto interno)
- Acessibilidade ja resolvida e prioridade critica
- Time vai manter o codigo apos entrega
- Identidade pode ser aplicada via "skin" (cores, radius, fonts customizadas)

**Crie componentes proprios quando:**
- Identidade visual e o diferencial principal do produto
- A Killer Interaction exige comportamento impossivel em shadcn/ui
- O produto e um produto de design (portfolio, agencia, produto SaaS premium)
- A "assinatura" do produto depende de interacoes customizadas

**Regra pratica:** comece com shadcn/ui para componentes genericos (Input, Button, Modal).
Crie proprios para os componentes que carregam a identidade (Card, Navigation, Feature Hero).

## 4.3 Css Variables Como Design Tokens

```css
/* globals.css */
:root {
  /* Brand */
  --color-brand-50: oklch(97% 0.02 var(--brand-hue));
  --color-brand-500: oklch(55% 0.18 var(--brand-hue));
  --color-brand-900: oklch(25% 0.12 var(--brand-hue));

  /* Neutros */
  --color-surface: oklch(99% 0 0);
  --color-surface-raised: oklch(97% 0 0);
  --color-border: oklch(90% 0 0);
  --color-text: oklch(15% 0 0);
  --color-text-muted: oklch(50% 0 0);

  /* Radius */
  --radius-sm: 6px;
  --radius-md: 10px;
  --radius-lg: 16px;
  --radius-xl: 24px;

  /* Motion */
  --duration-fast: 150ms;
  --duration-normal: 250ms;
  --duration-slow: 400ms;
  --ease-out: cubic-bezier(0.0, 0.0, 0.2, 1);
  --ease-in: cubic-bezier(0.4, 0.0, 1, 1);
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
}

.dark {
  --color-surface: oklch(10% 0 0);
  --color-surface-raised: oklch(14% 0 0);
  --color-border: oklch(22% 0 0);
  --color-text: oklch(95% 0 0);
  --color-text-muted: oklch(60% 0 0);
}

## A Grande Ideia

[1 paragrafo — o conceito central em linguagem humana]

## Interacao Assinatura

[O que e + como funciona + por que e novo + como usar]

## Fluxo Principal

[Passo a passo com nome de cada tela e o que acontece nela]

## Identidade Visual

[Paleta: primary, neutral, semantic]
[Tipografia: families + scale]
[Radius + Motion]
[Mood/tom: palavras que descrevem a personalidade visual]

## Componentes

[Lista com variantes e estados obrigatorios]

## Arquitetura De Pastas

[Estrutura real de diretorios]

## Codigo

[Quando solicitado: completo, tipado, pronto para rodar]

## Checklist De Polimento

[Items marcados/desmarcados do checklist Etapa E]

❌ Modal com 3+ acoes sem hierarquia clara
❌ Botao "Salvar" sem feedback de loading/sucesso
❌ Formulario com 10+ campos em uma tela
❌ Spinner girando em tela cheia por mais de 300ms
❌ Mensagem de erro generica ("Algo deu errado")
❌ Empty state em branco sem convite a acao
❌ Tipografia com menos de 16px em body (mobile)
❌ Icone sem label em acao critica
❌ Hover state sem transicao (mudanca instantanea)
❌ Z-index arbitrario (9999, 99999, 999999)
❌ Cores hardcoded no componente (sempre via token)
❌ onClick em elemento nao-semantico sem role

✅ Skeleton screens em vez de spinners
✅ Optimistic UI em acoes previsivelmente bem-sucedidas
✅ Undo toast em vez de confirmacao de delecao (mais elegante)
✅ Progressive disclosure (mostrar mais conforme o usuario precisa)
✅ Inline validation em forms (nao so no submit)
✅ Placeholder content em zero-states (ajuda o usuario a entender o que vera)
✅ Keyboard shortcut em acoes frequentes (com tooltip que mostra o atalho)
✅ Focus management apos acoes (foco vai para o elemento relevante)
✅ Scroll restoration ao navegar de volta
✅ Persist scroll position em listas paginadas

Brand: Indigo vibrante sobre fundo quase-preto (oklch)
Surface: #0a0a0f, #111118, #1a1a24
Border: #2a2a38
Text: #f0f0ff (primary), #8888aa (muted)
Accent: #6366f1 (indigo-500), #818cf8 (hover)
Radius: 8-12px (moderado)

Brand: Laranja-ambar quente, saturado mas nao agressivo
Surface: #fafaf8, #f5f4f1, #eceae5
Border: #e0ddd8
Text: #1a1714 (primary), #6b6560 (muted)
Accent: #e8650a (amber-600), #f97316 (hover)
Radius: 14-20px (arredondado, organico)

Brand: Verde/Cyan neon sobre preto profundo
Surface: #050507, #0d0d12, #141419
Border: #1e1e28
Text: #ffffff (primary), #666680 (muted)
Accent: #00ff88 (neon green), #00e0ff (cyan)
Radius: 4-8px (sharp, tecnico)

Brand: Lilas/Roxo suave, nao saturado
Surface: #f8f7ff, #f2f0ff, #ebe8ff
Border: #d4d0f0
Text: #1e1a3e (primary), #7b7899 (muted)
Accent: #7c3aed (violet-700), #8b5cf6 (hover)
Radius: 10-16px

Brand: Azul-marinho profundo, solido, sem alegria excessiva
Surface: #ffffff, #f8fafc, #f1f5f9
Border: #e2e8f0
Text: #0f172a (primary), #64748b (muted)
Accent: #1e40af (blue-800), #2563eb (hover)
Radius: 6-10px (contido, profissional)