Readme

v1.0.9

Stellar-Tokens

Welcome to the BioNTech Stellar Design System Tokens repository.

Overview

This repository contains the design tokens generated in Figma's Tokens Studio representing various design properties such as colors, typography, spacing, and more.

It serves as the shared source of truth between Figma and all development environments by transforming Figma's Tokens Studio JSON formatting of tokens into CSS variables and styles that can be consumed by BioNTechs various digital products.

Dependencies

This project relies on the following external libraries:

• style-dictionary: Style Dictionary is a Core library for managing and transforming design tokens into usable code for different platforms, such as the web with CSS variables.
• @tokens-studio/sd-transforms: Provides Figma Token Studio specific transformations for Style Dictionary.
• figma-assets-generator: Utility for generating assets from Figma tokens (optional).
• token-transformer: Utility that converts tokens from Tokens Studio to something Style Dictionary can read, removing any math operations or aliases, only resulting in raw values.
• fs: Node.js built-in file system access library.
• node-fetch: Promise-based HTTP fetching library.
• request: Simplified HTTP request library.

How to

1. Generate a Personal Access Token in Gitlab

• Open the drawer pannel by clicking the top left icon, then click on your Avatar and select edit profile.
• Go to Access Tokens, click add new token and allow the api scoped permission levels.
• Give the token a descriptive name and decide for yourself when that token should expire.
• Scroll down and click Create personal access token.
• Copy and save the generated token key (keep it confidential). You'll need it in the next step.

Important: Token Studio currently only supports Personal Access Tokens, not Project Access Tokens.

2. Configure Token Studio API synching with Gitlab

• Open Token Studio plugin in Figma and open the Settingtab.
• Under Sync Providers, click add new and select Gitlab.
• Name connection. Ex: "Stellar-Tokens|Gitlab"
• Paste your previously generated Personal Access Token.
• Paste the repository url bnt/stellar-tokens.
• Set Branch as main.
• Set Base URLas https://git.namics.com/.
• Click save.
• As a final step the plugin will ask you if you want to pull the latest tokens from the repository. Accept it.

3. Create a local repository

git clone [email protected]:bnt/stellar-tokens.git

4. Push or Pull changes

Figma Tokens Studio allows you to manage your design tokens in Figma and synchronize them with our Gitlab repository for consistency. Here's how to push and pull changes:

4.1 Push changes (Tokens Studio → Gitlab)

Whenever you make a change in Tokens Studio, you have to manually hit Push to GitLabwith the ↑ icon on the bottom left corner, to push your local changes to the remote. Anytime you do that you have to supply a commit message. You can choose the branch you want to push your changes to, so you could just try new tokens out without overwriting the currently live ones.

4.1 Pull changes (Gitlab → Tokens Studio)

If you only want to pull the latest changes, hit Pull from GitLab with the ↓ icon on the bottom left corner. The plugin will let you know when your local changes differ from the ones stored on the remote by showing a blue dot.

5. Integration in you Digital Product environment

Authorization

There are multiple ways how authorization can be handled. Our choice is to use a .npmrc configuration file that points to the registry and should contain a secret project authorization token.

5.1. Generate an access token

You'll need an access token with the read_package_registry and write_package_registry scopes to publish and install packages. Here's how to generate one:

• Open the drawer pannel by clicking the top left icon, then click on your Avatar and select edit profile.
• Go to Access Tokens, click add new token and allow the read_package_registry and write_package_registry`scoped permission levels.
• Give the token a descriptive name and decide for yourself when that token should expire.
• Scroll down and click Create personal access token.
• Copy and save the generated access token key (keep it confidential).
• Set an environment variable named STELLAR-DS-TOKENS_AUTH_TOKEN with your access token and configure npm to use it (npm config set @<your_scope>:always-auth=true).

5.2. Store the access token in an environmental variable

• Set an environmental variable named STELLAR-DS-TOKENS_AUTH_TOKEN

Important: Consider using a tool like dotenv in Node.js projects to load environment variables from a separate .env file that is excluded from version control.

5.3. Create a .npmrc file

Important: Due to security concerns, it's generally recommended to create the .npmrc file in your project's root directory (next to package.json) instead of your home directory. This way, you can add it to your .gitignore file to prevent accidental credential exposure.

5.4. Configure the registry

In your .npmrc file, add the following lines:

save-exact=true
@bnt:registry=https://git.namics.com/api/v4/projects/4954/packages/npm/
//git.namics.com/api/v4/projects/4954/packages/npm/:_authToken="${STELLAR-DS-TOKENS_AUTH_TOKEN}"

STELLAR-DS-TOKENS_AUTH_TOKEN is an environment variable that stores the authentication token so that the same configuration can be used locally and on running environments.

Important: Make sure to add .npmrc to your .gitignore file to prevent accidentally committing it to your Git repository.

Important: This token should not be added inline and/or committed to the code source control.

Important: Consider using a tool like dotenv in Node.js projects to load environment variables from a separate .env file that is excluded from version control.

5.5. Publishing the package

• With this setup, you can now use npm publish to publish your package to your GitLab package registry. npm will automatically retrieve the access token from the NPM_AUTH_TOKEN environment variable when needed for authentication.

5.6. Installing the package

• Run npm install @bnt/stellar-tokens to install the latest version of the package from GitLab registry.
• We can also have full control of the version that will be installed. It can be a specific version that can be manually changed, or it could be set to always get the latest version with every npm install.