core/tokens

@use "@vrembem/core/tokens";

Modules

The tokens Sass module implements three extensions to further expand how tokens can be defined and managed.

• @vrembem/core/palette: Adds token support for generating and accessing palette based tokens.
• @vrembem/core/breakpoints: Adds token support for responsive values that change across breakpoints.
• @vrembem/core/themes: Adds token support for themed values using light, dark, and custom themes.

Basic usage

The tokens module manages design tokens as CSS custom properties. Use set() to store tokens, get() to reference them, and output() to render them as CSS.

@use "@vrembem/core/tokens";

// Store tokens under a component namespace
@include tokens.set("button", (
  "background": teal,
  "foreground": salmon,
  "padding": 1em 1.5em
));

// Reference tokens in your styles
.button {
  background: tokens.get("button", "background");
  color: tokens.get("button", "foreground");
  padding: tokens.get("button", "padding");
}

// Output all stored tokens as CSS custom properties
@include tokens.output();

.button {
  background: var(--vb-button-background);
  color: var(--vb-button-foreground);
  padding: var(--vb-button-padding);
}

:root {
  --vb-button-background: teal;
  --vb-button-foreground: salmon;
  --vb-button-padding: 1em 1.5em;
}

The examples in this section assume you are using the default configuration provided by Vrembem such as prefix-tokens, breakpoints, and palette. For more information on config options, see the core/config documentation.

Breakpoints

When the core/breakpoints plugin is loaded, tokens can be made responsive by setting a value map with "type": "breakpoints". The "initial" key sets the initial value, and breakpoint keys set values at specific breakpoints.

@use "@vrembem/core/tokens";
@use "@vrembem/core/breakpoints";

@include tokens.set("layout", (
  "padding": (
    "type": "breakpoints",
    "initial": 1em,
    "md": 1.5em,
    "lg": 2em
  )
));

@include tokens.output();

:root {
  --vb-layout-padding: 1em;
}

@media (min-width: 760px) {
  :root {
    --vb-layout-padding: 1.5em;
  }
}

@media (min-width: 990px) {
  :root {
    --vb-layout-padding: 2em;
  }
}

Palette

When the core/palette plugin is loaded, color tokens are generated using the values set in the palette config option. The palette plugin also extends the tokens.get() function when returning a palette token by allowing more precise control over lightness, chroma and alpha channels.

@use "@vrembem/core/tokens";
@use "@vrembem/core/palette";

// Reference palette tokens with custom lightness, chroma and alpha values
// Example: tokens.get("palette", "[name]", $l, $c, $a);
.button {
  background: tokens.get("palette", "primary", $a: 50%);
  color: tokens.get("palette", "primary", 18%, 60%);
}

// Use a variant key to reference a predefined palette-variant
.surface {
  background: tokens.get("palette", "primary", "700");
}

.button {
  background: oklch(from var(--vb-primary) l c h / 50%);
  color: oklch(18% calc(var(--vb-primary-c) * 0.6) var(--vb-primary-h));
}

.surface {
  background: oklch(30% var(--vb-primary-c) var(--vb-primary-h));
}

You can also define primitive palette colors (such as "green", "blue", etc) that can be aliased using semantic tokens (such as "primary", "secondary", etc). This can be used to create themes by changing the semantic color mapping for a specific theme.

@use "@vrembem/core/config";

// Tip: use `config.merge` if you'd like to keep existing configurations of a map
@include config.set("palette", (
  // Define primitive palette colors
  "green": #35cc86,
  "blue": #3680dd,
  "gray": #718298,
  "red": #ce5247,

  // Define aliases to existing palette colors
  "primary": "green",
  "secondary": "blue",
  "neutral": "gray",
  "important": "red",
));

Themes

When the core/themes plugin is loaded, tokens can be themed by setting a value map with "type": "mode" or "type": "theme". The map key is used as the mode or theme name. All other key/value pairs in the provided map are used as their tokens.

@use "@vrembem/core/tokens";
@use "@vrembem/core/themes";

@include tokens.set("core", (
  "light": (
    "type": "mode",
    "color-scheme": light,
    "background": lightblue,
    "foreground": darkblue
  ),
  "dark": (
    "type": "mode",
    "color-scheme": dark,
    "background": darkblue,
    "foreground": lightblue
  ),
  "forest": (
    "type": "theme",
    "background": lightGreen,
    "foreground": darkGreen
  )
));

@include tokens.output();

:root,
[data-mode=auto] {
  color-scheme: light;
  --vb-background: lightblue;
  --vb-foreground: darkblue;
}
@media (prefers-color-scheme: dark) {
  :root,
  [data-mode=auto] {
    color-scheme: light;
    --vb-background: darkblue;
    --vb-foreground: lightblue;
  }
}

[data-mode=light] {
  color-scheme: light;
  --vb-background: lightblue;
  --vb-foreground: darkblue;
}

[data-mode=dark] {
  color-scheme: dark;
  --vb-background: darkblue;
  --vb-foreground: lightblue;
}

[data-theme=forest] {
  --vb-background: lightGreen;
  --vb-foreground: darkGreen;
}

To create a theme using palette aliasing, import the palette plugin module and remap aliases in the desired theme namespace. The tokens.get("palette-remap", ()) getter will automatically inject "type": "theme" on the returned palette map.

@use "@vrembem/core/config";
@use "@vrembem/core/tokens";
@use "@vrembem/core/themes";
@use "@vrembem/core/palette";

// Configure your palette colors and semantic aliases
@include config.set("palette", (
  "green": #35cc86,
  "blue": #3680dd,
  "primary": "green"
));

