npm package: @nulogy/tokens
Description: Design tokens for the Nulogy Design System - http://nulogy.design
Author: Nulogy
Latest version: 6.2.0

# @nulogy/tokens

> Nulogy's design tokens. This package processes token definitions into various formats (CSS variables, JS constants).

![npm (scoped)](https://img.shields.io/npm/v/@nulogy/tokens.svg)

## What are tokens?

> Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.

- [Salesforce](https://www.lightningdesignsystem.com/design-tokens/)

## 📦 Installation

This package is primarily consumed by other Nulogy Design System packages like `@nulogy/components` and `@nulogy/css`. Direct installation into applications is generally not required.

However, if you need direct access, you can install it via pnpm:

`pnpm add @nulogy/tokens`

## ✨ Generated Files

The build process generates the following files in the `output/` directory (note: this directory is gitignored, the files are published to npm from `dist/` after build and postbuild steps):

- `nds_tokens.js`: JavaScript constants (ES Modules).
- `nds_tokens.css`: CSS custom properties (variables).
- `nds_tokens.ts`: TypeScript source identical to `nds_tokens.js`, used for generating type declarations.
- `nds_tokens.d.ts`: TypeScript declaration file, generated by the `postbuild` script.

## 💻 Development

Available commands:

- `pnpm build`: Cleans the `dist/` directory and generates token files (`.js`, `.css`, `.ts`) in the `output/` directory. It then runs the `postbuild` script.
- `pnpm clean`: Removes the `dist/` directory.
- `pnpm test`: Runs tests using `vitest`.
- `pnpm format:check`: Checks code formatting using `prettier`.
- `pnpm format:fix`: Automatically fixes code formatting issues using `prettier`.
- `pnpm postbuild`: Copies generated files from `output/` to `dist/` and generates TypeScript declaration files (`.d.ts`) in `dist/`.

The core build logic resides in `src/build/`.

- `main.ts`: Entry point for the build script.
- `generate.ts`: Reads token definition files, processes them for different devices (desktop, tablet, phone), and coordinates writing output files.
- `format.ts`: Contains functions to format the raw token data into CSS variables and JavaScript exports, including appropriate headers and variable naming conventions (e.g., `--nds-desktop-color-blue` for CSS, `DESKTOP_COLOR_BLUE` for JS).
- `constants.ts`: Defines constants used during the build, such as device names and base units.

## ✏️ Adding or Editing Tokens

Tokens are defined in separate modules within the `src/tokens/` directory. Each sub-directory represents a category of tokens (e.g., `color`, `spacing`, `typography`).

**To add or modify tokens:**

1.  **Locate or Create the Category File:** Find the relevant file within a subdirectory in `src/tokens/` (e.g., `src/tokens/color/index.ts`). If adding a new category, create a new subdirectory and an `index.ts` file within it. This is an important step, as the build process will look for the `index.ts` as the entry point for the category.
2.  **Define Tokens:** Token files export a default function that accepts a `baseUnit` argument and returns an object containing the token definitions. The structure of this object determines the naming of the generated variables. Nested objects create hierarchical names.

    _Example (`src/tokens/color/index.ts`):_

    ```typescript
    // src/tokens/color/index.ts
    export default (_baseUnit: number) => ({
      primary: {
        blue: '#0E7FAE', // Generates DESKTOP_COLOR_PRIMARY_BLUE, --nds-desktop-color-primary-blue, etc.
        darkBlue: '#004361',
      },
      neutral: {
        100: '#FFFFFF',
        200: '#F8F8F8',
      },
      // ... other colors
    })
    ```

3.  **Naming Convention:**

    - The **folder name** (e.g., `color`) becomes the middle part of the variable name.
    - **Keys** in the returned object (e.g., `primary`, `blue`, `neutral`, `100`) are joined to form the rest of the variable name.
    - The build script automatically prefixes names with the **device** (`desktop`, `tablet`, `phone`) and converts the final name to `SNAKE_CASE` for JS and `kebab-case` for CSS.

4.  **Run Build:** After making changes, run `pnpm build` to regenerate the token files in the `output/` directory.

5.  **Verify Changes:** Check the generated files in `output/` or `dist/` (specifically `nds_tokens.css` and `nds_tokens.js`) to ensure the new or modified tokens appear correctly.

6.  **Commit:** Commit the changes to the token definition file(s) in `src/tokens/`. Do **not** commit the generated files in `output/` or `dist/`. The files in `dist/` will be updated during the release process.

## 💬 Questions

- [#support-design-system](slack://channel?team=T024N2KKA&id=CBAFQ4X7X)