Chakra UI Refactor & Review

Step 1 — Orient and determine intent

• Chakra UI version — check

  package.json

  ; use v3 by default
• Framework — Next.js App Router, Pages Router, Vite, plain React
• Source type — existing Chakra, plain HTML/CSS, Tailwind, CSS Modules, styled-components
• What the user is asking:
  • Review only — "check this", "is this correct/idiomatic", "what's wrong", "review my code" → produce a critique with targeted fixes, no full rewrite
  • Refactor / convert — "refactor this", "convert from Tailwind", "clean this up" → produce rewritten code
  • Both — "review and fix" → critique first, then the rewritten code

Step 2 — Analyze the code

• Do all interactive elements have accessible labels? (

  aria-label

  on icon buttons,

  htmlFor

  /

  id

  on label+input pairs,

  alt

  on images)
• Is keyboard navigation possible? (focus rings not suppressed, interactive elements are actually focusable)
• Does the heading hierarchy make sense? (no skipped levels, no

  h1

  used as a style shortcut)
• Are form fields wrapped in

  Field.Root

  with

  Field.Label

  and

  Field.ErrorText

  ?
• Does the component work without color as the only signal?

• Do layout components specify behavior at multiple breakpoints?
• Are there hardcoded pixel values where responsive tokens would work better?
• Would this break on mobile? (fixed widths,

  overflow: hidden

  on small viewports)

• Are v3 prop names used? (

  disabled

  not

  isDisabled

  ,

  colorPalette

  not

  colorScheme

  ,

  gap

  not

  spacing

  ,

  open

  not

  isOpen

  )
• Are compound components used correctly? (

  Field.Root

  /

  Field.Label

  ,

  Dialog.Root

  /

  Dialog.Content

  , etc.)
• Is

  "use client"

  placed correctly in Next.js App Router?
• Are there v2 patterns still present? (

  extendTheme

  ,

  ColorModeScript

  ,

  useColorModeValue

  ,

  sx

  prop)

• Are hardcoded colors used where semantic tokens would work? (

  bg="#f9fafb"

  →

  bg="bg.subtle"

  )
• Are raw hex or palette values used instead of semantic tokens? These won't respect dark mode.
• Are there inline

  style={{}}

  props that should be Chakra style props?

• Is there unnecessary nesting? (

  Box > Box > Box

  when one would do)
• Is manual spacing (

  mt={4}

  on every child) used where

  Stack gap={4}

  would be cleaner?
• Are the right layout primitives used? (

  Flex

  vs

  Stack

  vs

  Grid

  vs

  SimpleGrid

  )

• Does the same visual pattern repeat 3+ times? (candidate for a component or recipe)
• Are there one-off style overrides that suggest a recipe or slot recipe?
• Are prop types / TypeScript types present and accurate?

Step 3a — Review output

• Missing

  aria-label

  on an icon-only button
• Form field with no label association
• Interactive

  Box

  with

  onClick

  but no keyboard access
• Wrong v3 prop name that silently does nothing (

  isDisabled

  doesn't disable in v3)

• "use client"

  missing on a component that uses hooks in App Router

• Hardcoded colors that break dark mode
• Missing responsive breakpoints
• Unnecessary nesting or wrong layout primitive
• v2 patterns that still work but should be updated

• Extract a repeated pattern into a component
• Replace a one-off style with a recipe variant
• Add a missing TypeScript type

**Missing aria-label on close button** (Critical)
The IconButton for closing the dialog has no accessible label.

// Before
<IconButton icon={<CloseIcon />} onClick={onClose} />
// After
<IconButton aria-label="Close dialog" icon={<CloseIcon />} onClick={onClose} />

Step 3b — Refactor / convert output

Conversion strategy by source

<div>

Box

Flex

Stack

Grid

<section>

<article>

Box as="section"

Box as="article"

<nav>

Box as="nav"

<ul>

<li>

Box as="ul"

Box as="li"

Stack

<button>

Button

IconButton

<a>

Link

<img>

Image

alt

<input>

<select>

Input

NativeSelect

Field.Root

display: flex

Flex

display="flex"

flex-direction: column

Stack

flexDir="column"

gap: 16px

gap={4}

padding: 16px 24px

py={4} px={6}

border-radius: 8px

rounded="md"

color: #6b7280

color="fg.muted"

background: #f9fafb

bg="bg.subtle"

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" }}

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

className

// Before
<div className={styles.card}>...</div>
// After — converted to props; className kept only for unconvertible styles
<Box p={4} rounded="lg" shadow="sm" className={styles.fadeIn}>...</Box>

Box

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

• Flatten

  Box > Box > Box

  nesting; replace

  mt

  /

  mb

  on every child with

  Stack gap={N}

• Replace

  sx

  with

  css

  (v3 rename); update nested

  &:hover

  selectors inside it
• Replace

  bg="gray.50"

  →

  bg="bg.subtle"

  and other semantic token equivalents
• Update v2 prop names:

  isDisabled→disabled

  ,

  colorScheme→colorPalette

  ,

  spacing→gap

• Update compound components:

  FormControl→Field.Root

  ,

  Modal→Dialog

  ,

  Select→NativeSelect

Preserve behavior — non-negotiable

• Keep all event handlers, state variables, and conditional rendering exactly as-is
• Keep

  aria-*

  attributes; add missing ones where clearly needed
• Keep semantic HTML intent (

  <nav>

  →

  Box as="nav"

  , not just

  Box

  )
• Keep

  "use client"

  where it exists; add it only when the component genuinely needs it
• Don't add

  "use client"

  just because a component uses Chakra UI
• A partially-converted component that works is better than a fully-converted one that doesn't

asChild

for Next.js Link and Image

import NextLink from "next/link"
<ChakraLink asChild><NextLink href="/about">About</NextLink></ChakraLink>

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

Refactor output format

- Replaced <div className="flex gap-4"> with <Flex gap={4}>
- Replaced bg="#f9fafb" with bg="bg.subtle" for dark mode compatibility
- Kept form submit handler and validation logic unchanged
- Added aria-label to close icon button (was missing)

When to ask vs proceed

• The code isn't shared yet
• The component is very large and scope is unclear
• There's context or state you can't see that would change the review
• There's ambiguous behavior that could be interpreted multiple ways