# Design Tokens for Dialtone

Design tokens for Dialpad's design system Dialtone and everything related to building and publishing them.

Design tokens are all the defined values that are part of the design system, such as color, spacing, typography, and
more. The goal is to store design tokens as JSON and output and publish them to many different formats (CSS, LESS,
Android, iOS, etc.) upon build.

> **Dialtone v10:** see [DLT-2979](https://dialpad.atlassian.net/browse/DLT-2979) / [#1426](https://github.com/dialpad/dialtone/pull/1426) for the v10 upgrade and its breaking changes. This is a MAJOR version release.

## Usage

To use Dialtone Tokens in your project:

### Web (npm)

#### Install Dependency

```shell
npm install @dialpad/dialtone-tokens
```

#### Import CSS Tokens

```css
@import "@dialpad/dialtone-tokens/dist/tokens-base-light.css"; // Light variables
@import "@dialpad/dialtone-tokens/dist/tokens-base-dark.css";  // Dark variables
```

Token CSS is wrapped in `@layer dialtone.base`. If your project can't use CSS Cascade Layers, import the no-layers variant instead (same variables, no `@layer` wrapper):

```css
@import "@dialpad/dialtone-tokens/no-layers/tokens-base-light.css";
@import "@dialpad/dialtone-tokens/no-layers/tokens-base-dark.css";
```

This mirrors the [no-layers build](https://dialtone.dialpad.com/guides/migration/css-cascade-layers/#no-layers-build) available in `@dialpad/dialtone-css` and `@dialpad/dialtone` — use it if you import token CSS directly rather than through those packages. Every token CSS file that carries `@layer` has a no-layers counterpart at the same path under `no-layers/`.

If you theme at runtime, use `initDialtoneThemeNoLayers` from `themes/config-no-layers` to load the no-layers core tokens — `setBrand`/`setContrast`/`setMaterial` need no equivalent option since brand, contrast, and material overrides were never wrapped in `@layer`:

```js
import { initDialtoneThemeNoLayers } from '@dialpad/dialtone-tokens/themes/config-no-layers';
import Dp from '@dialpad/dialtone-tokens/themes/dp';

initDialtoneThemeNoLayers(Dp, 'light', document.documentElement);
```

`initDialtoneTheme(..., { layers: false })` from `themes/config` still works too, but resolves the no-layers core via a runtime dynamic import, so it applies a moment after the call returns rather than synchronously — prefer `initDialtoneThemeNoLayers` for new code.

dialtone-tokens provides a postcss plugin that you can use to convert all tokens using rem to px. This could be useful if you are using dialtone in an embedded situation where you don't have control over the root font size.

You can reference this script from:

- @dialpad/dialtone-tokens package: `@dialpad/dialtone-tokens/dist/postcss/rem-to-px.js`
- @dialpad/dialtone package: `@dialpad/dialtone/tokens/postcss/rem-to-px.js`

To use this script you will have to run it as part of your build process on the tokens files you are importing. There are various ways to run postcss as part of your build process, please see the documentation here: <https://github.com/postcss/postcss?tab=readme-ov-file#usage>

#### Use CSS Token

```css
.my-css-class {
  color: var(--dt-color-purple-200)
}
```

Or

#### Import LESS Tokens

```less
@import "@dialpad/dialtone-tokens/dist/less/tokens-base-light.less"; // Light variables
@import "@dialpad/dialtone-tokens/dist/less/tokens-base-dark.less";  // Dark variables
```

#### Use LESS Token

```less
.my-css-class {
  color: @dt-color-purple-200
}
```

#### Import JSON

```js
import "@dialpad/dialtone-tokens/dist/tokens-base-light.json" // Light tokens
import "@dialpad/dialtone-tokens/dist/tokens-base-dark.json" // Dark tokens
```

### iOS (swift)

1. Within your XCode project `File > Swift Packages > Add Package Dependency`
2. Enter repository url: `https://github.com/dialpad/dialtone-tokens-swift`

### Android (compose/xml)

#### pom.xml

```xml
<dependency>
  <groupId>design.dialpad.tokens</groupId>
  <artifactId>dialtone-tokens</artifactId>
  <version>1.2.0</version>
</dependency>
```

#### Install Dependency

```shell
mvn install
```

<!-- #### Import Compose Tokens

```
import design.dialpad.DialtoneTokens;
```

#### Use Compose Token

```
DialtoneTokens.dtColorPurple200
``` -->

## Quick Start for Contributors

1. clone repo
2. `pnpm install`
3. `nx run dialtone-tokens:build` to build tokens. Built tokens will be output to the dist folder.

- `base.json` Contains tokens exported from figma.
- `tokens/tokens.json` Contains tokens in style dictionary format (generated from `base.json`).
- `dist` Contains tokens in their final output form, in multiple different formats.