175 lines
5.8 KiB
Text
175 lines
5.8 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**
|
|
|
|
---
|
|
|
|
## 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: se usar, definir um padrão único do repositório (não inventar por componente)
|
|
|
|
---
|
|
|
|
## 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, mas preferir português:
|
|
- `BotaoPrimario.vue`, `CartaoInfo.vue`, `CampoTexto.vue`
|
|
- Props e eventos: preferir português e sem ambiguidades:
|
|
- Props: `rotulo`, `desabilitado`, `carregando`, `modeloValor`
|
|
- Eventos: `update:modelValue`, `confirmar`, `cancelar`, `clicar`
|
|
|
|
---
|
|
|
|
## 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/
|
|
Botao.vue
|
|
index.ts
|
|
README.md
|
|
cartao/
|
|
Cartao.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)
|
|
|
|
---
|
|
|
|
## 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`
|
|
|
|
---
|
|
|
|
## 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 Botao } from "./Botao.vue"`
|
|
- `src/index.ts` deve exportar todos os componentes publicamente
|
|
- Não exportar itens internos não documentados
|
|
|
|
---
|
|
|
|
## 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)
|
|
|
|
---
|
|
|
|
## 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
|