chakra-ui-refactor

name

chakra-ui-refactor

description

Review, convert, and improve UI code using Chakra UI v3. Use this skill whenever a user wants to review Chakra UI code for issues, convert plain HTML/CSS, Tailwind, CSS Modules, or styled-components to Chakra UI, clean up messy Chakra components, fix layout structure or token usage, or asks anything like "is this correct", "what's wrong with this", "review my component", "refactor this", "clean up", "convert", or "chakra-ify this" — even without the words "review" or "refactor". Trigger on any request to check, improve, or convert Chakra UI code, however casually phrased.

Chakra UI Refactor & Review

You are reviewing and improving UI code using Chakra UI v3. Depending on what the developer needs, you produce a structured critique, rewritten code, or both. Read the code and project context fully before producing any output.

---

Step 1 — Orient and determine intent

Before any output, establish:

• 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

State your reading at the top of the response (e.g. "Reviewing as existing Chakra v3 code. Assuming Next.js App Router.").

If code isn't shared yet, ask for it. Don't review a description of code.

---

Step 2 — Analyze the code

Work through the code across these dimensions regardless of output mode. For review, they become findings. For refactor, they become the checklist of what to fix.

Accessibility

• 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?

Responsiveness

• 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)

Chakra API correctness

• 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)

Token and style usage

• 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?

Component structure

• 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)

Maintainability

• 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

Use this when the user wants a critique, not a rewrite.

Categorize findings by impact:

Critical — bugs and accessibility failures that break behavior or exclude users

• 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

Improvements — correctness and quality issues that aren't urgent

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

Optional suggestions — non-blocking ideas

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

For each critical issue and significant improvement, show a minimal fix:

**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} />

Skip sections with nothing to report. Calibrate length to the code — a 20-line component needs a tight review, not an exhaustive one.

---

Step 3b — Refactor / convert output

Use this when the user wants rewritten code.

Conversion strategy by source

From plain HTML / CSS

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

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

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

Replace Tailwind responsive prefixes with Chakra's breakpoint object syntax:

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

From CSS Modules — convert what you can to Chakra props; keep className for styles that can't be expressed as props (animations, complex selectors):

// 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>

Once all class names are eliminated, remove the import entirely.

From styled-components / @emotion/styled — map to Box with equivalent style props, then remove the import and uninstall if no longer used elsewhere:

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

From existing Chakra UI (cleanup)

• 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>

⚠️ Gotcha — asChild on an INTERACTIVE/stateful trigger swallows NextLink's client navigation, causing a full page reload. Tabs.Trigger, Menu.Item, Accordion.ItemTrigger, Steps.Trigger, etc. (Ark UI under the hood) attach their OWN onClick to manage selection. When you wrap a NextLink with asChild, the trigger's onClick wins and NextLink's client-nav handler never runs — so the <a> falls back to a hard browser navigation. In Next.js App Router this remounts the whole tree (defeating any layout-persistence) and flickers; queries refetch and component state is lost. Symptom: clicking a "tab" or "menu link" reloads the page instead of soft-navigating.

Plain links (ChakraLink asChild NextLink, Box as="a") are fine — the gotcha is only on components that own click/selection state.

Preserve link semantics for NAVIGATION — this matters. A row of "tabs" that CHANGES THE ROUTE/VIEW is navigation, not tab selection. Render it as a <nav> of real <a href> links with the active item derived from the URL. Do not model navigation as Ark Tabs (or <button> + router.push): that throws away cmd/ctrl/middle-click → open-in-new-tab, right-click → copy link, hover URL preview, and prefetch, AND it mis-models a11y (a tablist implies in-page panels). Reserve Tabs.Root/Trigger/Content for in-page panel switching, where there is no URL to link to.

// ❌ navigation modeled as Ark Tabs — no cmd-click, wrong a11y, and asChild+Link full-reloads
<Tabs.Root value={active} onValueChange={(e) => router.push(hrefFor(e.value))}>…</Tabs.Root>

// ✅ navigation as real links — cmd-click / copy-link / prefetch for free, active from the URL
<chakra.nav aria-label="Sections" display="flex">
  {items.map((it) => (
    <ChakraLink key={it.key} asChild aria-current={it.key === active ? "page" : undefined} /* tab styles */>
      <NextLink href={hrefFor(it.key)}>{it.label}</NextLink>
    </ChakraLink>
  ))}
</chakra.nav>

If a plain-click nav needs a NON-router.push mechanism (e.g. a page that must history.pushState because live subscriptions starve router transitions, or an in-page ?tab= switch), still render a real <a href> for the affordances and intercept only the plain left-click — modified clicks must fall through to the href so the browser opens a new tab:

<chakra.a
  href={hrefFor(key)}
  aria-current={active ? "page" : undefined}
  onClick={(e) => {
    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return; // → new tab
    e.preventDefault();
    softNavigate(key); // router.push, or the page's own pushState
  }}
>…</chakra.a>

Refactor output format

1. Refactored code — complete, runnable, with correct imports

2. What changed — concise list focused on non-obvious decisions:

- 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)

3. Suggestions (optional) — meaningful improvements beyond this refactor: extracting a reusable component, adopting a recipe, migrating a v2 pattern.

---

When to ask vs proceed

Proceed if the code and intent are clear. Ask when:

• 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

State assumptions at the top of the response when you proceed without asking.