outsystems-design-tokens/README.md

Store the Design Tokens used on the Ionic Framework and Widgets Library

# outsystems-design-tokens

Store the Design Tokens used on the OutSystems UI Frameworks. Other related assets, like Font files, are stored on the `assets` folder.

## Table of Contents

- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Output Files](#output-files)
- [Options](#options)
  - [Source & Destination](#source--destination)
  - [Prefixes](#prefixes)
  - [Output Control](#output-control)
  - [File Names](#file-names)
- [Features](#features)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)

## Introduction

This repository contains the design tokens used in the OutSystems UI Frameworks. Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. These tokens are used in the Ionic Framework and Widgets Library to ensure consistency and scalability in design.

## Installation

To install the dependencies, run:

```sh
npm install
```

## Usage

To build the design tokens, you can use the provided script. The script parses command line arguments to set environment variables and then runs the build process.

### Build Tokens

To build the tokens with default settings, run:
```sh
npm run build.tokens
```

Alternatively, you can use the binary command:
```sh
npx build.tokens [options]
```

When installed as a package in another project:
```sh
npx build.tokens --dest src/scss/ --prefix custom
```

## Output Files

By default, the build generates three files:

1. **`_root.scss`** - CSS custom properties (`:root` variables)
2. **`_variables.scss`** - SCSS variables with CSS variable fallbacks
3. **`_utilities.scss`** - Utility classes for direct HTML usage

## Options

### Source & Destination

| Option | Description | Default |
|--------|-------------|---------|
| `--src` | Source directory containing token files (glob pattern) | `tokens/**/*.json` (from package) |
| `--dest` | Destination directory for built tokens | `dist/` |
| `--config` | Path to custom Style Dictionary configuration file | - |

### Prefixes

| Option | Description | Default |
|--------|-------------|---------|
| `--prefix` | Prefix for CSS custom properties and utility classes | `token` |
| `--scss-prefix` | Separate prefix for SCSS variable names (optional) | Same as `--prefix` |

**Example with different prefixes:**
```sh
npx build.tokens --prefix token --scss-prefix ion
```
This generates:
- SCSS variables: `$ion-bg-body`
- CSS custom properties: `--token-bg-body`
- Utility classes: `.token-bg-body`

### Output Control

| Option | Description | Default |
|--------|-------------|---------|
| `--root` | Generate CSS custom properties file | `true` |
| `--scss` | Generate SCSS variables file | `true` |
| `--utilities` | Generate utility classes file | `true` |

### File Names

| Option | Description | Default |
|--------|-------------|---------|
| `--root-file` | Custom name for CSS custom properties file | `_root.scss` |
| `--scss-file` | Custom name for SCSS variables file | `_variables.scss` |
| `--utilities-file` | Custom name for utility classes file | `_utilities.scss` |

## Features

### 🎨 Token Organization

- **Ordered Output**: Tokens are automatically sorted with primitives first, followed by semantic tokens, ensuring proper CSS variable fallbacks
- **Alias Resolution**: Semantic tokens automatically reference primitive tokens using CSS variable fallbacks

### 📦 SCSS Variables

SCSS variables include CSS custom property fallbacks and alias references:

```scss
// Primitive token
$token-primitives-blue-100: var(--token-primitives-blue-100, #e9ecfc);

// Semantic token referencing primitive
$token-semantics-primary-100: var(--token-semantics-primary-100, $token-primitives-blue-100);
```

### 🎭 Typography Maps

Typography tokens are generated as SCSS maps for easy use in mixins:

```scss
$token-display-sm-regular: (
  font-size: $token-font-size-800,
  font-style: normal,
  font-weight: $token-font-weight-regular,
  letter-spacing: $token-font-letter-spacing-0,
  line-height: $token-font-line-height-1100,
  text-transform: none,
  text-decoration: none,
);
```

### 🛠️ Utility Classes

Utility classes are generated with:
- CSS logical properties for spacing (`margin-block-start`, `padding-inline-end`, etc.)
- Both CSS custom property declarations and direct values
- Full typography styles

```scss
.token-margin-space-400 {
  margin-block-start: $token-space-400;
  margin-inline-end: $token-space-400;
  margin-block-end: $token-space-400;
  margin-inline-start: $token-space-400;
}
```

### 📏 Letter Spacing

Letter spacing values are automatically converted from percentage to pixels for better browser compatibility.

## Examples

### Basic Usage

Generate all files with default settings:
```sh
npm run build.tokens
```

### Custom Destination

Output to a specific directory:
```sh
npx build.tokens --dest src/styles/
```

### Custom Prefix

Use a custom prefix for all tokens:
```sh
npx build.tokens --prefix custom
```

### Separate SCSS Prefix

Use different prefixes for SCSS and CSS:
```sh
npx build.tokens --prefix token --scss-prefix ion --dest src/scss/
```

### Generate Only CSS Custom Properties

Skip SCSS variables and utilities:
```sh
npx build.tokens --scss false --utilities false
```

### Generate Only Utility Classes

Skip CSS custom properties and SCSS variables:
```sh
npx build.tokens --root false --scss false
```

### Custom File Names

Use custom names for output files:
```sh
npx build.tokens --root-file theme.scss --scss-file vars.scss --utilities-file utils.scss
```

### Complete Example

```sh
npx build.tokens \
  --dest src/styles/ \
  --prefix token \
  --scss-prefix ion \
  --root-file _tokens.scss \
  --scss-file _variables.scss \
  --utilities-file _utilities.scss \
  --scss true \
  --utilities true
```

## Contributing
We welcome contributions! Please see our CONTRIBUTING.md for guidelines on how to contribute to this project.

## License
This project is licensed under the BSD-3-Clause License. See the LICENSE file for more details.