GIDS Design Tokens

The design tokens used by GIDS's default Ganpatiinfo theme (and, in future, any other Ganpatiinfo-maintained themes). The design tokens are stored as DTCG files.

Currently, the tokens are created and managed in Figma as variables and then exported to DTCG via the Tokens Brücke plug-in. In the future, we aim to make the DTCG files the main source of truth and setup some tooling to import them back into Figma.

Usage

Important: This is a private package (for now), so only other packages in this repo can consume it. They MUST therefore add this as a devDependency, so that they don't accidentally publish NPM packages that depend on this, which would break for consumers.

How to access the DTCG files

The paths to the DTCG files are exposed as constants that you can export into your own build scripts. For example:

import { readFile } from 'node:fs/promises';
import { ganpatiinfoTokensDistFilepath } from '@ganpatiinfo/gids-ganpatiinfo-theme';

const contents = await readFile(ganpatiinfoTokensSrcFilepath);
const ganpatiinfoDtcgData = JSON.parse(contents.toString());

// do interesting stuff with ganpatiinfoDtcgData

How to filter out private tokens

The DTCG files contain both "private" theme-interal tokens as well as the "public" ones that make up our theme API.

A function is provided to differentiate between them:

import { isPublicTokenPath } from '@ganpatiinfo/gids-ganpatiinfo-theme';

isPublicTokenPath('Theme.color.canvas'); // true
isPublicTokenPath('Primitives.greyCool.250'); // false

Development

1. Use the Tokens Brücke Figma plug-in to export a DTCG tokens file to src/ganpatiinfo.tokens.json (overwrite that file when doing so). Make sure you set the following options when doing so: _ Color mode: HEX _ Add styles to: "Keep separate" _ Include variable scopes: OFF _ Use DTCG keys format: ON * Include .value string for aliases: OFF
2. Run npm run build to pre-process the raw DTCG file. This is needed to workaround some bugs in the Figma plug-in where it doesn't quite follow the DTCG spec correctly. One day, we might be able to eliminate this.
   • The output can then be found in the dist/ folder.

Testing

Use npm run test to run tests on the design tokens and icons.

Currently these check:

• That certain pairs of color tokens meet minimum contrast ratios
• That the distributable version of the tokens file contains all the design tokens specified in the GIDS theme interface
• That all icon glyphs specified in the GIDS theme interface are present

In order to enable quick feedback loops, the color contrast tests parse the source ganpatiinfo.tokens.json file and then preprocess it on the fly the same way that npm build does and then run the tests on the preprocessed token data. For details refer to parseAndResolveTokens.ts.

Directory structure

design-tokens/
 │
 ├─ js/       # JS (ESM) files which provide
 │            # this package's public API.
 │
 ├─ scripts/  # Scripts used for building.
 │
 ├─ src/      # Source DTCG files
 │            # (*.tokens.json).
 │
 └─ test/     # Test code.