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