@synergy-design-system/tokens 2.21.0 → 2.23.0

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 (16) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +231 -9
  3. package/dist/js/index.d.ts +517 -522
  4. package/dist/js/index.js +259 -264
  5. package/dist/scss/_tokens.scss +203 -204
  6. package/dist/themes/dark.css +204 -207
  7. package/dist/themes/light.css +204 -207
  8. package/dist/themes/sick2018_dark.css +268 -0
  9. package/dist/themes/sick2018_light.css +268 -0
  10. package/dist/themes/sick2025_dark.css +268 -0
  11. package/dist/themes/sick2025_light.css +268 -0
  12. package/package.json +20 -8
  13. package/src/figma-variables/output/sick2018-dark.json +1183 -0
  14. package/src/figma-variables/output/sick2018-light.json +1183 -0
  15. package/src/figma-variables/output/sick2025-dark.json +1183 -0
  16. package/src/figma-variables/output/sick2025-light.json +1183 -0
package/CHANGELOG.md CHANGED
@@ -1,3 +1,17 @@
1
+ # [@synergy-design-system/tokens-v2.23.0](https://github.com/synergy-design-system/synergy-design-system/compare/tokens/2.22.0...tokens/2.23.0) (2025-08-19)
2
+
3
+
4
+ ### Features
5
+
6
+ * ✨ export new sick2025 themes ([#985](https://github.com/synergy-design-system/synergy-design-system/issues/985)) ([148730d](https://github.com/synergy-design-system/synergy-design-system/commit/148730d68037ea74dc241ca6627aa6a32af876ab))
7
+
8
+ # [@synergy-design-system/tokens-v2.22.0](https://github.com/synergy-design-system/synergy-design-system/compare/tokens/2.21.0...tokens/2.22.0) (2025-08-07)
9
+
10
+
11
+ ### Features
12
+
13
+ * ✨ Synchronize tokens via Figma API to github ([#929](https://github.com/synergy-design-system/synergy-design-system/issues/929)) ([51f6aeb](https://github.com/synergy-design-system/synergy-design-system/commit/51f6aeb2e9407c1d808ee0be02d279ada0e3cac7))
14
+
1
15
  # [@synergy-design-system/tokens-v2.21.0](https://github.com/synergy-design-system/synergy-design-system/compare/tokens/2.20.1...tokens/2.21.0) (2025-07-09)
2
16
 
3
17
 
package/README.md CHANGED
@@ -23,8 +23,8 @@ As projects may use various forms of applying styles, we provide different ways
23
23
 
24
24
  ### Using CSS themes
25
25
 
26
- 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`.
27
- The tokens package ships with two themes: 🌞 light and 🌛 dark.
26
+ 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 one of the framework packages like `@synergy-design-system/react`.
27
+ The tokens package ships two **themes** (sick2018 and sick2025), with each providing two **modes**: 🌞 light and 🌛 dark.
28
28
 
29
29
  > The css styles are used as a single source of truth, also when working with the provided JavaScript or SASS exports!
30
30
  > Always make sure to load one of the css themes!
@@ -34,9 +34,11 @@ The tokens package ships with two themes: 🌞 light and 🌛 dark.
34
34
  <head>
35
35
  <!-- Example 1: Referencing directly in a HTML document -->
36
36
  <!-- Make sure to add the stylesheet before using any components -->
37
+ <!-- Note that "light.css" will point to the default theme of the tokens package. See table below for defaults -->
37
38
  <link rel="stylesheet" href="/node_modules/@synergy-design-system/tokens/dist/themes/light.css" />
38
39
 
39
40
  <!-- Alternative: Use the dark theme -->
41
+ <!-- Note that "dark.css" will point to the default theme of the tokens package. See table below for defaults -->
40
42
  <link rel="stylesheet" href="/node_modules/@synergy-design-system/tokens/dist/themes/dark.css" />
41
43
  </head>
42
44
  <body>
@@ -51,10 +53,12 @@ The tokens package ships with two themes: 🌞 light and 🌛 dark.
51
53
 
52
54
  You are also able to switch themes during the runtime. For the time being, we do not ship a utility function for this, as it is easy to implement. Each theme applies the variables via a `:root` selector, as well as a `className` that may be added to the `document.body`.
53
55
 
54
- | Theme | Stylesheet to use | Body className |
55
- | :---- | :------------------------ | :---------------- |
56
- | light | `tokens/themes/light.css` | `syn-theme-light` |
57
- | dark | `tokens/themes/dark.css` | `syn-theme-dark` |
56
+ | Theme | Mode | Stylesheet to use | Corresponding classNames | Default for Version |
57
+ | :------- | :---- | :--------------------------------- | :-------------------------------------- | :-----------------: |
58
+ | sick2018 | light | `tokens/themes/sick2018_light.css` | `syn-theme-light`, `syn-sick2018-light` | `2.0.0` |
59
+ | sick2018 | dark | `tokens/themes/sick2018_dark.css` | `syn-theme-dark`, `syn-sick2018-dark` | |
60
+ | sick2025 | light | `tokens/themes/sick2025_light.css` | `syn-sick2025-light` | `3.0.0` |
61
+ | sick2025 | dark | `tokens/themes/sick2025_dark.css` | `syn-sick2025-dark` | |
58
62
 
59
63
  To switch the theme, proceed in the following way:
60
64
 
@@ -103,7 +107,12 @@ To switch the theme, proceed in the following way:
103
107
  // Use this way when you already use a build system like webpack or vite
104
108
  // to make it part of your bundle.
105
109
  // Note this import should happen BEFORE you render any components!
110
+
111
+ // Light theme
106
112
  import "@synergy-design-system/tokens/themes/light.css";
113
+
114
+ // Dark theme
115
+ import "@synergy-design-system/tokens/themes/dark.css";
107
116
  ```
108
117
 
109
118
  ---
@@ -168,6 +177,13 @@ div {
168
177
  }
169
178
  ```
170
179
 
180
+ ### JSON files
181
+
182
+ Currently the raw .json tokens files are exported under `/src/figma-tokens/*/`.
183
+
184
+ > Note:
185
+ > These files are deprecated and will be removed in the new major version of Synergy, as the whole tokens structures are getting refactored.
186
+
171
187
  ---
172
188
 
173
189
  ## Optional: Configuring tokens in VSCode
@@ -184,16 +200,105 @@ Just make sure to add a valid path to the light theme in the `.vscode/settings.j
184
200
 
185
201
  ---
186
202
 
187
- ## Documentation
203
+ ## Developer Documentation
204
+
205
+ ### Architecture and Data Flow
206
+
207
+ ```
208
+ Figma
209
+ ↓
210
+ Figma REST API
211
+ ↓
212
+ Raw JSON Files (src/figma-variables/variableTokens.json + styleTokens.json)
213
+ ↓
214
+ Transform Scripts (scripts/figma/)
215
+ ↓
216
+ Style Dictionary compliant JSON Files (src/figma-variables/output/)
217
+ ↓
218
+ Style Dictionary Processing (scripts/build.js)
219
+ ↓
220
+ Build Output (dist/)
221
+ ```
188
222
 
189
223
  ### Building the tokens
190
224
 
225
+ Tokens are a mix of [Figma Variables](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma) and [Figma styles](https://help.figma.com/hc/en-us/articles/360039238753-Styles-in-Figma-Design). They are fetched from Figma via [Figma API](https://www.figma.com/developers/api).
226
+
227
+ To trigger a new fetching use `pnpm fetch:figma`, to update the tokens.
228
+ This scripts needs the figma access token and optionally the figma file id, so it knows, where it should fetch the tokens from. If not available, it fetches the tokens from the main (_bZFqk9urD3NlghGUKrkKCR_).
229
+
230
+ ```bash
231
+ # Required: Figma Personal Access Token
232
+ export FIGMA_TOKEN="your_figma_token_here"
233
+
234
+ # Optional: Specific Figma File/Branch ID (Default: Main Branch)
235
+ export FIGMA_FILE_ID="your_figma_file_id"
236
+ ```
237
+
238
+ ```bash
239
+ # Fetch all Figma data (Variables + Styles)
240
+ pnpm fetch:figma
241
+
242
+ # Only fetch variables and transform into Style Dictionary format
243
+ pnpm fetch:variables
244
+
245
+ # Only fetch styles and transform into Style Dictionary format
246
+ pnpm fetch:styles
247
+
248
+ # Transform already fetched variables into Style Dictionary format
249
+ pnpm build:variables
250
+
251
+ # Transform already fetched styles into Style Dictionary format
252
+ pnpm build:styles
253
+
254
+ # Process transformed tokens with Style Dictionary (build final output)
255
+ pnpm build
256
+ ```
257
+
258
+ #### Figma variables
259
+
260
+ The variables are created to support several modes.
261
+ Currently supported modes are:
262
+
263
+ - **sick2018-light**
264
+ - **sick2018-dark**
265
+ - **sick2025-light**
266
+ - **sick2025-dark**
267
+
268
+ For each mode a json file is created, with the corresponding tokens and values.
269
+
270
+ #### Figma styles
271
+
272
+ For the styles a separate `styles.json` is created.
273
+
274
+ #### Output
275
+
191
276
  Outputs of the tokens are created using [Style Dictionary](https://amzn.github.io/style-dictionary/).
192
- 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`).
277
+ You can trigger a build using `pnpm build` in the `tokens` package root. This will create the css themes (located in `dist/themes/` with files like `light.css`, `dark.css`, `sick2018_light.css`, `sick2018_dark.css`, `sick2025_light.css`, and `sick2025_dark.css`), as well as the JavaScript exports (located at `dist/js/index.js`) and scss variables (`dist/scss/_tokens.scss`).
193
278
 
194
279
  ---
195
280
 
196
- ### `add-missing-tokens.js`
281
+ ### Project structure
282
+
283
+ #### `/src/figma-variables/`
284
+
285
+ - **`variableTokens.json`**: Raw data of Figma Variables and Collections, directly fetched from the Figma API
286
+ - **`styleTokens.json`**: Raw data of Figma Styles, directly fetched from the Figma API
287
+ - **`output/`**: Transformed token files in Style Dictionary-compatible formats
288
+ - `sick2018-light.json`: Light Theme Tokens for SICK 2018
289
+ - `sick2018-dark.json`: Dark Theme Tokens for SICK 2018
290
+ - `sick2025-light.json`: Light Theme Tokens for SICK 2025
291
+ - `sick2025-dark.json`: Dark Theme Tokens for SICK 2025
292
+
293
+ #### `/scripts/figma/`
294
+
295
+ - **`fetch-variables.js`**: Downloads Figma Variables via the REST API
296
+ - **`style-dict-outputter.js`**: Custom outputter for Figma Styles export
297
+ - **`transform-tokens.js`**: Transforms Figma Variables into Style Dictionary format
298
+ - **`transform-styles.js`**: Transforms Figma Styles into Style Dictionary format
299
+ - **`helpers.js`**: Utility functions
300
+
301
+ #### `/scripts/add-missing-tokens.js`
197
302
 
198
303
  **Purpose**:
199
304
  This script is designed to inspect and append missing CSS variables based on a given prefix.
@@ -207,3 +312,120 @@ This script is designed to inspect and append missing CSS variables based on a g
207
312
  - `extractVariables(data, prefix)`: Extracts variables from the provided data based on the prefix.
208
313
  - `compareAndAppendVariables(sourceFilePath, targetFilePath, prefix)`: Compares source and target files for missing variables and appends them.
209
314
  - `addMissingTokens(prefix)`: Main function that loops through target files and checks for missing variables.
315
+
316
+ ### Github Action
317
+
318
+ The **Sync Figma variables to tokens** workflow (`.github/workflows/sync-figma-to-tokens.yml`) provides an automated way to synchronize design tokens from Figma to the codebase via GitHub Actions.
319
+
320
+ **Purpose**:
321
+ This workflow fetches the latest Figma variables and styles, transforms them into the appropriate token formats, runs tests to ensure integrity, and creates a pull request with the updated tokens.
322
+
323
+ **Trigger**:
324
+ The workflow is manually triggered using `workflow_dispatch` with configurable inputs.
325
+
326
+ **Input Parameters**:
327
+
328
+ - **`figma_file_id`** (required): The Figma file or branch ID to sync from
329
+ - Default: `"bZFqk9urD3NlghGUKrkKCR"` (main Synergy Design System file)
330
+ - Can be either a branch ID or the main file ID
331
+ - **`branch_name`** (required): Name for the new Git branch
332
+ - Default: `"feat/update-tokens-from-figma"`
333
+ - **`pull_request_name`** (required): Title for the pull request
334
+ - Default: `"feat: ✨ Update tokens from Figma"`
335
+
336
+ **Workflow Steps**:
337
+
338
+ 1. **Repository Setup**: Checks out the repository with full history
339
+ 2. **Environment Setup**: Installs pnpm, Node.js 22, and project dependencies
340
+ 3. **Token Synchronization**: Runs `pnpm -C ./packages/tokens fetch:figma && pnpm -C ./packages/tokens build:figma` to fetch and transform Figma data
341
+ 4. **Quality Assurance**: Builds and tests the updated tokens to ensure integrity
342
+ 5. **Pull Request Creation**: Creates a new branch and pull request with the changes
343
+
344
+ **Required Secrets**:
345
+
346
+ - **`FIGMA_TOKEN`**: Personal Access Token from Figma (required for API access)
347
+
348
+ **Permissions**:
349
+
350
+ The workflow requires the following permissions:
351
+
352
+ - `contents: write` - To create branches and commits
353
+ - `pull-requests: write` - To create pull requests
354
+
355
+ **Usage Example**:
356
+
357
+ 1. Navigate to the Actions tab in the GitHub repository
358
+ 2. Select "Sync Figma variables to tokens"
359
+ 3. Click "Run workflow"
360
+ 4. Configure the input parameters as needed
361
+ 5. Click "Run workflow" to start the process
362
+
363
+ The workflow will automatically create a pull request with reviewers assigned (`kirchsuSICKAG`, `schilchSICKAG`) for review and approval.
364
+
365
+ ---
366
+
367
+ ### Updating Test Files
368
+
369
+ When adding new tokens or changing existing token values, the test reference files in `packages/tokens/test/` must be updated to maintain test integrity.
370
+
371
+ #### Test System Overview
372
+
373
+ The token package includes a test system that validates the consistency between the built token files and reference files:
374
+
375
+ - **`test/light.css`**: Reference file containing expected CSS variables for the light theme
376
+ - **`test/dark.css`**: Reference file containing expected CSS variables for the dark theme
377
+ - **`test/test-css-variables.js`**: Test script that compares built files against reference files
378
+
379
+ #### When to Update Test Files
380
+
381
+ Test files need to be updated in the following scenarios:
382
+
383
+ 1. **Adding new tokens**: When new design tokens are added to Figma and fetched
384
+ 2. **Changing token values**: When existing token values are modified in Figma
385
+ 3. **Removing tokens**: When tokens are deprecated or removed from the design system
386
+
387
+ #### How to Update Test Files
388
+
389
+ After the new / updated tokens are fetched and build:
390
+
391
+ 1. **Build the tokens**: Ensure the latest tokens are built
392
+
393
+ ```bash
394
+ cd packages/tokens
395
+ pnpm build
396
+ ```
397
+
398
+ 2. **Run the comparison test**: This will show differences between built and reference files
399
+
400
+ ```bash
401
+ pnpm compare
402
+ ```
403
+
404
+ 3. **Update reference files**: If the changes are intentional, copy the built files to the test directory or update the files manually with the changes
405
+
406
+ ```bash
407
+ # Copy the newly built files to serve as new reference files
408
+ cp dist/themes/light.css test/light.css
409
+ cp dist/themes/dark.css test/dark.css
410
+ ```
411
+
412
+ 4. **Verify the update**: Run the test again to ensure everything matches
413
+ ```bash
414
+ pnpm compare
415
+ ```
416
+
417
+ #### Test Output
418
+
419
+ The test script provides detailed feedback:
420
+
421
+ - ✅ **Success**: When all variables match between built and reference files
422
+ - 🚫 **Missing variables**: Variables present in reference but missing in built files
423
+ - ➕ **Extra variables**: New variables in built files not present in reference
424
+ - 🔄 **Different values**: Variables with changed values between built and reference files
425
+
426
+ #### Important Notes
427
+
428
+ - Always review the test output carefully before updating reference files
429
+ - The reference files serve as a safeguard against unintended token changes
430
+
431
+ ---