From 5d78d648e1e9e7c6a41e550753747d0556438385 Mon Sep 17 00:00:00 2001
From: Luiz Silva <luiz@e-licencie.com.br>
Date: Fri, 2 Jan 2026 21:29:21 -0300
Subject: [PATCH] docs: aprimorar README para humanos e IAs

---
 README.md | 133 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 111 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 8093e12..b23f3c9 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,74 @@
 # eli-vue — Design System (Vue 3 + TypeScript)
 
-Biblioteca de componentes Vue 3 (Design System) para reutilização em múltiplos projetos, com foco em:
+Biblioteca de componentes Vue 3 (Design System) para reutilização em múltiplos projetos.
+
+Este README foi escrito para **humanos e IAs**: ele descreve o objetivo do repositório, regras, estrutura, fluxo de contribuição, comandos e um roadmap de melhorias.
+
+## Fonte da verdade (regras)
+
+As regras oficiais do repositório estão no arquivo **`.agent`**.
+
+Antes de propor mudanças:
+
+- leia o `.agent`
+- procure padrões já existentes no código
+- atualize a documentação correspondente (README raiz e/ou README do componente)
+
+## Objetivos
 
 - consistência visual e comportamental
 - tipagem forte (TypeScript `strict`)
 - documentação em português
 - exemplos executáveis via playground
 
-As regras do repositório estão descritas em **`.agent`**.
+## O que NÃO entra no contexto
+
+- `node_modules/`: dependências (não versionar; não usar como fonte da verdade)
+- `dist/`: gerado no build (não versionar)
+
+## Arquitetura do repositório
+
+```
+src/
+  componentes/
+    botao/
+      EliBotao.vue
+      index.ts
+      README.md
+    campo/
+      EliInput.vue
+      index.ts
+      README.md
+    indicador/
+      EliBadge.vue
+      index.ts
+      README.md
+  tipos/
+    botao.ts
+    campo.ts
+    indicador.ts
+    index.ts
+  playground/
+    App.vue
+    *.playground.vue
+  index.ts
+```
+
+### Convenções (nomenclatura)
+
+- Componentes usam **prefixo `Eli`** (ex.: `EliBotao`, `EliInput`).
+- Pastas preferem **português** (ex.: `src/componentes/botao`, `src/componentes/campo`).
+- Tipos compartilhados ficam em `src/tipos/`.
+- Sem TSX; padrão SFC: `<template>` + `<script lang="ts">` + `defineComponent`.
+- `any` é proibido.
 
 ## Instalação
 
-Como dependência do projeto:
-
 ```bash
 pnpm add eli-vue
 ```
 
-> Observação: `vue` e `vuetify` são **peerDependencies**. Garanta que seu projeto já os tenha instalados.
+> Observação: `vue` e `vuetify` são **peerDependencies**.
 
 ## Uso
 
@@ -38,26 +89,64 @@ createApp(App).use(EliVue).mount("#app");
 import { EliBotao, EliInput, EliBadge } from "eli-vue";
 ```
 
-## Convenções do projeto
+## Como rodar localmente
 
-- Componentes usam **prefixo `Eli`** (ex.: `EliBotao`, `EliInput`).
-- Pastas seguem **português** (ex.: `src/componentes/botao`, `src/componentes/campo`, `src/componentes/indicador`).
-- Sem TSX; padrão SFC: `<template>` + `<script lang="ts">` + `defineComponent`.
-- Evitar `any`.
-
-## Como criar um novo componente (checklist)
-
-1. Criar pasta em `src/componentes/<nome_em_portugues>/`
-2. Criar `EliNomeDoComponente.vue` com `defineComponent` + comentários úteis
-3. Criar `index.ts` re-exportando o componente
-4. Criar `README.md` do componente (API, exemplos, casos de borda)
-5. Criar playground em `src/playground/<nome>.playground.vue` (3+ variações)
-6. Exportar no `src/index.ts`
-
-## Como rodar o playground
+### Playground
 
 ```bash
 pnpm dev
 ```
 
-O playground fica em `src/playground` e serve para validar visualmente os componentes durante o desenvolvimento.
+O playground (`src/playground`) valida visualmente variações e interações.
+
+### Build da lib + geração de tipos
+
+```bash
+pnpm run build
+```
+
+Gera `dist/` (artefatos de build) e `dist/types` (declarações `.d.ts`).
+
+## Guia rápido para IAs (antes de codar)
+
+1) **Leia** `.agent` e este README.
+2) **Busque padrões** antes de criar API nova (props/emits/slots).
+3) **Não use `any`**.
+4) **Centralize tipos** em `src/tipos/`.
+5) Ao mudar API/comportamento:
+   - atualize o `README.md` do componente
+   - atualize ou crie um `*.playground.vue`
+6) Rode `pnpm run build` antes de finalizar.
+
+## Como criar/alterar um componente (checklist)
+
+1. Criar pasta em `src/componentes/<nome_em_portugues>/`
+2. Criar `EliNomeDoComponente.vue` com `defineComponent` + comentários úteis
+3. Criar `index.ts` com re-export (ex.: `export { default as EliX } from './EliX.vue'`)
+4. Criar `README.md` do componente (API, exemplos, casos de borda, A11y)
+5. Criar playground em `src/playground/<nome>.playground.vue` (mín. 3 variações)
+6. Exportar no `src/index.ts`
+
+### Critérios de aceite (qualidade)
+
+- `pnpm run build` passa (inclui `vue-tsc`)
+- zero `any`
+- `defineComponent` em todos os componentes
+- README do componente atualizado quando API mudar
+- playground demonstrando variações + interação
+
+## Roadmap de melhorias (a aplicar)
+
+### Curto prazo (qualidade / consistência)
+- [ ] Padronizar comentários úteis em todos os componentes (explicar decisões e estados)
+- [ ] Tipar `emits` com validação de payload (quando houver)
+- [ ] Consolidar nomenclatura de props/eventos em português (avaliar breaking changes)
+
+### Médio prazo (DX + segurança)
+- [ ] Adicionar ESLint + Prettier e regras (incluindo proibição de `any`)
+- [ ] Adicionar testes unitários com Vitest + @vue/test-utils
+- [ ] Criar pipeline de CI rodando `pnpm run build`
+
+### Longo prazo (docs e maturidade)
+- [ ] Documentação visual (Storybook ou VitePress)
+- [ ] Tokens de design (cores/spacing) e guideline de acessibilidade