@lmc-eu/spirit-design-tokens - npm Package Compare versions

Comparing version 2.1.2 to 3.0.0-alpha.0

CHANGELOG.md

@@ -6,2 +6,12 @@ # Change Log
 
+<a name="3.0.0-alpha.0"></a>
+
+# [3.0.0-alpha.0](https://github.com/lmc-eu/spirit-design-system/compare/@lmc-eu/spirit-design-tokens@2.1.2...@lmc-eu/spirit-design-tokens@3.0.0-alpha.0) (2024-10-17)
+
+### BREAKING CHANGES
+
+- **design-tokens:** Introduce new design tokens structure [#DS-1430](https://github.com/lmc-eu/spirit-design-system/issues/DS-1430) ([1cbfaf0](https://github.com/lmc-eu/spirit-design-system/commit/1cbfaf0))
+
+**Note:** Version bump only for package @lmc-eu/spirit-design-tokens
+
 <a name="2.1.2"></a>
@@ -8,0 +18,0 @@

package.json

 {
   "name": "@lmc-eu/spirit-design-tokens",
-  "version": "2.1.2",
+  "version": "3.0.0-alpha.0",
   "description": "Design tokens for Spirit Design System",
@@ -31,3 +31,3 @@ "license": "MIT",
     "build:js": "vite build",
-    "build:scss": "shx mkdir -p scss && shx cp -r src/scss/generated/* src/scss/@tokens.scss scss/",
+    "build:scss": "shx mkdir -p scss && shx cp -r src/scss/* scss/",
     "clean": "rimraf esm cjs umd scss types",
@@ -50,3 +50,3 @@ "lint": "npm-run-all --serial lint:scripts lint:styles",
   },
-  "gitHead": "4681801ad8248eac87c692fd3ac07e6e52c6651f"
+  "gitHead": "eda367a6bf7f76f4c64ccce48ac34b84a9645188"
 }

README.md

@@ -5,3 +5,3 @@ # @lmc-eu/spirit-design-tokens
 
-⚠️ Spirit design tokens are managed with and generated by [Supernova]. DO NOT EDIT MANUALLY!
+⚠️ Spirit design tokens are managed with and generated by [Supernova][supernova]. DO NOT EDIT MANUALLY!
 
