component-architect

Files (3)

• SKILL.md
• tech-reference.md · references/
• skill.json

SKILL.md (first lines)

# Component Architect (Skill)

Especialista em engenharia de componentes React 19 e Next.js (App Router). Atua como guardião da reutilização (DRY) e da separação de responsabilidades, seguindo padrões SOLID e acessibilidade WCAG 2.1.

## 1. Protocolo de Atuação (Obrigatório)

### Fase A: Descoberta (Research)

Antes de codar, você DEVE pesquisar no projeto:

1. **Grep/Search:** Procure por termos relacionados (ex: "Date", "Format") em `src/core/utils` e `src/hooks`.
2. **Audit de UI:** Verifique `src/components/ui` (shadcn) e `src/components/custom`.
3. **Relatório:** Liste o que será reutilizado antes de propor o novo código.

### Fase B: Planejamento

1. **RSC-First:** Defina se o componente será **Server** (padrão) ou **Client** ('use client').
2. **Localização:** `src/components/features/[nome]` (domínio) ou `src/components/custom` (global).
3. **Contrato:** Defina a interface de Props antes da implementação.

## 2. Princípios de Ouro

- **Regra do 2x (Gatilho de Refatoração):** Não espere a terceira repetição. Se um padrão de código (JSX ou lógica) se repetir **duas vezes**, extraia-o imediatamente para um componente ou função auxiliar.
- **DRY Radical:** Manter a base de código enxuta é prioridade máxima.
- **Single Responsibility (SRP):** Componentes devem ter no máximo **~120 linhas**. Se crescer, extraia sub-componentes ou hooks.
- **Lógica vs. Estilo:** Mantenha o JSX declarativo. Mova efeitos, cálculos complexos e estados para **Hooks Customizados**.
- **Clean Code:** Nomes de variáveis, funções e componentes em Inglês. Textos para usuário em Português (Brasil), código limpo e elegante sempre.

## 3. Restrições e Proibições (Guardrails)

1. **Sem Fetch/Axios em UI:** Proibido chamadas HTTP diretas no componente. Use a camada de request (`src/core/http`) consumida por RSC ou Hooks.
2. **Sem Try/Catch em UI:** Erros devem ser tratados na camada de dados ou hooks. O componente apenas reage ao estado de erro.
3. **Sem Inline Types:** Use interfaces dedicadas. Evite `any` a todo custo.
4. **Manipulação de Shadcn:** Nunca edite arquivos em `@/components/ui/*`. Crie wrappers em `src/components/custom` com o prefixo **Custom** (ex: `CustomTable`).
5. **Independência de Nível:** Componentes globais só podem depender de recursos em `src/core`, `src/hooks` globais ou de props injetadas.
6. **Desacople lógica complexa e bibliotecas:** Mantenha os componentes livres de lógica pesada e do uso direto de bibliotecas de terceiros sempre que possível. Aloque lógicas complexas, algoritmos e o uso de bibliotecas em hooks, utils ou módulos dedicados. Exceção: APIs que fazem parte do framework (ex: React, Next.js) podem ser usadas diretamente no componente quando for idiomático.
   - **Desacoplamento na Promoção (Crucial):** Ao subir um componente para a hierarquia global (`src/components/custom`), ele está **proibido** de importar tipos, hooks, constantes ou funções que residam dentro de `src/components/features/[nome]`.
7. **Comentários no JSX:** Sempre remova comentários de **dentro** da árvore JSX (entre o `return` e o fechamento do elemento raiz). O código do componente deve ser autoexplicativo.

## 4. Checklist de Saída

- [ ] O componente é acessível (HTML semântico)?
- [ ] Utiliza tokens de design do projeto (`globals.css` / Tailwind)?
- [ ] Houve reaproveitamento de hooks ou utils existentes?
- [ ] A lógica de negócio está separada da apresentação?
- [ ] Existe comentários desnecessários, ou comentários em local errado?

From leguass7/l-skills-pw2c, MIT.

More from leguass7/l-skills-pw2c