Logo

Migration Guide: from Chakra-based Blok to Tailwind + shadcn Blok

This guide provides a comprehensive, end‑to‑end explanation of how to migrate from the legacy Chakra‑based Blok Design System to the new Tailwind CSS + shadcn/ui–based Blok. Because the underlying technologies, patterns, and component architecture have fundamentally changed, this document outlines everything teams need to understand before and during migration.

This page is meant to serve as the authoritative migration reference for Sitecore teams, partners, and external developers.

Understanding the technology shift

Why the migration matters

The new Blok introduces major foundational changes:

  • Chakra UI → shadcn/ui (source‑owned components instead of library abstraction)
  • Style props → Tailwind utility classes
  • Old theming system → CSS variables + Tailwind tokens
  • Package-based components → registry-based component sourcing

These changes impact how components are written, extended, themed, tested, and maintained.

Migration areas you must address

A successful migration requires work in several areas:

Components

  • Chakra components must be replaced with their Blok (shadcn-based) equivalents.
  • Custom Chakra components often require full rewrites.
  • Interaction patterns may need adjustments due to differences in event handling and accessibility primitives.

Styling & layout

  • All Chakra props must be translated into Tailwind classes.
  • Layout primitives (Stack, Flex, Grid) require structural changes.
  • Global spacing, border radius, typography, and color decisions must be re‑evaluated.

Theming

  • Chakra’s theme configuration does NOT map 1:1 to Tailwind.
  • Theming must be recreated using Tailwind tokens and CSS variables.
  • Any custom theme tokens must be reviewed and re‑implemented.

Design tokens

  • Chakra token names differ from Blok’s token architecture.
  • Teams must align tokens with Blok’s official scales.

Component distribution

  • Instead of importing packages, components are installed from Blok’s registry.
  • Teams must adjust to owning their component source code.

Accessibility

  • Shadcn/ui provides primitives closer to native behavior.
  • Teams must validate focus states, keyboard flows, and ARIA rules.

Coexistence strategy (if needed)

Chakra and Tailwind can temporarily coexist but cause complexity:

  • Conflicting resets
  • Duplicated components
  • Mixed styling patterns

Full migration is recommended.

Recommended migration path

1. Component inventory

Identify:

  • All Chakra components used
  • Custom Chakra components
  • Theme extensions
  • Design system overrides

2. Map to Blok equivalents

Use Blok docs to find:

  • Matching components
  • Gaps requiring new component creation

3. Introduce Tailwind

  • Add Tailwind config and Blok base styles
  • Install required components via the registry

4. Rebuild components & screens

Rebuild feature by feature:

  • Replace Chakra components
  • Rewrite custom components using shadcn patterns
  • Apply Tailwind classes

5. Recreate theme & tokens

  • Convert Chakra theme tokens into Tailwind equivalents
  • Remove Chakra-specific theme logic

6. Validate & test thoroughly

  • Accessibility
  • Responsive behavior
  • Component interactions
  • Visual consistency

Best practices for teams

  • Do not try to recreate the Chakra look and feel.
  • Follow Blok’s updated design language and spacing system.
  • Align everything with official tokens.
  • Use the registry for consistent component sourcing.
  • Document internal patterns (e.g., modifiers, variants).

FAQ (initial version)

Future additions

This page will evolve with:

  • Deeper migration examples
  • Team-specific migration playbooks
  • Troubleshooting guides