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
• Installation
• Usage
• Output Files
• Options
  • Source & Destination
  • Prefixes
  • Dynamic font (rem)
  • Output Control
  • File Names
• Features
• Examples
• Contributing
• 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:

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:

npm run build.tokens

Alternatively, you can use the binary command:

npx build.tokens [options]

When installed as a package in another project:

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:

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:

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 |

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:

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

$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

.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:

npm run build.tokens

Custom Destination

Output to a specific directory:

npx build.tokens --dest src/styles/

Custom Prefix

Use a custom prefix for all tokens:

npx build.tokens --prefix custom

Separate SCSS Prefix

Use different prefixes for SCSS and CSS:

npx build.tokens --prefix token --scss-prefix ion --dest src/scss/

Generate Only CSS Custom Properties

Skip SCSS variables and utilities:

npx build.tokens --scss false --utilities false

Generate Only Utility Classes

Skip CSS custom properties and SCSS variables:

npx build.tokens --root false --scss false

Custom File Names

Use custom names for output files:

npx build.tokens --root-file theme.scss --scss-file vars.scss --utilities-file utils.scss

Complete Example

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.