Skip to navigation Skip to navigation Skip to content

Creating themes

Learn how to configure themes and their style tokens.

Theme basics #

Themes are groups of settings that define a series of reusable design-token-style settings for your project. Normally, one theme (the default theme) will be all you'll need to style your project, and you can define all of your style options within it. Occasionally, having multiple themes is beneficial, and Hydrogen allows you to define as many themes as you need.

Theme style values act as variables of sorts, where you define a key and assign it a unique style value. You'll then be able to use that key inside of relevant Hydrogen attributes: data-h2-color='base(myColorKey)'. This is powerful because it enables designers to create and set concrete, reusable style values that can be changed project-wide in a matter of seconds.

The default theme #

Hydrogen requires that you have at least one theme defined in your configuration, and that theme must have its key value set to default. This default theme allows you to set base styles for your project and doesn't require any special work to be applied.

Subsequent themes require a unique key value and when used in your code, only work if your project's data-h2 wrapper value contains the theme's key as a value.

hydrogen.config.json 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
"themes": [
  {
    "key": "default",
    "typography": []
    "colors": []
    "fonts": []
    "font_weights": []
    "gradients": []
    "radii": []
    "shadows": []
    "transitions": {
      "durations": []
      "functions": []
      "delays": []
    },
    "wrappers": []
  },
  ...
]

Creating and applying themes #

Custom themes you create above and beyond the default theme can be as simple or complex as the settings will allow. In a lot of cases, all you'll need to do is create a new series of color settings. In other cases, you'll want to modify the typography, font families, spacing, and more.

When defining theme settings, make sure that you apply the settings using the same key values defined in your default theme. This will allow the themes to swap styles instantaneously when their key is applied to the site. Activating your new theme is as simple as adding your key to your site's data-h2 attribute: data-h2='myTheme'.

hydrogen.config.json 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"themes": [
  {
    "key": "default",
    "colors": [
      {
        "default": {
          "key": "primary",
          "color": "red"
        }
      }
    ]
  },
  {
    "key": "myTheme",
    "colors": [
      {
        "default": {
          "key": "primary",
          "color": "blue"
        }
      }
    ]
  }
]

When styling your project, you might run into an instance where you need styles to apply explicitly to a custom theme, but not the default app. Hydrogen allows you to do this by applying the theme's key value as a query modifier. Styles used this way will only apply to the element when the theme's key is applied to the data-h2 attribute.

1
base:myTheme(primary)

Core theme settings #

The theme key #

The key definition for your theme sets the value you will use inside of Hydrogen attributes to trigger theme styles. As described above, there must always be a theme with the key set to default in your settings, but you can then name other themes using custom values.

For example, if you set the theme's key to myTheme, you would use it inside of a Hydrogen attribute like this: data-h2-color="base:myTheme(primary)". This style would only trigger when the theme's key was applied to the site-wide data-h2 attribute.

hydrogen.config.json 
1
"key": "myTheme",

Typography #

A theme's typography settings allow you to customize how Hydrogen's typography system will generate font sizes and layout whitespace values. By linking the typography setting with a media query defined in your media settings, you can trigger different styles at different breakpoints in order to create the best possible experience for the amount of space available.

You can add as many typography definitions as you need to achieve your intended level of granularity and control.

  • query_key accepts any of the keys you've defined in your media settings. This will trigger the typography object's settings at that media query. Setting the value to base (or your custom base query key) will set that specific typography setting to be the default setting.
  • size allows you to set the base font size on the html element. This will then set the foundation for your body copy and subsequent headings. It's recommended that you use a percentage value for this setting to avoid removing control from the user's accessibility options.
  • type_scale will tell Hydrogen how to generate heading sizes from h6 through h1. The type scale website provides helpful information about type scales and how they work.
  • line_heights accepts optional configurations for each of the type scale's units, the most important of which is body, whose value is used to determine how Hydrogen calculates whitespace multipliers. body will default to a value of 1.4 if you don't specify a custom value.
hydrogen.config.json 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
"typography": [
  {
    "query_key": "base",
    "size": "100%",
    "type_scale": "1.25",
    "line_heights": {
      "caption": "1.5",
      "body": "1.4",
      "h6": "1.1",
      "h5": "1.1",
      "h4": "1.1",
      "h3": "1.1",
      "h2": "1.1",
      "h1": "1.1",
      "display": "1.1"
    }
  },
  ...
],

Theme style settings #

Hydrogen provides a handful of style settings that allow you to define custom, reusable values that you can access inside of Hydrogen attributes. You can think of these theme style settings as design tokens - by configuring these values, you ensure that common values are always used consistently, as well as allowing you to change individual values site-wide by altering your configuration.

