From 86d451efa1939dfa0c406b9de5278060245fbf08 Mon Sep 17 00:00:00 2001
From: Luiz Silva <luiz@e-licencie.com.br>
Date: Fri, 2 Jan 2026 20:57:49 -0300
Subject: [PATCH] chore: add agent rules

---
 .agent | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 175 insertions(+)
 create mode 100644 .agent

diff --git a/.agent b/.agent
new file mode 100644
index 0000000..0598f4a
--- /dev/null
+++ b/.agent
@@ -0,0 +1,175 @@
+# 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, mas preferir português:
+  - `BotaoPrimario.vue`, `CartaoInfo.vue`, `CampoTexto.vue`
+- 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/
+      Botao.vue
+      index.ts
+      README.md
+    cartao/
+      Cartao.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 Botao } from "./Botao.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