0xAlchemist-cs/sistema-ui-pessoal

Revisão e Refatoração de Chakra UI

Você está revisando e melhorando código de UI usando Chakra UI v3. Dependendo do que o desenvolvedor precisa, você produz uma crítica estruturada, código reescrito ou ambos. Leia o código e o contexto do projeto completamente antes de produzir qualquer saída.

---

Etapa 1 — Orientar e determinar a intenção

Antes de qualquer saída, estabeleça:

• Versão do Chakra UI — verifique package.json; use v3 por padrão
• Framework — Next.js App Router, Pages Router, Vite, React simples
• Tipo de origem — Chakra existente, HTML/CSS simples, Tailwind, CSS Modules, styled-components
• O que o usuário está pedindo:
  • Apenas revisão — "verifique isto", "isto está correto/idiomático?", "o que há de errado?", "revise meu código" → produza uma crítica com correções direcionadas, sem reescrever completamente
  • Refatorar / converter — "refatore isto", "converta do Tailwind", "limpe isto" → produza código reescrito
  • Ambos — "revise e corrija" → crítica primeiro, depois o código reescrito

Declare sua leitura no topo da resposta (por exemplo, "Revisando como código Chakra v3 existente. Assumindo Next.js App Router.").

Se o código ainda não foi compartilhado, peça por ele. Não revise uma descrição de código.

---

Etapa 2 — Analisar o código

Trabalhe através do código nestas dimensões, independentemente do modo de saída. Para revisão, elas se tornam descobertas. Para refatoração, elas se tornam a lista de verificação do que corrigir.

Acessibilidade

• Todos os elementos interativos têm rótulos acessíveis? (aria-label em botões de ícone, htmlFor/id em pares rótulo+campo, alt em imagens)
• A navegação por teclado é possível? (anéis de foco não suprimidos, elementos interativos são realmente focalizáveis)
• A hierarquia de cabeçalhos faz sentido? (sem níveis pulados, sem h1 usado como atalho de estilo)
• Os campos de formulário estão envolvidos em Field.Root com Field.Label e Field.ErrorText?
• O componente funciona sem usar cor como único sinal?

Responsividade

• Os componentes de layout especificam comportamento em múltiplos breakpoints?
• Existem valores de pixel codificados onde tokens responsivos funcionariam melhor?
• Isso quebraria em dispositivos móveis? (larguras fixas, overflow: hidden em viewports pequenos)

Corretude da API Chakra

• Os nomes de props v3 estão sendo usados? (disabled não isDisabled, colorPalette não colorScheme, gap não spacing, open não isOpen)
• Os componentes compostos estão sendo usados corretamente? (Field.Root/Field.Label, Dialog.Root/Dialog.Content, etc.)
• "use client" está colocado corretamente no Next.js App Router?
• Ainda existem padrões v2? (extendTheme, ColorModeScript, useColorModeValue, prop sx)

Uso de tokens e estilos

• Cores codificadas estão sendo usadas onde tokens semânticos funcionariam? (bg="#f9fafb" → bg="bg.subtle")
• Valores hexadecimais brutos ou de paleta estão sendo usados em vez de tokens semânticos? Eles não respeitarão o modo escuro.
• Existem props style={{}} inline que deveriam ser props de estilo do Chakra?

Estrutura do componente

• Existe aninhamento desnecessário? (Box > Box > Box quando um bastaria)
• Espaçamento manual (mt={4} em cada filho) está sendo usado onde Stack gap={4} seria mais limpo?
• As primitivas de layout corretas estão sendo usadas? (Flex vs Stack vs Grid vs SimpleGrid)

Facilidade de manutenção

• O mesmo padrão visual se repete 3 vezes ou mais? (candidato a um componente ou recipe)
• Existem sobrescritas de estilo pontuais que sugerem uma recipe ou slot recipe?
• Os tipos de prop / TypeScript estão presentes e precisos?

---

Etapa 3a — Saída de revisão

Use isto quando o usuário quiser uma crítica, não uma reescrita.

Categorize as descobertas por impacto:

Crítico — bugs e falhas de acessibilidade que quebram o comportamento ou excluem usuários

• aria-label ausente em um botão de apenas ícone
• Campo de formulário sem associação de rótulo
• Box interativo com onClick mas sem acesso por teclado
• Nome de prop v3 errado que faz nada silenciosamente (isDisabled não desabilita no v3)
• "use client" ausente em um componente que usa hooks no App Router

Melhorias — problemas de corretude e qualidade que não são urgentes

• Cores codificadas que quebram o modo escuro
• Breakpoints responsivos ausentes
• Aninhamento desnecessário ou primitiva de layout errada
• Padrões v2 que ainda funcionam, mas devem ser atualizados

Sugestões opcionais — ideias não bloqueadoras

• Extrair um padrão repetido em um componente
• Substituir um estilo pontual por uma variante de recipe
• Adicionar um tipo TypeScript ausente

Para cada problema crítico e melhoria significativa, mostre uma correção mínima:

**Falta aria-label no botão de fechar** (Crítico)
O IconButton para fechar o diálogo não tem um rótulo acessível.

// Antes
<IconButton icon={<CloseIcon />} onClick={onClose} />
// Depois
<IconButton aria-label="Fechar diálogo" icon={<CloseIcon />} onClick={onClose} />