// Define your palette themes by remapping the alias
@include tokens.set("core", (
  "forest": tokens.get("palette-remap", ("primary": "green")),
  "ocean": tokens.get("palette-remap", ("primary": "blue"))
));

// Output all tokens
@include tokens.output();

[data-theme=forest] {
  --vb-primary: var(--vb-green);
  --vb-primary-l: var(--vb-green-l);
  --vb-primary-c: var(--vb-green-c);
  --vb-primary-h: var(--vb-green-h);
}

[data-theme=ocean] {
  --vb-primary: var(--vb-blue);
  --vb-primary-l: var(--vb-blue-l);
  --vb-primary-c: var(--vb-blue-c);
  --vb-primary-h: var(--vb-blue-h);
}

Themes and modes can be used together to create light and dark modes for any theme. This reduces the necessary token definitions needed since the semantic tokens set in modes can be reused across all themes.

<html data-mode="light" data-theme="forest">

Reference

Tokens provides a straightforward API for managing design tokens. Define, reference and output custom properties both globally and on a per-component basis. The tokens module can also be extended by registering hooks and event listeners.

set

Mixin to store custom properties for later definition and reference. Can also update the entire custom properties map or a stored component map by passing "*" value to $component or $prop respectively.

Arguments

Example

// Set a single option
@include tokens.set("block", "accent", teal);

// Set multiple options at once
@include tokens.set("block", (
  "background": darkGreen,
  "foreground": lightPink
));

set-scoped

Mixin to store and output custom properties scoped to the current selector. Properties set using this mixin are excluded from the global output() mixin, making them component-scoped rather than output in :root.

Arguments

Example

// Set component scoped token
.button {
  @include tokens.set-scoped("button", (
    "color": #000,
    "contrast-color": #fff,
  ));
}

// CSS Output
.button {
  --vb-button-color: #000;
  --vb-button-contrast-color: #fff;
}

get

Function to return a custom property reference that has been stored in the custom properties map using set(). Can also return the entire custom properties map or one of the stored component maps.

Arguments

Example

.block {
  background: tokens.get("block", "background");
  color: tokens.get("block", "foreground-hover", "foreground");
}

.block {
  background: var(--vb-block-background);
  color: var(--vb-block-foreground-hover, var(--vb-block-foreground));
}

output

Output all custom properties of a provided component. Or output all custom properties from all components by passing "*" as the argument. Wraps the output in a :root selector and emits the "output" event for registered listeners.

Arguments

Example

@include tokens.output("block");

:root {
  --vb-block-accent: teal;
  --vb-block-background: blue;
  --vb-block-foreground: green;
}

override

Mixin to override previously defined custom properties. This is primarily used in the context of a modifier. Provided component must be registered in the custom properties map.

Arguments

Example

.block--modifier {
  @include tokens.override("block", (
    "background": darkGreen,
    "foreground": lightPink
  ));
}

.block--modifier {
  --vb-block-background: darkGreen;
  --vb-block-foreground: lightPink;
}

register

Register a component in the custom properties map. This is used when a component is needed to be available for later use but without setting any custom properties.

Arguments

Example

// Register the component's namespace if there are no properties set.
@include tokens.register("block");

// Provide a fallback if a specific property has not been set.
.block {
  padding: tokens.get("block", "padding", 1em);
}

.block {
  padding: var(--vb-block-padding, 1em);
}

define

Mixin to define a custom property using the provided property name and value. Automatically applied with prefix and component name if provided. This is used internally by tokens.output and tokens.override.

Arguments

Example

.block {
  @include tokens.define("block", "accent", orange);
}

.block {
  --vb-block-accent: orange;
}

reference

Function to create reference to a custom property using the provided component name, property and optional fallback. Automatically applies the necessary custom property prefix and component name.

Arguments

Example

.block {
  background: tokens.reference("block", "accent", orange);
}

.block {
  background: var(--vb-block-accent, orange);
}

has

Function used to check if a custom property has been set.

Arguments

Example

@include tokens.set("block", "background", darkGreen);

@debug tokens.has("block", "background"); // Returns true
@debug tokens.has("block", "border"); // Returns false

remove

Mixin used to remove a previously set custom property.

Arguments

Example

// Remove the "background" property from the "block" component.
@include tokens.remove("block", "background");

log

Log to console all custom properties, a component map or component theme. Provided component must be registered in the custom properties map.

Arguments

Example

@include tokens.log("block");

// Debug output:
// Custom properties of "block": (
//   "background": blue,
//   "foreground": green,
// )

add-hook

Register a hook function that intercepts token operations. Setter hooks are called during set() when a value map contains a "type" key matching the hook's key. Getter hooks are called during get() when the component matches the hook's key.

Arguments

Example

// Register a setter hook for a custom "breakpoints" type
@include tokens.add-hook("setter", "breakpoints", meta.get-function("my-setter"));

// Register a getter hook for the "palette" component
@include tokens.add-hook("getter", "palette", meta.get-function("my-getter"));

remove-hook

Remove a previously registered hook.

Arguments

Example

@include tokens.remove-hook("setter", "breakpoints");
@include tokens.remove-hook("getter", "palette");

on

Register a listener for a specific token event. Listeners are called whenever the event is emitted. Multiple listeners can be registered for the same event using unique IDs.

Arguments

Example

// Listen for the "output" event emitted by tokens.output()
@include tokens.on("output", "my-output-listener", meta.get-mixin("my-output"));

off

Remove a previously registered event listener.

Arguments

Example

@include tokens.off("output", "my-output-listener");