Skip to content
Home

Design tokens (WIP)#

Description#

Beta: The --token-* CSS custom properties are in beta. We encourage you to start using them and welcome your feedback. The token API may still change, but we will communicate any breaking changes.

The design tokens are synchronized from Figma with the "Design Tokens" GitHub Action and converted to CSS variables with the make-properties script. We currently generate color and radius tokens. Typography is skipped.

Overview#

  • Design tokens are synchronized from Figma by a GitHub Action, which opens a draft pull request for review.
  • We generate color tokens and radius values. Typography aliases and string values are skipped for now.
  • We export Foundation colors, plus light and dark brand token modes for DNB and Sbanken (Carnegie is light-only for now)

How to update#

1. Run the "Design Tokens" workflow#

  1. Open Actions → Design Tokens, then select Run workflow on main.
  2. The workflow reads the Figma variables with the variables REST API, writes the *.tokens.json files listed below, regenerates the CSS files, builds the library and Portal, updates the visual snapshots and opens or updates a draft pull request. Existing reviewer commits are preserved. If Figma and the pull request are already synchronized, it reports that no changes were found.
  3. Review the token values, removals and visual snapshots before marking the pull request ready.
  4. Review and (squash) merge the pull request.

Every mode of the exported collections has to be listed in TOKEN_EXPORTS (packages/dnb-eufemia/scripts/figma/tasks/tokensExtractor.ts). If a mode is added in Figma, the workflow fails until the mode is added there and to the token files in makePropertiesFile.ts, so a new mode cannot go unnoticed.

The workflow writes color.tokens.json with only the foundation colors the brand collection actually uses, because the API returns the remote variables used in the file. A manual export contains the whole collection instead, so switching between the two shows up as a large diff in that one file without changing the generated CSS.

The workflow needs the repository secret FIGMA_TOKEN (a personal access token with the file_variables:read scope) and the repository variable FIGMA_TOKENS_FILE (the key of the "💻 Eufemia - Web" file). The Figma variables API is only available to Enterprise organizations.

2. Exporting design tokens manually#

As a fallback, the same files can be exported by hand.

We currently export the Figma variable collections for:

  • "Foundation" collection "colors" (color.tokens.json)
  • "💻 Eufemia - Web" collection "brand" with modes:
    • "dnb-light" (brand/dnb-light.tokens.json)
    • "dnb-dark" (brand/dnb-dark.tokens.json)
    • "sbanken-light" (brand/sbanken-light.tokens.json)
    • "sbanken-dark" (brand/sbanken-dark.tokens.json)
    • "dnbcarnegie-light" (brand/dnbcarnegie-light.tokens.json)

Place color.tokens.json directly in packages/dnb-eufemia/src/style/themes/figma, and place the brand-mode exports in its brand subfolder.

Detailed steps:

  • Go to the "💻 Eufemia - Web" file in Figma. (You need edit permissions to see sub-collections)
  • Active "Design" mode.
  • Click the "Open variables" icon next to the label "Variables" in the right side-menu (must deselect elements to see the side-menu).
  • Click the "Collections options" icon next to the "Collections" heading and ensure "All collections" is selected.
  • Right click the collections "brand" and "colors" and select "Export Modes".
  • Unzip the downloaded JSON files and place them in packages/dnb-eufemia/src/style/themes/figma, using the relative filenames listed above.

We export the collections from the same Figma file in order to ensure the collections are in sync. Each brand-mode export is a complete snapshot of the collection, so light and dark files also contain shared font and radius values. The generator filters unsupported typography values and produces the mode-specific CSS from these complete exports.

3. Generate CSS files#

The CSS files are automatically generated during the "Prebuild" step by the makePropertiesFile.ts script (packages/dnb-eufemia/scripts/prebuild/tasks/makePropertiesFile.ts).

Generate locally (manual)#

To generate the files manually you can run the command yarn workspace @dnb/eufemia make-properties.

To fetch the tokens from Figma locally, add FIGMA_TOKEN and FIGMA_TOKENS_FILE to your .env file and run yarn workspace @dnb/eufemia figma:tokens.

Naming conventions/transforms#

Since Figma has different rules and limitations than CSS we have established some naming conventions to avoid errors.

  • only use alphanumeric characters. (a-z and 0-9)
  • Variables are not case-sensitive. (onDark and ondark are considered the same variable)
  • We use dashes (-) to separate groups and words.

Transforms#

During the CSS generation, Figma variables are converted to lower case. And groups are separated by dashes (-).

Only characters a-z A-Z 0-9. and - are supported. Any unsupported characters will throw an error.

We also add the prefix token to the variables from the Brand collection.

Example#

Figma variable: Color/Dimmer/Action-Pressed-Subtle-OnDark

CSS variable: --token-color-dimmer-action-pressed-subtle-ondark

Potential issues#

Even following all the rules, we still risk naming overlap since groups and words use the same separator in CSS color/action/pressed and color/action-pressed would map to the same variable.

But these will at least be caught on build.

Suggest an edit