Voca design system foundations

This package contains the most atomic building blocks of Voca design system - tokens & variables. Design tokens are platform-agnostic entities that are defined and used by the designers. They also act as a source for the style-dictionary to generate usable files and variables for the web platform and possibly more.

Tokens and the generated variables are classified by categories: border, breakpoint, color, motion, shadow, spacing, typography.

Contents

1. Consumption
2. Development

Consumption

Design Tokens

Tokens are located in tokens directory in the form of JSON files. There are two types of tokens in our system - base & semantic. tokens/base represent our core set of values & scales, while tokens/semantic only reference the base tokens, however they carry design intent and context. Tokens are structured following the CTI pattern - Category, Type, Item. Meaning that top level properties in JSON file are Category objects, their properties are Type objects and the Type properties are Item objects, containing the actual token value.

{
  "category": {
    "type": {
      "item": {
        "value": "token_value"
      }
    }
  }
}

In certain cases, like semantic color tokens, there can be an additional Sub-item level.

Token variables

Each category as a separate directory has a set of consumable files containing variables:

1. .css - global CSS variables
2. .scss - SCSS variables
3. .js - ES6 named exports for each variable
4. .d.ts - TS variable type declarations
5. .json - variables in JSON format (note: it's different from token JSON files in tokens/)
6. ... If you need additional format, please, feel free to contact our team with a request

Usage

CSS

.css files contain CSS variables (custom properties) which are applied at the :root of the document upon import or load of our stylesheet. Meaning they will be globally available due to CSS cascade & inheritance feature, so you don't have to re-import them in every file that references these variables.

/* import all variables anywhere in the root of your app once*/
@import '~@teliads/foundations/index.css';
/* Webpack */
/* or only specific category */
@import '~@teliads/foundations/color/variables.css'; /* Webpack */
/* TBA for other bundlers */

/* then refer anywhere in your app */
.button {
    background-color: var(--vds-color-background-interactive-primary);

    /* or with a fallback, if required */
    background-color: var(--vds-color-background-interactive-primary, purple);
}

Note: loading all the variables could make browser dev-tools experience unpleasant for some, since all the variables will be visible when inspecting styles.

SCSS

.scss files contain SCSS variables, which are different from CSS variables and should be consumed in a different manner, as they are scoped to the module they're declared in. So in order to use our SCSS variables you need to load them in every module you reference them.

// import all the variables to your scss module (file)
@use '~@teliads/foundations'; // Webpack

// use variables through imported namespace
.button {
  background-color: foundations.$vds-color-background-interactive-primary;
}

// or import only a single category
@use '~@teliads/foundations/color/variables';

.button {
  background-color: variables.$vds-color-background-interactive-primary;
}

// or with a custom namespace
@use '~@teliads/foundations/color/variables' as colors; // Webpack

.button {
  background-color: colors.$vds-color-background-interactive-primary;
}

* More on SCSS Namespaces ⚠ You might be tempted to use @import rule to define the variables globally, however refrain from doing so, as this rule will be discontinued.

Javascript / Typescript

Javascript files contain variables which are exported individually as named exports. There's a type declaration file for Typescript to resolve automatically if you're using typescript. But the usage remains the same for JS and TS users.

// React + styled-components

// you can import individual variables from barrel file
import { vdsColorBackgroundInteractivePrimary } from '@teliads/foundations';

const Button = styled.button`
  background-color: ${vdsColorBackgroundInteractivePrimary};
`;

// or namespace all of the variables and refer to them via namespace object
import * as vdsVariables from '@teliads/foundations';

const Button = styled.button`
  background-color: ${vdsVariables.vdsColorBackgroundInteractivePrimary};
`;

// or you can import only the category you need
import { vdsColorBackgroundInteractivePrimary } from '@teliads/foundations/color/variables';

const Button = styled.button`
  background-color: ${vdsColorBackgroundInteractivePrimary};
`;

JSON

In case you need to access variables in a more language agnostic context, you can use .json files containing token objects or use the design tokens themselves, which are located in the tokens directory (⚠ keep in mind that these files have unresolved referenced values). The actual usage is highly dependent on your use case and the context you're using the file in.

Development

This package is a build tool, which bridges the styling values in design and the front-end platform. It's main purpose is to provide a single source of truth for the design tokens and generate platform-specific variables from them. Design tokens are defined with Figma Token Studio plugin and then, on-demand (⚠ automation is missing here - requires manual export/import a.k.a copy/paste), are exported to JSON files in tokens directory. Then the Style Dictionary library is used to read those JSON files and generate platform-specific variables according to the configuration provided.

Installation

Since it's a part of the monorepo, it's recommended to install it with yarn in the root of the project.

Updating token variables

1. Update the source - design tokens JSON files in tokens directory.
2. Commit the changes and create a PR.
3. Wait for the Foundations: generate output workflow to finish.
4. You should now see a new commit added to your PR with the generated output.
5. Review the changes and merge the PR.

Modifying the output

The output is controlled by build.ts script. There you can use the JS in combination with the style-dictionary API to customise the output in any way you need.

Scripts

• build - 1) runs style dictionary build script which generates output and 2) runs prettier to add EOL at EOF of generated output files (not required after [email protected])
• test - runs jest test suite for this package
• test-watch - runs jest test suite for this package and listens for changes

Workflows

• Foundations: generate output - on PR creation runs build script and commits the generated output to the PR branch.
• Foundations: release - on PR merge to main branch bumps package version according to provided PR label and publishes the package to NPM registry.