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.).

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

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.

Outputs

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

<button
  data-esds-button-size="small"
  data-esds-button-type="primary"
>
  Click Me !
</button>

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/tailwind.css';

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

/* ... */

<button class="bg-yellow-500">Click Me !</button>

Scripts

TODO

Import tokens into figma

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