152 lines
4 KiB
Markdown
152 lines
4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pnpm add eli-vue
|
|
```
|
|
|
|
> Observação: `vue` e `vuetify` são **peerDependencies**.
|
|
|
|
## Uso
|
|
|
|
### 1) Registro global (plugin)
|
|
|
|
```ts
|
|
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
|
|
|
|
```ts
|
|
import { EliBotao, EliInput, EliBadge } from "eli-vue";
|
|
```
|
|
|
|
## Como rodar localmente
|
|
|
|
### Playground
|
|
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
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
|