@telus-uds/system-themes v0.0.2-prerelease.2

System themes 🛠️

Builds UDS themes, resolving aliases to tokens.

Quick start

1. Install as a dev dependency into your UDS theme:

   npm install --dev @telus-uds/system-themes

2. Add a build script to the UDS theme package.json

   {
     // ...
     "scripts": {
       "build": "system-themes-build"
     }
   }

   ℹ️ You will probably want to set some env vars also in the build script, see below for details

Configuration

All configuration is done through environment variables.

• THEME_PATH is the input theme filename to build. Defaults to ./index.js.
• UDS_THEME_MODULE_* any module that should be loaded into the build context for resolving theme aliases, see below.

Env vars can be set in the command line or via a .env file.

The theme is always outputted to ./build/theme.js.

Theme Modules and aliases

Themes are assumed to alias values in node.js modules. For example, if a theme token has the value {system.size.none}, a system module should be loaded into the context by setting the variable UDS_THEME_MODULE_SYSTEM=path/to/system/module. Same for the token value {palette.color.purple} requires the context to be loaded by setting the variable UDS_THEME_MODULE_PALETTE=path/to/palette/module.

Example:

To load the react-native system constants and the allium palette, set the following env vars:

• UDS_THEME_MODULE_SYSTEM='@telus-uds/system-themes/src/tokens/rn'
• UDS_THEME_MODULE_PALETTE='@telus-uds/palette-allium'

Icons

Icons are treated differently from other aliases. Any token alias that has icon as at the second level (i.e. *.icon.*), will be treated as an icon.

Icon aliases are expected to resolve to a icon file that can be imported. Icon imports are assumed to importable from an index file, ignoring the filename in the palette.

For example, if a icon alias resolves to the palette key: AddUser: '@telus-uds/palette-allium/build/rn/icons/add-user.icon.svg' the built theme will import AddUser from '@telus-uds/palette-allium/build/rn/icons'.

Fonts

Fonts are treated differently from other aliases. Any token alias that has font at the second level (i.e. *.font.*), will be treated as an font.

Palette fonts are unwrapped to create virtual fontName and fontWeight palette keys. For example, if the palette has the font keys:

{
  font: {
    Times: {
      200: 'path/to/times-200.ttf',
      300: 'path/to/times-300.ttf'
    }
  }
}

The theme build will create the virtual palette keys:

{
  fontName: {
    Times: 'Times'
  },
  fontWeight: {
    200: '200',
    300: '300'
  }
}

Themes should reference fonts by referencing a valid fontName and fontWeight combination. The build will validate that these pairs reference a valid font in the original palette.

Javascript API

A JS API can also be consumed directly.

const buildTheme = require('@telus-uds/system-themes')

const options = {
  themeInput: {
    // Your theme input
  },
  tokenModules: {
    // Aliases in the theme will be resolved to paths here
    system: {}
    palette: {},
    // Any other context for resolving tokens
  }
}

const context = builtTheme(options)

// The build theme
const {themeOutput} = context