When adjusting styles (especially global styles) in your project, it's important to understand how CSS works in Stackbit projects. Read this guide for an overview of how styling works in Stackbit themes.

Choosing the Right Path

When making a change to styles in a Stackbit project, the first decision to make is whether or not those styles should be adjustable by your site's content editors.

If you don't need multiple options or to expose flexibility, choose the hard-coded approach. Otherwise, see below on implementing user-controlled global styles.

If you are unsure which approach to take, start with the hard-coded approach. It's much simpler, and can always be made dynamic and more flexible.

Hard-Coded Global Styles

Stackbit components and themes are built with Tailwind CSS. If you want to adjust Tailwind-level values, you can do so by extending the Tailwind configuration file at tailwind.config.js in the root of your project. Learn more about Tailwind config.

If you want to set specific global styles, you can instead use a CSS file in your project. Every theme comes with a src/css/main.css file that contains theme-specific styling. You could add your styles directly to this file or import a separate file. How you organize your CSS code is up to you.

For example, say you wanted to make the default font family for all headings be the monospaced font. You could do something like this in your main.css file:

@layer base {
  h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    @apply font-mono;
  }
}

When making global changes to primitive elements, use the @layer directive.

User-Controlled Global Styles

New themes come with a style editor out of the box. These are global styles that can be adjusted by any editor of your site.

Global styles editor

The values are stored in a data file in your project, located at content/data/style.json. These values are then injected into your site's Tailwind configuration. Learn more about styling works with Stackbit.

Let's look at an example where you wanted to let your content editors adjust the base font size for your site.

Step 1: Add Default Value

Begin by adding a default value to your content/data/style.json file. This helps ensure that when we're using the setting, it's going to exist. Let's assume 16px by default, and we'll call the setting baseFontSize.

{
  "type": "ThemeStyle",
  "body": "#414c58",
  // ...
  "baseFontSize": "16px"
}

Step 2: Add Model Definition

Override the model definition by first duplicating the default definition. This may vary from theme to theme. Given our example above, we would begin by adding the following content to .stackbit/models/ThemeStyle.yaml:

type: data
name: ThemeStyle
label: Theme Style
file: style.json
fieldGroups:
  - name: color-palettes
    label: Color Palettes
fields:
  - type: color
    name: body
    label: Body
    group: color-palettes
  - type: color
    name: headlines
    label: Headlines
    group: color-palettes
  - type: color
    name: primary
    label: Primary
    group: color-palettes
  - type: color
    name: secondary
    label: Secondary
    group: color-palettes
  - type: color
    name: neutral
    label: Neutral
    group: color-palettes
  - type: color
    name: complementary
    label: Complementary
    group: color-palettes
  - type: color
    name: complementary-alt
    label: Complementary Alt
    group: color-palettes

Let's add a "Font Sizes" group and our base font size field (as a string).

type: data
name: ThemeStyle
label: Theme Style
file: style.json
fieldGroups:
  - name: font-sizes
    label: Font Sizes
  - name: color-palettes
    label: Color Palettes
fields:
  - type: string
    name: baseFontSize
    label: Base Font Size
    group: font-sizes
  - type: color
    name: body
    label: Body
    group: color-palettes
  # ...

Now, go check out the editor. You should see the new field and be able to change the value.

Base Font Size Setting

Step 3: Add Tailwind Setting

The last piece of the puzzle is to extend Tailwind's font size settings, specifically targeting the base style.

const themeStyle = require('./content/data/style.json')

module.exports = {
  // ...
  theme: {
    extend: {
      fontSize: {
        base: themeStyle.baseFontSize
      }
      // ...
    }
  }
}

Now try changing the value of the base font size to something ridiculously large and see some of the content shift accordingly.

Base Font Size Setting with 48px