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.

Instalação (projeto consumidor já usa Vuetify)

Se o seu projeto já está configurado com Vuetify 3, basta instalar este pacote:

pnpm add eli-vue

Dica: mantenha vue e vuetify atualizados dentro das faixas suportadas.

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");

Exemplo completo (main.ts) — com Vuetify 3

Este é o modelo recomendado para projetos consumidores (Vite + Vue 3) que já usam Vuetify 3:

import { createApp } from "vue";
import App from "./App.vue";

// Vuetify
import "vuetify/styles";
import { createVuetify } from "vuetify";

// eli-vue (Design System)
import EliVue from "eli-vue";
import "eli-vue/dist/eli-vue.css";

const vuetify = createVuetify({
  // opcional: componentes/directives/tema do seu projeto
});

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

Nota: o eli-vue não cria nem configura Vuetify; ele assume que o consumidor já tem Vuetify.

2) Importação direta de componentes

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

Exemplos rápidos de uso

EliBotao

<template>
  <EliBotao @click="salvar">Salvar</EliBotao>
</template>

EliInput (v-model)

<template>
  <EliInput v-model="nome" label="Nome" placeholder="Digite seu nome" />
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";

export default defineComponent({
  setup() {
    const nome = ref("");
    return { nome };
  },
});
</script>

EliBadge

<template>
  <EliBadge badge="3">
    <v-icon>mdi-bell</v-icon>
  </EliBadge>
</template>

Troubleshooting (problemas comuns)

1) "Failed to resolve component" / componente não registrado

Você provavelmente esqueceu de:

• usar o plugin: app.use(EliVue)
• ou importar e registrar o componente localmente

2) Estilos não aplicam / layout estranho

Confirme que o consumidor importou:

• vuetify/styles
• eli-vue/dist/eli-vue.css

3) Ícones não aparecem

Alguns exemplos usam <v-icon> com Material Design Icons. O eli-vue não instala ícones no seu projeto.

• garanta que o seu projeto consumidor está configurado com o pacote de ícones desejado (ex.: MDI)
• ou substitua o conteúdo do slot por outro elemento

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