Extending Chakra UI Theme for Consistent Brand Tokens

Problem: Inconsistent brand values across components

When a design system grows, hard-coding hex values in style props or CSS classes leads to drift. One button might use #0066ff while another uses a slightly different shade, making visual updates tedious and error‑prone.

Solution: Extend the Chakra theme with extendTheme

Chakra UI’s extendTheme function lets you add or override design tokens (colors, spacing, radii, etc.) while keeping the library’s defaults. The resulting object is passed to ChakraProvider, making every token available through style props or the useStyleConfig hook.

Worked example: Adding a brand color and spacing scale

// src/theme.ts
import { extendTheme } from '@chakra-ui/react';

export const theme = extendTheme({
  colors: {
    brand: {
      50: '#eff6ff',
      100: '#dbeafe',
      200: '#bfdbfe',
      300: '#93c5fd',
      400: '#60a5fa',
      500: '#3b82f6',
      600: '#2563eb',
      700: '#1d4ed8',
      800: '#1e40af',
      900: '#1e3a8a',
      950: '#172554',
    },
  },
  spacing: {
    xs: '0.5rem',
    sm: '0.75rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem',
  },
});

Next, make the theme available to the whole app:

import { ChakraProvider } from '@chakra-ui/react';
import { theme } from './theme';
import App from './App';

function Root() {
  return (
    
      
    
  );
}
export default Root;

Now any component can reference the new token:

import { Box, Text } from '@chakra-ui/react';

export function Card() {
  return (
    
      Hello, world!
    
  );
}

Verification and TypeScript safety

After saving the files, run your dev server (e.g., npm run dev) and inspect a rendered Box with the browser’s developer tools. The computed background-color should match #3b82f6 (the value of brand.500).

With TypeScript enabled, attempting to use a non‑existent token such as bg='brand.999' will trigger a compile‑time error, showing that the theme augmentation provides autocomplete and prevents misspelled keys.

Trade‑off and limitation

Extending the theme is additive, but if you override a token that Chakra UI components rely on—like colors.gray—you must verify that the replacement meets WCAG contrast ratios. Otherwise, built‑in components may lose accessibility guarantees. Additionally, changing the theme after the provider has mounted forces a re‑render of ChakraProvider, which can cause a brief flash of unstyled content (FOUC) unless the theme object is memoized or generated statically.

Actionable closing

1. Install Chakra UI and its peer dependencies: npm i @chakra-ui/react @chakra-ui/theme (or yarn equivalent).
2. Create a src/theme.ts file and add your tokens using extendTheme as shown above.
3. Wrap your application with ChakraProvider passing the custom theme.
4. Replace hard‑coded values with token references (e.g., bg='brand.500').
5. Run the app, inspect the rendered output, and verify TypeScript errors for misspelled tokens.
6. If you override existing tokens, run an accessibility audit (e.g., with axe) to confirm contrast compliance.

By centralizing brand tokens in the theme, you gain consistency, type safety, and easier future updates while preserving Chakra UI’s built‑in accessibility and dark‑mode support.