tokens

Infomaniak's Design System - DTCG Tokens

Contains the list of Infomaniak's Design System tokens based on the Design Tokens Community Group - (DTCG - 2025.10) format, and scripts to convert them to different formats (CSS, Figma, Tailwind, etc.).

• Documentation ↗

Project architecture

flowchart TD
    %% --- Subgraphs ---

    subgraph Prototyping["Prototyping"]
        FigmaDoc["🎨 Figma"]
    end

    subgraph TokensInput["Tokens Input"]
        Folder["📁 DTCG Token Files<br/>(T1, T2, T3, Modifiers)"]
    end

    subgraph BuildTokens["Transform & Build Tokens"]
        Transform["⚙️ Transform"]
        B_MD["build-markdown-tokens"]
        B_CSS["build-css-tokens"]
        B_Swift["build-swift-tokens"]
        B_Kotlin["build-kotlin-tokens"]
        B_Figma["build-figma-tokens"]

        Transform --> B_MD & B_CSS & B_Swift & B_Kotlin & B_Figma
    end

    subgraph Output["Output"]
        O_MD["Markdown files"]
        O_CSS["CSS variables"]
        O_TW["Tailwind theme"]
        O_Swift["Swift package"]
        O_JC["Lib Jetpack Compose"]
        O_FT["figma-tokens.json<br/>(TokensBrücke)"]
    end

    subgraph Distribution["Distribution"]
        D_SB["🌐 Storybook"]
        D_NPM["📦 NPM<br/>(@infomaniak-design-system/tokens)"]
        D_iOS["📥 ios-design-system"]
        D_Android["📥 android-design-system"]
        D_Figma["💻 Figma<br/>(TokensBrücke Plugin)"]
    end

    %% --- Main Flow and Intermediate Steps ---

    Export["Export TokensBrücke"]
    Convert["Convert to DTCG"]
    Manual["Manual review + copy"]
    Validate["Validate DTCG Tokens"]

    %% Connecting to the Subgraph to force vertical centering
    FigmaDoc --> Export
    Export --> Convert
    Convert --> Manual
    Manual --> TokensInput
    TokensInput --> Validate
    Validate --> Transform

    %% --- Build to Output Connections ---

    B_MD --> O_MD
    B_CSS --> O_CSS
    B_CSS --> O_TW
    B_Swift --> O_Swift
    B_Kotlin --> O_JC
    B_Figma --> O_FT

    %% --- Output to Distribution Connections ---

    O_MD --> D_SB

    %% Converging both CSS and Tailwind into NPM
    O_CSS & O_TW --> D_NPM

    O_Swift --> D_iOS
    O_JC --> D_Android
    O_FT --> D_Figma

Loading

Definition

A design token is a pair consisting of a name and a value. They're assembled into a list of tokens to apply styles to elements.

File structure

• tokens: Contains the list of all the tokens used by the design system.
  • t1-primitive: Contains the primitive tokens: it's a list of all the possible values to use for the design tokens. Developers should not use these values directly in their code, as they should rely on more abstract tokens (see t2, t3).
  • t2-semantic: Contains the semantic tokens: it's a list of token's having a semantic meaning (ex: "color.brand"). All the values of these tokens are pointing to the t1-primitive tokens: they can't have their own values.
  • t3-component: Contains the component tokens: it's a list of tokens that are used to style components or elements of the interface. All the values of these tokens are pointing to the t1-primitive or t2-semantic tokens: they can't have their own values.
  • modifiers: Contains the list of tokens that are used as alternate values for the t2-semantic and t3-component tokens.

Modifiers

• contexts are set of tokens associated with a context name that can be used to provide alternative values for the tokens.
• contexts are grouped by modifier:
  • Each context can only be used once per modifier.
  • Multiple modifiers can be combined to create the final set of tokens.

Example

• modifiers:
  • theme:
    • light.tokens.json: Contains the tokens for the light theme.
    • dark.tokens.json: Contains the tokens for the dark theme.
  • platform:
    • mobile.tokens.json: Contains the tokens for the mobile platform.
    • desktop.tokens.json: Contains the tokens for the desktop platform.

