@synergy-design-system/tokens

v3.5.0

Published

2 days ago

Design tokens for Synergy, the SICK Design System

0High
0Medium
0Low

schilchsickag

kirchsusickag

klaarse_sickag

SDS SICK Synergy Design System Design Tokens

@synergy-design-system/tokens

This package provides the design tokens that form the base for all components of the Synergy Design System. It provides exports for colors, spacings, shadows, sizings, typography and more that can be also consumed by applications directly.

The source of the tokens can be found at Figma

Installation

Please make sure to install the tokens package as a dependency:

npm install --save @synergy-design-system/tokens

For best compliance, please make sure to install the same version that is also used in your @synergy-design-system/components package!

Provided tokens

As projects may use various forms of applying styles, we provide different ways to consume our tokens.

Using CSS themes

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. The tokens package ships two themes (sick2018 and sick2025), with each providing two modes: 🌞 light and 🌛 dark.

The css styles are used as a single source of truth, also when working with the provided JavaScript or SASS exports! Always make sure to load one of the css themes!

<!DOCTYPE html>
  <head>
    <!-- Example 1: Referencing directly in a HTML document -->
    <!-- Make sure to add the stylesheet before using any components -->
    <!-- Note that "light.css" will point to the default theme of the tokens package. See table below for defaults -->
    <link rel="stylesheet" href="/node_modules/@synergy-design-system/tokens/dist/themes/light.css" />

    <!-- Alternative: Use the dark theme -->
    <!-- Note that "dark.css" will point to the default theme of the tokens package. See table below for defaults -->
    <link rel="stylesheet" href="/node_modules/@synergy-design-system/tokens/dist/themes/dark.css" />
  </head>
  <body>
    <div style="background: var(--syn-color-primary-500)">
      Content
    </div>
  </body>
</html>

Switching themes during runtime

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.

To switch the theme, proceed in the following way:

<!DOCTYPE html>
  <head>
    <!--
      -- Load both themes initially.
      -- The last theme will be the default, in this case the light theme
    -->
    <link rel="stylesheet" href="/node_modules/@synergy-design-system/tokens/dist/themes/dark.css" />
    <link rel="stylesheet" href="/node_modules/@synergy-design-system/tokens/dist/themes/light.css" />
  </head>
  <body>
    <button id="theme-switch">Switch Theme</button>
    <script>
    const switchTheme = ({ target }) => {
      const { body } = document;
      const currentTheme = body.classList.contains('syn-theme-dark') ? 'dark' : 'light';

      if (currentTheme === 'light') {
        // Light theme
        body.classList.remove('syn-theme-light');
        body.classList.add('syn-theme-dark');
        target.innerText = 'Switch to light theme';
      } else {
        // Dark theme
        body.classList.remove('syn-theme-dark');
        body.classList.add('syn-theme-light');
        target.innerText = 'Switch to dark theme';
      }
    }

    document
      .querySelector('#theme-switch')
      .addEventListener('click', switchTheme);
    </script>
  </body>
</html>

// Example 2: Importing for bundlers
// In most build systems, you will be able to import css files directly
// Use this way when you already use a build system like webpack or vite
// to make it part of your bundle.
// Note this import should happen BEFORE you render any components!

// Light theme
import "@synergy-design-system/tokens/themes/light.css";

// Dark theme
import "@synergy-design-system/tokens/themes/dark.css";

Usage in JavaScript

We provide JavaScript exports for the design tokens. All tokens map to the corresponding css variables to make sure we have a single source of truth.

// Using variables in JavaScript

// Import the css variables first as they are our single source of truth
import "@synergy-design-system/tokens/themes/light.css";

// Imports all tokens
import * as tokens from "@synergy-design-system/tokens";

// Set the background color of a queried div via JavaScript
const elm = document.querySelector("div");
div.style.backgroundColor = tokens.SynColorPrimary500;

// Get the value
console.log(div.style.backgroundColor);
// Will print 'var(--syn-color-primary-500)'

Usage in SCSS:

Our variables are also available as scss variables that make it possible to consume them in sass based projects.

