Docs: Introduce Tokens Structure Decision

docs/decisions/009-tokens-structure.md

@@ -0,0 +1,49 @@
+# Tokens Structure
+
+Date: 2024-11-19
+
+Status: accepted
+
+## Context
+
+Our Design System uses design tokens.
+
+## Decision
+
+This is what we decided on:
+
+1. We divide tokens into `Global Tokens` and `Theme Tokens`. The `Global Tokens` are non-themed tokens – their
+   values are the same in all themes, for example breakpoints. The `Theme Tokens` have the same structure, but in each theme,
+   their value can differ, for example colors.
+2. Global tokens are divided into `Borders`, `Gradients`, `Other`, `Radii`, `Shadows`, `Spacing` and `Typography`. Each category
+   has its own file and contains tokens that are related to the category. The `Other` category contains tokens that do not fit
+   into any other category.
+3. The `Gradients` and `Shadows` tokens use CSS variables to define the colors. This allows us to theme them.
+4. We use scales for tokens that have multiple values. For example, the `Spacing` category contains `space-0`, `space-100`, `space-200`, etc.
+   We use hundreds for the scale, so our users have plenty of space to add their own values between the predefined ones.
+5. The `Theme Tokens` contains folders for each theme.
+6. In `Theme Tokens` we provide a list of SCSS variables and also a mixin with CSS variables. The mixin is used to generate CSS variables
+   for the theme. The SCSS variables are used to define the values of the tokens.
+
+### Color token structure
+
+These are decisions related to the color tokens:
+
+1. We decided to create a `component` group which contains tokens for unique components. This way, we can easily find the colors
+   that are used in a specific component and we know that these colors are not used anywhere else.
+2. We decided to add infix `-state-` to the state tokens before the state. This way, we know which tokens are used for states
+   and are related to each other.
+3. We decided to have a `disabled` group which covers the disabled state and is used for all components.
+4. We decided to have suffixes `-basic` and `-subtle` for tokens for components which need two different contrast levels.
+5. We decided to have `form-field` group which contains tokens for form fields. This group has a subgroup `filled` for
+   tokens which are used for filled part of the form field. In the future, we can add more subgroups for different form field types.
+6. We decided to have a `neutral` group which contains tokens for neutral colors.
+7. We decided to create color tokens for gradients and shadows. These tokens are used in the `Gradients` and `Shadows` categories.
+   To support multiple shadow or gradients colors in one `Gradients` or `Shadows` token, we use `-color-01`, `-color-02`, etc. suffixes.
+
+## Consequences
+
+By following this structure, we can easily find tokens and we know where to add new tokens. We can also easily add new themes
+and we know where to add new tokens for the themes. This structure is easy to understand and maintain.
+
+Our tokens follow the structure described in this decision.