outsystems-design-tokens

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

• _root.scss - CSS custom properties (:root variables)
• _variables.scss - SCSS variables with CSS variable fallbacks
• _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

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.