Migrating from MUI

cia migrate mui reads a MUI (Material UI, v5+) theme object you already have and writes a starting cia theme.scss with the same real values — one CLI command, not a rewrite from scratch.

What this actually does

This is a token migration, not a component migration. It reads plain values off your createTheme({...}) result — colors, spacing, border radius, font family — and maps them onto cia's own token contract. It never imports @mui/material and never touches your <Button>/<Card>/etc. components — cia has no React component library to translate them to (see the recipes book for cia's actual framework story: copy-and-own patterns, not a component package). Migrating your component markup is a separate, manual step that happens after the theme is in place.

Usage

# writes ./cia-themes/migrated.scss
npx cia migrate mui ./src/theme.ts

# name the output theme
npx cia migrate mui ./src/theme.ts --name acme

# pipe-safe: dump the mapping + confidence report as JSON instead of writing a file
npx cia migrate mui ./src/theme.ts --json | jq '.cia.report'

path is any module — .js, .ts, .mjs, .cjs — that exports a MUI theme: a default export, a named theme export, or the result of createTheme({...}) assigned directly. TypeScript files are loaded via jiti (no separate build step needed).

What gets mapped

Not mapped: shadows[0..24], per-heading typography.h1..h6.fontSize, breakpoints. MUI's 24-elevation shadow system has no natural match against cia's 5 named shadow steps (shadow-sm through shadow-2xl) — forcing an automatic mapping there would be arbitrary, not more correct, so it's surfaced once as an informational note instead. cia's breakpoints are a fixed system scale, not themed per project, so they're not migrated at all.

Hover and active states aren't read from MUI's .dark/.light shades. Once a -default token is set, cia derives its hover/active states automatically via m.states() (color-mix(in oklch, ...)) — the same mechanism the Tailwind and Bootstrap migrators already rely on. Mapping MUI's own shade values on top would create two competing hover mechanisms in one theme.

Example

A MUI theme with a primary color, a border radius, and a font:

// src/theme.ts
export const theme = createTheme({
  palette: {
    primary: { main: "#3A5FCD" },
    error: { main: "#D32F2F" },
  },
  shape: { borderRadius: 6 },
  typography: { fontFamily: '"Inter", system-ui, sans-serif' },
});

npx cia migrate mui ./src/theme.ts writes:

// migrated theme — generated by `cia migrate mui`
// Mapping confidence — HIGH: 3 · MEDIUM: 0 · LOW: 0 · UNMAPPED: 1

@use 'css-is-awesome/scss/mixins' as m;

@include m.theme('migrated') {
  --action-primary-default: #3A5FCD;
  --error-default: #D32F2F;
  --radius-md: 0.375rem;
  --font-sans: "Inter", system-ui, sans-serif;

  @include m.states(action-primary);
  @include m.states(error);
}

Next steps

1. Review the file — MEDIUM/LOW/UNMAPPED entries are flagged inline, and a fresh migration will always be a partial theme: it only has the tokens your MUI config actually defined. The rest of cia's 127 required tokens need filling in — see Authoring a theme for the full contract and the validator loop.
2. @use the file from your app's SCSS entry, set <html data-theme="migrated">, and run your build.
3. Run npm run validate-themes (or node scripts/theme-validator.js <your-file> on its own) to confirm WCAG 2.2 AA contrast once the required tokens are filled in.
4. Migrate component markup separately, on your own timeline — see the recipes book for the patterns cia documents (dialog, combobox, data-table, forms, and more), each with real framework examples to adapt.

Further reading

• /docs/authoring/themes — the full token contract and the validator loop.
• /docs/migration-chakra — the same tool, for Chakra UI.
• /docs/migration-tailwind, /docs/migration-bootstrap — the two other cia migrate tools.