@nulogy/tokens

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

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

📦 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):

   // 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