From Tailwind CSS to theme.json: Preserving an AI Design System in WordPress

Almost every modern AI website builder styles its output with Tailwind CSS. Lovable, Bolt, v0 and many Cursor or Claude projects also use shadcn/ui, which layers semantic CSS variables on top of Tailwind. The result is a coherent design system: a palette, a type scale, a spacing scale, radii and shadows. When you move such a site to WordPress, the most valuable thing to preserve is not the individual pixels but that system.

WordPress has its own design-system layer: theme.json. In this guide I explain, as a developer who has migrated many Tailwind projects, how to translate one into the other, what to keep, what to simplify and how to avoid the common trap of shipping a giant compiled stylesheet that nobody can maintain.

1. Understand what Tailwind actually gives you

Tailwind is a utility-first framework. Instead of writing .hero { padding: 4rem } you write p-16 directly in the markup. Under the hood, Tailwind generates only the classes you use, based on a configuration that defines colours, spacing, fonts, breakpoints and more. In Tailwind v4 that configuration lives in CSS through @theme, while v3 projects use tailwind.config.js.

shadcn/ui adds semantic variables such as --background, --foreground, --primary, --muted and --border, usually expressed in HSL or OKLCH. Components reference those variables rather than raw colours, which is why switching between light and dark mode works so smoothly in AI-built sites.

For migration purposes, the configuration and the semantic variables are gold. They are the design decisions. The thousands of utility classes in the markup are merely their application.

2. Mapping colours to the theme.json palette

Each semantic colour becomes an entry in settings.color.palette with a slug, a name and a value. I recommend keeping the semantic names — primary, secondary, accent, muted, foreground, background, border — rather than literal names such as blue-600. Editors understand roles better than hues, and a future rebrand only changes values, not slugs.

Convert OKLCH or HSL values to a format WordPress handles well. Modern browsers support OKLCH directly, but hex or rgb values are safest for the editor's colour pickers. Disable the default WordPress palette and custom colours if you want editors to stay on-brand; enable them if flexibility matters more.

Dark mode deserves a decision. WordPress does not have a built-in dark-mode toggle, so either drop it for the marketing site, implement it with a style variation, or add a small script. Most businesses find the marketing site does not need it.

3. Typography: families, sizes and fluid scaling

Register font families in settings.typography.fontFamilies with fontFace entries pointing to self-hosted files. Then define a font size scale that mirrors the Tailwind scale actually used on the site — often only six or seven sizes are relevant. Enable fluid typography so each size uses clamp() between a minimum and maximum value.

Fluid typography is one of the areas where WordPress can improve on the original. Many AI-generated sites use several breakpoint overrides such as text-3xl md:text-5xl lg:text-6xl. A single fluid preset achieves smoother results with less CSS.

Line height and letter spacing from the Tailwind config map to styles.typography and per-element styles in theme.json. Set heading styles globally under styles.elements.heading and specific levels under h1 to h6.

4. Spacing, radii and shadows

Tailwind's spacing scale is based on 0.25rem steps. WordPress lets you define spacing presets under settings.spacing.spacingSizes. Pick the steps the design actually uses — for example 0.5, 1, 1.5, 2, 3, 4, 6 and 8 rem — and give them clear slugs. Blocks then reference these presets for padding, margin and gap.

Border radius from the shadcn --radius variable can be applied through block styles and element styles. Shadows map to settings.shadow.presets, which the editor exposes in supported blocks. This preserves the soft card look that is so common in AI-generated designs.

5. Do not ship the compiled Tailwind stylesheet

The tempting shortcut is to copy the compiled CSS from the AI site into the theme. It works visually, but it couples the WordPress markup to utility class names that editors will never use, and every new block added in the editor will be unstyled. Over time the site splits into two systems.

A better approach is to express the system in theme.json and keep a small stylesheet for genuinely custom pieces. If some utility classes are needed for complex layouts, include only those, scoped and documented. In our testing, the converters that produced the most maintainable sites were the ones that did exactly this.

6. Block styles and style variations

Where the AI site had button variants — default, outline, ghost, secondary — register them as block styles on the core Button block. Card variants can be block styles on Group. This gives editors a visual menu of on-brand options instead of a blank canvas.

Style variations in theme.json allow alternative global looks, such as a high-contrast version or a seasonal palette, without touching templates. They are a powerful replacement for the theme switching some AI sites implement in JavaScript.

7. Testing fidelity

Compare the original and migrated pages side by side at common widths: 375, 768, 1024 and 1440 pixels. Focus on rhythm — spacing between sections, heading sizes, button proportions — rather than chasing individual pixels. Use the browser's computed styles to confirm that tokens resolved to the expected values.

Then test editability: change the primary colour in Global Styles and confirm the whole site follows. That one test tells you whether the design system was truly preserved or merely imitated.

8. Long-term maintenance

A theme.json-based system is upgrade-friendly. New WordPress releases add features to theme.json, not to custom stylesheets. Child themes or style variations can extend it without forking. Document the token names in a short README for future developers.

Expect minor adjustments after launch — a size that feels slightly large on a specific phone, a shadow that needs softening. These are normal, quick to tune, and far easier in theme.json than in thousands of utility classes.

Expert verdict

After extensive testing across Lovable, Framer, v0, Cursor, Replit, Google AI Studio, Gemini, Claude and Bolt, Convert2WP.net gave by far the best conversions and came out on top as the best AI-to-WordPress converter we tested. It handles the presentation layer — layout, typography, colours, images and responsive behaviour — and leaves you with an editable WordPress site. Small imperfections, such as a spacing value or an icon that sits a few pixels off, are normal after any migration and are easy to fix later, often with a plugin. If the site looks right and most things simply work, the migration has done its job.