@ubloimmo/front-tokens

Internal library and private NPM package used to pull figma team styles from API and export them into code-ready typescript & css tokens.

Generating tokens

Want to convert figma values to code-ready tokens ? Here's how to do it!

Prerequisites

This project uses typescript with Bun under the hood. Thats it!

Install it by following their Installation guide.

Installation

Clone the repository to your machine

git clone https://github.com/UbloImmo/front-tokens.git

Install all package dependencies

bun install

Environment setup

Duplicate the provided .env.example file

cp .env.example .env

And populate is values.

Variable name	Value	Description	Required
FIGMA_TOKEN	String	Personal figma API token	true
FIGMA_TEAM_ID	String	Figma team ID	true
FIGMA_FILE_URLS	CSV String	figma files URLS to filter team styles	false

Note: If FIGMA_FILE_URLS is not specified, all exported team styles will be converted to tokens.

Updating tokens manually from the command line

Fetch styles from figma API and export tokens

bun update

Exports

Exported tokens are located in /lib directory under the following files and values.

File name	Exported constants	Type	Description
/lib/tokens.all.ts	tokens	readonly Token[]	Array of all exported tokens
/lib/tokens.collection.ts	TEXT	readonly TokenOrGroupCollection	Hierarchy of all text tokens and token groups
	GRADIENT	readonly TokenOrGroupCollection	Hierarchy of all gradient tokens and token groups
	COLOR	readonly TokenOrGroupCollection	Hierarchy of all color tokens and token groups
	EFFECT	readonly TokenOrGroupCollection	Hierarchy of all effect tokens and token groups
	ASSET	readonly TokenOrGroupCollection	Hierarchy of all asset tokens and token groups
/lib/tokens.values.ts	texts	readonly TokenValues	Nested object containing all text tokens.
	gradients	readonly TokenValues	Nested object containing all gradient tokens.
	colors	readonly TokenValues	Nested object containing all color tokens.
	effects	readonly TokenValues	Nested object containing all effect tokens.
	assets	readonly TokenValues	Nested object containing all asset tokens.
/lib/index.ts	All of the above

Updating tokens from CI/CI pipeline

This repository already contains the update.yml GitHub workflow file for all your automated updating needs.

Note: The workflow only runs when triggered manually through the repository's Actions tab.

Pipeline steps

The pipeline fetches the most recent changes made to sourced figma files and generates new code-ready tokens if needed. If changes have been detected, a new commit will be made to main along with a version bump.

The resulting generated files will be published to NPM and a new Release will be made available.

Running an update from CI

Go to update.yml's GitHub Action page and click on Run workflow.

Consuming generated tokens

Generated tokens are made available to third-party Javascript / Typescript projects through a private NPM package.

Installation

Install the package with the package manager of your choice

# NPM
npm install @ubloimmo/front-tokens
# Yarn
yarn add @ubloimmo/front-tokens
# Bun
bun add @ubloimmo/front-tokens

Usage

Import the generated tokens in your code...

Note: Imports are tree-shakable, refer to the Exports section for more information

// Token groups and values, with detailed group information
import { COLOR, GRADIENT, EFFECT, ASSET, TEXT } from "@ubloimmo/front-tokens";
// Token groups and values, without detailed group information
import { colors, gradients, assets, texts, effects } from "@ubloimmo/front-tokens"
// Array containing all generated tokens, without grouping
import { tokens } from "@ubloimmo/front-tokens"

...and use them in your code

Typescript

import { texts } from "@ubloimmo/front-tokens";

const isMobile: boolean = getIsMobile();
const SmallFontSize = texts[isMobile ? "mobile" : "desktop"].small.css.style.fontSize;

React component

import { colors } from "@ubloimmo/front-tokens";
import { useState, useMemo, useCallback } from "react";

const MyComponent = () => {
  const [isActive, setIsActive] = useState(false);
  
  const color = useMemo(
    () => isActive
      ? colors.ublo.main.value // rgba(90, 55, 216, 1)
      : colors.black.medium.value, // rgba(22, 22, 22, 1)
    [isActive]
  )
  
  const toggleActive = useCallback(
    () => setIsActive(!isActive),
    [setIsActive, isActive]
  )
  
  return (
    <div
      onClick={toggleActive}
      style={{ color }}
    >
      My text
    </div>
  )
}

Styled-components

import { texts, effects } from "@ubloimmo/tokens"

const H1 = styled.h1`
  ${texts.Desktop.H1.css.rules} // font-family: Avenir;\nfont-weight: 500;\nfont-size: 2.5rem;\nfont-style: normal;\ntext-indent: unset;\ntext-decoration: none;\ntext-transform: unset;\nline-height: 2.6524999618530276rem%;\nletter-spacing: -0.0625rem;\ntext-overflow: unset;\ntext-align: left;\nvertical-align: left;\nfont-feature-settings: normal;
`
const H1WithShadow = styled(H1)`
  box-shadow: ${effects.upfront.css.style.boxShadow}
`