| name | wp-block-styles |
| description | Style WordPress blocks with theme.json: presets, block-level styles, style variations, and custom CSS. Configure typography, colors, spacing, and layouts. |
| compatibility | WordPress 6.6+ for theme.json v3. Some features require earlier versions. |
WordPress Block Styles & theme.json
When to Use
Use this skill when:
- Configuring theme.json for block styling
- Creating color, typography, and spacing presets
- Adding block style variations
- Customizing specific block appearances
- Setting up global styles
theme.json Fundamentals
Basic Structure
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
},
"styles": {
},
"customTemplates": [],
"templateParts": [],
"patterns": []
}
Version History
| Version | WordPress | Key Features |
|---|
| 1 | 5.8+ | Initial release |
| 2 | 5.9+ | Layout settings, custom presets |
| 3 | 6.6+ | Style variations, enhanced presets |
Settings Section
Layout Settings
{
"settings": {
"layout": {
"contentSize": "840px",
"wideSize": "1200px"
},
"useRootPaddingAwareAlignments": true
}
}
Color Settings
{
"settings": {
"color": {
"custom": true,
"customGradient": true,
"customDuotone": true,
"defaultPalette": false,
"defaultGradients": false,
"defaultDuotone": false,
"palette": [
{
"slug": "primary",
"color": "#0073aa",
"name": "Primary"
},
{
"slug": "secondary"
Typography Settings
{
"settings": {
"typography": {
"fluid": true,
"customFontSize": true,
"dropCap": true,
"fontStyle": true,
"fontWeight": true,
"letterSpacing": true,
"lineHeight": true,
"textDecoration": true,
"textTransform": true,
"writingMode": true,
"fontFamilies": [
Fluid Typography
{
"settings": {
"typography": {
"fluid": true,
"fontSizes": [
{
"slug": "large",
"size": "1.5rem",
"fluid": {
"min": "1.25rem",
"max": "1.75rem"
},
"name": "Large"
}
]
}
}
}
Spacing Settings
{
"settings": {
"spacing": {
"margin": true,
"padding": true,
"blockGap": true,
"units": ["px", "em", "rem", "%", "vw", "vh"],
"spacingScale": {
"operator": "*",
"increment": 1.5,
"steps": 7,
"mediumStep": 1.5,
"unit": "rem"
Border & Shadow Settings
{
"settings": {
"border": {
"color": true,
"radius": true,
"style": true,
"width": true
},
"shadow": {
"presets": [
{
"slug": "sm",
"shadow": "0 1px 2px rgba(0,0,0,0.05)",
"name": "Small"
},
{
"slug": "md",
"shadow": "0 4px 6px rgba(0,0,0,0.1)",
"name"
Dimension Settings
{
"settings": {
"dimensions": {
"minHeight": true,
"aspectRatio": true,
"aspectRatios": [
{
"slug": "square",
"ratio": "1",
"name": "Square"
},
{
"slug": "4-3",
"ratio": "4/3",
"name": "4:3"
},
{
"slug": "16-9",
"ratio": "16/9",
"name"
Styles Section
Global Styles
{
"styles": {
"color": {
"background": "var(--wp--preset--color--white)",
"text": "var(--wp--preset--color--secondary)"
},
"typography": {
"fontFamily": "var(--wp--preset--font-family--system)",
"fontSize": "var(--wp--preset--font-size--medium)",
"lineHeight": "1.6"
},
"spacing": {
"blockGap": "1.5rem",
"padding": {
"top": "0",
"right": "var(--wp--preset--spacing--50)",
"bottom": "0",
"left"
Block-Specific Styles
{
"styles": {
"blocks": {
"core/paragraph": {
"spacing": {
"margin": {
"top": "0",
"bottom": "1.5rem"
}
}
},
"core/heading": {
"spacing": {
"margin": {
"top": "2rem",
"bottom": "1rem"
}
}
},
"core/button": {
"border": {
"radius": "6px"
Block Style Variations
Registering via theme.json (6.6+)
{
"styles": {
"blocks": {
"core/button": {
"variations": {
"outline": {
"color": {
"background": "transparent",
"text": "var(--wp--preset--color--primary)"
},
"border": {
"color": "var(--wp--preset--color--primary)",
"style": "solid",
"width": "2px"
},
":hover": {
"color": {
"background": "var(--wp--preset--color--primary)",
Registering via PHP
function my_register_block_styles() {
register_block_style(
'core/button',
array(
'name' => 'pill',
'label' => __( 'Pill', 'theme-name' ),
'inline_style' => '.wp-block-button.is-style-pill .wp-block-button__link { border-radius: 50px; }',
)
);
register_block_style(
'core/group',
array(
'name' => 'card',
'label' => __( 'Card', 'theme-name' ),
'style_handle' => 'my-theme-block-styles', // External CSS file
)
);
register_block_style(
'core/list',
array(
'name' => 'checkmark',
'label' => __( 'Checkmark', 'theme-name' ),
)
);
}
add_action( 'init', 'my_register_block_styles' );
Style via JSON File (6.6+)
Create styles/block-style-card.json:
{
"version": 3,
"title": "Card",
"slug": "card",
"blockTypes": ["core/group"],
"styles": {
"color": {
"background": "var(--wp--preset--color--white)"
},
"border": {
"radius": "12px"
},
"shadow": "var(--wp--preset--shadow--md)",
"spacing": {
"padding": "var(--wp--preset--spacing--50)"
}
}
}
Global Style Variations
Creating Variations
Place JSON files in /styles/ directory:
styles/dark-mode.json:
{
"version": 3,
"title": "Dark Mode",
"settings": {
"color": {
"palette": [
{
"slug": "primary",
"color": "#60a5fa",
"name": "Primary"
},
{
"slug": "secondary",
"color": "#f1f5f9",
"name": "Secondary"
}
]
}
},
"styles": {
"color": {
"background":
Font Variation
styles/serif.json:
{
"version": 3,
"title": "Serif",
"settings": {
"typography": {
"fontFamilies": [
{
"slug": "heading",
"fontFamily": "'Playfair Display', Georgia, serif",
"name": "Playfair Display"
}
]
}
},
"styles": {
"typography": {
"fontFamily": "var(--wp--preset--font-family--serif)"
}
}
}
CSS Custom Properties
Preset Variables
WordPress generates CSS variables from presets:
--wp--preset--color--primary
--wp--preset--color--secondary
--wp--preset--font-size--small
--wp--preset--font-size--medium
--wp--preset--font-family--system
--wp--preset--spacing--10
--wp--preset--spacing--50
--wp--preset--shadow--sm
--wp--preset--shadow--lg
--wp--preset--gradient--primary-to-secondary
Usage in Styles
{
"styles": {
"blocks": {
"core/group": {
"color": {
"background": "var(--wp--preset--color--light-gray)"
},
"spacing": {
"padding": "var(--wp--preset--spacing--50)"
}
}
}
}
}
Custom CSS Properties
{
"settings": {
"custom": {
"lineHeight": {
"tight": 1.2,
"normal": 1.6,
"loose": 2
},
"contentWidth": "840px",
"sidebarWidth": "300px",
"headerHeight": "80px"
}
}
}
Generated variables:
--wp--custom--line-height--tight: 1.2;
--wp--custom--line-height--normal: 1.6;
--wp--custom--content-width: 840px;
Custom CSS
Global Custom CSS
{
"styles": {
"css": ".site-header { position: sticky; top: 0; z-index: 100; } .wp-block-button:hover { transform: translateY(-2px); transition: transform 0.2s; }"
}
}
Per-Block Custom CSS
{
"styles": {
"blocks": {
"core/button": {
"css": "&:hover { transform: translateY(-2px); } &:active { transform: translateY(0); }"
},
"core/image": {
"css": "& img { transition: transform 0.3s; } &:hover img { transform: scale(1.02); }"
}
}
}
}
Block-Level Settings
Disable Features for Specific Blocks
{
"settings": {
"blocks": {
"core/paragraph": {
"color": {
"custom": false,
"customGradient": false
}
},
"core/heading": {
"typography": {
"customFontSize": false
}
},
"core/group": {
"layout": {
"allowEditing": false
}
}
}
}
}
Custom Presets for Blocks
{
"settings": {
"blocks": {
"core/button": {
"color": {
"palette": [
{
"slug": "button-primary",
"color": "#0073aa",
"name": "Button Primary"
},
{
"slug": "button-secondary",
"color": "#333333",
"name": "Button Secondary"
}
]
}
}
}
}
}
Complete theme.json Example
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"appearanceTools": true,
"useRootPaddingAwareAlignments": true,
"layout": {
"contentSize": "840px",
"wideSize": "1200px"
},
"color": {
"defaultPalette": false,
"defaultGradients": false,
"palette": [
{ "slug": "primary", "color": "#0073aa"
Resources
