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.

Basic Usage

Configuring tokens

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: 'theme');
 
: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: 'theme');
 
$_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 configuration

It also supports both at the same time.

@use 'node_modules/@matteusan/sentro' with ($prefix: 'sdc', $context: 'theme');
 
$_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
    )
  );
}

Nesting tokens

You can also nest tokens. Though we do not recommend nesting too deep as it can be hard to manage. We recommend using up until 2 levels of nesting. This leaves you with a good balance between manageability and flexibility.

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

Using tokens

Using these tokens in 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 */
.my-component {
  background: var(--sdc-token-brand-color);
  color: var(--sdc-token-brand-color-ink);
}

Using tokens with !important

You can also use the sentro.token-get() function with the !important flag attached to the value. By default, the !important flag is set to false.

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

CSS Output

/* CSS Output */
.my-component {
  background: var(--sdc-token-brand-color) !important;
  color: var(--sdc-token-brand-color-ink) !important;
}

Using tokens with a custom separator

When you want to use custom separators for your tokens, the global separator can be changed using the $separator parameter. Please refer to this guide for more information.