Skip to content
Theme UI
GitHub

Theme Specification

Theme UI is based on the System UI Theme Specification, with a few optional additions. The top-level naming convention used in the theme object come from this specification. Additionally, naming conventions for colors and typography are included to help ensure deeper interoperability with components from various other libraries. This is also intended to help ensure that themes created for Theme UI are suitable for white-label applications and general purpose theming.

Theme Scales

The theme object is made up of the following scales (i.e. property-specific objects) for use in CSS styles.

Theme KeyCSS Properties
colorscolor, background-color, border-color
fontsfont-family
fontSizesfont-size
fontWeightsfont-weight
lineHeightsline-height
spacemargin, margin-top, margin-right, margin-bottom, margin-left, padding, padding-top, padding-right, padding-bottom, padding-left, grid-gap, grid-column-gap, grid-row-gap
letterSpacingsletter-spacing
sizeswidth, height, min-width, max-width, min-height, max-height
bordersborder, border-top, border-right, border-bottom, border-left
borderWidthsborder-width
borderStylesborder-style
radiiborder-radius
shadowsbox-shadow, text-shadow
zIndicesz-index
// example theme
{
colors: {
text: '#000',
background: '#fff',
primary: '#07c',
secondary: '#05a',
accent: '#609',
muted: '#f6f6f6f',
},
fonts: {
body: 'system-ui, sans-serif',
heading: 'system-ui, sans-serif',
monospace: 'Menlo, monospace',
},
fontWeights: {
body: 400,
heading: 700,
bold: 700,
},
lineHeights: {
body: 1.5,
heading: 1.125,
},
}

Color

The theme.colors scale (i.e. color palette) should be an object literal with the following keys.

KeyDescription
textBody foreground color
backgroundBody background color
primaryPrimary brand color for links, buttons, etc.
secondaryA secondary brand color for alternative styling
accentA contrast color for emphasizing UI
mutedA faint color for backgrounds, borders, and accents that do not require high contrast with the background color

Other color keys can be added, including raw color values for aliasing the values above.

Color Modes

To use Theme UI color modes, color scales should include at least a text and background color. These values are used in the ColorMode component to set body foreground and background colors. Color modes should be defined as nested objects within a theme.colors.modes object. Each key in this object should correspond to a color mode name, where the name can be anything, but typically light and dark are used for applications with a dark mode. The initialColorMode key is required to enable color modes and will be used as the name for the root color palette.

// example color scale with modes
{
initialColorMode: 'light',
colors: {
text: '#000',
background: '#fff',
primary: '#07c',
secondary: '#05a',
muted: '#f6f6f6f',
modes: {
dark: {
text: '#fff',
background: '#000',
primary: '#0cf',
secondary: '#09c',
muted: '#111',
},
papaya: {
// this color mode will fallback to the root color object
// for values not defined here
text: '#433',
background: 'papayawhip',
},
},
},
}

Typography

To ensure that themes built for Theme UI are as portable and interoperable as possible, the following keys should be defined within each theme scale. Additional keys can be included for more complex styling.

  • fonts
    • body: default body font family
    • heading: default heading font family
    • monospace: default monospace font family for <pre>, <code>, etc.
  • fontWeights
    • body: body font weight
    • heading: default heading font weight
    • bold: default bold font weight
  • lineHeights
    • body: body line height
    • heading: default heading line height

Font Sizes (Typographic Scale)

Font sizes are typically defined as an array, from smallest to largest.

// example fontSizes scale
{
fontSizes: [
12, 14, 16, 20, 24, 32, 48, 64,
],
}

For illustration purposes, the index values of the array can be thought of as loosely mapping to heading levels, but these values are not in any way tied to HTML elements.

IndexHeading-Level Equivalent
0h6
1h5
2h4
3h3
4h2
5h1

Variants

Use variants to define custom groups of styles. These are commonly used for typographic styles, buttons, and themeable layout components.

// example typographic style variants
{
colors: {
white: #FFFFFF,
primary: #663399,
text: #393939,
secondary: #DAA520,
},
fonts: {
body: 'system-ui, sans-serif',
heading: 'system-ui, sans-serif',
monospace: 'Menlo, monospace',
},
fontWeights: {
body: 400,
heading: 700,
bold: 700,
},
lineHeights: {
body: 1.5,
heading: 1.125,
},
// variants can use custom, user-defined names
text: {
heading: {
fontFamily: 'heading',
lineHeight: 'heading',
fontWeight: 'heading',
},
caps: {
textTransform: 'uppercase',
letterSpacing: '0.1em',
},
},
// variants for buttons
buttons: {
primary: {
// you can reference other values defined in the theme
color: 'white',
bg: 'primary',
},
secondary: {
color: 'text',
bg: 'secondary',
},
}
}

User-defined variants can then be referenced in the sx prop or in theme.styles.

// example using variants
<h1
sx={{
variant: 'text.heading',
}}>
Hello
</h1>
<button
sx={{
variant: 'buttons.primary',
}}>
Beep
</button>

Styles

The Theme UI styles object is primarily used as a way to style MDX content and helps avoid the need to use global CSS. The styles defined within this object can also be used with the Styled component.

The theme.styles object may include the following keys, which map to elements that can be rendered by markdown:

  • p (paragraph)
  • a (anchor link)
  • h1 (heading)
  • h2
  • h3
  • h4
  • h5
  • h6
  • img
  • pre
  • code
  • ol (ordered list)
  • ul (unordered list)
  • li (list item)
  • blockquote
  • hr (horizontal rule)
  • em (emphasis)
  • table
  • tr (table row)
  • th (table header)
  • td (table data)
  • strong
  • delete
  • b (bold)
  • i (italic)
  • inlineCode (MDX-specific key for <code> that is not a child of <pre>
  • thematicBreak (MDX-specific key for <hr>)
  • div (not rendered in MDX)
  • root (theme-ui-specific)

Objects within theme.styles can reference other values in the theme object. For example, headings can be defined with values from the typographic scales.

// example heading styles
{
styles: {
h1: {
fontFamily: 'heading',
fontWeight: 'heading',
lineHeight: 'heading',
fontSize: 5,
},
},
}

Variants can also be used within the theme.styles object.

// example heading using text styles variant
{
// ...base theme object
text: {
heading: {
fontFamily: 'heading',
fontWeight: 'heading',
lineHeight: 'heading',
}
},
styles: {
h1: {
variant: 'text.heading',
fontSize: 5,
}
}
}

Breakpoints

To configure the default breakpoints used in responsive array values, add a breakpoints array to your theme. Each breakpoint should be a string with a CSS length unit included. These values will be used to generate mobile-first (i.e. min-width) media queries, which can then be used to apply responsive styles.

// example custom breakpoints
{
breakpoints: [
'40em', '56em', '64em',
],
}
Edit the page on GitHub
Previous:
Object Styles
Next:
Gatsby Plugin