If you’re a developer providing support to a CultivateWP client, then this guide is for you. You should have a basic familiarity with CSS, PHP, and WordPress. While this guide won’t answer all your questions, it should hopefully answer common questions and point you in the right direction.

Add or change color options

We use theme.json to define the brand colors available in the theme. These colors are most often used for buttons and full width background colors on groups.

Towards the top of the theme.json file you’ll find the settings.color.palette section. Each color has a slug, color, and name. Example:

{
	"slug": "foreground",
	"color": "#000000",
	"name": "Foreground"
},
{
	"slug": "background",
	"color": "#ffffff",
	"name": "Background"
},
{
	"slug": "primary",
	"color": "#0000EE",
	"name": "Primary"
},
{
	"slug": "secondary",
	"color": "#00FFFF",
	"name": "Secondary"
},Code language: JSON / JSON with Comments (json)

To add a new color, go to the bottom of the list and add the next one in the series. Ex: if the last color currently is “octonary”, then add “nonary”.

To change a color, find the appropriate one in the list and change the hex code. That’s why we use “primary” and “secondary” instead of “blue” and “green” – so we can change the colors without having to change the variable names, which are used as class names in WordPress.

Layout changes – content width, sidebar width, block gap

All of the layout variables are located in settings.custom.layout in theme.json (example).

  • content = the width of the content area when using the “Content Sidebar” or “Content” layout
  • wide = the width of the content area when using the “Full Width Content” layout (ex: homepage)
  • sidebar = the width of the sidebar
  • padding = the left/right padding on the screen. Note: on small screens we decrease this to 10px (example) to ensure the content area is 300px wide on a 320px wide phone for ads.
  • block-gap = the space between blocks in the content editor
  • block-gap-large = the padding above and below full width sections

Changing font sizes

Our design system has 12 different font sizes in theme.json (example). They scale up proportionally from “min” (12px) to “gargantuan” (44px mobile / 52px desktop).

The fonts are in “rems” for accessibility, so they scale up and down as the user increases / decreases the font size of the root. To convert rems to pixels, multiply by 16. To convert pixels to rems, divide by 16.

  • 20px = 1.25 rems (20 / 16)
  • 1.75rem = 28px (1.75 * 16)

For the larger font sizes, we also use clamp() for responsive font sizes. It contains three parameters – minimum size (ie: mobile), ideal size, and maximum size (ie: desktop). We set the ideal size using vw units so it’s based on the vertical width of the screen. This is handy because you can just divide the desktop font by 10 and it will use the desktop font @ 1000px screen width.

Let’s say we wanted the “large” size to be 18px on mobile and 22px on desktop. We would use clamp( 1.125rem, 2.2vw, 1.375rem)

  • 18px / 16 = 1.125rem for mobile
  • 22px / 10 = 2.2vw for ideal
  • 22px / 16 = 1.375rem for desktop

Changing body font size

The body text uses the “medium” font size (example). If you need to change it by one or two pixels, you can edit the value of the medium font size (example). If you need to change it more significantly, you could change the body text to use the “large” font size instead (here).

Changing heading font sizes

h1-h3 each have unique font sizes, while h4-h6 all use the same. You can edit the heading font size here. If you change one, you may want to change the others to scale them up/down to match. For instance, if you decreased the h2 font size from “huge” to “big”, you should decrease the h3 from “big” to “x-large”, and decrease h4-h6 from “x-large” to “large”.

Go themes

For Go themes, the header & footer logo are defined in theme.json in the settings.custom section. Example:

"footer-logo": {
	"width": "96px",
	"height": "96px",
	"slug": "secondary",
	"format": "svg"
},
"header-logo": {
	"desktop-width": "363px",
	"desktop-height": "40px",
	"desktop-margin": "26px",
	"mobile-width": "218px",
	"mobile-height": "24px",
	"mobile-margin": "18px",
	"slug": "primary",
	"format": "svg"
},Code language: JSON / JSON with Comments (json)

If the format is set to “svg” then it will look for it in /assets/icons/logo. If the format is set to “png” or “jpg” it will look for it in /assets/images.

Place the new logo in the appropriate directory, then update the theme.json with the slug (ie: filename without extension), format (the file extension), width, and height.

The header logo has two sets of widths and heights. The desktop width/height is used when the desktop navigation is visible, while the mobile width/height is used when the mobile menu toggle is visible.

Pro & VIP themes

Our custom designed Pro & VIP themes typically include the site logo in the SASS partials, _site-header.scss and _site-footer.scss. After making changes, you’ll need to compile the SASS to CSS.

We also customize the login logo to use the site logo. Go to /inc/login-logo.php OR /inc/site-icon.php to customize the logo path, width, and height (example).

Editing blocks

We use ACF to build custom blocks. Here’s a detailed tutorial describing how our blocks are built.

  • You can edit the block registration (ex: what block editor features it supports) in /blocks/{block name}/block.json.
  • You can make style edits to a block by editing its stylesheet in /blocks/{block name}/style.css
  • You can edit the markup of the block by editing the render file in /blocks/{block name|/render.php.
  • Some blocks contain additional functionality which can be edited in /blocks/{block name}/init.php.

Here’s a functional example of a block with all four files.

Moving blocks to a non-Cultivate theme

We try our best to make our blocks as atomic and portable as possible to avoid vendor lock-in. If you are building a new theme for a client who is currently using a CultivateWP theme, you’ll want to carry forward the blocks we built so no content is lost on the new site.

  1. Make sure ACF Pro is installed. You or the client will need to purchase your own license once you stop using a CultivateWP theme.
  2. Copy the /blocks/ directory from our theme to your new theme.
  3. Copy our blocks.php file (here) into your theme and require it in functions.php.
  4. You may need to go through the blocks and remove or modify functionality that depends on the CultivateWP theme (ex: cwp_icon() is our helper function for outputting an SVG icon)

Compiling CSS

Our themes contain styles in three locations:

  • Theme.json defines the style guide with colors, font sizes, font families, and layouts.
  • Each custom block has its own CSS file in /blocks/{block-name}/style.css
  • Everything else (ex: site header, core blocks…) is styled with SASS partials in /assets/scss/partials

Theme.json and the block CSS can be edited directly, but edits to the SASS partials will require compiling so they are included in the main.css and editor-styles.css files.

Here’s a guide with more information on the SASS Compile Setup.

Download the theme locally, open Terminal on your computer, and navigate to the theme directory (ex: cd ~/Downloads/mytheme/). Then type npm install to install the SASS package.

You can then make changes to the SASS partials, and type npm run sass-prod to compile the minified CSS.