Mastering theme.json
What is theme.json?
theme.json is the central configuration file for block themes. It defines:
- Global styles
- Block-specific settings
- Color palettes
- Typography presets
- Layout defaults
- Feature toggles
Basic Structure
{
"$schema": "https://schemas.wp.org/wp/6.5/theme.json",
"version": 3,
"settings": {},
"styles": {},
"customTemplates": [],
"templateParts": [],
"patterns": []
}Settings Section
Color Configuration
{
"settings": {
"color": {
"custom": true,
"customGradient": true,
"palette": [
{
"name": "Primary",
"slug": "primary",
"color": "#2563eb"
},
{
"name": "Secondary",
"slug": "secondary",
"color": "#7c3aed"
},
{
"name": "Dark",
"slug": "dark",
"color": "#1e293b"
},
{
"name": "Light",
"slug": "light",
"color": "#f8fafc"
}
],
"gradients": [
{
"name": "Primary to Secondary",
"slug": "primary-secondary",
"gradient": "linear-gradient(135deg, #2563eb 0%, #7c3aed 100%)"
}
]
}
}
}Typography Configuration
{
"settings": {
"typography": {
"fluid": true,
"fontFamilies": [
{
"name": "System",
"slug": "system",
"fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
},
{
"name": "Inter",
"slug": "inter",
"fontFamily": "Inter, sans-serif",
"fontFace": [
{
"fontFamily": "Inter",
"fontWeight": "400",
"fontStyle": "normal",
"src": ["file:./assets/fonts/inter-regular.woff2"]
},
{
"fontFamily": "Inter",
"fontWeight": "700",
"fontStyle": "normal",
"src": ["file:./assets/fonts/inter-bold.woff2"]
}
]
}
],
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "0.875rem",
"fluid": {
"min": "0.875rem",
"max": "1rem"
}
},
{
"name": "Medium",
"slug": "medium",
"size": "1rem"
},
{
"name": "Large",
"slug": "large",
"size": "1.5rem",
"fluid": {
"min": "1.25rem",
"max": "1.75rem"
}
},
{
"name": "X-Large",
"slug": "x-large",
"size": "2.5rem",
"fluid": {
"min": "2rem",
"max": "3rem"
}
}
]
}
}
}Spacing Configuration
{
"settings": {
"spacing": {
"padding": true,
"margin": true,
"blockGap": true,
"units": ["px", "em", "rem", "%", "vw", "vh"],
"spacingScale": {
"operator": "*",
"increment": 1.5,
"steps": 7,
"mediumStep": 1.5,
"unit": "rem"
},
"spacingSizes": [
{"name": "XS", "slug": "10", "size": "0.5rem"},
{"name": "S", "slug": "20", "size": "1rem"},
{"name": "M", "slug": "30", "size": "1.5rem"},
{"name": "L", "slug": "40", "size": "2rem"},
{"name": "XL", "slug": "50", "size": "3rem"}
]
}
}
}Layout Configuration
{
"settings": {
"layout": {
"contentSize": "750px",
"wideSize": "1200px"
}
}
}Styles Section
Global Styles
{
"styles": {
"color": {
"background": "var(--wp--preset--color--light)",
"text": "var(--wp--preset--color--dark)"
},
"typography": {
"fontFamily": "var(--wp--preset--font-family--system)",
"fontSize": "var(--wp--preset--font-size--medium)",
"lineHeight": "1.6"
},
"spacing": {
"padding": {
"left": "var(--wp--preset--spacing--30)",
"right": "var(--wp--preset--spacing--30)"
}
}
}
}Element Styles
{
"styles": {
"elements": {
"h1": {
"typography": {
"fontSize": "var(--wp--preset--font-size--x-large)",
"fontWeight": "700",
"lineHeight": "1.2"
}
},
"link": {
"color": {
"text": "var(--wp--preset--color--primary)"
},
":hover": {
"color": {
"text": "var(--wp--preset--color--secondary)"
}
}
},
"button": {
"color": {
"background": "var(--wp--preset--color--primary)",
"text": "#ffffff"
},
"border": {
"radius": "4px"
}
}
}
}
}Block-Specific Styles
{
"styles": {
"blocks": {
"core/paragraph": {
"spacing": {
"margin": {
"bottom": "1.5rem"
}
}
},
"core/heading": {
"spacing": {
"margin": {
"top": "2rem",
"bottom": "1rem"
}
}
},
"core/button": {
"border": {
"radius": "8px"
},
"spacing": {
"padding": {
"top": "0.75rem",
"bottom": "0.75rem",
"left": "1.5rem",
"right": "1.5rem"
}
}
}
}
}
}Custom CSS Variable Reference
| CSS Variable Pattern | Example |
|---|---|
| Color | var(--wp--preset--color--primary) |
| Font Size | var(--wp--preset--font-size--large) |
| Font Family | var(--wp--preset--font-family--inter) |
| Spacing | var(--wp--preset--spacing--30) |
| Gradient | var(--wp--preset--gradient--primary-secondary) |
Feature Toggles
{
"settings": {
"appearanceTools": true,
"border": {
"color": true,
"radius": true,
"style": true,
"width": true
},
"color": {
"link": true,
"text": true,
"background": true
},
"custom": {
"lineHeight": true,
"spacing": true
}
}
}
Tip: Use
"appearanceTools": true as a shortcut to enable many common design tools at once: padding, margin, border, color, spacing, and more.
Next Steps
In the next lesson, we'll create block templates.
๐ฏ Lesson Complete! You can now configure comprehensive styling through theme.json.