Theme style settings have two sets of values: their default settings, and optional dark mode settings. By providing custom dark mode styles for a setting, you can granularly control how a specific setting alters its look or layout for that specific mode.

hydrogen.config.json 
1
2
3
4
5
6
7
8
9
10
11
"setting": [
  {
    "key": "",
    "default": {
      "value": "",
    },
    "dark": {
      "value": "",
    },
  },
],

Colors #

Colors are one of the most important settings you can configure for a theme. Each color requires a key value and a default CSS color value, but also provides customizable modifier options should you need them.

  • color accepts any CSS color value (e.g. hex, rgba, etc.).
  • The modifiers array allows you to define custom modifiers for this color. Modifiers are accessed in code using dot notation. For example: data-h2-color="base(primary.dark)". By default, Hydrogen generates 6 modifiers for you:
    • light
    • lighter
    • lightest
    • dark
    • darker
    • darkest
  • You can overwrite these default modifiers by specifying their key, or you can create your own modifiers using custom keys.
hydrogen.config.json 
1
2
3
4
5
6
7
8
9
10
11
12
13
"colors": [
  {
    "key": "primary",
    "default": {
      "color": "#9D5CFF",
      "modifiers": [
        "key": "myModifier",
        "color": "#B340E8"
      ],
    },
  },
  ...
],

Containers (deprecated) #

Containers have been deprecated in favor of the newer wrapper theme setting found below.

Fonts #

The fonts configuration allows you to define reusable font family values.

  • family accepts any CSS font family value, including comma separated values. Don't forget to include ' characters around family names where necessary.
hydrogen.config.json 
1
2
3
4
5
6
7
8
9
"fonts": [
  {
    "key": "sans",
    "default": {
      "family": "sans-serif",
    },
  },
  ...
],

Font weights #

The font_weights configuration allows you to define reusable font weight values.

  • weight accepts any CSS font weight value.
hydrogen.config.json 
1
2
3
4
5
6
7
8
9
"font_weights": [
  {
    "key": "semibold",
    "default": {
      "weight": "600",
    },
  },
  ...
],

Gradients #

The gradients option allows you to define reusable linear or radial gradient values that can be used in properties such as background.

  • gradient accepts CSS gradient syntax, including directions and a variable number of color stops.
hydrogen.config.json 
1
2
3
4
5
6
7
8
9
"gradients": [
  {
    "key": "linear",
    "default": {
      "gradient": "linear-gradient(to right, purple, blue)",
    },
  },
  ...
],

Radii #

This option allows you to define reusable border-radius values.

  • radius accepts any valid CSS unit.
hydrogen.config.json 
1
2
3
4
5
6
7
8
9
"radii": [
  {
    "key": "rounded",
    "default": {
      "radius": "5px",
    },
  },
  ...
],

Shadows #

The shadows option allows you to configure reusable box-shadow values.

  • shadow accepts any valid CSS box-shadow value.

Tip: it's recommended that you experiment with slightly darker shadow values when considering dark mode. This will give them an extra pop and much more visible contrast against your dark mode backgrounds.

hydrogen.config.json 
1
2
3
4
5
6
7
8
9
10
11
12
"shadows": [
  {
    "key": "small",
    "default": {
      "shadow": "0 0.1rem 0.2rem 0 rgba(0, 0, 0, .2)",
    },
    "dark": {
      "shadow": "0 0.1rem 0.2rem 0 rgba(0, 0, 0, .5)",
    },
  },
  ...
],

Transitions #

The transitions configuration is unique in that it provides three different sub-configurations: durations, functions, and delays. These allow you to set reusable values for each, creating more granular control over animation values.

  • duration accepts a valid CSS time unit.
  • function accepts a valid CSS transition animation function (e.g. ease, linear, etc.).
  • delay accepts a valid CSS time unit.
hydrogen.config.json 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
"transitions": {
  "durations": [
    {
      "key": "short",
      "default": {
        "duration": ".2s",
      },
    },
    ...
  ],
  "functions": [
    {
      "key": "ease",
      "default": {
        "function": "ease",
      },
    },
    ...
  ],
  "delays": [
    {
      "key": "quick",
      "default": {
        "delay": ".1s",
      },
    },
    ...
  ]
}

Wrappers #

Wrappers allow you to specify consistent, reusable width values that can be helpful in ensuring consistent page or element sizes.

  • max_width allows you to set the wrapper's width value in any CSS unit.
hydrogen.config.json 
1
2
3
4
5
6
7
8
9
"wrappers": [
  {
    "key": "small",
    "default": {
      "max_width": "39rem",
    },
  },
  ...
],

Previously

« Dark mode

Up next

Styling »