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
.
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.
<h1sx={{// 0-479px: Red// 480px - 767px: Blue// 768px - 1023px: Yellow// 1024px - 1439px: Yellow// 1440px and up: Pinkcolor: ["red", "blue", "yellow", null, "pink"],}}>Breakpoints</h1>
Read more about breakpoints in theme-ui
Changing logo sizes
A common change you will need to make is to the logo size.
The logo size is managed in the following location: src/gatsby-plugin-theme-ui/index.js
. In many cases the size of your logo will control the size of your navbar/header. There is also an option in the sizes file which can override the auto height inherited from content and specify a fixed height.
Try this in src/gatsby-plugin-theme-ui/index.js
for a big logo:
sizes: {...tailwind.sizes,maxPageWidth: "1440px", // Sets the max width of elements like the header/footer on really large screensmaxContentWidth: "720px", // Sets the container size on larger screens, e.g. tablets and laptopsheaderHeight: "auto", // Provides fallback setting to control header heightlogoWidthXS: "80px", // Logo width on extra small screens, up to 480pxlogoWidthS: "150px", // Logo width on small screens, 480px - 768pxlogoWidthM: "150px", // Logo width on medium screens, 768px - 1024pxlogoWidthL: "260px", // Logo width on large screens, 1024px - 1440pxlogoWidthXL: "260px", // Logo width on extra large screens, above 1440pxlogoHeightXS: "80px", // Logo height on extra small screens, up to 480pxlogoHeightS: "150px", // Logo height on small screens, 480px - 768pxlogoHeightM: "150px", // Logo height on medium screens, 768px - 1024pxlogoHeightL: "260px", // Logo height on large screens, 1024px - 1440pxlogoHeightXL: "260px", // Logo height on extra large screens, above 1440pxiconsFooter: "32px", // Sets the icons size for the footericonsHeader: "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 contentvariants.contentContainer
: Targets the container for the content, useful for changing site margins/content sizevariants.main
: Targets the main component in the site, useful for changing spacing between header, footer, and main areasvariants.header
: Targets the header componentvariants.branding
: Targets the branding container div which contains the logo and site titlevariants.siteLogo
: Targets the logo componentvariants.siteTitle
: Targets the root site title component, useful to change font size of the site title.variants.nav
: Targets the main nav elementvariants.navUl
: Targets the ul element containing the nav menuvariants.navUlSub
: Targets the ul element containing the sub menuvariants.navLi
: Targets the li element containing nav menu itemsvariants.navLiSub
: Targets the li element containing sub menu itemsvariants.navLink
: Targets the styles for the nav links in the header, useful to change the nav stylesvariants.navLinkActive
: Targets the styles for the active nav linkvariants.navLinkSub
: Targets the styles for the submenu linksvariants.navLinkSubActive
: Targets the styles for the active submenu linkvariants.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.org/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 screensmaxContentWidth: "720px", // Sets the container size on larger screens, e.g. tablets and laptopsheaderHeight: "auto", // Provides fallback setting to control header heightlogoWidthXS: "40px", // Logo width on extra small screens, up to 480pxlogoWidthS: "50px", // Logo width on small screens, 480px - 768pxlogoWidthM: "50px", // Logo width on medium screens, 768px - 1024pxlogoWidthL: "60px", // Logo width on large screens, 1024px - 1440pxlogoWidthXL: "60px", // Logo width on extra large screens, above 1440pxlogoHeightXS: "40px", // Logo height on extra small screens, up to 480pxlogoHeightS: "50px", // Logo height on small screens, 480px - 768pxlogoHeightM: "50px", // Logo height on medium screens, 768px - 1024pxlogoHeightL: "60px", // Logo height on large screens, 1024px - 1440pxlogoHeightXL: "60px", // Logo height on extra large screens, above 1440pxiconsFooter: "32px", // Sets the icons size for the footericonsHeader: "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: {},}