WordPress Global Styles Reference Tables

Avatar of Ganesh Dahal
Ganesh Dahal on (Updated on )

We’ve covered a lot of ground in this series. So much so that I thought it would be helpful to condense all the various block theme settings and styles from theme.json into a single page right here.

UGURUS by DigitalOcean for agency owners

UGURUS offers elite coaching and mentorship for agency owners looking to grow. Start with the free Agency Accelerator today.

The following information is based on the WordPress documentation for ease of reference only. At the time of writing, Global Styles (theme.json) and user interface customizations are being actively developed. And, of course, all of this is still very much in active development. If you notice something has changed or is incorrect, please let me know in the comments!

Table of contents


Settings

{
  "version": 2,
  "settings": {
    "border": {},
    "color": {},
    "typography": {},
    "layout": {},
    "spacing": {},
    "outline": {},
    "appearanceTools": true | false,
    "useRootPaddingAwareAlignments": true | false
}

We’ll start with the settings configurations, where we have broken this out into multiple tables for Typography, Colors, Custom, and Spacing.

Remember, these “top-level” styles are applied on the <body> element. And it might be helpful to recall the syntax we’re dealing with:

  • CSS Custom properties: --wp--preset--{preset-category}--{preset-slug}
  • CSS classes: .has-{preset-slug}-{preset-category}

Border

The border section enables border controls in the editor UI.

{
  "version": 2,
  "settings": {
    "border": {
      "color": true,
      "radius": true,
      "style": true,
      "width": true
  }
}
JSON PropertyWhat it DoesCSS Equivalent
settings.border.colorEnables the border color control.border-color
settings.border.radiusEnables the border radius control.border-radius
settings.border.styleEnables the border style control.border-style
settings.border.widthEnables the border width control.border-width

Color

The color section sets the theme’s color palettes, gradients, and duotone effects.

{
  "version": 2,
  "settings": {
      "color": {
        "palette": {
          "slug": "",
          "color": "",
          "name": "",
        },
        "gradients": [
          {
            "slug": "",
            "gradient": "",
            "name": ""
          }
        ],
        "duotone": {
          "slug": "",
          "color": "",
          "name": "",
        }
        "link": true | false
      }
    }
  }
}
JSON PropertyWhat it DoesCSS Custom Properties
settings.color.pallete.colorDefines color values for use throughout the theme.--wp–preset--color--{slug}
settings.color.gradients.colorDefines gradient patterns for use throughout the theme.--wp–preset--gradient--{slug}
settings.color.duotoneDefines duotone effects for use throughout the site.–-wp–preset--duotone--{slug}
settings.color.linkEnables the setting to change the theme’s default link color in the Site Editor.–-wp–preset-–color-–link

Typography

{
  "version": 2,
  "settings": {
    "styles": {
      "typography": {
        "dropCap": true | false,
        "customFontSize": true | false,
        "fluid": "<undefined>" | false,
        "fontSizes": [
          {
            "fluid": {
              "min": "",
              "max": ""
            },
           "slug": "",
           "size": "",
           "name": ""
         },
       ],
      "fontFamilies": [
        {
          "fontFamily": "",
          "name": "",
          "slug": "",
          "fontFace": ""
        },
      ],
      "lineHeight": true | false,
      "fontStyle": true | false,
      "letterSpacing": true | false,
      "textDecoration": true | false,
      "textTransform": true | false,
    }
  }
}
JSON PropertiesWhat it DoesCSS Custom Property
settings.typography.fontSizesDefines font size throughout the site.--wp--preset--font-size--{slug}
settings.typography.fontFamiliesDefines typographic font use throughout the site.--wp--preset--font-family--{slug}
settings.typography.lineHeightDefines line height to use throughout the site.--wp--preset--line-height--{slug}
settings.typography.fontStyleDefines font style to use throughout the site.--wp--preset--line-height--{slug}
settings.typography.fontWeightDefines font weight for use throughout the site.--wp--preset--font-weight--{slug}
settings.typography.letterSpacingDefines letter spacing for use throughout the site.--wp--preset--letter-spacing--{slug}
settings.typography.textDecorationDefines text decoration for use throughout the site.–wp-preset–text-decoration–{slug}
settings.typography.textDecoration.lineDefines link text decoration line for use throughout the site.--wp-preset--text-decoration--line
settings.typography.textDecoration.styleDefines link text decoration line style for use throughout the site.--wp-preset--text-decoration--style--{slug}
settings.typography.textDecoration.colorDefines link text decoration color for use throughout the site.--wp–preset--text-decoration--color--{slug}
settings.typography.textDecoration.thicknessDefines link text decoration line thickness for use throughout the site.--wp–preset--text-decoration--thickness--{slug}
settings.typography.textTransformDefines text transformation type (uppercase, lowercase) for use throughout the site.--wp--preset--text-transform--{slug}

Spacing

These settings enable/disable spacing controls for margin and padding in the Site Editor and allow you to set which CSS units to support.

"styles": {
  "spacing":{
    "padding": true,
    "margin": true,
    "units": [ "px", "em", "rem", "vh", "vw", "%" ]
  }
}

The Site and Block Editors include slider form inputs that allow you to set spacing on a scale of predefined values. We can customize that scale with the spacingScale property:

{
  "version": 2,
  "settings": {
    "spacing": {
      "spacingScale": {
        "operator": "+",
        "increment": <number>,
        "steps": <number>,
        "mediumStep": <number>,
        "unit": ""
      }
    }
  }
}
JSON PropertyWhat it DoesExample
settings.spacing.operatorDetermines whether the control scales up or down.+
settings.spacing.incrementDetermines much the spacing changes per step.0.25
settings.spacing.stepsDetermines the number of available steps on the scale.6
settings.spacing.mediumStepSets the midpoint of the range scale.1.5
settings.spacing.unitSets the CSS length unit of the numeric value.rem

One more thing we can do with spacing is create CSS custom properties that can be used throughout the theme:

{
  "version": 2,
  "settings": {
    "spacing": {
      "spacingSizes": [
        {
          "size": "",
          "slug": "",
          "name": ""
        }
      ]
    }
  }
}
JSON PropertyWhat it DoesExample
settings.spacing.spacingSizes.sizeSets the custom size value, including unit.3.5rem
settings.spacing.spacingSizes.slugThe slug used in the CSS custom property name.medium
settings.spacing.spacingSizes.nameProvides the label for the size in the Site and Block Editor UI.Medium

The resulting CSS custom property syntax is: --wp-preset--spacing--<slug>

Layout

{
  "version": 2,
  "settings": {
    "layout": {
      "contentSize": "",
      "wideSize": "",
      "type": "",
    }
  }
}
JSON PropertyWhat it DoesGenerated CSS Property
settings.layout.contentSizeSets the maximum width of the default content container for pages and posts.--wp--style--global--content-size
settings.layout.contentWideSets the maximum width of the“wide” content container for pages and posts.--wp--style--global--wide-size
settings.layout.typeDetermines is the container is default or constrained.

Appearance tools

{
  "version": 2,
  "settings": {
    "appearanceTools": true | false,
}

Setting this to true is a shorthand for enabling the following settings:

{
  "version": 2,
  "settings": {
    "border": {
      "color": true,
      "radius": true,
      "style": true,
      "width": true
    },
    "color": {
      "link": true
    }
    "spacing": {
      "margin": true,
      "padding": true,
      "blockGap": true,
    },
    "typography": {
      "lineHeight": true
    }
  }
}

Root padding-aware alignments

{
  "version": 2,
  "settings": {
    "useRootPaddingAwareAlignments": true | false
}

Setting this to true is a shorthand for enabling the following settings:

{
  "version": 2,
  "settings": {
    "spacing": {
      "margin": true,
      "padding": true
    },
  }
}

Styles

The idea here is that styles are organized by top-level styles (those that set styles on the <body>), global styles (those that set styles on global elements, like headings), and block styles (those that set styles on specific blocks).

{
  "version": 2,
  "styles": {
    // Top-level styles
    // etc.

    // Global-level styles
    "elements": { },

    // Block-level styles
    "blocks": {  }
  }
}

Top-level styles

{
  "version": 2,
  "styles": {
    // Top-level styles
    "border": [],
    "color": [],
    "spacing": [],
    "typography": [],
    "filter": "",
    "shadow": "",
    "outline": []
  }
}
PropertyStyleCSS equivalentAdditional props
bordercolorborder-color
radiusborder-radius
styleborder-style
widthborder-width
topborder-topcolorstylewidth
rightborder-rightcolorstylewidth
bottomborder-bottomcolorstylewidth
leftbottom-leftcolorstylewidth
colorbackgroundbackground-color
gradientbackground-image
textcolor
spacingblockGapgap (in Flexbox and Grid containers)
marginmarginbottomleftrighttop
paddingpaddingbottomleftrighttop
typographyfontFamilyfont-family
fontSizefont-size
fontStylefont-style
fontWeightfont-weight
letterSpacingletter-spacing
lineHeightline-height
textDecorationtext-decoration
textTransformtext-transform
filterduotonefilter
shadowbox-shadow
outlinecoloroutline-color
offsetoutline-offset
styleoutline-style
widthoutline-width

Global styles

{
  "version": 2,
  "styles": {
    "elements": {
      "buttons": {
        "border": {
          "radius": ""
          },
          "color": {
            "background": "",
            "text": ""
          }, 
          "heading": {},  
          "h1": { },
          "h2": { },
          "h3": { },
          "h4": { },
          "h5": { },
          "h6": { },              
          "link": {
            "border": { },
            "color": { },
            "spacing": { },
            "typography": { }
            }
          }
        }
    }
  }
}
JSON PropertyWhat It DoesWhere It Is Used
styles.elements.buttonsDefines button element properties (e.g., bordercolor, etc.) for use throughout the site.Buttons
styles.elements.headingDefines styles of all the headings, the (<h1> to <h6>) elements for use throughout the site.<h1> to <h6> (all)
styles.elements.h1 to styles.elements.h6Individually defines styles for <h1> to <h6> elements of the heading block for use throughout the site.<h1> to <h6> (individually)
styles.elements.linkDefines link <a> element style for use throughout the site.<a>
styles.elements.citeDefines styles for the blockquote.citequote.cite classes for use throughout the site.Quote, Pullquote
styles.elements.captionDefines styles for <figcaption> and <caption> elements for Image and Table blocks, respectively, for use throughout the site.Figure, Table
styles.elements.spacing.paddingSets the padding of headings, row, blocks and paragraph blocks for use throughout the site.Headings, row, blocks, paragraph
styles.elements.typographySets the default typography style for headings and paragraph blocks for use throughout the site.headings, paragraph

Global-level styles: interactive elements

{
  "version": 2,
    "styles": {
      "elements": {
        "button": {
          "color": {
            "background": " ",
            "text": " "
          }
          ":hover": {
            "color": {
              "background": " ",
              "text": " "
            }
          },
          ":focus": {
            "color": {
              "background": " ",
              "text": " "
            }
          },
          ":active": {
            "color": {
              "background": " ",
              "text": " "
          }
        },
        ":visited": {
          "color": {
            "background": " ",
            "text": " "
          }
        }
      }
    }
  }
}

Note: We can use any already predefined JSON properties in settings presets like typography, outline, shadow, etc., to add styling to any global JSON elements.

JSON PropertyStyleWhat It DoesCSS Equivalent
styles.elements.colorBackgroundDefines link background color for use entire site.a:link { background-color }
TextDefines link text color for use entire site.a:link { color }
styles.elements.:hoverBackgroundDefines hover state link background color for use entire site.a:hover { background-color }
TextDefines hover state link text color for use entire site.a:hover { color }
styles.elements.:focusBackgroundDefines focus state link background color for use entire site.a:focus { background-color }
TextDefines focus state link text color for use entire site.a:focus { color }
styles.elements.:activeBackgroundDefines active state link background color for use entire site.a:active { background-color }
TextDefines active state link text color for use entire site.a:active { color }
styles.elements.:visitedBackgroundDefines visited state link background color for use entire site.a:visited { background-color }
TextDefines visited state link text color for use entire site.a:visited { color }

Custom

This table shows examples of custom properties you could make using the Custom section of the theme.json file. The CSS custom properties generated by the Custom section use the following syntax: --wp--custom--<variable-name>

JSON PropertySyntaxGenerated Custom Property
settings.custom.spacing.padding--wp--custom--{padding}--wp--custom--padding
settings.custom.typography--wp--custom--{typography}--wp--custom--typography
settings.custom.fontWeight--wp--custom--{font-weight}--wp--custom--front-weight
settings.custom.lineHeight--wp--custom--{line-height}--wp--custom--line-height
settings.custom.someColor--wp--custom--{some-color}--wp--custom--some-color
settings.custom.someParagraph--wp--custom--{some-paragraph}--wp--custom--some-paragraph

Block-level styles

All the global-level styles including the elements may be used to customize the CSS for individual blocks to overwrite the global customization. Block-level styles have precedence over top-level styles (global).

{
  "version": 2,
  "styles": {
    // Top-level styles
    // etc.

    // Global-level styles
    "elements": { },

    // Block-level styles
    "blocks": {
      "core/<BLOCKNAME>": {
        // Define or overwrite any global styles
        "typography": {
          "fontSize": " ",
          "fontWeight": "",
          "lineHeight": "",
          "letterSpacing": "",
          "textDecoration": "",
          "textTransform": "" 
        },
        // Define or overwrite any global elements styles
        "elements": {
          "link": {
            "typography": {
              "textDecoration": ""
            },
            "color": {
              "text": " ",
              "background-color": ""
            },
            ":hover": {
              "typography": {
                "textDecoration": ""
              },
              "color": {
                "text": "",
                "background-color": ""
              },
            },
            ":focus": {
              "typography": {
                "textDecoration": ""
              },
              "color": {
                "text": " ",
                "background-color": ""
              },
            },
            ":active": {
              "typography": {
                "textDecoration": ""
              },
              "color": {
                "text": " ",
                "background-color": ""
              },
            },
            ":visited": {
              "typography": {
                "textDecoration": ""
              },
              "color": {
                "text": "",
                  "background-color": ""
              },
            },
          },
        },     
      },
      // Additional blocks
      "core/<BLOCKNAME>": {
        "typography": { },
        // etc.
      }
    }
  }
}
JSON PropertyStyleWhat It Does
.styles.core.<BLOCKNAME>.typographyfont-sizeDefines or overwrites the global font size of this block only.
font-weightDefines or overwrites the global font weight of this block only.
line-heightDefines or overwrites he global font height of this block only.
letter-spacingDefines or overwrites he global letter spacing of this block only.
text-decorationDefines or overwrites he global text decoration of this block only.
text-transformDefines or overwrites the global text transformation of this block only.
.styles.core.<BLOCKNAME>.elements.link.typographytext-decorationDefines or overwrites the global link typography of this block only.
.styles.core.<BLOCKNAME>.elements.link.color`background-colorDefines or overwrites the global link background color of this block only.
colorDefines or overwrites the global link text color of this block only.
.styles.core.<BLOCKNAME>.elements.link.:hover.typographytext-decorationDefines or overwrites the global text decoration of hover link state of this block only.
.styles.core.<BLOCKNAME>.elements.link.:hover.colorbackground-colorDefines or overwrites the global background color of hover link state of this block only.
colorDefines or overwrites the global background color of hover link state of this block only.
.styles.core.<BLOCKNAME>.elements.link.:active.typographytext-decorationDefines or overwrites the global text decoration of active link state of this block only.
.styles.core.<BLOCKNAME>.elements.link.:active.colorbackground-colorDefines or overwrites the global background color of active link state of this block only.
colorDefines or overwrites the global background color of active link state of this block only.
.styles.core.<BLOCKNAME>.elements.link.:focus.typographytext-decorationDefines or overwrites the global text decoration of focus link state of this block only.
.styles.core.<BLOCKNAME>.elements.link.:focus.colorbackground-colorDefines or overwrites the global background color of focus link state of this block only.
colorDefines or overwrites the global background color of focus link state of this block only.
.styles.core.<BLOCKNAME>.elements.link.:visited.typographytext-decorationDefines or overwrites the global text decoration of visited link state of this block only.
.styles.core.<BLOCKNAME>.elements.link.:visited.colorbackground-colorDefines or overwrites the global background color of visited link state of this block only.
colorDefines or overwrites the global background color of visited link state of this block only.

For use case examples of block-level CSS customization, you may refer to the latest Twenty Twenty-Three theme and other recent block themes in the theme directory.

Wrapping up

You made it through this compelete guide to WordPress block theme CSS and settings! We started with a brief introduction that compares WordPress block themes to the “classic” PHP templating system. From there, we talked a bit about JSON because, funny enough, that’s how we “write” CSS in WordPress block themes.

Then there’s theme.json the actual file where all of those styles are defined, much like style.css was for classic PHP themes. The file is tightly structured into sections for toggling WordPress settings and defining CSS globally throughout a block theme.

And once we’re done defining a block theme’s settings and styles, the WordPress Style Engine takes over, processing our JSON into a nicely organized set of CSS styles used in the theme.

It’s crazy just how different block themes are when it comes to defining and managing styles in WordPress! All of this is still in active development, and we are likely to see new features and options added to theme.json.

See something that’s new or has changed? Please let me know in the comments!