@@ -11,127 +11,78 @@ ## Table of Contents
 1. [Available Design Tokens](#available-design-tokens)
+   1. [Global Tokens](#global-tokens)
+   2. [Theme Tokens](#theme-tokens)
 2. [Install](#install)
 3. [Basic Usage](#basic-usage)
-4. [`@tokens` API](#tokens-api)
+   1. [In JavaScript](#in-javascript)
+4. [Rebranding Spirit](#rebranding-spirit)
 5. [FAQ](#faq)
+6. [License](#license)
 
 ## Available Design Tokens
 
-| Category      | Supernova | Figma | Sass                 |
-| ------------- | --------- | ----- | -------------------- |
-| 🖼 Borders    | ✅        | ❌    | [`_borders.sass`]    |
-| 🎨 Colors     | ✅        | ✅    | [`_colors.sass`]     |
-| 🖌️ Gradients  | ✅        | ✅    | [`_gradients.sass`]  |
-| 📏️ Measures  | ✅        | ❌    | [`_measures.sass`]   |
-| ⚙️ Other      | ✅        | ❌    | [`_other.sass`]      |
-| 🎱 Radii      | ✅        | ❌    | [`_radii.sass`]      |
-| ⛱ Shadows    | ✅        | ✅    | [`_shadows.sass`]    |
-| 🔠 Typography | ✅        | ✅    | [`_typography.sass`] |
+Tokens are split into two categories: Global and Themes. Global tokens are
+shared across all themes, while the theme tokens are specific to a particular theme.
 
-## Install
+They are managed in our [Figma][spirit-figma] and exported to our [Supernova workspace][spirit-supernova].
 
-🙋🏻‍♂️ **Hold on! Do you already use [`spirit-web`]?** Then you don't need to
-install this package because `spirit-design-tokens` is installed automatically
-as a dependency of [`spirit-web`].
+All content in `src` is generated by Supernova and should not be edited manually.
 
-If you want to use just `spirit-design-tokens` alone in your project, run:
+The `scss` directory contains `@global.scss` and `@themes.scss` files linking all available tokens.
 
-```shell
-yarn add @lmc-eu/spirit-design-tokens
-```
+### Global Tokens
 
-or
+The category consists of these groups:
 
-```shell
-npm install --save @lmc-eu/spirit-design-tokens
-```
+- 🖼 Borders
+- 🖌️ Gradients
+- ⚙️ Other
+- 🎱 Radii
+- 🏖️ Shadows
+- 📏️ Spacing
+- 🔡 Typography
 
-## Basic Usage
+These tokens are shared globally and independently on themes.
 
-The recommended approach in Sass is to import all Spirit design tokens at once
-via the [`@tokens` API](#tokens-api):
+### Theme Tokens
 
-```scss
-@use 'sass:map';
-@use 'node_modules/@lmc-eu/spirit-design-tokens/scss/@tokens' as tokens;
+You can find the list of the themes in the `src/themes` directory. Each theme has
+its own directory with the same set of design tokens, but with different values.
 
-.MyComponentThatMightGoToSpiritInFuture {
-  font-family: map.get(tokens.$body-medium-text-regular, font-family);
-  color: tokens.$text-primary-default;
-}
-```
+Each theme consists of the same set of tokens, but with different values.
 
-This makes it easier to [migrate your code to Spirit][migrate-to-spirit] in the
-future.
+The category currently consists only of this group:
 
-<details>
-<summary>Optional: import by categories</summary>
+- 🎨 Colors
 
-You can also import individual design token files by categories, e.g.:
+We currently support two themes:
 
-```scss
-@use 'sass:map';
-@use 'node_modules/@lmc-eu/spirit-design-tokens/scss/colors';
-@use 'node_modules/@lmc-eu/spirit-design-tokens/scss/typography';
+- Light
+- Light Inverted
 
-.MyComponent {
-  font-family: map.get(typography.$body-medium-text-regular, font-family);
-  color: colors.$text-primary-default;
-}
-```
+Where the former is the default and both of them can be used on the same page.
 
-This approach is a bit more descriptive and thus provides slightly better
-developer experience. You may find it more convenient in situations you
-**don't** suppose your code will make its way to Spirit as this approach is
-incompatible with `@tokens` API that makes rebranding possible.
+## Install
 
-</details>
+🙋🏻‍♂️ **Hold on! Do you already use [`spirit-web`][web-docs]?** Then you don't need to
+install this package because `spirit-design-tokens` is installed automatically
+as a dependency of `spirit-web`.
 
-### In JavaScript
+If you want to use just `spirit-design-tokens` alone in your project, run:
 
-Additionally the design tokens are also provided as a JavaScript object.
+```shell
+yarn add @lmc-eu/spirit-design-tokens
+```
 
-```js
-import * as SpiritDesignTokens from '@lmc-eu/spirit-design-tokens';
+or
 
-const desktopBreakpoint = SpiritDesignTokens.breakpoints.desktop;
+```shell
+npm install --save @lmc-eu/spirit-design-tokens
 ```
 
-The structure is the same as in the SASS.
+## Basic Usage
 
-## `@tokens` API
+SCSS is the primary language for styling Spirit components.
 
-`@tokens` API enables quick and easy rebranding of Spirit Sass styles by
-[replacing the path](#b-via-load-path) to design tokens. You need to be familiar
-with it if you are building your custom design system based on Spirit or you are
-going to contribute to Spirit.
+The best way to use the design tokens is to load their path in SASS:
 
-### Accessing `@tokens`
-
-#### a) via full path
-
-Access Spirit design tokens via the `@tokens` API without having to configure
-load path, just like shown in the [basic example](#basic-usage). This is a good
-choice for starting off quickly. However, it **doesn't enable rebranding**.
-
-#### b) via load path
-
-To get ready for rebranding, access Spirit design tokens via the `@tokens` API
-while keeping them open to be replaced by another set of design tokens:
-
-```scss
-@use 'sass:map';
-@use '@tokens' as tokens;
-
-.MyComponentThatIsReadyForSpirit {
-  font-family: map.get(tokens.$body-medium-text-regular, font-family);
-  color: tokens.$text-primary-default;
-}
-```
-
-##### Configuring Load Path
-
-Because the `@tokens` file doesn't exist locally, tell Sass where it should
-look for unreachable files. This is also a required step if you are importing
-Spirit components from their Sass source.
-
 ```shell
@@ -141,4 +92,6 @@ sass --load-path=node_modules/@lmc-eu/spirit-design-tokens/scss my-styles.scss
 
+Or integrate them into your build system:
+
 <details>
-<summary>Or with Webpack and <code>sass-loader</code>:</summary>
+<summary>Webpack example with <code>sass-loader</code>:</summary>
 
@@ -175,22 +128,71 @@ ```javascript
 
-### Exposing Your Custom Design Tokens
+<details>
+<summary>Vite example:</summary>
 
-In Spirit, the [`@tokens.scss`] file simply @forwards all design tokens exposed
-by [`index.scss`] which in turn @forwards all design token categories. To make
-your design tokens compatible with Spirit, just create a `@tokens.scss` file and
-@forward all your design tokens through it, e.g.:
+```javascript
+// vite.config.js
 
+// …
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  css: {
+    preprocessorOptions: {
+      scss: {
+        includePaths: [path.resolve(__dirname, 'node_modules/@lmc-eu/spirit-design-tokens/scss')],
+      },
+    },
+  },
+});
+// …
+```
+
+</details>
+
+This way the [`spirit-web`][web-docs] package or your own components can simply reach token values like this:
+
 ```scss
-// @tokens.scss
+@use 'sass:map';
+@use '@global' as global-tokens;
 
-@forward 'borders';
-@forward 'colors';
-@forward 'gradients';
-@forward 'measures';
-@forward 'other';
-@forward 'radii';
-@forward 'shadows';
-@forward 'typography';
+.MyComponentThatMightGoToSpiritInFuture {
+  font-family: map.get(global-tokens.$body-1-regular, font-family);
+  margin-bottom: global-tokens.$space-300;
+}
 ```
 
+For your components you can also load the token files directly:
+
+```scss
+@use 'node_modules/@lmc-eu/spirit-design-tokens/scss/@global' as global-tokens;
+```
+
+As mentioned, all themes contain the same set of tokens, so to use them you need to either
+choose which theme you want to use and load it directly or use the `@themes` file to
+generate CSS variables and use them in your components. The [`spirit-web`][web-docs] package does
+this for you.
+
+### In JavaScript
+
+Additionally the design tokens are also provided as a JavaScript object.
+
+```js
+import * as SpiritDesignTokens from '@lmc-eu/spirit-design-tokens';
+
+const desktopBreakpoint = SpiritDesignTokens.breakpoints.desktop;
+```
+
+The structure is the same as in the SASS.
+
+## Rebranding Spirit
+
+The system is designed to be easily rebranded. To do so, you need to provide
+your own design tokens and use `@global` and `@themes` files. Then forward your tokens
+to these files and set the correct load path for your project.
+
+Your tokens should contain the same structure as the Spirit tokens. The simplest
+way to do this is to have the same structure in your Figma file and export it
+using Supernova. If that's not possible, you can copy our tokens and adjust their values
+to your needs. You can also add new tokens required by your design system.
+
 ## FAQ
@@ -200,11 +202,11 @@
 <summary>
-Why do I need to rename <code>@tokens</code> to <code>tokens</code> when @using?
+Why do I need to rename <code>@global</code> to <code>global-tokens</code> when @using?
 </summary>
 
-Because @using the `@tokens` module without renaming would produce an error:
+Because @using the `@global` module without renaming would produce an error:
 
 ```log
-Error: Invalid Sass identifier "@tokens"
+Error: Invalid Sass identifier "@global"
   ╷
-1 │ @use '@tokens';
+1 │ @use '@global';
   │ ^^^^^^^^^^^^^^
@@ -218,3 +220,3 @@ ```
 
-We prefix the `@tokens.scss` file with `@` to differentiate it from other Sass
+We prefix the `@global.scss` file with `@` to differentiate it from other Sass
 files in the directory.
@@ -225,3 +227,3 @@
 inside Sass files. As a result, it's clear why e.g. `@use 'tools'` refers to
-a local file and `@use '@tokens'` does not. However, **it's only a naming
+a local file and `@use '@global'` does not. However, **it's only a naming
 convention,** there is no special tooling or configuration for Sass partials
@@ -231,3 +233,3 @@ starting with `@`.
 Imported module **needs to be renamed to be compatible with SCSS** syntax
-when it's used later on. That's why `@use '@tokens' as tokens`.
+when it's used later on. That's why `@use '@global' as global-tokens`.
 
@@ -243,3 +245,3 @@ Look at the following snippets and compare which one offers better
 @use 'tools'; // Calls './_tools.scss'. You don't have to explain this to me.
-@use 'tokens'; // Wait, this file doesn't exist… What's going on here? Is it
+@use 'global'; // Wait, this file doesn't exist… What's going on here? Is it
 // an error?
@@ -254,3 +256,3 @@ ```
 @use 'tools'; // Calls './_tools.scss'.
-@use '@tokens' as tokens; // OK, './[e-mail]' is not here, but the at-sign
+@use '@global' as global-tokens; // OK, './[e-mail]' is not here, but the at-sign
 // prefix suggests a special behavior. Maybe I'll learn more in the docs?
@@ -279,6 +281,18 @@ ```
 To make your Sass design tokens compatible with Spirit, don't forget to expose
-them via your custom [`@tokens` API](#tokens-api).
+them via Sass load path.
 
 </details>
 
+<details>
+<summary>Do I need themes? And if so, how many?</summary>
+
+You need at least one theme to define the default values for your design tokens.
+If you want to support multiple themes, you can add more. The number of themes
+is up to you and your design system requirements.
+
+But remember, each theme should contain the same set of tokens, just with different
+values. This way, you can switch between themes without changing your components.
+
+</details>
+
 ## License
@@ -288,14 +302,5 @@
 
+[spirit-figma]: https://www.figma.com/design/w9Ca4hvkuYLshsrHu1bYwT/
+[spirit-supernova]: https://spirit.design/
 [supernova]: https://spirit.supernova-docs.io
-[`@tokens.scss`]: src/scss/@tokens.scss
-[`index.scss`]: src/scss/index.scss
-[`_borders.sass`]: src/scss/generated/_borders.scss
-[`_colors.sass`]: src/scss/generated/_colors.scss
-[`_gradients.sass`]: src/scss/generated/_gradients.scss
-[`_measures.sass`]: src/scss/generated/_measures.scss
-[`_other.sass`]: src/scss/generated/_other.scss
-[`_radii.sass`]: src/scss/generated/_radii.scss
-[`_shadows.sass`]: src/scss/generated/_shadows.scss
-[`_typography.sass`]: src/scss/generated/_typography.scss
-[`spirit-web`]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web
-[migrate-to-spirit]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/CONTRIBUTING.md#migrating-your-components-to-spirit
+[web-docs]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web#readme

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

167167

increased by24.03%

Number of package files

30

increased by15.38%

Number of lines in readme file

295

increased by1.72%

Worsened metrics

Number of low quality alerts

2

increased by100%

No dependency changes