267 lines
8.9 KiB
Text
267 lines
8.9 KiB
Text
# 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**
|
|
|
|
---
|
|
|
|
## O que NÃO entra no contexto do agente
|
|
|
|
- `node_modules/`: dependências da arquitetura (não versionar / não usar como “fonte da verdade”).
|
|
- `dist/`: pasta **gerada** pelo build (não versionar). Use para validar o build localmente.
|
|
|
|
---
|
|
|
|
## 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: caso seja necessário o uso de ícones, usar **lucide** (biblioteca `lucide-vue-next`) como padrão do repositório.
|
|
|
|
---
|
|
|
|
## 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:
|
|
- **Padrão do repositório:** componentes com prefixo `Eli` (ex.: `EliBotao`, `EliInput`).
|
|
- Pastas preferem português (ex.: `src/componentes/botao/`, `src/componentes/campo/`).
|
|
- Props e eventos: preferir português e sem ambiguidades:
|
|
- Props: `rotulo`, `desabilitado`, `carregando`, `modeloValor`
|
|
- Eventos: `update:modelValue`, `confirmar`, `cancelar`, `clicar`
|
|
|
|
---
|
|
|
|
## Convenção atual de entradas (IMPORTANTE)
|
|
|
|
O componente **`EliInput` foi removido**. O padrão atual é a família **`EliEntrada*`**:
|
|
|
|
- `EliEntradaTexto`
|
|
- `EliEntradaNumero`
|
|
- `EliEntradaDataHora`
|
|
|
|
E o contrato padrão para entradas é:
|
|
- prop `value`
|
|
- evento `update:value`
|
|
- prop obrigatória `opcoes` (contém `rotulo` e outras opções)
|
|
|
|
Exemplo:
|
|
|
|
```vue
|
|
<EliEntradaTexto v-model:value="nome" :opcoes="{ rotulo: 'Nome' }" />
|
|
```
|
|
|
|
---
|
|
|
|
## 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/
|
|
EliBotao.vue
|
|
index.ts
|
|
README.md
|
|
cartao/
|
|
EliCartao.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)
|
|
|
|
Pastas geradas/ignoradas:
|
|
- `dist/` (build)
|
|
- `node_modules/` (dependências)
|
|
|
|
---
|
|
|
|
## 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`
|
|
|
|
### Centralização de tipos (padrão do repositório)
|
|
|
|
- Tipos compartilhados (uniões, enums, aliases) devem ficar em `src/tipos/`.
|
|
- Cada domínio pode ter seu arquivo:
|
|
- `src/tipos/botao.ts`
|
|
- `src/tipos/campo.ts`
|
|
- `src/tipos/indicador.ts`
|
|
- Re-export central em `src/tipos/index.ts`.
|
|
- Componentes importam tipagens de `src/tipos`.
|
|
|
|
---
|
|
|
|
## 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 EliBotao } from "./EliBotao.vue"`
|
|
- `src/index.ts` deve exportar todos os componentes publicamente
|
|
- Não exportar itens internos não documentados
|
|
|
|
---
|
|
|
|
## Convenção atual de EliTabela (IMPORTANTE)
|
|
|
|
### Filtro avançado
|
|
|
|
O filtro avançado da `EliTabela` é configurado via `tabela.filtroAvancado`.
|
|
|
|
Regras:
|
|
- O **operador é travado na definição** (o usuário não escolhe operador)
|
|
- Cada filtro pode ser usado **no máximo 1 vez**
|
|
- UI: modal mostra **apenas os componentes de entrada** definidos no filtro
|
|
- Persistência: salva em `localStorage` apenas `{ coluna, valor }[]` por `tabela.nome`
|
|
|
|
Se você for evoluir isso para backend:
|
|
- usar `parametrosConsulta.filtros` (`tipoFiltro[]`) no `tabela.consulta`
|
|
- manter compatibilidade com simulação local (quando necessário)
|
|
|
|
---
|
|
|
|
## Publicação do pacote (npm)
|
|
|
|
### Regra de publicação (sem usar `package.json.files`)
|
|
|
|
Este repositório **não usa** o campo `package.json.files`.
|
|
O controle do que vai para o tarball publicado é feito via **`.npmignore`**.
|
|
|
|
**Ação obrigatória:** sempre que adicionar/renomear/remover arquivos importantes para consumo (ex.: `IA.md`, mudanças de CSS em `dist/`, novas tipagens geradas), revisar e atualizar o `.npmignore`.
|
|
|
|
**Validação obrigatória:** após alterar `.npmignore`, rodar:
|
|
|
|
```bash
|
|
npm pack --dry-run
|
|
```
|
|
|
|
E confirmar que o tarball inclui o que deve estar disponível para consumidores.
|
|
|
|
---
|
|
|
|
## 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)
|
|
|
|
### Documentação para IAs consumidoras (IA.md)
|
|
|
|
O arquivo **`IA.md`** (na raiz) é um guia para **IAs que vão consumir/importar** o pacote `eli-vue`.
|
|
|
|
Sempre que houver mudanças relevantes de consumo, **`IA.md` deve ser atualizado** — por exemplo:
|
|
|
|
- instalação / comandos recomendados (pnpm/npm/yarn)
|
|
- peerDependencies (Vue/Vuetify) e requisitos mínimos
|
|
- forma de uso do plugin (`import EliVue from "eli-vue"`) e registro
|
|
- caminho/nome do CSS publicado em `dist/` (ex.: `eli-vue/dist/eli-vue.css`)
|
|
- exports públicos (componentes adicionados/removidos/renomeados)
|
|
|
|
---
|
|
|
|
## 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
|