Theme Color Synchronization (WordPress + Tailwind)
This project uses a "Single Source of Truth" architecture. Colors are defined once in theme.json and automatically mapped to Tailwind CSS utility classes.
1. Define the Palette (theme.json)
Add your colors to the settings.color.palette array. This generates the CSS variables and the UI color circles in the WordPress editor.
- Open theme.json in your theme's root directory.
- Locate the settings.color.palette array.
- Add an object for each color with a name (for the UI), a slug (for the variable name), and the color (hex code).
"palette": [
{
"name": "Primary",
"slug": "primary",
"color": "#0B1931"
},
{
"name": "Nav", // Label
"slug": "nav", // ID
"color": "#ffffff" // color hex
}
]Step 2: Tailwind Configuration
Update your tailwind.config.js to map your custom names to the WordPress-generated CSS variables. This allows you to use Tailwind classes like text-primary or bg-nav while ensuring they stay in sync with your WordPress settings.
- Open tailwind.config.js.
- Inside the theme.extend.colors object, map your custom names to the WordPress-generated CSS variables.
- The variable pattern is always var(--wp--preset--color--[your-slug])
/** @type {import('tailwindcss').Config} */
module.exports = {
theme: {
extend: {
colors: {
primary: 'var(--wp--preset--color--primary)',
secondary: 'var(--wp--preset--color--secondary)',
accent: 'var(--wp--preset--color--accent)',
text: 'var(--wp--preset--color--text)',
background: 'var(--wp--preset--color--background)',
nav: 'var(--wp--preset--color--nav)', // --[slug]
},
fontFamily: {
sans: 'var(--wp--preset--font-family--sans)',
serif: 'var(--wp--preset--font-family--serif)',
}
},
},
}3. Apply Global Defaults (theme.json)
Use the styles block in your theme.json to apply these colors to specific elements or blocks automatically. Note: This block must be at the root of your JSON, a peer to settings.
"styles": {
"settings": {},
"blocks": {
"core/navigation": {
"color": {
"text": "var(--wp--preset--color--nav)"
}
}
},
"elements": {
"link": {
"color": {
"text": "var(--wp--preset--color--nav)"
},
":hover": {
"color": {
"text": "var(--wp--preset--color--accent)"
}
}
}
}
}