npm package: @ganpatiinfo/gids-ganpatiinfo-theme
Description: The raw, DTCG-formatted design tokens & SVG assets used by the Ganpatiinfo theme for GIDS.
Author: Ganpatiinfo Design System
Latest version: 3.0.0

# 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](https://tr.designtokens.org/format/).

Currently, the tokens are created and managed in Figma as variables and then exported to DTCG via the [Tokens Brücke plug-in](https://www.figma.com/community/plugin/1254538877056388290/tokensbrucke). 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:

```js
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:

```js
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](https://www.figma.com/community/plugin/1254538877056388290/tokensbrucke) 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](./test/utils/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.
```