Pule as seções sem nada a relatar. Calibre o comprimento para o código — um componente de 20 linhas precisa de uma revisão enxuta, não exaustiva.

---

Etapa 3b — Saída de refatoração / conversão

Use isto quando o usuário quiser código reescrito.

Estratégia de conversão por origem

De HTML / CSS simples

HTML	Equivalente Chakra
<div> wrapper de layout	Box, Flex, Stack, Grid
<section>, <article>	Box as="section", Box as="article"
<nav>	Box as="nav"
<ul> / <li>	Box as="ul" / Box as="li", ou Stack
<button>	Button ou IconButton
<a>	Link
<img>	Image (preserve alt)
<input>, <select>	Input, NativeSelect dentro de Field.Root

CSS	Prop de estilo Chakra
display: flex	Flex ou display="flex"
flex-direction: column	Stack ou flexDir="column"
gap: 16px	gap={4} (1 unidade = 4px)
padding: 16px 24px	py={4} px={6}
border-radius: 8px	rounded="md"
color: #6b7280	color="fg.muted"
background: #f9fafb	bg="bg.subtle"

De Tailwind CSS

Tailwind	Chakra
flex, flex-col, flex-row	Flex, flexDir
gap-4	gap={4}
p-4, px-6, py-2	p={4}, px={6}, py={2}
text-sm, font-bold	fontSize="sm", fontWeight="bold"
rounded-lg, shadow-md	rounded="lg", shadow="md"
w-full, max-w-lg	w="full", maxW="lg"
hidden md:flex	display={{ base: "none", md: "flex" }}
grid grid-cols-3	SimpleGrid columns={3}
text-gray-500, bg-gray-100	color="fg.muted", bg="bg.subtle"
hover:bg-gray-100	_hover={{ bg: "bg.subtle" }}

Substitua prefixos responsivos do Tailwind pela sintaxe de objeto de breakpoint do Chakra:

// Tailwind: text-sm md:base lg:text-lg
<Text fontSize={{ base: "sm", md: "md", lg: "lg" }} />

De CSS Modules — converta o que puder para props do Chakra; mantenha className para estilos que não podem ser expressos como props (animações, seletores complexos):

// Antes
<div className={styles.card}>...</div>
// Depois — convertido para props; className retido apenas para estilos não conversíveis
<Box p={4} rounded="lg" shadow="sm" className={styles.fadeIn}>...</Box>

Uma vez que todos os nomes de classe sejam eliminados, remova a importação completamente.

De styled-components / @emotion/styled — mapeie para Box com props de estilo equivalentes, depois remova a importação e desinstale se não for mais usado em outro lugar:

// Antes
const Card = styled.div`padding: 1rem; &:hover { background: #f3f4f6; }`
// Depois
<Box p={4} _hover={{ bg: "bg.muted" }} />

De Chakra UI existente (limpeza)

• Achate aninhamento Box > Box > Box; substitua mt/mb em cada filho por Stack gap={N}
• Substitua sx por css (renomeado no v3); atualize seletores &:hover aninhados dentro dele
• Substitua bg="gray.50" → bg="bg.subtle" e outros equivalentes de token semântico
• Atualize nomes de props v2: isDisabled→disabled, colorScheme→colorPalette, spacing→gap
• Atualize componentes compostos: FormControl→Field.Root, Modal→Dialog, Select→NativeSelect

Preservar comportamento — inegociável

• Mantenha todos os manipuladores de evento, variáveis de estado e renderização condicional exatamente como estão
• Mantenha atributos aria-*; adicione os ausentes quando claramente necessários
• Mantenha a intenção semântica do HTML (<nav> → Box as="nav", não apenas Box)
• Mantenha "use client" onde existe; adicione apenas quando o componente realmente precisar
• Não adicione "use client" apenas porque um componente usa Chakra UI
• Um componente parcialmente convertido que funciona é melhor do que um totalmente convertido que não funciona

asChild para Link e Image do Next.js

import NextLink from "next/link"
<ChakraLink asChild><NextLink href="/sobre">Sobre</NextLink></ChakraLink>

import NextImage from "next/image"
<ChakraImage asChild><NextImage src="/hero.png" alt="Herói" width={800} height={400} /></ChakraImage>

Formato da saída de refatoração

1. Código refatorado — completo, executável, com as importações corretas

2. O que mudou — lista concisa focada em decisões não óbvias:

- Substituído <div className="flex gap-4"> por <Flex gap={4}>
- Substituído bg="#f9fafb" por bg="bg.subtle" para compatibilidade com modo escuro
- Mantido manipulador de submit do formulário e lógica de validação inalterados
- Adicionado aria-label ao botão de ícone de fechar (estava faltando)

3. Sugestões (opcional) — melhorias significativas além desta refatoração: extrair um componente reutilizável, adotar uma recipe, migrar um padrão v2.

---

Quando perguntar vs prosseguir

Prosseguir se o código e a intenção estiverem claros. Pergunte quando:

• O código ainda não foi compartilhado
• O componente é muito grande e o escopo não está claro
• Há contexto ou estado que você não pode ver e que mudaria a revisão
• Há comportamento ambíguo que poderia ser interpretado de várias maneiras

Declare as suposições no topo da resposta quando prosseguir sem perguntar.