vue-componentes/README.md

eli-vue — Design System (Vue 3 + TypeScript)

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

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

pnpm add eli-vue

Observação: vue e vuetify são peerDependencies.

Uso

1) Registro global (plugin)

import { createApp } from "vue";
import EliVue from "eli-vue";

import App from "./App.vue";

createApp(App).use(EliVue).mount("#app");

2) Importação direta de componentes

import { EliBotao, EliInput, EliBadge } from "eli-vue";

Como rodar localmente

Playground

pnpm dev

O playground (src/playground) valida visualmente variações e interações.

Build da lib + geração de tipos

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