# 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)
  - [Dynamic font (rem)](#dynamic-font-rem)
  - [Output Control](#output-control)
  - [var() fallbacks](#var-fallbacks)
  - [Utility class custom properties](#utility-class-custom-properties)
  - [Modes and Themes](#modes-and-themes)
  - [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`

### Dynamic font (rem)

To support dynamic font scaling (e.g. user preferences or zoom), you can output **font-size tokens** in `rem` instead of `px`. Set the base font size (in pixels) that corresponds to `1rem` in your app; font-size token values will be converted to `rem` using that base. Other tokens (spacing, border, shadow, etc.) stay in `px`.

| Option | Description | Default |
|--------|-------------|---------|
| `--base-font-size` | Base font size in px for rem conversion. Font-size tokens are output in `rem` using this base. | `16` |
| `--default-font-size` | Alias for `--base-font-size` | same |

**Example:**
```sh
npx build-tokens
# or override the base, e.g. for 14px root:
npx build-tokens --base-font-size 14
```
With the default `16`, font-size tokens are in rem (e.g. `1rem` = 16px). Set `font-size` on `html` to control scaling. Pass `--base-font-size 0` to output font sizes in `px` instead.

### Output Control

| Option | Description | Default |
|--------|-------------|---------|
| `--root` | Generate CSS custom properties file | `true` |
| `--scss` | Generate SCSS variables file | `true` |
| `--utilities` | Generate utility classes file | `true` |
| `--css` | Also compile the SCSS output to plain CSS (`_root.css`, `_utilities.css`) | `false` |
| `--use-custom-font` | Keep the font family named in the token source, with the system stack appended | `true` |
| `--utilities-css-vars` | Declare the matching `--<property>` custom property inside each utility class | `true` |
| `--mode-files` | Generate theme files for non-default modes (e.g. `_theme-dark.scss`) | `true` |
| `--fallbacks` | Include the resolved value as a fallback inside every `var()` reference | `true` |

### Font family

`font.font-family.*` tokens carry the family authored in the source with the native system
stack appended as fallback:

```css
--token-font-family: "Inter", -apple-system, system-ui, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, ...;
```

Pass `--use-custom-font false` when your application decides which face to load — the named
family is dropped and only the system stack is emitted:

```sh
npx build-tokens --use-custom-font false
```

```css
--token-font-family: -apple-system, system-ui, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, ...;
```

### Plain CSS output

The generator writes SCSS partials. Pass `--css true` to additionally compile them to plain CSS
next to the SCSS, for consumers with no Sass build step:

```sh
npx build-tokens --css true
```

`_root.css` is compiled from `_root.scss` and `_utilities.css` from `_utilities.scss`, so each
respects its own flag — `--root false` or `--utilities false` skips the matching CSS file.
Compilation needs the `sass` package; without it `_utilities.css` is written as a stub and
`_root.css` is skipped with a warning.

### var() fallbacks

By default every reference carries its resolved value as a fallback, so the output works even when the `:root` file is not loaded:

```scss
$token-bg-body: var(--token-bg-body, $token-primitives-base-white);
--token-bg-body: var(--token-primitives-base-white, #ffffff);
```

With `--fallbacks false` the references are emitted bare:

```scss
$token-bg-body: var(--token-bg-body);
--token-bg-body: var(--token-primitives-base-white);
```

That is terser and guarantees a single source of values at runtime (nothing can go stale), but the `:root` custom properties **must** be present — otherwise the variables resolve to nothing. Do not combine it with `--root false` unless you load `_root.css` from elsewhere; the CLI warns if you do.

### Utility class custom properties

By default each utility class declares a CSS custom property next to the real declaration:

```scss
.token-bg-body {
  --background: #{$token-bg-body};
  background-color: $token-bg-body;
}

.token-margin-400 {
  --margin-top: #{$token-space-400};
  --margin-end: #{$token-space-400};
  --margin-bottom: #{$token-space-400};
  --margin-start: #{$token-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;
}
```

Those companions are what lets an Ionic-style component pick the value up from its host: applying the class to the host re-themes the component's internals, not just the host element itself.

With `--utilities-css-vars false` only the plain declarations are emitted:

```scss
.token-bg-body {
  background-color: $token-bg-body;
}

.token-margin-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;
}
```

Use it when you want classic utility classes and no extra custom properties in the cascade. The values themselves are unaffected — they are still `var(--token-…)` references, so runtime theming (including `.os-dark-theme`) keeps working. Only turn it off if nothing in your codebase reads the `--background` / `--color` / `--margin-*` / `--padding-*` / `--border-radius` / `--border-color` / `--border-width` / `--box-shadow` contract.

### Modes and Themes

Token collections can carry multiple modes (e.g. `colors` has `light` and `dark`, `shape` has `soft`/`round`/`rectangular`). The default mode of each collection is compiled into the regular output files; every other mode is additionally emitted as its own file — the `dark` colour mode as **`_theme-dark.scss`** — a mixin re-declaring only the custom properties that differ from light, plus a ready `.os-dark-theme` class:

```scss
@use "tokens/theme-dark"; // emits .os-dark-theme { --token-…: …dark values… }
```

```html
<body class="os-dark-theme">…</body>
```

Other collections' modes are **parallel variants**, not themes, so they are flattened into the main output under explicit names rather than hidden behind a class — every variant is usable at once, per component:

```scss
border-radius: $token-shape-md;             // the default variant (soft)
border-radius: $token-shape-round-md;       // 999px
border-radius: $token-shape-rectangular-md; // 0px
```

`--default-modes shape=round` changes which variant the unprefixed `$token-shape-*` names carry; the explicitly-named ones are always present.

| Option | Description | Default |
|--------|-------------|---------|
| `--default-modes` | Default mode per collection, e.g. `"shape=soft,colors=light"` | `shape=soft` |

### 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: 1.375,
  text-transform: none,
  text-decoration: none,
);
```

`line-height` in these maps (and in the matching utility classes) is a **unitless ratio**
derived at build time — line-height ÷ font-size, e.g. `1.714286` for `body-md`'s 14px/24px —
rather than a reference to the absolute `$token-font-line-height-*` ramp. On the element the
role is applied to the result is identical; the difference is that descendants setting only a
`font-size` get a proportional line box instead of inheriting a fixed length, which is what a
consumer's `body` rule needs. The ramp itself stays absolute for direct use as box heights.
Because the ratio is a build-time number (CSS cannot divide two lengths at runtime), a root-level
override of the ramp no longer reaches composite text — only its direct consumers.

### 🛠️ 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 is authored as a percentage of the font size (Figma's unit) and emitted in `em`, which has the same meaning and is valid CSS — `1%` becomes `0.01em`. Percentages are not accepted by CSS `letter-spacing`.

## 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 Plain CSS Alongside the SCSS

```sh
npx build-tokens --css true
```

### 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 \
  --css true
```

## Contributing
We welcome contributions! Please see our [CONTRIBUTING.md](./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.