Theme UI

Theme UI based design tokens are used throughout the Catalyst series of themes and starters as this is the suggested best practice when building Gatsby themes. The theme is based on the tailwind presets as this provides a good base set of standard spacings, sizings, etc. You will also see a reference to colors like baseColors.pink[5] in the theme file, these basecolors can be found on the TailwindCSS docs.

The file you should modify to set design tokens is always located in the following location:

.
├── src
  ├── gatsby-plugin-theme-ui
    ├── index.js

Colors

By default these themes support a dark and light mode. This can be disabled by setting useColorMode to false in theme options for gatsby-theme-catalyst-core and removing the color.modes object inside the Theme-UI config.

Try copying and pasting the following code into your theme file and see what happens:

import { merge } from "theme-ui"
import { BaseTheme } from "gatsby-theme-catalyst-core"

export default merge(BaseTheme, {
  // Modifications to the base theme go here. This is an example changing colors and using variants to change your navigation links. Uncomment the code below to see what happens.
  colors: {
    background: "pink",
    modes: {
      dark: {
        background: "purple",
      },
    },
  },
})

Typography and changing fonts

To add a custom font you need to first add the font as a dependency in your starter site, for example:

yarn add typeface-raleway

Then at the top of src/gatsby-plugin-theme-ui/index.js file you will need to import the font and declare it, like this for Raleway:

import { tailwind } from "@theme-ui/preset-tailwind"
import "typeface-raleway"

export default {
  ...tailwind,
  fonts: {
    ...tailwind.fonts,
    body: '"Raleway", sans-serif',
  },
}

Breakpoints

Breakpoints are set using Theme UI theme file and default to 480px, 768px, 1024px, and 1440px. The mobile menu is enabled at the 2nd breakpoint, 768px, but you can change this by changing the second breakpoint.

breakpoints: ["480px", "768px", "1024px", "1440px"],

The array notation is used to target different screen sizes based on the breakpoints set in the theme file. You can use null, to inherit the previous value.

<h1
  sx={{
    // 0-479px: Red
    // 480px - 767px: Blue
    // 768px - 1023px: Yellow
    // 1024px - 1439px: Yellow
    // 1440px and up: Pink
    color: ["red", "blue", "yellow", null, "pink"],
  }}
>
  Breakpoints
</h1>

Variants

Variants are a feature of Theme UI that allow for easier customization of visual style through the use of predefined variants that can be customized in the theme specification file. Most major areas of the catalyst themes are preconfigured to use variants. This lets you change css styles without having to shadow a whole component.

The following is a list of variants available to use with layout themes. Other themes may have additional variants documented in their respective docs.

variants.siteContainer: Targets the container for the entire site content
variants.contentContainer: Targets the container for the content, useful for changing site margins/content size
variants.main: Targets the main component in the site, useful for changing spacing between header, footer, and main areas
variants.header: Targets the header component
variants.branding: Targets the branding container div which contains the logo and site title
variants.siteLogo: Targets the logo component
variants.siteTitle: Targets the root site title component, useful to change font size of the site title.
variants.nav: Targets the main nav element
variants.navUl: Targets the ul element containing the nav menu
variants.navUlSub: Targets the ul element containing the sub menu
variants.navLi: Targets the li element containing nav menu items
variants.navLiSub: Targets the li element containing sub menu items
variants.navLink: Targets the styles for the nav links in the header, useful to change the nav styles
variants.navLinkActive: Targets the styles for the active nav link
variants.navLinkSub: Targets the styles for the submenu links
variants.navLinkSubActive: Targets the styles for the active submenu link
variants.footer: Targets the footer component

Here is an example of changing the size of the site title using variants.

variants: {
    siteTitle: {
      fontSize: [4, null, null, 5, null],
    },
  },

Base theme

The following “base theme” is used through Gatsby Theme Catalyst. It provides a consistent starting point for your themes and is based on the Tailwind defaults. This was changed in gatsby-theme-catalyst-core v2.0.0 to remove the default dark mode as this was making it difficult to modify the starter themes to remove dark mode.