{"record":{"id":"acae61dbf4ac7dc2","repo":"shadcn-ui/ui","slug":"the-base-color-migration-requires-css-variables","errorCode":null,"errorMessage":"The `base-color` migration requires CSS variables. Your `components.json` has `cssVariables: false`, which uses inline Tailwind color classes instead of theme variables.","messagePattern":"The `base-color` migration requires CSS variables\\. Your `components\\.json` has `cssVariables: false`, which uses inline Tailwind color classes instead of theme variables\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/shadcn/src/migrations/migrate-base-color.ts","lineNumber":45,"sourceCode":"  reason: string\n}\n\nexport async function migrateBaseColor(\n  config: Config,\n  options: {\n    from?: string\n    to?: string\n    yes?: boolean\n  } = {}\n) {\n  if (!config.resolvedPaths.tailwindCss) {\n    throw new Error(\n      \"We could not find a valid CSS file in your `components.json` file. Please ensure you have a valid `tailwind.css` path in your `components.json` file.\"\n    )\n  }\n\n  if (!config.tailwind.cssVariables) {\n    throw new Error(\n      \"The `base-color` migration requires CSS variables. Your `components.json` has `cssVariables: false`, which uses inline Tailwind color classes instead of theme variables.\"\n    )\n  }\n\n  const baseColorChoices = BASE_COLORS.map((baseColor) => ({\n    title: baseColor.label,\n    value: baseColor.name,\n  }))\n  const baseColorNames: string[] = BASE_COLORS.map(\n    (baseColor) => baseColor.name\n  )\n\n  // Only the target is validated. The source can be a legacy base color\n  // (e.g. slate) an existing project still uses.\n  if (options.to && !baseColorNames.includes(options.to)) {\n    throw new Error(\n      `Unknown base color: ${options.to}. Available base colors: ${baseColorNames.join(\n        \", \"","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/shadcn-ui/ui/blob/c06da1d0e91e97b607d1359372347528bb35b090/packages/shadcn/src/migrations/migrate-base-color.ts#L27-L63","documentation":"Second guard inside migrateBaseColor. The base-color migration works by swapping theme CSS variables (--background, --primary, ...) between palettes; it cannot operate on projects configured with `tailwind.cssVariables: false`, which use inline Tailwind color classes (bg-neutral-900, text-zinc-500) instead of variables. The guard rejects that configuration up front instead of silently doing nothing.","triggerScenarios":"Running `npx shadcn@latest migrate base-color` on a project whose components.json contains \"cssVariables\": false — typically projects initialized with --no-css-vars or created by older shadcn versions that defaulted to inline classes.","commonSituations":"Legacy shadcn/Tailwind v3 projects that never adopted CSS variables; teams that deliberately chose inline palette classes; copying a components.json from an old project into a new one.","solutions":["Adopt CSS variables first: set \"cssVariables\": true in components.json and convert your components/classes to use theme variables (re-running `shadcn init` with css variables, or updating the theme stylesheet to define :root/.dark vars), then re-run the base-color migration.","If you intend to keep inline color classes, skip this migration entirely — change colors by swapping the Tailwind palette in your Tailwind config/classes manually."],"exampleFix":"// before — components.json\n\"tailwind\": { \"css\": \"~/src/app/globals.css\", \"baseColor\": \"zinc\", \"cssVariables\": false }\n\n// after (after also converting classes/defs to theme variables)\n\"tailwind\": { \"css\": \"~/src/app/globals.css\", \"baseColor\": \"zinc\", \"cssVariables\": true }","handlingStrategy":"validation","validationCode":"// Before running `shadcn migrate base-color`, read components.json and check the flag:\nimport { readFileSync } from 'fs'\n\nconst config = JSON.parse(readFileSync('components.json', 'utf-8'))\nif (config.tailwind?.cssVariables !== true) {\n  console.error(\n    'base-color migration needs cssVariables: true. Convert the project to theme variables first.'\n  )\n  process.exit(1)\n}","typeGuard":"type RawConfig = { tailwind?: { cssVariables?: boolean } }\n\nfunction usesCssVariables(raw: unknown): raw is RawConfig & {\n  tailwind: { cssVariables: true }\n} {\n  return (\n    !!raw &&\n    typeof raw === 'object' &&\n    (raw as RawConfig).tailwind?.cssVariables === true\n  )\n}","tryCatchPattern":null,"preventionTips":["Initialize new projects with CSS variables enabled (the default) so base-color migrations remain available.","Treat `cssVariables: false` as a deliberate lock-out of theme migrations; record it in the project README.","When inheriting an old project, check this flag before attempting any shadcn migration."],"tags":["shadcn","tailwind","config","css-variables","migration"],"backgroundTag":"unsupported-config-value","analyzedSha":"c06da1d0e91e97b607d1359372347528bb35b090","analyzedAt":"2026-08-21T17:08:35.471Z","contentChangedAt":"2026-08-21T17:08:35.471Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}