From cbfc1432e75d0b91472ab24bb7549383fef18f3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Kry=C5=A1p=C3=ADn?= Date: Thu, 17 Oct 2024 11:32:35 +0200 Subject: [PATCH] fixup! Docs(web): Introduce General Changes into the Migration Guide #DS-1489 --- docs/migrations/web/MIGRATION-v3.md | 134 +++++++++++++++------------- 1 file changed, 71 insertions(+), 63 deletions(-) diff --git a/docs/migrations/web/MIGRATION-v3.md b/docs/migrations/web/MIGRATION-v3.md index 9a6da1a11b..fc03b5290a 100644 --- a/docs/migrations/web/MIGRATION-v3.md +++ b/docs/migrations/web/MIGRATION-v3.md @@ -8,77 +8,84 @@ Introducing version 3 of the _spirit-web_ package. - [General Changes](#general-changes) - [Themes](#themes) - - [Spacing values](#spacing-values) - - [Helpers: Typography `text` infix and Heading emphasis](#helpers-typography-text-infix-and-heading-emphasis) - - [Utilities: Removed and new classes](#utilities-removed-and-new-classes) - - [Migrating product components](#migrating-product-components) + - [Spacing Values](#spacing-values) + - [Helpers: Typography and Headings](#helpers-typography-and-headings) + - [Utilities: Removed and New Classes](#utilities-removed-and-new-classes) + - [Migrating Your Own Components](#migrating-your-own-components) - [Component Changes](#component-changes) - - [Button: renamed modifier `square`](#button-square-modifier-renamed-to-symmetrical) + - [Button: `square` Modifier Renamed to `symmetrical`](#button-square-modifier-renamed-to-symmetrical) ## General Changes -## Themes +### Themes Starting from version 3, the design system now supports multiple themes based on the -theme tokens. As in Figma, the first theme is the default one. +theme tokens. + +See our [Themes decision][themes-decision] for more information and why we decided to implement this feature. + +#### Introduction + +The design system now supports multiple themes based on the theme tokens. As in +[Figma][spirit-figma-file], where the first theme column is the default, the first theme in the +tokens map `@themes` is the default. + +We use CSS variables to apply colors to the components. This way, we can easily switch +the theme by adding a CSS class to the root element. This change affects all nested components +that apply any color. The default theme is set to the `:root` element and all the themes are generated -to classes that can be applied to the any element. Their names are based on the +to CSS classes that can be applied to the any element. Their names are based on the theme names in tokens. -This change affects all components that apply any color. +#### Component Changes We did all the work and our components are now using CSS variables to -apply colors, however, if you have any custom styles you need to update them. - -Also, all your components that previously used color tokens should be updated to -use CSS variables. See [Migrating product components](#migrating-product-components) -for more information. +apply colors. -To switch the theme, simply add the theme class to the element you want to apply the theme to. -All the colors in the nested component will be switched to the theme colors. +Also, all your components or any custom styles you have, that previously used +color tokens should be updated to use CSS variables. -Using themes we were able to remove `inverted` variants and some `brand` tokens. +See [Migrating Your Own Components](#migrating-your-own-components) for more information. -See our [Themes decision][themes-decision] for more information and why we decided to implement this feature. +#### Inverted Variants -### Spacing values +Using themes, we were able to remove the `inverted` design tokens and component variants, and also some `brand` tokens. -New spacing values were added to the design system this caused a change in the -spacing tokens and some values were updated. +### Spacing Values -All spacing props and utility classes are influenced by this change. +New spacing values were added to the design system, updating spacing design tokens and affecting all spacing props and utility classes. #### Migration Guide Use this table to update the spacing tokens in your project. -| **Old tokens** | | **New tokens** | | -| -------------- | ---- | -------------- | ---- | -| space-0 | 0 | space-0 | 0px | -| space-100 | 1px | space-100 | 1px | -| space-200 | 2px | space-200 | 2px | -| space-300 | 4px | space-300 | 4px | -| | | space-400 | 6px | -| space-400 | 8px | space-500 | 8px | -| space-500 | 12px | space-600 | 12px | -| space-600 | 16px | space-700 | 16px | -| | | space-800 | 20px | -| space-700 | 24px | space-900 | 24px | -| space-800 | 32px | space-1000 | 32px | -| space-900 | 40px | space-1100 | 40px | -| space-1000 | 48px | space-1200 | 48px | -| | | space-1300 | 56px | -| space-1100 | 64px | space-1400 | 64px | -| | | space-1500 | 72px | -| space-1200 | 80px | space-1600 | 80px | -| | | space-1700 | 96px | - -If you are going to use fulltext search&replace in your project, we suggest you to +| | **Old tokens** | **New tokens** | +| ----- | -------------- | -------------- | +| 0 | space-0 | space-0 | +| 1 px | space-100 | space-100 | +| 2 px | space-200 | space-200 | +| 4 px | space-300 | space-300 | +| 6 px | — | space-400 | +| 8 px | space-400 | space-500 | +| 12 px | space-500 | space-600 | +| 16 px | space-600 | space-700 | +| 20 px | — | space-800 | +| 24 px | space-700 | space-900 | +| 32 px | space-800 | space-1000 | +| 40 px | space-900 | space-1100 | +| 48 px | space-1000 | space-1200 | +| 56 px | — | space-1300 | +| 64 px | space-1100 | space-1400 | +| 72 px | — | space-1500 | +| 80 px | space-1200 | space-1600 | +| 96 px | — | space-1700 | + +If you are going to use fulltext search-and-replace in your project, we suggest you to start from the largest values and work your way down to the smallest ones. This way you will avoid replacing values you already replaced. -### Helpers: Typography `text` infix and Heading emphasis +### Helpers: Typography and Headings As the word `text` was omitted from the typography tokens, the typography helpers were updated to reflect this change. Also, the `heading` helpers were updated to @@ -86,13 +93,14 @@ support the emphasis. #### Migration Guide -From `body` typography helpers remove the `text` infix. +Remove the `text` infix from `body` typography helpers. For example: - `.typography-body-large-text-bold` → `.typography-body-large-bold` - `.typography-body-xsmall-text-regular` → `.typography-body-xsmall-regular` +More font weights are now available for headings. Rename `text` to `bold` in the `heading` helpers. For example: @@ -100,7 +108,7 @@ For example: - `.typography-heading-xlarge-text` → `.typography-heading-xlarge-bold` - `.typography-heading-xsmall-text` → `.typography-heading-xsmall-bold` -### Utilities: Removed and new classes +### Utilities: Removed and New Classes Some utility classes were removed and new ones were added. @@ -119,28 +127,28 @@ New utility classes: - `.bg-secondary` - `.bg-tertiary` -### Migrating product components +### Migrating Your Own Components -First, you need to update your tokens. You can either use Supernova to export -your tokens in new structure, or you can manually update your tokens or update +First, you need to update your design tokens. You can either use Supernova to export +your design tokens in new structure, or you can manually update your tokens, or update our tokens package if you are using it. -Here are some steps to migrate your product components to use the new tokens and themes: +Here are the steps to migrate your own components to use the new design tokens and themes: 1. If you load `foundation`, `components`, `helpers`, and `utilities` separately, you need - add `@forward 'themes';` before them in your main file. If you load whole `scss` folder, + to `@forward 'themes'` before them in your main SCSS file. If you load the whole `scss` folder, you don't need to do anything. 2. Replace module load `@use '@tokens' as tokens;` in your components with `@use '@global' as global-tokens;`. 3. Rename all the tokens in your components to use the new structure. 1. Replace all module name `tokens.*` → `global-tokens.*`. 2. Replace all spacing tokens with new values. See [Spacing values](#spacing-values) for more information. - 3. Replace all radius tokens with new values. We added new radius token in between, so you need to update them. - 4. Replace all typography tokens with new values. We removed `text` infix from typography tokens and added emphasized headings. - 5. Switch all color tokens to use CSS variables. You can use `globals` settings module to load prefix. - 6. If you used `$border-style` tokens, you need to replace them with direct values. - 7. If you used `$focus` token, you need to replace it with `$focus-ring` token. - 8. If you used `$grid-gutter` tokens, you need to replace them with `$grid-spacing` tokens. -4. That's it! You should now have your components updated to use the new tokens and themes. + 3. Replace all radius tokens with new values. We added new a radius token in between, so you need to update them. + 4. Replace all typography tokens with new values. We removed the `text` infix from typography tokens and added emphasized headings. + 5. Switch all color tokens to use CSS variables. Use the `token-prefix` tokens to set prefix. // TODO update this after implementing DS-1493 + 6. If you used `$border-style` tokens, you need to replace them with direct values (`solid`, `dashed`, etc.). + 7. If you used the `$focus` token, you need to replace it with the `$focus-ring` token. + 8. If you used `$grid-gutter` tokens, you need to replace them with equivalent `$grid-spacing` tokens. +4. That's it! You should now have your components updated to use the new design tokens and themes. 🎉 Here is a simple example of how to update your component styles: @@ -156,16 +164,15 @@ $gap: tokens.$space-400; After: ```scss -@use '@global' as global-tokens; -@use '@lmc-eu/spirit-web/scss/settings/globals' as globals; +@use '@global-tokens' as global-tokens; -$color: var(--#{globals.$prefix}color-text-primary); +$color: var(--#{global-tokens.$token-prefix}color-text-primary); $gap: global-tokens.$space-500; ``` ## Component Changes -### Button: `square` modifier renamed to `symmetrical` +### Button: `square` Modifier Renamed to `symmetrical` Button `square` modifier was renamed to `symmetrical`. @@ -177,4 +184,5 @@ Instead of using `.Button--square`, use a `.Button--symmetrical`. --- +[spirit-figma-file]: https://www.figma.com/design/w9Ca4hvkuYLshsrHu1bYwT/ [themes-decision]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/decisions/008-themes.md