import { Meta } from '@storybook/blocks';
import { parameters } from '../utils/docsPage.js';

<Meta title="Components/Theming/CSS variables" parameters={{ ...parameters }} />

# CSS variables

The [`Theme`](?path=/docs/components-theme--default) component uses **[CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)** to control major parts of your page's theme.

All other components in this library use those variables for styling basic colours and typography, helping keep our pages uniform and making it easier to customise the theme. CSS variables also allow our clients to easily change elements of our theme to match their brand.

This doc explains which variables are set and how you can use them in custom components you create.

> **Note:** CSS variables do not currently affect [ai2svelte](https://github.com/reuters-graphics/ai2svelte/) graphics, so you should continue to make sure your colours match the theme of your page directly in Adobe Illustrator for those graphics.

## Using CSS variables directly

If you're new to how CSS variables work, [here's a video](https://www.youtube.com/watch?v=PHO6TBq_auI) that does a decent job explaining what they are, how they work and why they're useful.

You can use any of the CSS variables the `Theme` component sets in your own code with the [`var()`](https://www.w3schools.com/css/css3_variables.asp) function.

```svelte
<p>My custom text</p>

<style lang="scss">
  p {
    color: var(--theme-colour-text-primary);
    font-family: var(--theme-font-family-sans-serif);
  }
</style>
```

## Customising variables

You can redefine any of the above CSS variables in the `<Theme>` component. Read more in [the docs](/docs/theming-theme--custom-theme) and **use the [Theme builder](/docs/theming-theme-builder--docs)**.

```svelte
<Theme
  base="light"
  theme="{{
    colour: {
      // This replaces the default text-secondary colour '#666666' for light theme
      'text-secondary': '#213310',
    },
  }}"
>
  <!-- page stuff -->
</Theme>
```

## Adding extra variables

You can even add custom variables through the `Theme` component.

For example, let's say you want to define a border radius for some card elements on your page. You can add a custom property to the `theme` prop like this:

```svelte
<Theme
  base="light"
  theme="{{
    style: {
      'border-radius': '22px',
    },
  }}"
>
  <!-- page stuff -->
</Theme>
```

... and then access the CSS variable in your code like this:

```svelte
<div class="card"></div>

<style lang="scss">
  .card {
    border-radius: var(--theme-style-border-radius);
  }
</style>
```

Using the `Theme` component for your own CSS variables helps unify important style values across a project. It also lets clients more easily customise those values for whatever matches their brand.

You can also change a variable's value based on some condition. For example, to set a smaller border radius on mobile screens, you might:

```svelte
<script>
  // other code

  let windowWidth;
</script>

<svelte:window bind:innerWidth="{windowWidth}" />

<Theme
  base="light"
  theme="{{
    style: {
      'border-radius': windowWidth > 475 ? '22px' : '11px',
    },
  }}"
>
  <!-- page stuff -->
</Theme>
```