Note that because of the complexity of sass based toolchains (e.g. vite ones differ from webpack ones and there are multiple loaders for node_modules), we only show examples using the relative path to the filesystem. Configuration for those systems is NOT part of this guide.

// ! All paths are relative, we assume your input file is named src/example.scss

// Import the design tokens first.
// This can be done in a sass file or in any other way described above.
// Make sure to NOT add the .css file suffix, this will not work in sass
@import "../node_modules/@synergy-design-system/tokens/dist/themes/light";

// Import the scss variables
@import "../node_modules/@synergy-design-system/tokens/dist/scss/tokens";

// You are now able to use the provided tokens
div {
  background: $SynColorPrimary500;
}

// When compiled, this should render the following output
:root,
.syn-theme-light {
  // Other syn- variables truncated
  --syn-color-primary-500: #0ca2eb;
}

div {
  background: var(--syn-color-primary-500);
}

JSON files

Currently the raw .json tokens files are exported under /src/figma-tokens/*/.

Note: These files are deprecated and will be removed in the new major version of Synergy, as the whole tokens structures are getting refactored.

Optional: Configuring tokens in VSCode

Using VSCode? You may also want to install vunguyentuan.vscode-css-variables to include css variable auto completion in your project. Just make sure to add a valid path to the light theme in the .vscode/settings.json file like this:

"cssVariables.lookupFiles": [
    "node_modules/@synergy-design-system/tokens/dist/themes/light.css"
],

Developer Documentation

Architecture and Data Flow

Figma
    ↓
Figma REST API
    ↓
Raw JSON Files (src/figma-variables/variableTokens.json + styleTokens.json)
    ↓
Transform Scripts (scripts/figma/)
    ↓
Style Dictionary compliant JSON Files (src/figma-variables/output/)
    ↓
Style Dictionary Processing (scripts/build.js)
    ↓
Build Output (dist/)

Building the tokens

Tokens are a mix of Figma Variables and Figma styles. They are fetched from Figma via Figma API.

To trigger a new fetching use pnpm fetch:figma, to update the tokens. 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).

# Required: Figma Personal Access Token
export FIGMA_TOKEN="your_figma_token_here"

# Optional: Specific Figma File/Branch ID (Default: Main Branch)
export FIGMA_FILE_ID="your_figma_file_id"

# Fetch all Figma data (Variables + Styles)
pnpm fetch:figma

# Only fetch variables and transform into Style Dictionary format
pnpm fetch:variables

# Only fetch styles and transform into Style Dictionary format
pnpm fetch:styles

# Transform already fetched variables into Style Dictionary format
pnpm build:variables

# Transform already fetched styles into Style Dictionary format
pnpm build:styles

# Process transformed tokens with Style Dictionary (build final output)
pnpm build

# Or do it all at once
FIGMA_FILE_ID="FILE_ID" FIGMA_TOKEN="FIGMA_TOKEN" pnpm build:all

Figma variables

The variables are created to support several modes. Currently supported modes are:

sick2018-light
sick2018-dark
sick2025-light
sick2025-dark

For each mode a json file is created, with the corresponding tokens and values.

Figma styles

For the styles a separate styles.json is created.

Output

Outputs of the tokens are created using Style Dictionary. 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).

Project structure

`/src/figma-variables/`

variableTokens.json: Raw data of Figma Variables and Collections, directly fetched from the Figma API
styleTokens.json: Raw data of Figma Styles, directly fetched from the Figma API
output/: Transformed token files in Style Dictionary-compatible formats
- sick2018-light.json: Light Theme Tokens for SICK 2018
- sick2018-dark.json: Dark Theme Tokens for SICK 2018
- sick2025-light.json: Light Theme Tokens for SICK 2025
- sick2025-dark.json: Dark Theme Tokens for SICK 2025

`/scripts/figma/`

fetch-variables.js: Downloads Figma Variables via the REST API
style-dict-outputter.js: Custom outputter for Figma Styles export
transform-tokens.js: Transforms Figma Variables into Style Dictionary format
transform-styles.js: Transforms Figma Styles into Style Dictionary format
helpers.js: Utility functions

`/scripts/add-missing-tokens.js`

Purpose:
This script is designed to inspect and append missing CSS variables based on a given prefix.

It reads from a source directory containing fallback styles and checks against a target directory for missing variables.
Variables are extracted based on a specified prefix.
Missing variables are appended to the target files.

Key Functions:

extractVariables(data, prefix): Extracts variables from the provided data based on the prefix.
compareAndAppendVariables(sourceFilePath, targetFilePath, prefix): Compares source and target files for missing variables and appends them.
addMissingTokens(prefix): Main function that loops through target files and checks for missing variables.

Github Action

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.

Purpose:
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.

Trigger:
The workflow is manually triggered using workflow_dispatch with configurable inputs.

Input Parameters:

figma_file_id (required): The Figma file or branch ID to sync from
- Default: "bZFqk9urD3NlghGUKrkKCR" (main Synergy Design System file)
- Can be either a branch ID or the main file ID
branch_name (required): Name for the new Git branch
- Default: "feat/update-tokens-from-figma"
pull_request_name (required): Title for the pull request
- Default: "feat: ✨ Update tokens from Figma"

Workflow Steps:

Repository Setup: Checks out the repository with full history
Environment Setup: Installs pnpm, Node.js 22, and project dependencies
Token Synchronization: Runs pnpm -C ./packages/tokens fetch:figma && pnpm -C ./packages/tokens build:figma to fetch and transform Figma data
Quality Assurance: Builds and tests the updated tokens to ensure integrity
Pull Request Creation: Creates a new branch and pull request with the changes

Required Secrets:

FIGMA_TOKEN: Personal Access Token from Figma (required for API access)

Permissions:

The workflow requires the following permissions:

contents: write - To create branches and commits
pull-requests: write - To create pull requests

Usage Example:

Navigate to the Actions tab in the GitHub repository
Select "Sync Figma variables to tokens"
Click "Run workflow"
Configure the input parameters as needed
Click "Run workflow" to start the process

The workflow will automatically create a pull request with reviewers assigned (kirchsuSICKAG, schilchSICKAG) for review and approval.

Updating Test Files

When adding new tokens or changing existing token values, the test reference files in packages/tokens/test/ must be updated to maintain test integrity.

Test System Overview

The token package includes a test system that validates the consistency between the built token files and reference files:

test/light.css: Reference file containing expected CSS variables for the light theme
test/dark.css: Reference file containing expected CSS variables for the dark theme
test/test-css-variables.js: Test script that compares built files against reference files

When to Update Test Files

Test files need to be updated in the following scenarios:

Adding new tokens: When new design tokens are added to Figma and fetched
Changing token values: When existing token values are modified in Figma
Removing tokens: When tokens are deprecated or removed from the design system

How to Update Test Files

After the new / updated tokens are fetched and build:

Build the tokens: Ensure the latest tokens are built
```
cd packages/tokens
pnpm build
```
Run the comparison test: This will show differences between built and reference files
```
pnpm compare
```
Update reference files: If the changes are intentional, copy the built files to the test directory or update the files manually with the changes
```
# Copy the newly built files to serve as new reference files
cp dist/themes/sick*.css test
```
Verify the update: Run the test again to ensure everything matches
```
pnpm compare
```

Test Output

The test script provides detailed feedback:

✅ Success: When all variables match between built and reference files
🚫 Missing variables: Variables present in reference but missing in built files
➕ Extra variables: New variables in built files not present in reference
🔄 Different values: Variables with changed values between built and reference files

Important Notes

Always review the test output carefully before updating reference files
The reference files serve as a safeguard against unintended token changes

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@synergy-design-system/tokens

Installation

Provided tokens

Using CSS themes

Switching themes during runtime

Usage in JavaScript

Usage in SCSS:

JSON files

Optional: Configuring tokens in VSCode

Developer Documentation

Architecture and Data Flow

Building the tokens

Figma variables

Figma styles

Output

Project structure

/src/figma-variables/

/scripts/figma/

/scripts/add-missing-tokens.js

Github Action

Updating Test Files

Test System Overview

When to Update Test Files

How to Update Test Files

Test Output

Important Notes

`/src/figma-variables/`

`/scripts/figma/`

`/scripts/add-missing-tokens.js`