DEV Community

Cover image for Generating a Custom Chakra UI v3 Theme from Design Tokens: A Complete Guide
Kiran Mantha
Kiran Mantha

Posted on

Generating a Custom Chakra UI v3 Theme from Design Tokens: A Complete Guide

#chakraui #react #programming #webdev

A practical, framework-agnostic guide to generating a **Chakra UI v3* theme from Figma design tokens — adaptable to any token format.*

Chakra UI v3 introduced a new theming system based on tokens, semantic tokens, conditions, and recipes. While the official docs are great, many teams struggle with automating theme generation from Figma in a scalable, maintainable way.

This guide walks you through:

  • The exact structure Chakra UI v3 expects in themeConfig.json
  • What goes into tokens vs semanticTokens
  • How to support responsive values, multiple themes, and text styles
  • How to integrate the generated theme into your React app

No Figma plugin or proprietary format required — just JSON design tokens and a Node.js script.

Let's start by creating a json called themeConfig.json which defines the final chakra theme.

Important: Chakra UI v3 Uses Panda CSS Under the Hood

Chakra UI v3 is built on top of Panda CSS — a CSS-in-JS engine that powers its styling, theming, and component system.

This means:

  • Your themeConfig.json is not just Chakra-specific — it's a Panda CSS config.
  • The tokens, semanticTokens, conditions, and recipes you define are fully compatible with Panda CSS.
  • You can reuse the same theme in non-React projects (Vue, Svelte, etc.) via Panda.

Official Docs to Bookmark

Resource Link
Chakra UI v3 Docs https://chakra-ui.com
Panda CSS Docs https://panda-css.com
Panda Theme Tokens https://panda-css.com/docs/concepts/theme-tokens
Chakra + Panda Integration https://chakra-ui.com/docs/styled-system/theming

Pro Tip: Read both docs — Chakra handles the React layer, Panda handles the CSS engine.

Critical Rule: No Token References in Final Output

themeConfig.json must contain only **fully resolved values — never {primitives.colors.blue.500}**

Wrong (Do Not Do This) 

{ "colors": { "brand": { "500": { "value": "{primitives.colors.blue.500}" } } } }
Enter fullscreen mode Exit fullscreen mode

Correct (Required) 

{ "colors": { "brand": { "500": { "value": "#0ea5e9" } } } }
Enter fullscreen mode Exit fullscreen mode

Why?

  • Panda CSS does not resolve references at runtime
  • Your build script must resolve all {...} references
  • Final output must be static, predictable, and framework-ready

