Skip to content

Commit

Permalink
Docs(web): Document usage of the updated design tokens and themes #DS…
Browse files Browse the repository at this point in the history 
…-1489
  • Loading branch information
@adamkudrna @crishpeen
adamkudrna authored and crishpeen committed Nov 5, 2024
1 parent d0f1f55 commit cbc0e86
Show file tree
Hide file tree
Showing 3 changed files with 106 additions and 46 deletions.
36 changes: 21 additions & 15 deletions docs/migrations/web/MIGRATION-v3.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -152,36 +152,42 @@ Here are the steps to migrate your own components to use the new design tokens a
1. If you load `foundation`, `components`, `helpers`, and `utilities` separately, you need
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-tokens' as global-tokens;`.
3. Rename all the tokens in your components to use the new structure.
1. Replace module name in all variable usages: `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 a new radius token in between, so you need to update all of 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` token to set the 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. 🎉
2. Rename all the tokens in your components to use the new structure.
1. Replace all spacing tokens with new values. See [Spacing Values](#spacing-values) for more information.
2. Replace all radius tokens with new values. We added a new radius token in between, so you need to update all of them.
3. Replace all typography tokens with new values. We removed the `text` infix from typography tokens and added emphasized headings.
4. Revisit all color tokens to use the new structure.
5. If you used `$border-style` tokens, you need to replace them with direct values (`solid`, `dashed`, etc.).
6. If you used the `$focus` token, you need to replace it with the `$focus-ring` token.
7. If you used `$grid-gutter` tokens, you need to replace them with equivalent `$grid-spacing` tokens.
3. 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:

Before:

```scss
// _theme.scss

@use '@tokens' as tokens;

$color: tokens.$text-primary;
$border-style: tokens.$border-style-100;
$border-color: tokens.$border-secondary-default;
$background-color: tokens.$background-cover;
$gap: tokens.$space-400;
```

After:

```scss
@use '@global-tokens' as global-tokens;
// _theme.scss

@use '@tokens' as tokens;

$color: var(--#{global-tokens.$token-prefix}color-text-primary);
$gap: global-tokens.$space-500;
$border-style: solid;
$border-color: tokens.$border-basic;
$background-color: tokens.$background-primary; // This may require using the "light-on-brand" theme in HTML/JSX. Check with your designer.
$gap: tokens.$space-500;
```

## Component Changes
Expand Down
24 changes: 10 additions & 14 deletions packages/web/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,7 @@ Similarly, component's tools serve as a storage of component-scoped:

## Linking Design Tokens

Components can (and should!) reuse Spirit [design tokens][design-tokens].

Component's theme properties can be linked to design tokens. This way, the
Component's theme properties are very often linked to [design tokens][design-tokens]. This way, the
appearance of individual components is always unified and coherent: **anytime
design tokens change, all components are updated consistently.**

Expand All @@ -77,17 +75,16 @@ structure and naming.

### Sass Implementation

When contributing to Spirit Sass styles, always link Spirit design tokens via
the [`@tokens` API][tokens-api] with
[configured load path][configuring-load-path]. This is crucial for the
When contributing to Spirit Sass styles, always [link Spirit design tokens][design-tokens-in-sass]
with a [configured load path][design-tokens-in-sass]. This is crucial for the
[rebranding][rebranding] functionality of Spirit.

From the implementation point of view, design tokens are Sass variables
organized in Sass modules. Within component styles, Sass modules with design
tokens are referred to just by filename. However, because the modules do not
exist in the place they are called in (the [`spirit-design-tokens`][design-tokens] package is
stored in `node_modules`), the correct load path for the desired set of design
tokens must be [provided on build time][configuring-load-path]. This is the only
tokens must be [provided on build time][design-tokens-in-sass]. This is the only
way how Sass modules can be affected from outside, without giving in their
advantages.

Expand Down Expand Up @@ -136,13 +133,13 @@ The documentation should include these sections:
- `% yarn test` for test package (lint, format, unit testing, types)
- `% yarn test:unit` for unit tests

### SASS Unit Testing
### Sass Unit Testing

We use [sass-true][sass-true] for unit testing of our SASS components. The
We use [sass-true][sass-true] for unit testing of our Sass components. The
tests are located in `src/scss/components/<ComponentName>/__tests__` and are
named `<ComponentName>.test.scss`. The tests are run as a part of the Jest
testing suite. Our primary focus is on testing mixins and functions as they
are the most complex parts of our SASS components.
are the most complex parts of our Sass components.

## Migrating Your Components to Spirit

Expand All @@ -163,7 +160,7 @@ To make your code ready for rebranding before moving to Spirit:
```

2. Add the previously removed path to load paths of your Sass compiler.
See the [`spirit-design-tokens` docs][configuring-load-path] to learn how to
See the [`spirit-design-tokens` docs][design-tokens-in-sass] to learn how to
do that.

3. Try using another `@tokens` file with a different brand and see how your
Expand Down Expand Up @@ -218,10 +215,9 @@ To avoid conflicts, we need a convention to distinguish situations when somethin
</details>

[design-tokens]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens
[tokens-api]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#tokens-api
[configuring-load-path]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#configuring-load-path
[rebranding]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web#rebranding
[design-tokens-in-sass]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#in-sass
[design-tokens-faq]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#faq
[rebranding]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web#rebranding
[sass-modules]: https://sass-lang.com/blog/the-module-system-is-launched
[es-modules]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
[sass-true]: https://github.com/oddbird/true
92 changes: 75 additions & 17 deletions packages/web/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,17 +38,75 @@ Link the complete, vendor-prefixed and minimised CSS with default Spirit brandin

👉 Alternatively, you can use [CDN](#cdn) links when you don't want to install any npm packages.

### Theming

To enable component independent, **scoped changes of appearance**, Spirit Design System uses themes. You can use any of
the provided themes or [create your own](#custom-themes). Just include the theme CSS file before the foundation CSS file.
Given the naming convention `theme-<NAME OF THE THEME>`, you can easily switch the theme at any point in your HTML:

```html
<body class="text-primary bg-primary">
<p>This paragraph uses the default light theme.</p>
<section class="theme-light-on-brand bg-primary">
<p class="text-primary">This paragraph uses the light theme on brand background.</p>
</section>
</body>
```

### Advanced Implementation in Product with Sass

❗ **Important:** Make sure you have `sass` dependency installed in your project (`sass` is marked as optional peer dependency since you can use the pre-built distribution CSS).
And also [configure Sass load path][configuring-load-path] for `@tokens` and
`node_modules` so all dependencies are resolved correctly by Sass.
❗ **Important:** Make sure you have the `sass` dependency installed in your project (`sass` is marked as optional peer dependency since you can use the pre-built distribution CSS).
Also [configure Sass load path][design-tokens-load-path] for `@tokens`, `@themes`, and `node_modules` so all dependencies are resolved correctly by Sass.

Having the Sass load path configured, import just the components you need in
your Sass stylesheet:
Having the Sass load path configured, you can import just the components you need in your Sass stylesheet:

```scss
// my-product-styles.scss

// Spirit themes and foundation are mandatory
@use 'node_modules/@lmc-eu/spirit-web/scss/themes';
@use 'node_modules/@lmc-eu/spirit-web/scss/foundation';

// Spirit components can be hand-picked
@use 'node_modules/@lmc-eu/spirit-web/scss/components/Button';

// Spirit helpers and utilities are optional
@use 'node_modules/@lmc-eu/spirit-web/scss/helpers';
@use 'node_modules/@lmc-eu/spirit-web/scss/utilities';
```

### Custom Themes

#### Automatically: Using Figma and Supernova

The recommended way to create custom themes is using Figma and Supernova to define and export your design tokens, including their themed variants.
Once you have your design tokens, you can [use them in your Sass project][design-tokens-usage].

To generate actual themes based on provided design tokens, just include our `themes` file in your Sass project:

```scss
@use 'node_modules/@lmc-eu/spirit-web/scss/themes';
```

#### Manual Theme Creation

If you don't use Figma and Supernova or you need to theme just a small piece of your UI, you can create your own themes manually.
Just define your theme variables so they match the structure outlined in the
[`scss/themes/_color-tokens.scss`][design-tokens-color-tokens] file in the design tokens package.

For example:

```scss
@use '@tokens' as tokens;

:root,
.my-theme-light {
--#{tokens.$token-prefix}color-text-primary: #007bff;
}

.my-theme-dark {
--#{tokens.$token-prefix}color-text-primary: #beddff;
}
```

### Prefixing CSS Class Names
Expand Down Expand Up @@ -82,13 +140,13 @@ Some components require JavaScript plugins for their full functionality. You can

#### Individual or Compiled

Plugins can be included individually as an EcmaScript module (using `import { <plugin> } from '@lmc-eu/spirit-web'`, see [Using Spirit Web as a module](#using-spirit-web-as-a-module)), or all at once using `js/{cjs|esm|bundle}/spirit-web.js` or the minified `js/{cjs|esm|bundle}/spirit-web.min.js` (do not include both), all files are UMD ready.
Plugins can be included individually as an ECMAScript module (using `import { <plugin> } from '@lmc-eu/spirit-web'`, see [Using Spirit Web as a module](#using-spirit-web-as-a-module-in-browser)), or all at once using `js/{cjs|esm|bundle}/spirit-web.js` or the minified `js/{cjs|esm|bundle}/spirit-web.min.js` (do not include both), all files are UMD ready.

```html
<script src="node_modules/@lmc-eu/spirit-web/js/cjs/spirit-web.min.js" async></script>
```

If you use a bundler (Webpack, Rollup, ...), you can use `/js/*.js` files which are EcmaScript modules.
If you use a bundler (Webpack, Rollup, …), you can use `/js/*.js` files which are ECMAScript modules.

#### Using Spirit Web as a Module in Browser

Expand All @@ -107,11 +165,11 @@ We provide a version of Spirit Web as `ESM` (`spirit-web.esm.js` and `spirit-web
Nearly all Spirit-Web plugins can be enabled and configured through HTML alone with data attributes (our preferred way of using JavaScript functionality).
Be sure to only use one set of data attributes on a single element (e.g., you cannot trigger a tooltip and modal from the same button.).

ℹ️ For turning off this functionality just do not set the `data-spirit-toggle` attribute and use the Programnatic API.
ℹ️ For turning off this functionality just do not set the `data-spirit-toggle` attribute and use the Programmatic API.

> #### Selectors
>
> Currently to query DOM elements we use the native methods `querySelector` and `querySelectorAll` for performance reasons, so you have to use valid selectors.
> Currently, to query DOM elements we use the native methods `querySelector` and `querySelectorAll` for performance reasons, so you have to use valid selectors.
> If you use special selectors, for example: `collapse:Example` be sure to escape them.
#### Events
Expand Down Expand Up @@ -146,7 +204,7 @@ If you’d like to get a particular plugin instance, each plugin exposes a `getI
#### CSS Selectors in Constructors

You can also use a CSS selector as the first argument instead of a DOM element to initialize the plugin.
Currently the element for the plugin is found by the `querySelector` method since our plugins support a single element only.
Currently, the element for the plugin is found by the `querySelector` method since our plugins support a single element only.

```javascript
var modal = new Modal('#myModal');
Expand All @@ -170,10 +228,9 @@ Spirit Design System is also available on CDN:

## Rebranding

Design tokens and their [`@tokens` API][tokens-api] enable quick and easy
rebranding of Spirit Sass components and styles. Once you have created your own
design tokens, just provide them to your Sass compiler and you are ready to go!
Learn more in the [`spirit-design-tokens` docs][rebranding].
Design tokens enable quick and easy rebranding of Spirit Sass components and styles.
Once you have created your own design tokens, just provide them to your Sass compiler and you are ready to go!
Learn more in the [`spirit-design-tokens` docs][design-tokens-rebranding].

## Development

Expand All @@ -200,12 +257,13 @@ Check your browser console to see if you are using any of the deprecated functio

See the [LICENSE][license] file for information.

[configuring-load-path]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#configuring-load-path
[design-tokens-usage]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#basic-usage
[design-tokens-load-path]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#in-sass
[design-tokens-color-tokens]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/design-tokens/src/scss/themes/_color-tokens.scss
[design-tokens-rebranding]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#rebranding-spirit
[deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/static/deprecations-browser-console.png?raw=true
[examples]: https://spirit-design-system.netlify.app/packages/web/
[feature-flags-docs]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/contribution/feature-flags.md
[license]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/LICENSE.md
[postcss-prefix-selector]: https://www.npmjs.com/package/postcss-prefix-selector
[rebranding]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#b-via-load-path
[tokens-api]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/design-tokens#tokens-api
[vite]: https://vitejs.dev

0 comments on commit cbc0e86

Please sign in to comment.