@daniel-da-silva-alves/sddk 2.0.0

package/sddk/skills/system-design-document/references/sdd-template.md

@@ -0,0 +1,259 @@
+# Template de System Design Document (SDD)
+
+Use este template como base para gerar o documento SDD. Adapte as seções conforme a complexidade da feature.
+
+---
+
+## Estrutura do Documento
+
+```markdown
+# System Design Document (SDD)
+## {Nome da Feature}
+
+**Versão**: 1.0
+**Data**: {data de criação}
+**Projeto**: {nome do projeto}
+**Feature**: {nome da feature}
+**SRS Referência**: [srs.md](./srs.md)
+
+---
+
+## 1. Visão Geral Técnica
+
+### 1.1 Resumo
+Breve descrição técnica do que será implementado e como.
+
+### 1.2 Stack Tecnológica
+
+| Camada | Tecnologia | Justificativa |
+|:---|:---|:---|
+| Linguagem | {ex: TypeScript} | {por que esta escolha} |
+| Framework | {ex: Next.js 14} | {por que esta escolha} |
+| Banco de dados | {ex: PostgreSQL} | {por que esta escolha} |
+| ORM/Query | {ex: Prisma} | {por que esta escolha} |
+| Autenticação | {ex: NextAuth.js} | {por que esta escolha} |
+| Estilização | {ex: Tailwind CSS v4} | {por que esta escolha} |
+
+### 1.3 Decisões Arquiteturais
+
+| Decisão | Escolha | Alternativas Consideradas | Justificativa |
+|:---|:---|:---|:---|
+| Padrão | {ex: Clean Architecture} | MVC, Hexagonal | {razão} |
+| State Management | {ex: Zustand} | Redux, Context | {razão} |
+
+---
+
+## 2. Arquitetura do Sistema
+
+### 2.1 Diagrama de Arquitetura
+
+```mermaid
+graph TB
+    subgraph Frontend
+        A[Pages/Routes] --> B[Components]
+        B --> C[Hooks/State]
+    end
+    subgraph Backend
+        D[API Routes] --> E[Services]
+        E --> F[Repository]
+        F --> G[(Database)]
+    end
+    C --> D
+```
+
+### 2.2 Estrutura de Diretórios
+
+```
+src/
+├── app/                    # Routes / pages
+├── components/             # Componentes reutilizáveis
+│   ├── ui/                 # Design system (atoms)
+│   └── features/           # Componentes de feature
+├── lib/                    # Utilitários e helpers
+├── services/               # Lógica de negócio
+├── repositories/           # Acesso a dados
+├── types/                  # TypeScript types/interfaces
+└── config/                 # Configurações
+```
+
+### 2.3 Camadas e Responsabilidades
+
+| Camada | Responsabilidade | Exemplo |
+|:---|:---|:---|
+| **Presentation** | UI, formulários, validação visual | Componentes React |
+| **Application** | Orquestração, use cases | Services |
+| **Domain** | Regras de negócio puras | Entidades, Value Objects |
+| **Infrastructure** | Acesso a dados, APIs externas | Repositories, API clients |
+
+---
+
+## 3. Modelo de Dados
+
+### 3.1 Entidades
+
+#### {NomeEntidade}
+
+| Campo | Tipo | Constraints | Descrição |
+|:---|:---|:---|:---|
+| id | UUID | PK, auto-generated | Identificador único |
+| {campo} | {tipo} | {constraints} | {descrição} |
+| created_at | DateTime | NOT NULL, default NOW | Data de criação |
+| updated_at | DateTime | NOT NULL, auto-update | Última atualização |
+
+### 3.2 Relacionamentos
+
+```mermaid
+erDiagram
+    ENTITY_A ||--o{ ENTITY_B : "has many"
+    ENTITY_B }|--|| ENTITY_C : "belongs to"
+```
+
+### 3.3 Migrations
+
+Lista de migrations necessárias em ordem:
+1. `001_create_{table}.sql` — Criar tabela principal
+2. `002_create_{table}.sql` — Criar tabelas secundárias
+
+---
+
+## 4. Design de API
+
+### 4.1 Endpoints
+
+#### `POST /api/{resource}`
+- **Descrição**: {o que faz}
+- **Auth**: {requer autenticação? qual role?}
+- **Request Body**:
+  ```json
+  {
+    "field": "type — descrição"
+  }
+  ```
+- **Response 200**:
+  ```json
+  {
+    "data": {}
+  }
+  ```
+- **Errors**: 400 (validação), 401 (não autenticado), 403 (não autorizado), 500 (erro interno)
+
+### 4.2 Validações
+
+| Endpoint | Campo | Regra |
+|:---|:---|:---|
+| POST /api/{resource} | {campo} | {regra de validação} |
+
+---
+
+## 5. Design de Interface (Frontend)
+
+### 5.1 Componentes
+
+| Componente | Tipo | Descrição |
+|:---|:---|:---|
+| `{ComponentName}` | Page | {descrição} |
+| `{ComponentName}` | Feature | {descrição} |
+| `{ComponentName}` | UI/Atom | {descrição} |
+
+### 5.2 Estado e Fluxo de Dados
+
+Descrever como o estado flui entre componentes:
+- Fonte de dados
+- Estado local vs global
+- Cache strategy
+
+### 5.3 Design Tokens
+
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--color-primary` | {valor} | {onde usar} |
+| `--spacing-md` | {valor} | {onde usar} |
+
+---
+
+## 6. Integrações
+
+### 6.1 APIs Externas
+
+| Serviço | Propósito | Endpoint | Auth |
+|:---|:---|:---|:---|
+| {nome} | {para quê} | {URL base} | {tipo de auth} |
+
+### 6.2 Eventos / Webhooks
+
+| Evento | Trigger | Payload |
+|:---|:---|:---|
+| {nome} | {quando dispara} | {dados enviados} |
+
+---
+
+## 7. Tratamento de Erros
+
+### 7.1 Estratégia
+
+| Camada | Estratégia | Exemplo |
+|:---|:---|:---|
+| Frontend | {ex: Error Boundary + toast} | {quando usar} |
+| API | {ex: HTTP status + error body padronizado} | {formato} |
+| Service | {ex: Custom exceptions + logging} | {tipos de erro} |
+
+### 7.2 Error Codes
+
+| Código | Mensagem | Ação do Usuário |
+|:---|:---|:---|
+| {code} | {mensagem} | {o que fazer} |
+
+---
+
+## 8. Segurança
+
+### 8.1 Autenticação
+Descrever mecanismo de autenticação.
+
+### 8.2 Autorização
+Descrever modelo de permissões (RBAC, ABAC, etc.).
+
+### 8.3 Proteção de Dados
+Campos sensíveis, criptografia, LGPD/GDPR.
+
+---
+
+## 9. Referências ao SRS
+
+| Seção SDD | Requisito SRS | Referência |
+|:---|:---|:---|
+| 3. Modelo de Dados | RF-001 | [SRS#3 RF-001](./srs.md#rf-001) |
+
+---
+
+## 10. Fontes de Documentação Técnica
+
+### 10.1 Configuração de Fontes
+
+| Tecnologia | Versão | Fonte Primária | URL Oficial | MCP/Skill |
+|:---|:---|:---|:---|:---|
+| {tecnologia} | {versão} | {URL oficial / MCP / Skill / Docs local} | {URL} | {nome do MCP ou —} |
+
+### 10.2 Documentação Local do Projeto
+
+| Caminho | Conteúdo |
+|:---|:---|
+| {caminho} | {descrição do conteúdo} |
+
+### 10.3 Regra de Consulta
+
+Ordem de prioridade para consulta de documentação durante o desenvolvimento:
+1. Documentação local do projeto (caminhos listados em 10.2)
+2. MCP/Skill (se listado na coluna MCP/Skill em 10.1)
+3. URL oficial (usar `read_url_content` na URL listada em 10.1)
+4. Web search (usar `search_web` com query: "{tecnologia} {versão} {tópico} site:{domínio oficial}")
+```
+
+## Regras de Preenchimento
+
+1. **Cada decisão arquitetural DEVE ter justificativa** — nunca apenas "porque sim"
+2. **Modelo de dados DEVE corresponder aos requisitos do SRS** — usar matriz de referência
+3. **Endpoints DEVEM cobrir todos os requisitos funcionais** do SRS
+4. **Componentes DEVEM ser granulares** — nunca um componente monolítico
+5. **Design tokens DEVEM ser definidos** — nunca usar valores hardcoded
+6. **Fontes de documentação DEVEM ser configuradas** para cada tecnologia da stack com versão pinada

package/sddk/skills/system-design-document/references/standards-api-template.md

@@ -0,0 +1,128 @@
+# Template: Convenções de API do Projeto
+
+Use este template para gerar `.specs/standards/api-conventions.md`. Preencha com as respostas do onboarding. Se o projeto não tem API, criar com "N/A — projeto sem API".
+
+```markdown
+# Convenções de API
+
+**Projeto**: {nome do projeto}
+**Última atualização**: {data}
+
+---
+
+## 1. Padrão de API
+
+**Tipo**: {REST | GraphQL | tRPC | gRPC}
+**Versionamento**: {ex: URL path /api/v1/, header, nenhum}
+**Base URL**: {ex: /api/v1}
+
+---
+
+## 2. Formato de Response
+
+### Response de Sucesso
+```json
+{
+  "data": { ... },
+  "meta": {
+    "page": 1,
+    "perPage": 20,
+    "total": 150
+  }
+}
+```
+
+### Response de Erro
+```json
+{
+  "error": {
+    "code": "{ERROR_CODE}",
+    "message": "{mensagem legível}",
+    "details": [ ... ]
+  }
+}
+```
+
+### HTTP Status Codes
+
+| Status | Quando usar |
+|:---|:---|
+| 200 | Sucesso (GET, PUT, PATCH) |
+| 201 | Recurso criado (POST) |
+| 204 | Sucesso sem body (DELETE) |
+| 400 | Validação / input inválido |
+| 401 | Não autenticado |
+| 403 | Não autorizado (sem permissão) |
+| 404 | Recurso não encontrado |
+| 409 | Conflito (ex: email já existe) |
+| 422 | Entidade não processável |
+| 429 | Rate limit excedido |
+| 500 | Erro interno do servidor |
+
+---
+
+## 3. Naming de Endpoints
+
+| Regra | Exemplo correto | Exemplo errado |
+|:---|:---|:---|
+| Substantivos no plural | `/api/v1/users` | `/api/v1/user` |
+| Sem verbos na URL | `GET /users` | `GET /getUsers` |
+| Kebab-case para multi-palavras | `/order-items` | `/orderItems` |
+| Recursos aninhados | `/users/:id/orders` | `/getUserOrders` |
+
+---
+
+## 4. Paginação
+
+**Tipo**: {cursor | offset | keyset}
+
+### Formato de Request
+{ex para offset:}
+```
+GET /api/v1/users?page=2&per_page=20
+```
+
+### Formato de Response (meta)
+```json
+{
+  "meta": {
+    "page": 2,
+    "per_page": 20,
+    "total": 150,
+    "total_pages": 8
+  }
+}
+```
+
+---
+
+## 5. Filtros e Ordenação
+
+### Filtros
+```
+GET /api/v1/users?status=active&role=admin
+```
+
+### Ordenação
+```
+GET /api/v1/users?sort=created_at&order=desc
+```
+
+---
+
+## 6. Autenticação
+
+**Método**: {ex: Bearer Token (JWT) via header Authorization}
+**Header**: `Authorization: Bearer {token}`
+**Refresh**: {ex: via POST /api/v1/auth/refresh com refresh token em httpOnly cookie}
+
+---
+
+## 7. Validação
+
+| Regra | Descrição |
+|:---|:---|
+| Validação no backend | TODA input é validada no servidor, independente do frontend |
+| Mensagens de erro | Retornar campo + mensagem específica |
+| Formato de erro de validação | `{"error": {"code": "VALIDATION_ERROR", "details": [{"field": "email", "message": "Email inválido"}]}}` |
+```

package/sddk/skills/system-design-document/references/standards-architecture-template.md

@@ -0,0 +1,76 @@
+# Template: Padrões Arquiteturais do Projeto
+
+Use este template para gerar `.specs/standards/architecture.md`. Preencha com as respostas do onboarding.
+
+```markdown
+# Padrões Arquiteturais do Projeto
+
+**Projeto**: {nome do projeto}
+**Última atualização**: {data}
+
+---
+
+## 1. Padrão Arquitetural Base
+
+**Padrão**: {ex: Domain-Driven Design (DDD)}
+**Justificativa**: {por que este padrão}
+
+### Camadas e Responsabilidades
+
+| Camada | Responsabilidade | Pode importar de | NÃO pode importar de |
+|:---|:---|:---|:---|
+| {ex: Domain} | {ex: Entidades, Value Objects, regras de negócio} | {nenhuma} | {Application, Infrastructure, Presentation} |
+| {ex: Application} | {ex: Use Cases, DTOs, Ports} | {Domain} | {Infrastructure, Presentation} |
+| {ex: Infrastructure} | {ex: Repositories, API clients, DB} | {Domain, Application} | {Presentation} |
+| {ex: Presentation} | {ex: Controllers, Views, Components} | {Application} | {Domain, Infrastructure} |
+
+### Estrutura de Diretórios Padrão
+
+```
+src/
+├── {camada1}/
+├── {camada2}/
+├── {camada3}/
+└── {camada4}/
+```
+
+---
+
+## 2. Padrões Avançados
+
+### {ex: Event Sourcing}
+- **Usado em**: {módulos/contextos onde se aplica}
+- **NÃO usado em**: {módulos onde NÃO se aplica}
+- **Implementação**: {detalhes técnicos}
+
+### {ex: BFF (Backend for Frontend)}
+- **Escopo**: {cada frontend tem seu BFF? ou BFF único?}
+- **Regra**: {BFF contém lógica de negócio? Ou apenas orquestra?}
+
+### {ex: CQRS (Command Query Responsibility Segregation)}
+- **Usado em**: {onde se aplica}
+- **Command**: {como são os commands}
+- **Query**: {como são as queries}
+
+---
+
+## 3. Regras de Dependência
+
+> [!IMPORTANT]
+> Estas regras NUNCA devem ser violadas. Violação é classificada como 🔴 Crítica no Code Review.
+
+1. {ex: Domain NUNCA importa de Infrastructure}
+2. {ex: Use Cases orquestram, NUNCA contêm lógica de domínio pura}
+3. {ex: Cada Aggregate tem seu próprio Repository}
+4. {ex: Repositories retornam Domain Entities, não DTOs}
+
+---
+
+## 4. Princípios de Design
+
+| Princípio | Como aplicamos |
+|:---|:---|
+| {ex: SSOT} | {ex: Estado vive no banco. Cache é derivado, nunca fonte primária} |
+| {ex: Separation of Concerns} | {ex: Cada módulo tem responsabilidade única} |
+| {ex: Fail Fast} | {ex: Validar inputs na borda do sistema} |
+```

package/sddk/skills/system-design-document/references/standards-coding-template.md

@@ -0,0 +1,114 @@
+# Template: Boas Práticas e Padrões de Código
+
+Use este template para gerar `.specs/standards/coding-standards.md`. Preencha com as respostas do onboarding.
+
+```markdown
+# Boas Práticas e Padrões de Código
+
+**Projeto**: {nome do projeto}
+**Última atualização**: {data}
+
+---
+
+## 1. Princípios Adotados
+
+| Princípio | O que significa NESTE projeto | Exemplo |
+|:---|:---|:---|
+| **SSOT** (Single Source of Truth) | {ex: Estado vive no banco. Cache é derivado.} | {ex: Não manter contadores em 2 tabelas} |
+| **DRY** (Don't Repeat Yourself) | {ex: Extrair quando repetir ≥ 2 vezes} | {ex: apiClient centralizado, não fetch repetido} |
+| **KISS** (Keep It Simple) | {ex: Preferir solução simples à elegante} | {ex: Usar map/filter ao invés de reduce complexo} |
+| **YAGNI** (You Aren't Gonna Need It) | {ex: Não implementar features "por garantia"} | {ex: Não criar abstração genérica para 1 uso} |
+| **SOLID** | {quais princípios do SOLID o projeto segue explicitamente} | — |
+
+---
+
+## 2. Regras de Abstração
+
+### Quando Extrair uma Função
+- {ex: Quando o bloco é usado ≥ 2 vezes}
+- {ex: Quando o bloco tem mais de 10 linhas e pode ter nome descritivo}
+- {ex: Quando o bloco faz algo semanticamente independente}
+
+### Quando Criar um Componente
+- {ex: Quando a UI é reutilizada em ≥ 2 lugares}
+- {ex: Quando o componente tem mais de ~100 linhas}
+- {ex: Quando tem estado ou lógica própria}
+
+### Quando Criar um Hook (React)
+- {ex: Quando lógica stateful é usada em ≥ 2 componentes}
+- {ex: Quando o componente fica mais limpo separando a lógica}
+
+### Quando Criar um Service
+- {ex: Quando a lógica de negócio não pertence ao componente/controller}
+- {ex: Quando a mesma operação é usada em múltiplos endpoints/páginas}
+
+---
+
+## 3. Tratamento de Erros
+
+### Estratégia por Camada
+
+| Camada | Estratégia |
+|:---|:---|
+| **Domain** | {ex: Lançar custom exceptions (DomainError, ValidationError)} |
+| **Application/Service** | {ex: Capturar domain errors, traduzir para DTOs de erro} |
+| **API/Controller** | {ex: Error handler global, mapear exceptions para HTTP status} |
+| **Frontend** | {ex: Error Boundary para crashes, toast para erros de ação} |
+
+### Custom Exceptions (se aplicável)
+```typescript
+// Hierarquia de erros do projeto
+class AppError extends Error { code: string; statusCode: number; }
+class ValidationError extends AppError { fields: FieldError[]; }
+class NotFoundError extends AppError { }
+class UnauthorizedError extends AppError { }
+class ConflictError extends AppError { }
+```
+
+### Mensagens de Erro
+- {ex: Mensagens voltadas ao usuário, nunca stack traces}
+- {ex: Logging do erro completo no servidor, mensagem limpa no client}
+- {ex: Códigos de erro padronizados (ERROR_CODE) para o frontend mapear}
+
+---
+
+## 4. Logging
+
+### Estratégia
+- **Formato**: {ex: Structured logging (JSON)}
+- **Níveis**: {ex: error, warn, info, debug}
+- **Ferramenta**: {ex: pino, winston, console estruturado}
+
+### O que Logar
+
+| Nível | Quando usar | Exemplo |
+|:---|:---|:---|
+| `error` | Falhas que impedem a operação | Erro de conexão DB, exception não tratada |
+| `warn` | Situações anormais mas recuperáveis | Rate limit próximo, fallback ativado |
+| `info` | Eventos de negócio importantes | Usuário criado, pagamento processado |
+| `debug` | Detalhes para debugging | Query SQL executada, payload recebido |
+
+### O que NUNCA Logar
+- Senhas, tokens, chaves de API
+- Dados pessoais sensíveis (CPF, cartão de crédito)
+- Payloads completos de request em produção
+
+---
+
+## 5. Testes (se aplicável)
+
+### Estratégia
+- **Tipo principal**: {ex: Testes manuais via manual-tests.md}
+- **Cobertura mínima**: {ex: N/A — foco em testes manuais}
+- **Quando automatizar**: {ex: Lógica de domínio crítica (cálculos, validações)}
+
+---
+
+## 6. Performance
+
+### Regras Gerais
+- {ex: Queries de listagem DEVEM ter paginação (máximo 100 por página)}
+- {ex: N+1 queries são proibidas — usar eager loading / join}
+- {ex: Imagens devem ser otimizadas (WebP, lazy loading)}
+- {ex: Bundle splitting para rotas de frontend}
+```

package/sddk/skills/system-design-document/references/standards-design-system-template.md

@@ -0,0 +1,137 @@
+# Template: Design System do Projeto
+
+Use este template para gerar `.specs/standards/design-system.md`. Preencha com as respostas do onboarding. Se o projeto é backend-only, criar o arquivo com conteúdo "N/A — projeto backend-only".
+
+```markdown
+# Design System
+
+**Projeto**: {nome do projeto}
+**Última atualização**: {data}
+
+---
+
+## 1. Paleta de Cores
+
+### Cores Primárias
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--color-primary-50` | {ex: #e8f0fe} | Backgrounds suaves |
+| `--color-primary-100` | {ex: #d2e3fc} | Hover em backgrounds |
+| `--color-primary-500` | {ex: #4285f4} | Ações primárias, links |
+| `--color-primary-700` | {ex: #1a73e8} | Hover em ações primárias |
+| `--color-primary-900` | {ex: #174ea6} | Texto em destaque |
+
+### Cores de Superfície
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--color-surface` | {ex: #ffffff} | Background de cards, modals |
+| `--color-surface-variant` | {ex: #f8f9fa} | Background de seções alternadas |
+| `--color-on-surface` | {ex: #1f1f1f} | Texto sobre surfaces |
+| `--color-on-surface-secondary` | {ex: #5f6368} | Texto secundário |
+| `--color-outline` | {ex: #dadce0} | Bordas, divisores |
+
+### Cores Semânticas
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--color-error` | {ex: #d32f2f} | Erros, validação |
+| `--color-success` | {ex: #0f9d58} | Sucesso, confirmação |
+| `--color-warning` | {ex: #f9ab00} | Alertas, avisos |
+| `--color-info` | {ex: #4285f4} | Informações |
+
+### Modo Escuro (se aplicável)
+| Token Light | Token Dark | Valor Dark |
+|:---|:---|:---|
+| `--color-surface` | `--color-surface-dark` | {ex: #1e1e1e} |
+
+---
+
+## 2. Tipografia
+
+### Fontes
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--font-family` | {ex: 'Inter', sans-serif} | Texto geral |
+| `--font-family-heading` | {ex: 'Outfit', sans-serif} | Headings |
+| `--font-family-mono` | {ex: 'JetBrains Mono', monospace} | Código |
+
+### Tamanhos
+| Token | Valor | Line Height | Uso |
+|:---|:---|:---|:---|
+| `--text-xs` | {ex: 0.75rem} | {ex: 1rem} | Labels, captions |
+| `--text-sm` | {ex: 0.875rem} | {ex: 1.25rem} | Body small |
+| `--text-base` | {ex: 1rem} | {ex: 1.5rem} | Body default |
+| `--text-lg` | {ex: 1.125rem} | {ex: 1.75rem} | Body large |
+| `--text-xl` | {ex: 1.25rem} | {ex: 1.75rem} | Heading 4 |
+| `--text-2xl` | {ex: 1.5rem} | {ex: 2rem} | Heading 3 |
+| `--text-3xl` | {ex: 1.875rem} | {ex: 2.25rem} | Heading 2 |
+| `--text-4xl` | {ex: 2.25rem} | {ex: 2.5rem} | Heading 1 |
+
+### Pesos
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--font-regular` | {ex: 400} | Texto normal |
+| `--font-medium` | {ex: 500} | Ênfase suave |
+| `--font-semibold` | {ex: 600} | Headings, labels |
+| `--font-bold` | {ex: 700} | Destaque forte |
+
+---
+
+## 3. Espaçamento
+
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--spacing-xs` | {ex: 0.25rem (4px)} | Espaço mínimo |
+| `--spacing-sm` | {ex: 0.5rem (8px)} | Dentro de componentes |
+| `--spacing-md` | {ex: 1rem (16px)} | Entre elementos |
+| `--spacing-lg` | {ex: 1.5rem (24px)} | Entre seções |
+| `--spacing-xl` | {ex: 2rem (32px)} | Entre blocos |
+| `--spacing-2xl` | {ex: 3rem (48px)} | Entre seções maiores |
+
+---
+
+## 4. Bordas e Sombras
+
+### Border Radius
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--radius-sm` | {ex: 4px} | Botões, inputs |
+| `--radius-md` | {ex: 8px} | Cards |
+| `--radius-lg` | {ex: 12px} | Modals, containers |
+| `--radius-full` | {ex: 9999px} | Avatars, badges |
+
+### Shadows
+| Token | Valor | Uso |
+|:---|:---|:---|
+| `--shadow-sm` | {ex: 0 1px 2px rgba(0,0,0,0.05)} | Cards sutis |
+| `--shadow-md` | {ex: 0 4px 6px rgba(0,0,0,0.07)} | Cards elevados |
+| `--shadow-lg` | {ex: 0 10px 15px rgba(0,0,0,0.1)} | Modals, dropdowns |
+
+---
+
+## 5. Componentes Base
+
+| Componente | Background | Padding | Radius | Shadow |
+|:---|:---|:---|:---|:---|
+| Card | `--color-surface` | `--spacing-lg` | `--radius-md` | `--shadow-sm` |
+| Button Primary | `--color-primary-500` | `--spacing-sm` `--spacing-md` | `--radius-sm` | none |
+| Button Secondary | transparent | `--spacing-sm` `--spacing-md` | `--radius-sm` | none |
+| Input | `--color-surface` | `--spacing-sm` `--spacing-md` | `--radius-sm` | inset border |
+| Modal | `--color-surface` | `--spacing-xl` | `--radius-lg` | `--shadow-lg` |
+| Badge | `--color-primary-50` | `--spacing-xs` `--spacing-sm` | `--radius-full` | none |
+
+---
+
+## 6. Breakpoints (Responsividade)
+
+| Token | Valor | Dispositivo |
+|:---|:---|:---|
+| `--breakpoint-sm` | {ex: 640px} | Mobile landscape |
+| `--breakpoint-md` | {ex: 768px} | Tablet |
+| `--breakpoint-lg` | {ex: 1024px} | Desktop |
+| `--breakpoint-xl` | {ex: 1280px} | Desktop largo |
+```
+
+## Regra para o Agente
+
+> [!IMPORTANT]
+> Quando o design system está definido, o agente NUNCA deve usar valores hardcoded para cores, espaçamentos, tipografia ou border-radius. SEMPRE usar os tokens definidos neste documento.