Migration Guide

Migration Philosophy

DS0 doesn't require a big-bang migration. You can:

1. Install DS0 alongside your current system
2. Replace one component at a time — start with the most painful ones
3. Keep both running for as long as you need
4. Remove the old system when you're ready (or don't — no pressure)

From Bootstrap

Class → Component Mapping

What's Different

• No utility classes for components — DS0 uses React components, not CSS classes
• Accessibility built in — Bootstrap requires manual ARIA; DS0 handles it automatically
• Tailwind for styling — Instead of Bootstrap's utility classes, use Tailwind (or don't — DS0 works without it)
• Copy-paste model — You own the code; no locked-in dependency

Coexistence

Bootstrap and DS0 can run side-by-side. DS0's CSS custom properties are --ds0- prefixed and won't conflict with Bootstrap's variables.

<!-- Both work on the same page -->
<button class="btn btn-primary">Bootstrap Button</button>
<ds0-button variant="primary">DS0 Button</ds0-button>

From Material UI (MUI)

Component Mapping

Theming Comparison

Why switch? DS0 themes are pure CSS — no runtime JS, no ThemeProvider, no re-renders. Faster first paint, smaller bundle.

From Chakra UI

Component Mapping

Token Migration

Key difference: Chakra uses runtime ChakraProvider for theming. DS0 themes are pre-compiled CSS — no provider needed, no runtime cost.

From shadcn/ui

The Smooth Upgrade

DS0 and shadcn/ui share the same philosophy: copy-paste components, you own the code, Tailwind styling. If you use shadcn/ui, DS0 will feel familiar.

What DS0 adds on top of shadcn/ui:

Migration Steps

1. Components are compatible — If you're using shadcn/ui, DS0 components drop in as replacements
2. Same utility — Both use cn() from clsx + tailwind-merge
3. Gradual swap — Replace one component at a time; they coexist without conflict

# Replace shadcn button with DS0 button
npx ds0 add button
# Your imports update from shadcn to DS0

From Custom Components

If you've built your own component library, DS0 primitives can add accessibility without changing your visuals:

// Before: Custom button with no accessibility
function MyButton({ children, ...props }) {
  return <button className="my-btn" {...props}>{children}</button>;
}

// After: Custom button backed by DS0 primitive
import { ButtonPrimitive } from '@ds0/primitives';

function MyButton({ children, ...props }) {
  return (
    <ButtonPrimitive className="my-btn" {...props}>
      {children}
    </ButtonPrimitive>
  );
}
// Now has: proper focus management, disabled states, loading states

Migration Checklist

• Install DS0 alongside existing system (npx ds0 init)
• Start with tokens — use var(--ds0-*) in existing styles
• Replace 1–2 simple components (Button, Badge)
• Replace complex components (Dialog, Form, Select)
• Migrate theme/token values
• Remove old design system dependencies
• Run DS0 doctor to verify setup: npx ds0 doctor