From 747bf814adef0844eaefaa37ed7e035b756d0b0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Kry=C5=A1p=C3=ADn?= Date: Tue, 19 Nov 2024 16:30:56 +0100 Subject: [PATCH] Docs: Introduce Tokens Structure Decision --- docs/decisions/009-tokens-structure.md | 68 ++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 docs/decisions/009-tokens-structure.md diff --git a/docs/decisions/009-tokens-structure.md b/docs/decisions/009-tokens-structure.md new file mode 100644 index 0000000000..7ca3c54bb5 --- /dev/null +++ b/docs/decisions/009-tokens-structure.md @@ -0,0 +1,68 @@ +# Tokens Structure + +Date: 2024-11-19 + +Status: accepted + +## Context + +Our Design System uses design tokens. + +Since Charm Version of our Design System, we use Figma as a single source of truth for our design tokens. +We use Figma Variables and Styles to define all tokens and import them into the codebase. No tokens are defined +outside of Figma. + +Previously, we used Supernova as a single source of truth for our design tokens, where part of the tokens was +imported from Figma and the rest was hardcoded in Supernova. With Figma Variables we are able to define all tokens +in Figma and import them into the codebase. This way, we have a single source of truth for all tokens. + +Figma Variables also introduced the possibility to define multiple themes in Figma. This way, we were able to +avoid confusion with `inverted` tokens and are able to solve this using themes. See the [Themes Decision](008-themes.md) +for more information about this. + +With Figma Variables, we unified the structure of our tokens in Figma and in the codebase. + +## Decision + +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. See the [Themes Decision](008-themes.md) for more information about themes. +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. + without any limits. We use hundreds for the scale, so our users have plenty of space to add their own values between the predefined ones. +5. If tokens values differ for each breakpoint, we use object with breakpoint keys. For example, the `Typography` category contains + styles where each style has a different configuration for each breakpoint. +6. The `Theme Tokens` contains directories for each theme. +7. 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. And if they are, we + know it's an issue. +2. We decided to add the `-state-` infix to the interaction state tokens before the state name. This way, we know which tokens + are used for states and are related to each other. +3. We decided to have suffixes `-basic` and `-subtle` for tokens for components which need two different contrast levels. +4. 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. +5. We decided to have a `disabled` group which covers the disabled state and is used for all components that can be disabled. +6. We decided to have a `neutral` group which contains tokens for neutral colors. +7. We decided to have a `selected` group which contains tokens for selected items. +8. We decided to have a single-purpose groups for tokens that are used only in one place. For example, we have a `text`, `background`, + `link`, etc. groups. +9. 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. +10. In `Shadows` tokens, we also have a `focus-ring` token which is used for focus rings. +11. Based on our [Dictionaries](../DICTIONARIES.md), we structure our tokens in groups and subgroups. For example, `emotion` colors + contains `success`, `warning`, `error` and `informative` subgroups or `button` colors contains `primary`, `secondary`, `tertiary`. + +## 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 hopefully easy to understand and maintain.