@synergy-design-system/tokens 1.0.0-main.5 → 1.0.0-main.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +126 -31
  3. package/dist/js/index.js +934 -0
  4. package/dist/scss/_tokens.scss +190 -0
  5. package/dist/{css → themes}/dark.css +12 -8
  6. package/dist/{css → themes}/light.css +12 -8
  7. package/package.json +9 -2
  8. package/src/figma-tokens/$metadata.json +13 -0
  9. package/src/figma-tokens/$themes.json +331 -0
  10. package/src/figma-tokens/_docs.json +1212 -0
  11. package/src/figma-tokens/color/dark.json +286 -0
  12. package/src/figma-tokens/color/light.json +286 -0
  13. package/src/figma-tokens/color/primitives.json +292 -0
  14. package/src/figma-tokens/globals.json +415 -0
  15. package/src/figma-tokens/semantic/button.json +18 -0
  16. package/src/figma-tokens/semantic/focus-ring.json +16 -0
  17. package/src/figma-tokens/semantic/input.json +272 -0
  18. package/src/figma-tokens/semantic/toggles.json +16 -0
package/CHANGELOG.md CHANGED
@@ -1,3 +1,10 @@
1
+ # [@synergy-design-system/tokens-v1.0.0-main.6](https://github.com/SickDesignSystem/synergy/compare/tokens/1.0.0-main.5...tokens/1.0.0-main.6) (2023-11-07)
2
+
3
+
4
+ ### Features
5
+
6
+ * ✨ add scss and js support for tokens ([#120](https://github.com/SickDesignSystem/synergy/issues/120)) ([1830066](https://github.com/SickDesignSystem/synergy/commit/1830066b12a061013a4fb67adaf0856de11f5e9a))
7
+
1
8
  # [@synergy-design-system/tokens-v1.0.0-main.5](https://github.com/SickDesignSystem/synergy/compare/tokens/1.0.0-main.4...tokens/1.0.0-main.5) (2023-11-07)
2
9
 
3
10
 
package/README.md CHANGED
@@ -1,54 +1,149 @@
1
- ## Documentation
1
+ # @synergy-design-system/tokens
2
+
3
+ This package provides the design tokens that form the base for all components of the synergy design system.
4
+ It provides multiple exports that can be consumed in applications.
2
5
 
3
6
  ---
4
7
 
5
- ### `add-missing-tokens.js`
8
+ ## Installation
6
9
 
7
- **Purpose**:
8
- This script is designed to inspect and append missing CSS variables based on a given prefix.
10
+ Please make sure to install the tokens package as a dependency:
9
11
 
10
- - It reads from a source directory containing fallback styles and checks against a target directory for missing variables.
11
- - Variables are extracted based on a specified prefix.
12
- - Missing variables are appended to the target files.
12
+ ```bash
13
+ npm install --save @synergy-design-system/tokens
14
+ ```
13
15
 
14
- **Key Functions**:
16
+ ---
15
17
 
16
- - `extractVariables(data, prefix)`: Extracts variables from the provided data based on the prefix.
17
- - `compareAndAppendVariables(sourceFilePath, targetFilePath, prefix)`: Compares source and target files for missing variables and appends them.
18
- - `addMissingTokens(prefix)`: Main function that loops through target files and checks for missing variables.
18
+ ## Provided tokens
19
+
20
+ As projects may use various forms of applying styles, we provide different ways to consume our tokens.
21
+
22
+ ### Using CSS themes
23
+
24
+ Provides the css variables that are used in synergy components as css variables and is **required** if you are using `@synergy-design-system/components` or a derived package like `@synergy-design-system/react`.
25
+ The tokens package ships with two themes: 🌞 light and 🌛 dark.
26
+
27
+ > The css styles are used as a single source of truth, also when working with the provided JavaScript or SASS exports!
28
+ > Always make sure to load one of the css themes!
29
+
30
+ ```html
31
+ <!DOCTYPE html>
32
+ <head>
33
+ <!-- Example 1: Referencing directly in a HTML document -->
34
+ <!-- Make sure to add the stylesheet before using any components -->
35
+ <link rel="stylesheet" href="/node_modules/@synergy-design-system/tokens/themes/light.css" />
36
+
37
+ <!-- Alternative: Use the dark theme -->
38
+ <link rel="stylesheet" href="/node_modules/@synergy-design-system/tokens/themes/dark.css" />
39
+ </head>
40
+ <body>
41
+ <div style="background: var(--syn-color-primary-500)">
42
+ Content
43
+ </div>
44
+ </body>
45
+ </html>
46
+ ```
47
+
48
+ ```javascript
49
+ // Example 2: Importing for bundlers
50
+ // In most build systems, you will be able to import css files directly
51
+ // Use this way when you already use a build system like webpack or vite
52
+ // to make it part of your bundle.
53
+ // Note this import should happen BEFORE you render any components!
54
+ import '@synergy-design-system/tokens/themes/light.css';
55
+ ```
19
56
 
20
57
  ---
21
58
 
22
- ### `build-tokens.js`
59
+ ### Usage in JavaScript
23
60
 
24
- **Purpose**:
25
- This script utilizes the `StyleDictionary` package to build design tokens and manage theme generation.
61
+ We provide JavaScript exports for the design tokens.
62
+ All tokens map to the corresponding css variables to make sure we have a single source of truth.
63
+
64
+ ```javascript
65
+ // Using variables in JavaScript
26
66
 
27
- - It has custom transformations and formats tailored for the project's needs.
28
- - Custom transformations include adding color names, providing fallback fonts, and others.
29
- - A custom format for outputting the generated tokens is also defined.
67
+ // Import the css variables first as they are our single source of truth
68
+ import '@synergy-design-system/tokens/themes/light.css';
30
69
 
31
- **Key Classes**:
70
+ // Imports all tokens
71
+ import * as tokens from '@synergy-design-system/tokens';
32
72
 
33
- - `TokenBuilder`:
34
- - `constructor({ sourcePaths, buildPath, prefix })`: Sets up paths and options for building tokens.
35
- - `init()`: Registers custom transforms and formats.
36
- - `registerTransforms()`: Registers custom token transformations.
37
- - `registerFormat(prefix)`: Registers a custom token format.
38
- - `buildTokens()`: Builds design tokens based on configurations.
73
+ // Set the background color of a queried div via JavaScript
74
+ const elm = document.querySelector('div');
75
+ div.style.backgroundColor = tokens.SynColorPrimary500;
76
+
77
+ // Get the value
78
+ console.log(div.style.backgroundColor);
79
+ // Will print 'var(--syn-color-primary-500)'
80
+ ```
39
81
 
40
82
  ---
41
83
 
42
- ### `create-themes.js`
84
+ ### Usage in SCSS:
85
+
86
+ Our variables are also available as scss variables that make it possible to consume them in sass based projects.
87
+
88
+ ```scss
89
+ // Import the design tokens first.
90
+ // This can be done in a sass file or in any other way described above.
91
+ // Make sure to NOT add the .css file suffix, this will not work in sass
92
+ @import "~@synergy-design-system/tokens/themes/light";
93
+
94
+ // Import the scss variables
95
+ @import "@synergy-design-system/tokens/scss/tokens";
96
+
97
+ div {
98
+ background: $SynColorPrimary500;
99
+ }
100
+
101
+ // This will render the following output:
102
+ :root {
103
+ --syn-color-primary-500: #0ca2eb;
104
+ }
105
+
106
+ div {
107
+ background: var(--syn-color-primary-500);
108
+ }
109
+ ```
110
+
111
+ ---
112
+
113
+ ## Optional: Configuring tokens in VSCode
114
+
115
+ Using VSCode?
116
+ You may also want to install vunguyentuan.vscode-css-variables to include css variable auto completion in your project.
117
+ Just make sure to add a valid path to the light theme in the `.vscode/settings.json` file like this:
118
+
119
+ ```json
120
+ "cssVariables.lookupFiles": [
121
+ "node_modules/@synergy-design-system/tokens/themes/light.css"
122
+ ],
123
+ ```
124
+
125
+ ---
126
+
127
+ ## Documentation
128
+
129
+ ### Building the tokens
130
+
131
+ Outputs of the tokens are created using [Style Dictionary](https://amzn.github.io/style-dictionary/).
132
+ You can trigger a build using `pnpm build` in the `tokens` package root. This will create the css themes (located in `dist/themes/light.css` and `dist/themes/dark.css`), as well as the JavaScript exports (located at `dist/js/index.js`) and scss variables (`dist/scss/_tokens.scss`).
133
+
134
+ ---
135
+
136
+ ### `add-missing-tokens.js`
43
137
 
44
138
  **Purpose**:
45
- This script orchestrates the theme creation process by utilizing the `TokenBuilder` and `addMissingTokens` functionalities.
139
+ This script is designed to inspect and append missing CSS variables based on a given prefix.
46
140
 
47
- - It specifies source paths for the design tokens and the destination path for the generated themes.
48
- - After creating the themes with `TokenBuilder`, it ensures any missing tokens are added.
141
+ - It reads from a source directory containing fallback styles and checks against a target directory for missing variables.
142
+ - Variables are extracted based on a specified prefix.
143
+ - Missing variables are appended to the target files.
49
144
 
50
145
  **Key Functions**:
51
146
 
52
- - `createThemes()`: The main function that sets up the `TokenBuilder`, initiates the token building process, and then ensures all tokens are present.
53
-
54
- **To run this script and fetch the tokens you will have to navigate to the *tokens* package folder and write on the terminal: *'pnpm build'*.**
147
+ - `extractVariables(data, prefix)`: Extracts variables from the provided data based on the prefix.
148
+ - `compareAndAppendVariables(sourceFilePath, targetFilePath, prefix)`: Compares source and target files for missing variables and appends them.
149
+ - `addMissingTokens(prefix)`: Main function that loops through target files and checks for missing variables.