# Design tokens

## Introduction

The content should be consistent with the brand look. In order to make sure that editors keep this consistency, Shopstory is built to be design-token first.

Shopstory recognizes following design tokens:

* colors
* fonts
* spacings
* page containers (margins and max widths)
* aspect ratios

For example, when user wants to change a color, the first thing we display is always the list of available color tokens:

![](/files/iVHdMwU5mrzY4WYxII63)

If the design system is configured properly then users will never have to resort to setting custom values and everything will be perfectly consistent with the brand language.

In Shopstory the design tokens are set in code.

## Master tokens

Shopstory comes by default with so called "master tokens". The master token labels start with `$` sign and you can spot them for example in a color picker: `$dark`, `$light`, etc:

<figure><img src="/files/8hSkGtOFKt3l66jW0oze" alt=""><figcaption></figcaption></figure>

Master tokens are important because all the built-in templates you see in a template picker are built with them.

#### Mapping master tokens

The most important trait of master design tokens is that they can (and should) be mapped to your own custom design tokens. For example, if your main dark background color is `#09034A` (dark blue) then when you define it in a configuration object you can map it to the `$backgroundDark` master token:

```typescript
export const shopstoryConfig = {
  //...
  colors: [
    {
      id: "dark-blue",
      label: "Dark blue",
      value: "#09034A",
      mapTo: ["$backgroundDark"]
    },
    // ...
  ],
}
```

Now the `$backgroundDark` token will disappear from the token list and all the built-in Shopstory templates will apply your custom dark blue color wherever `$backgroundDark` was used.

Thanks to this approach all the off-the-shelf Shopstory blocks (sections, cards, etc) will be compatible with your brand language.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.shopstory.app/design-tokens.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.