From cbc0e86db19859ecff103bf1c86601d9c95414fe Mon Sep 17 00:00:00 2001 From: Adam Kudrna Date: Tue, 29 Oct 2024 16:41:17 +0100 Subject: [PATCH] Docs(web): Document usage of the updated design tokens and themes #DS-1489 --- docs/migrations/web/MIGRATION-v3.md | 36 ++++++----- packages/web/CONTRIBUTING.md | 24 ++++---- packages/web/README.md | 92 +++++++++++++++++++++++------ 3 files changed, 106 insertions(+), 46 deletions(-) diff --git a/docs/migrations/web/MIGRATION-v3.md b/docs/migrations/web/MIGRATION-v3.md index f9b1ea2194..a56d73f18b 100644 --- a/docs/migrations/web/MIGRATION-v3.md +++ b/docs/migrations/web/MIGRATION-v3.md @@ -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 diff --git a/packages/web/CONTRIBUTING.md b/packages/web/CONTRIBUTING.md index d2ee0fc3d5..d97e5cecad 100644 --- a/packages/web/CONTRIBUTING.md +++ b/packages/web/CONTRIBUTING.md @@ -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.** @@ -77,9 +75,8 @@ 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 @@ -87,7 +84,7 @@ 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. @@ -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//__tests__` and are named `.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 @@ -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 @@ -218,10 +215,9 @@ To avoid conflicts, we need a convention to distinguish situations when somethin [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 diff --git a/packages/web/README.md b/packages/web/README.md index 8f787da526..f64b1b3a53 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -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-`, you can easily switch the theme at any point in your HTML: + +```html + +

This paragraph uses the default light theme.

+
+

This paragraph uses the light theme on brand background.

+
+ +``` + ### 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 @@ -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 { } 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 { } 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 ``` -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 @@ -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 @@ -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'); @@ -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 @@ -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