import { Meta, Markdown } from '@storybook/addon-docs/blocks';

# Tokens

Green Design System uses a token-based approach to design. This means
that design properties, such as colors and spacing values, are defined
in a single place and are then used throughout the design system.
This makes it easier to maintain and update the design system and helps to
ensure consistency across the components in the system and the products
that use them.

Tokens are  commonly referred to as <em>variables</em>, and these terms
can be used interchangeably for the most parts. The distiction is mainly an
abstract one, with the term <em>token</em> meaning the design value itself,
whereas <em>variable</em> often refers to the concrete implementation in code. In
CSS it is typically called `variables` though the technically correct terminlogy
is `CSS custom properties`. In Figma, they are called `variables`. Other
languagues and tools may have other names for the same concept.

## Token collections

Tokens in Green are grouped in the following collections:

- Colors\
  Green uses a three-level color system, which you can read more about under [https://seb.io/primitives/colours](https://seb.io/primitives/colours)
- Text\
  Text tokens include font sizes, line heights, and font weights. Read more under [https://seb.io/primitives/typography](https://seb.io/primitives/typography)
- Spacing\
  Spacing tokens define the spacing values used for paddings, margins, gaps and other spaces in the design. Read more under [https://seb.io/primitives/spacing](https://seb.io/primitives/spacing)
- Viewports\
  Viewport tokens define the breakpoints used in the design system.
- Shadows\
  Shadow tokens define the `box-shadow` values used in the design system.

## Using token variables

In most cases you don't need to use variables directly. They are already used in
the design of the components, and if you are using [Declarative Layout](/docs/concepts-declarative-layout--docs), you have a
simplified way of using the tokens. You can read more on this on [https://seb.io/primitives/colours](https://seb.io/primitives/colours).

However, in some cases you will need to use CSS variables directly in your code, so
let's briefly go over how to access them.

### Using the CSS variables

In CSS, you can access the tokens by using the `var()` function. If you are not familiar
with CSS variables, you can [read more about them on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).

By default, tokens are defined on the `:host` selector of every component, so in order to access them, the element you are styling
needs to be a child to a Green component. CSS variables, as opposed to other CSS properties, propagates down across shadow DOM boundaries,
so when they are defined on the `:host` selector of a component, they are available to all children of that component.

If a parent of your element is one of the declarative layout components from Green
(ie, container, flex, grid or card), you're already covered, but if not, you can use `<gds-theme>` for this purpose. `<gds-theme>` does not
add any visible layout to the page, but it provides access to all the CSS variables. The theme component can also be used to toggle
between light and dark mode, as well as setting the design version to be used by its descendants. You can [read more about the theme component here](/docs/components-theme--docs).

Here is an example of using the theme component to get access to variables:

<gds-theme design-version="2023">
  <div>Hello world</div>
</gds-theme>
```html
<gds-theme design-version="2023">
  <div style="background-color: var(--gds-sys-color-l2-neutral-02); color: var(--gds-sys-color-content-neutral-01); padding: var(--gds-sys-space-l);">
    Hello world
  </div>
</gds-theme>
```

Try inspecting this example in Chrome DevTools, and change the value of the `color-scheme` attribute in the `<gds-theme>` element to `dark` to see what happens to the color variables.