# Design System Vue 3 (TypeScript) — Regras do Agente

## Objetivo do projeto
Construir um Design System de componentes em **Vue 3** para reutilização em múltiplos projetos, com foco em:
- **Consistência visual e de comportamento**
- **Componentes bem tipados (TypeScript forte)**
- **Documentação em português** (para devs e para outras IAs)
- **Exemplos executáveis (playground)**
- **Facilidade de manutenção e evolução**

---

## Stack e padrões obrigatórios
- Vue 3
- TypeScript (modo estrito e tipagem forte)
- **defineComponent** (obrigatório)
- Sem TSX (padrão: `<template>` + `<script lang="ts">`)
- Estilo: preferir CSS scoped por componente (se aplicável)
- Ícones: se usar, definir um padrão único do repositório (não inventar por componente)

---

## Regras de idioma e nomenclatura
- **Variáveis, nomes de arquivos e nomes de pastas em português sempre que possível**
  - Ex.: `botao`, `cartao`, `campo_texto`, `seletor_opcoes`
  - Evitar abreviações confusas
- Nomes de componentes (PascalCase) podem seguir padrão técnico:
  - **Padrão do repositório:** componentes com prefixo `Eli` (ex.: `EliBotao`, `EliInput`).
  - Pastas preferem português (ex.: `src/componentes/botao/`, `src/componentes/campo/`).
- Props e eventos: preferir português e sem ambiguidades:
  - Props: `rotulo`, `desabilitado`, `carregando`, `modeloValor`
  - Eventos: `update:modelValue`, `confirmar`, `cancelar`, `clicar`

---

## Estrutura obrigatória do repositório
- Cada componente deve possuir **sua própria pasta** em `src/componentes/`
- Dentro de cada pasta do componente:
  - `README.md` (detalhado e em português)
  - `index.ts` (re-export)
  - Arquivo do componente `.vue`
  - (opcional) `tipos.ts` se necessário para manter tipagem limpa

Estrutura sugerida:

src/
  componentes/
    botao/
      EliBotao.vue
      index.ts
      README.md
    cartao/
      EliCartao.vue
      index.ts
      README.md
  playground/
    botao.playground.vue
    cartao.playground.vue
  index.ts

Raiz do projeto:
- `README.md` geral (guia do design system em português)

---

## Documentação obrigatória (README.md)
### 1) README.md na raiz (obrigatório)
Deve servir como guia para desenvolvedores e outras IAs, contendo:
- Visão geral do design system
- Como instalar e usar (ex.: importações, registro)
- Convenções do projeto (tipagem, pastas, playground)
- Como criar um novo componente (checklist)
- Como rodar o playground
- Padrões de versionamento (se aplicável)

### 2) README.md por componente (obrigatório)
Cada componente precisa ter um README.md com **mais detalhamento**:
- O que o componente resolve (objetivo)
- API completa:
  - Props (nome, tipo, padrão, descrição)
  - Emits (nome, payload, quando dispara)
  - Slots (nome, objetivo, exemplo)
- Exemplos de uso (mínimo 2)
- Casos de borda / comportamento esperado
- Acessibilidade (quando aplicável)
- Decisões de implementação relevantes (por que foi feito assim)

**Idioma:** sempre em português claro.

---

## Comentários obrigatórios nos componentes
Todos os componentes `.vue` devem conter comentários úteis, principalmente:
- Explicando a intenção de blocos importantes (watchers, computed, validações)
- Explicando decisões de tipagem
- Explicando regras de negócio / estados (carregando, erro, desabilitado)
Evitar comentários óbvios (“isso é um botão”).

---

## Tipagem forte (TypeScript) — regras
- Usar `strict: true`
- Evitar `any` (proibido), exceto se for inevitável e justificado no README do componente
- Preferir tipos explícitos para:
  - props complexas
  - retornos de funções
  - emits com payload tipado
- Para props complexas, usar `PropType<T>` quando necessário
- Padronizar nomes de tipos em português:
  - `tipoOpcao`, `tipoTamanho`, `tipoEstado`, `tipoTema`

---

## Padrão defineComponent (obrigatório)
- Sempre usar:
  - `<script lang="ts">`
  - `export default defineComponent({ ... })`
- Props com tipos explícitos
- Emits declarados e tipados
- Preferir `computed`, `ref` e `watch` com tipos claros

---

## Playground obrigatório para cada componente
- Todo componente criado deve ter **um teste demonstrativo** em `src/playground`
- O playground deve:
  - Exibir variações do componente (mínimo 3 variações)
  - Demonstrar interação (v-model, click, estados)
  - Validar visualmente comportamentos e casos de borda
- Nome do arquivo do playground:
  - `nome_do_componente.playground.vue`
  - Ex.: `botao.playground.vue`, `campo_texto.playground.vue`

---

## Regras de exportação e reuso
- Cada pasta do componente deve ter `index.ts` exportando o componente:
  - `export { default as EliBotao } from "./EliBotao.vue"`
- `src/index.ts` deve exportar todos os componentes publicamente
- Não exportar itens internos não documentados

---

## Qualidade e consistência
- Antes de finalizar um componente:
  - Conferir documentação (README raiz + README do componente)
  - Conferir comentários no `.vue`
  - Conferir playground criado e funcionando
  - Conferir tipagem (sem any; sem tipos implícitos perigosos)

---

## Checklist por componente (obrigatório)
Ao criar/alterar componente, garantir:
- [ ] Pasta do componente criada em `src/componentes/<nome_em_portugues>/`
- [ ] `.vue` com defineComponent + comentários úteis
- [ ] `index.ts` com export do componente
- [ ] README.md do componente completo (em português)
- [ ] Playground criado em `src/playground/`
- [ ] Export adicionado em `src/index.ts`
- [ ] Tipos fortes (sem any; PropType<T> quando necessário)

---

## Regra de mudança importante
Sempre que uma mudança for relevante para desenvolvedores/usuários/IA, **atualizar o README.md correspondente**:
- README da raiz (se impactar o projeto)
- README do componente (se impactar API/uso/comportamento)

---

## Postura do agente ao gerar código
- Gerar código enxuto, legível e consistente
- Priorizar clareza e tipagem forte
- Nunca “inventar” API sem documentar
- Se houver dúvida de padrão visual, criar uma implementação neutra, documentar e manter extensível