Store the Design Tokens used on the Ionic Framework and Widgets Library
npm install outsystems-design-tokensStore the Design Tokens used on the OutSystems UI Frameworks. Other related assets, like Font files, are stored on the assets folder.
- Introduction
- Installation
- Usage
- Output Files
- Options
- Source & Destination
- Prefixes
- Output Control
- File Names
- Features
- Examples
- Contributing
- License
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.
To install the dependencies, run:
``sh`
npm install
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.
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
By default, the build generates three files:
1. _root.scss - CSS custom properties (:root variables)_variables.scss
2. - SCSS variables with CSS variable fallbacks_utilities.scss
3. - Utility classes for direct HTML usage
| 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 | - |
| 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:
- CSS custom properties:
- Utility classes:
| Option | Description | Default |
|--------|-------------|---------|
| --root | Generate CSS custom properties file | true |--scss
| | Generate SCSS variables file | true |--utilities
| | Generate utility classes file | true |
| 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 |
- 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 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 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 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 values are automatically converted from percentage to pixels for better browser compatibility.
Generate all files with default settings:
`sh`
npm run build.tokens
Output to a specific directory:
`sh`
npx build.tokens --dest src/styles/
Use a custom prefix for all tokens:
`sh`
npx build.tokens --prefix custom
Use different prefixes for SCSS and CSS:
`sh`
npx build.tokens --prefix token --scss-prefix ion --dest src/scss/
Skip SCSS variables and utilities:
`sh`
npx build.tokens --scss false --utilities false
Skip CSS custom properties and SCSS variables:
`sh`
npx build.tokens --root false --scss false
Use custom names for output files:
`sh`
npx build.tokens --root-file theme.scss --scss-file vars.scss --utilities-file utils.scss
`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