In this example, developpers can use light OR dark theme (but not both at the same time) and mobile OR desktop platform.

light, dark, mobile and desktop are contexts and theme and platform are modifiers.

Platforms

Web

The tokens are published as a npm package: @infomaniak-design-system/tokens.

CSS

The css/tokens.root.css file contains all the base tokens as CSS variables and must be imported in every project.

The css/modifiers/<modifier>/<context>.(root|attr).css contains the tokens for the given modifier and context.

Note

The root suffix contains the tokens wrapped by the selector: :root, :host The attr suffix contains the tokens wrapped by the attribute selector: [data-esds-<modifier>="<context>"]

Import

You may import the CSS files as you prefer, but here's an example of how to use them:

/* src/styles/esds/tokens.css */
@import '@infomaniak-design-system/tokens/css/tokens.root.css';

/* src/styles/esds/themes/light.css */
@import '@infomaniak-design-system/tokens/css/modifiers/theme/light.root.css';

/* src/styles/esds/themes/dark.css */
@import '@infomaniak-design-system/tokens/css/modifiers/theme/dark.root.css';

/* src/styles/esds/modifiers.css */
@import '@infomaniak-design-system/tokens/css/modifiers/button-size/small.attr.css';
@import '@infomaniak-design-system/tokens/css/modifiers/button-type/primary.attr.css';
/* etc. */

<!-- index.html -->
<link
  rel="stylesheet"
  href="src/styles/esds/tokens.css"
/>
<link
  rel="stylesheet"
  href="src/styles/esds/themes/light.css"
  media="(prefers-color-scheme: light)"
/>
<link
  rel="stylesheet"
  href="src/styles/esds/themes/dark.css"
  media="(prefers-color-scheme: dark)"
/>

<link
  rel="stylesheet"
  href="src/styles/esds/modifiers.css"
/>

Usage

<body
  data-esds-theme="dark"
  data-esds-product="mail"
>
  <!-- Dark theme and product mail applies to children -->
</body>

Tailwind

The npm package contains a tailwind.css file that you can import and use in your Tailwind project:

/* src/styles/tailwind.css */
@import 'tailwindcss';
@import '@infomaniak-design-system/tokens/css/tokens.root.css';
@import '@infomaniak-design-system/tokens/tailwind.css';

<!-- index.html -->
<link
  rel="stylesheet"
  href="src/styles/tailwind.css"
/>

/* ... */

<button class="bg-brand-default">Click me!</button>

iOS

Swift

The package is published into a dedicated GitHub repository.

Installation

swift.package(url: "https://github.com/Infomaniak/ios-design-system", branch: "main")
swift.target(
    name: "MyTarget",
    dependencies: [
        .product(name: "DesignSystem", package: "ios-design-system")
    ]
)

Android

Kotlin

The package is published into a dedicated GitHub repository.

Installation

TODO

Figma bridge

Figma does not provide a way to import or export tokens directly (without the Enterprise plan). Thus, we have to perform a manual process.

Note

We use the Figma TokensBrücke plugin to import/export the figma variables.

Export the tokens from figma

Follow the instructions to export the tokens from figma, with the name tokens.json.

Then put this file at this destination packages/tokens/scripts/scripts/convert-figma-tokens/tokens/tokens.json.

Go to packages/tokens, and run the following command:

yarn convert-figma-tokens

It will export the tokens into packages/tokens/tokens/**, with a valid DTCG format.

Import the tokens into figma

Go to packages/tokens, and run the following command:

yarn build

Open the file packages/tokens/dist/figma.tokens.json, copy its content, and follow the instructions to import the tokens into figma.

Semantic versioning

The code is the source of truth for the semantic versioning.

The version is generated automatically when the develop -> main PR is undrafted. When the merge occurs, the packages are published automatically with their final version. Then we create manually a version with the same number in the Figma Token core file, to keep both worlds in sync.