Your transformation script is responsible for:

  1. Detecting {path.to.token}
  2. Traversing the token tree
  3. Recursively resolving nested references
  4. Replacing with final value (#0ea5e9, 1.5rem, etc.) 
function resolveReference(ref: string, tokens: any): any { if (!ref.startsWith('{') || !ref.endsWith('}')) return ref; const path = ref.slice(1, -1).split('.'); let value = tokens; for (const key of path) { value = value?.[key]; if (!value) throw new Error(`Unresolved token: ${ref}`); } return typeof value === 'object' && 'value' in value ? resolveReference(value.value, tokens) : value; }
Enter fullscreen mode Exit fullscreen mode

This is a sample function for token value resolution. The logic will vary on your figma design tokens structure.
Always resolve before writing to themeConfig.json

Prerequisites

  • Node.js ≥ 18
  • Chakra UI v3 (@chakra-ui/react@3.3.1 or later)
  • Design tokens exported as JSON (from Figma, Tokens Studio, etc.)

Step 1: Understand Chakra UI v3 Theme Structure

Chakra v3 uses a token-based system powered by Panda CSS. Your theme config must follow this shape:

interface ChakraThemeConfig { breakpoints: Record<string, string>; tokens: { colors: Record<string, any>; fonts: Record<string, string>; fontWeights: Record<string, any>; spacing: Record<string, any>; borders: Record<string, any>; radii: Record<string, any>; shadows: Record<string, any>; gradients: Record<string, any>; letterSpacings: Record<string, any>; }; semanticTokens: { colors: Record<string, any>; spacing: Record<string, any>; fontSizes: Record<string, any>; lineHeights: Record<string, any>; grid: Record<string, any>; }; textStyles: Record<string, { value: any }>; themes: Record<string, string>; // for CSS variable scoping }
Enter fullscreen mode Exit fullscreen mode

Let’s break down each section.

breakpoints

Define your responsive breakpoints in rem.

"breakpoints": { "base": "0rem", "sm": "40rem", "md": "48rem", "lg": "64rem", "xl": "80rem" }
Enter fullscreen mode Exit fullscreen mode

Use min-width values from your design system.

tokens — Primitive Design Tokens

These are raw, reusable values. Think of them as CSS variables.

colors

Primitive color palette (not semantic):

"colors": { "brand": { "50": { "value": "#f0f9ff" }, "500": { "value": "#0ea5e9" }, "900": { "value": "#0c4a6e" } }, "gray": { ... }, "transparent": { "value": "transparent" } }
Enter fullscreen mode Exit fullscreen mode

Use { value: ... } wrapper — required by Panda CSS.

fonts

Font families:

"fonts": { "heading": { "value": "'Inter', sans-serif" }, "body": { "value": "'Inter', sans-serif" }, "mono": { "value": "'Fira Code', monospace" } }
Enter fullscreen mode Exit fullscreen mode

Always wrap in { value: ... }

fontWeights, letterSpacings, spacing, borders, radii, shadows, gradients

All follow the same pattern:

"spacing": { "4": { "value": "1rem" }, "8": { "value": "2rem" } }, "radii": { "md": { "value": "0.375rem" } }, "shadows": { "sm": { "value": "0 1px 3px rgba(0,0,0,0.1)" } }
Enter fullscreen mode Exit fullscreen mode

Convert px to rem using base 16: px / 16 = rem

semanticTokens — Meaningful, Contextual Tokens

These are design decisions, not raw values.

Use when you want:

  • Responsive values
  • Theme-aware values (light/dark)
  • Semantic meaning (text.primary, bg.card)

Responsive Values (via object) 

"fontSizes": { "display.xl": { "value": { "base": "2.5rem", "sm": "3rem", "md": "3.75rem", "lg": "4.5rem" } } }
Enter fullscreen mode Exit fullscreen mode

base and sm = mobile

md = tablet (optional)

lg+ = desktop

Single Value (non-responsive) 

"fontSizes": { "body": { "value": "1rem" } }
Enter fullscreen mode Exit fullscreen mode

grid — Responsive Layout Tokens 

"grid": { "gutterSize": { "value": { "base": "1rem", "lg": "2rem" } }, "count": { "value": { "base": 4, "lg": 12 } } }
Enter fullscreen mode Exit fullscreen mode

textStyles — Reusable Typography

Define complete text styles:

"textStyles": { "heading.h1": { "value": { "fontSize": "{fontSizes.display.xl}", "lineHeight": "{lineHeights.tight}", "fontWeight": "{fontWeights.bold}", "fontFamily": "{fonts.heading}", "letterSpacing": "{letterSpacings.tight}", "textTransform": "uppercase" } } }
Enter fullscreen mode Exit fullscreen mode

Use token references with {path.to.token}

Use textCaseToTransform() to map Figma UPPERCASE to uppercase

themes — Multi-Theme Support (Light/Dark/Minimal/Contrast)

Chakra v3 supports CSS-scoped themes via [data-theme] or css classes. Below is an example with data-theme.

"themes": { "lightTheme": "[data-theme=light] &", "darkTheme": "[data-theme=dark] &", "minimalTheme": "[data-theme=minimal] &", "contrastTheme": "[data-theme=contrast] &" }
Enter fullscreen mode Exit fullscreen mode

Same can be replicated using css classes:

"themes": { "lightTheme": ".light &", "darkTheme": ".dark &", "minimalTheme": ".minimal &", "contrastTheme": ".contrast &" }
Enter fullscreen mode Exit fullscreen mode

then set the defined data-theme or classname to the body tag for different views.

Use in semanticTokens.colors like:

"colors": { "bg.page": { "value": { "_light": "#ffffff", "_darkTheme": "#0f172a", "_minimalTheme": "#f8f9fa", "_contrastTheme": "#000000" } } }
Enter fullscreen mode Exit fullscreen mode

_light is default

Use _themeNameTheme for custom themes

Final themeConfig.json Example 

{ "breakpoints": { ... }, "tokens": { "colors": { "brand": { "500": { "value": "#0ea5e9" } } }, "fonts": { ... }, "spacing": { ... } }, "semanticTokens": { "colors": { "text.primary": { "value": { "_light": "#1f2937", "_darkTheme": "#f1f5f9" } } }, "fontSizes": { "display.xl": { "value": { "base": "2.5rem", "lg": "4.5rem" } } } }, "textStyles": { "heading.h1": { "value": { ... } } }, "themes": { "lightTheme": "[data-theme=light] &", "darkTheme": "[data-theme=dark] &", "minimalTheme": "[data-theme=minimal] &", "contrastTheme": "[data-theme=contrast] &" } }
Enter fullscreen mode Exit fullscreen mode

No {...} references — all values fully resolved

Step 2: Generate themeConfig.json (Any Format to Chakra)

Write a Node.js script that:

  1. Reads your Figma JSON
  2. Resolves all {references}
  3. Converts px to rem
  4. Maps to Chakra/Panda structure
  5. Outputs dist/themeConfig.json

Your input format doesn’t matter — only the output does.

Example Script Skeleton 

// generate-theme.ts import fs from 'fs/promises'; import path from 'path'; const pxToRem = (px: number) => `${px / 16}rem`; function resolveReference(ref: string, tokens: any): any { if (!ref.startsWith('{') || !ref.endsWith('}')) return ref; const path = ref.slice(1, -1).split('.'); let value = tokens; for (const key of path) { value = value?.[key]; if (!value) throw new Error(`Unresolved token: ${ref}`); } return typeof value === 'object' && 'value' in value ? resolveReference(value.value, tokens) : value; } async function generateTheme() { const input = JSON.parse(await fs.readFile('tokens.json', 'utf-8')); const theme: any = { breakpoints: { base: '0rem', sm: '40rem', md: '48rem', lg: '64rem', xl: '80rem' }, tokens: { colors: {}, fonts: {}, spacing: {} }, semanticTokens: { colors: {}, fontSizes: {} }, textStyles: {}, themes: { lightTheme: '[data-theme=light] &', darkTheme: '[data-theme=dark] &', minimalTheme: '[data-theme=minimal] &', contrastTheme: '[data-theme=contrast] &' } }; // Map your tokens to Chakra/Panda // Use resolveReference() everywhere // ... await fs.mkdir('dist', { recursive: true }); await fs.writeFile('dist/themeConfig.json', JSON.stringify(theme, null, 2)); } generateTheme();
Enter fullscreen mode Exit fullscreen mode

Step 3: Use in React App 

// theme.ts import * as themeConfig from './dist/themeConfig.json'; import { createSystem, defaultConfig, defineConfig } from '@chakra-ui/react'; const customConfig = defineConfig({ theme: { ...(themeConfig as any), recipes: { /* your component recipes */ }, slotRecipes: { /* your slot recipes */ }, }, conditions: themeConfig.themes as any, }); export const system = createSystem(defaultConfig, customConfig); export const { ThemeProvider, theme } = system;
Enter fullscreen mode Exit fullscreen mode

App Entry 

// App.tsx import { ThemeProvider, theme } from './theme'; import { Theme } from '@chakra-ui/react'; export default function App() { return ( <ThemeProvider> <Theme accentColor="brand.500"> <YourApp /> </Theme> </ThemeProvider> ); }
Enter fullscreen mode Exit fullscreen mode

Switching Themes at Runtime 

<button onClick={() => document.documentElement.dataset.theme = 'minimal'}> Minimal Mode </button>
Enter fullscreen mode Exit fullscreen mode

Chakra automatically picks up [data-theme=minimal]

Best Practices

Do Don't
Resolve all {...} references Leave references in output
Use { value: ... } everywhere Use raw strings in tokens
Convert px to rem Keep px values
Use semanticTokens for responsive values Put responsive values in tokens
Use themes object for multi-theme Hardcode light/dark in tokens
Reference tokens with {path} in textStyles Duplicate values

Tools & Resources

Conclusion

You now have a complete, scalable pipeline:

Figma to JSON Tokens => generate-theme.ts => themeConfig.json (resolved) to Chakra UI v3
Enter fullscreen mode Exit fullscreen mode

This system:

  • Works with any token format
  • Supports responsive, multi-theme, semantic design
  • Is fully automated and type-safe
  • Scales to large design systems
  • Powered by Panda CSS — future-proof and framework-agnostic
  • Zero runtime token resolution

Share your ideas in the comments.

Happy theming!

Kiran 👋 👋

Top comments (0)