CSS Variables

Under the hood, the design system uses CSS custom properties, also known as CSS variables, to apply all token styles. For this most part you can treat this as an implementation detail, but there are some cases that might call for using the CSS variables directly. It also helps to understand what you'll see in your browser's developer tools.

Theme CSS variables

All design token defined in theme are automatically converted to CSS variables internally.

When you wrap your application in BlueprintProvider, it automatically generates CSS variables that look like:

body {
  /* ... */
  --hover-borders-width400: 1px solid;
  --hover-borders-width500: 2px solid;
  /* ... */
  --hover-colors-primary-100: #e6f1fe;
  --hover-colors-primary-200: #b9d9fa;
  --hover-colors-primary-300: #90c0f4;
  --hover-colors-primary-400: #69a8eb;
  /* ... */
}

Note
The generated custom properties are prefixed with hover-* to avoid conflicts with third party CSS.

Consuming CSS Variables

When using system components, we manage the conversion of theme tokens passed as style props to their respective css variable.

Tip
This is done automatically when you use style props or use the sx prop.

// You type this
<Box color="neutral.700" />
// And it is applied like this
.css-box {
   color: "var(--hover-colors-neutral-700)"
}

Consuming CSS variables directly
CSS variables should only be used directly when necessary. Prefer styling via style props or style objects (sx) as the idiomatic way of applying styles using the design system.

With that said, some cases for using CSS variables directly are:

When it is impossible or difficult to reference tokens from React context via useTheme()
Styling third-party components
Updating legacy code that uses raw CSS (though another option here is to use the Bootstrap theme)

Variable Helper

A few helper functions are available on the cssVariables export to generate named CSS variables.

import { cssVariables } from '@hover/blueprint';
const $space400 = cssVariables.space(400);
const $colorPrimary500 = cssVariables.color('primary.500');
$space400.reference; // `var(--hover-space-400)`
$space400.variable; // `--hover-space-400`
$color500.reference; // `var(--hover-colors-primary-500)`
$color500.variable; // `--hover-colors-primary-500`

Styling non-system components

In certain scenarios, you might need to style components that are not managed by the system. In this case, you can use the raw CSS variable values.

// let's say you have an embedded form
<FormiumForm />

You can write custom CSS to style the components

.formium-form {
  color: var(--hover-colors-neutral-700);
  background-color: var(--hover-colors-neutral-100);
}

or wrap the component in <Box/> and style it with convenience.

<Box sx={{ '.formium': { bg: 'gray.50', color: 'gray.700' } }}>
  <FormiumForm />
</Box>