Skip to content

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>

Read more about breakpoints in theme-ui

Changing social icon sizes

You can change the size of social icons in the header and footer via the Theme-UI file.

sizes: {
    ...tailwind.sizes,
    maxPageWidth: "1440px", // Sets the max width of elements like the header/footer on really large screens
    maxContentWidth: "60ch", // Sets the container size on larger screens, e.g. tablets and laptops
    iconsFooter: "32px", // Sets the icons size for the footer
    iconsHeader: "20px", // Sets the icons size for the header
  },

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.

// See https://theme-ui.com/ for more info and also https://www.gatsbyjs.com/docs/theme-ui/
// Try changing some of the colors below to see what happens.
import { tailwind, baseColors } from "@theme-ui/preset-tailwind"
import prism from "@theme-ui/prism/presets/oceanic-next"


export default {
  initialColorModeName: "light",
  useColorSchemeMediaQuery: true,
  ...tailwind,
  breakpoints: ["480px", "768px", "1024px", "1440px"],
  fonts: {
    ...tailwind.fonts,
    body:
      'system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"Noto Sans",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji"',
    heading: "inherit",
    monospace:
      'Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace',
  },
  colors: {
    ...tailwind.colors,
    background: baseColors.gray[1], //Try "#954264",
    text: baseColors.gray[8],
    textGray: "#6e6e6e",
    primary: baseColors.blue[7],
    secondary: baseColors.orange[7],
    accent: baseColors.orange[2],
    highlight: baseColors.orange[5],
    muted: baseColors.gray[2],
    header: {
      background: baseColors.gray[2],
      backgroundOpen: baseColors.blue[2],
      text: baseColors.gray[8],
      textOpen: baseColors.gray[8],
      icons: baseColors.gray[6],
      iconsOpen: baseColors.gray[8],
    },
    footer: {
      background: baseColors.gray[2],
      text: baseColors.gray[8],
      links: baseColors.gray[8],
      icons: baseColors.gray[8],
    },
  },
  sizes: {
    ...tailwind.sizes,
    maxPageWidth: "1440px", // Sets the max width of elements like the header/footer large screens
    maxContentWidth: "60ch", // Sets the container size on larger screens, e.g. tablets and laptops
    iconsFooter: "32px", // Sets the icons size for the footer
    iconsHeader: "20px", // Sets the icons size for the header
  },
  styles: {
    ...tailwind.styles,
    root: {
      backgroundColor: "background",
      color: "text",
      fontFamily: "body",
      fontWeight: "body",
      lineHeight: "body",
      fontSize: 2,
    },
    a: {
      color: "primary",
      textDecoration: "none",
      ":hover": {
        textDecoration: "underline",
      },
    },
    h1: {
      fontFamily: "heading",
      fontWeight: "heading",
      lineHeight: "heading",
      m: 0,
      mb: 1,
      fontSize: 6,
      mt: 4,
    },
    h2: {
      fontFamily: "heading",
      fontWeight: "heading",
      lineHeight: "heading",
      m: 0,
      mb: 1,
      fontSize: 5,
      mt: 4,
    },
    h3: {
      fontFamily: "heading",
      fontWeight: "heading",
      lineHeight: "heading",
      m: 0,
      mb: 1,
      fontSize: 4,
      mt: 3,
    },
    h4: {
      fontFamily: "heading",
      fontWeight: "heading",
      lineHeight: "heading",
      m: 0,
      mb: 1,
      fontSize: 3,
    },
    h5: {
      fontFamily: "heading",
      fontWeight: "heading",
      lineHeight: "heading",
      m: 0,
      mb: 1,
      fontSize: 2,
    },
    h6: {
      fontFamily: "heading",
      fontWeight: "heading",
      lineHeight: "heading",
      m: 0,
      mb: 2,
      fontSize: 1,
    },
    blockquote: {
      bg: "muted",
      p: 3,
      my: 3,
      mx: [1, 2, 4, null, null],
      borderLeft: "5px solid",
      borderColor: "primary",
    },
    inlineCode: {
      color: "text",
      bg: "muted",
      fontSize: 1,
      p: 1,
    },
    pre: {
      ...prism,
      fontSize: 1,
      p: 3,
      overflowX: "scroll",
    },
    table: {
      width: "100%",
      my: 3,
      borderCollapse: "collapse",
    },
    th: {
      verticalAlign: "bottom",
      borderWidth: "2px",
      borderStyle: "solid",
      borderColor: "muted",
      backgroundColor: "muted",
      padding: 2,
      textAlign: "inherit",
    },
    td: {
      borderWidth: "2px",
      borderStyle: "solid",
      borderColor: "muted",
      verticalAlign: "top",
      padding: 2,
    },
  },
  variants: {},
}

© 2021 Gatsby Theme Catalyst