Skip to content

Commit

Permalink
fixup! Docs(web): Introduce General Changes into the Migration Guide …
Browse files Browse the repository at this point in the history 
…#DS-1489
  • Loading branch information
@crishpeen
crishpeen committed Oct 17, 2024
1 parent db21506 commit cbfc143
Showing 1 changed file with 71 additions and 63 deletions.
134 changes: 71 additions & 63 deletions docs/migrations/web/MIGRATION-v3.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,99 +8,107 @@ 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
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:

- `.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.

Expand All @@ -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:

Expand All @@ -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`.

Expand All @@ -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:/lmc-eu/spirit-design-system/blob/main/docs/decisions/008-themes.md

0 comments on commit cbfc143

Please sign in to comment.