Tokens

Tokens are a valuable asset to your design system, as this is the source of truth for most of your CSS property values. By creating and managing tokens using powerful vanilla CSS features like the CSS custom properties feature, you'll be able to create a very reliable source of truth for your design system. Sentro makes this process very easy to do and to maintain.

Instantiation

The instantiation instructions can be found here.

Basic Usage

Configure your tokens using the sentro.token-config() mixin.

• It can be a map with a default value and variants, or a separate variable argument.
• For maps, the default key is the set non-variant key for the parent key (please see the examples below).

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

:root {
  @include sentro.token-config(
    $brand-color: (
      'default': #122c53,
      'ink': #fff
    ),
    $small-radius: 0.3rem,
    $medium-radius: 0.5rem,
  );
}

...

The token-config() mixin also supports map-based token sets using the $map parameter.

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

$_my-token-map: (
  'brand-color': (
    'default': #122c53,
    'ink': #fff
  ),
  'radius': (
    'small': 0.3rem,
    'medium': 0.5rem
  )
);

:root {
   @include sentro.token-config(
     $map: $_my-token-map
   );
}

...

Two-way token creation

It also supports both at the same time.

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

$_my-token-map: (
  'brand-color': (
    'default': #122c53,
    'ink': #fff
  ),
  'radius': (
    'small': 0.3rem,
    'medium': 0.5rem
  )
);

:root {
  @include sentro.token-config(
    $map: $_my-token-map,
    $accent-color: (
      'default': #122c53,
      'ink': #fff
    )
  );
}

You can also nest tokens. Though we do not recommend nesting too deep, about 3 levels is the maximum.

:root {
  @include sentro.token-config(
    $accent-color: (
      'default': #122c53,
      'ink': #fff,
      'variant': (
        'default': default-token,
        'light': light-ver,
        'dark': (
          'default': dark-ver, 
          'point-1': point-1-ver
        )
      )
    )
  );
}

Apply these tokens to your CSS property values using the sentro.token-get() function.

• If the token you created has the default as the key of its variant, you won't have to point it to add default to your token-get() key as sentro automatically maps it for you.

...

.my-component {
  background: sentro.token-get('brand-color');
  color: sentro.token-get('brand-color-ink');
}

CSS Output

/* CSS Output */
:root {
  --sdc-token-brand-color: #122c53;
  --sdc-token-brand-color-ink: #fff;
}

.my-component {
  background: var(--sdc-token-brand-color);
  color: var(--sdc-token-brand-color-ink);
}

Token API

token-config() mixin

⚠ Must be used within a selector!

Adds tokens to the design system.

There are two parameters to this mixin. The first one is to insert a pre-made token map. It could be from the design team, or from the project's UX lead. Then the second one is for adding your own tokens.

Both parameters can be used simultaneously, or if you don't want that you can always use one or the other.

SYNTAX

@include sentro.token-config({map} $map, $tokens...);

USAGE

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

:root {
  @include sentro.token-config(
    $brand-color: (
      'default': #122c53,
      'ink': #fff
    ),
    $small-radius: 0.3rem,
    $medium-radius: 0.5rem,
  );
}

...

token-check() function

⚠ Must be used within a conditional statement!

Checks if a token is a valid token or not. NOTE: It does not throw and error when the value is asserted as false, you need to make the error yourself.

SYNTAX

sentro.token-check({string} $query);

USAGE

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

@function tell-me-if-its-a-token($token) {
    @if sentro.token-check($token) {
        @return 'IT IS A TOKEN!';
    } @else {
        @return 'Oh, that\'s disappointing...';
    }
}

...

token-create() mixin

⚠ Must be used within a selector!

Creates a token.

This is the smallest and the most basic mixin for this API. This is where all the individual tokens gets passed and made into a design token available for querying.

SYNTAX

@include sentro.token-create({string} $key, {*} $value);

USAGE

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

:root {
  @include sentro.token-create('brand-color-light', #ff7700);
}

...

token-get() function

⚠ Must be used as a property value, css-function value, or key-fallback value!

Queries and retrieves a token in its CSS custom property form.

Allows you to query your own tokens and pass it off inside a property to be used.

SYNTAX

sentro.token-get({string} $key);

USAGE

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

.my-selector {
    background-color: sentro.token-get('brand-color-light');
}

...

token-get-raw() function

⚠ Must be used as a property value, css-function value, or key-fallback value!

Queries and retrieves a token in its raw value form.

Allows you to query your own tokens and pass it off inside a property to be used.

This is especially useful when using the sass version of the rgba() function.

SYNTAX

sentro.token-get-raw({string} $key);

USAGE

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

.my-selector {
    background-color: rgba(sentro.token-get-raw('brand-color-light'), 70%);
}

...

token-switch() function

Queries a token; if it is a token it returns the token, if not it returns the value as is.

This is especially useful when creating your styling API.

SYNTAX

sentro.token-switch({string} $query);

USAGE

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'token');

$fill: #ff7700 !default;

.my-selector {
    background-color: sentro.token-switch($fill);
}

...