@magnesium/theme

Introduction

Easily develop your Design System for the web, The Magnesium Sass Framework is here for that!

Installing

npm install @magnesium/theme

Usage

The theme component help you to easily manage theme styles with generate CSS custom properties declarations from user-provided theme's tokens map.

Options

Option	Description
$prefix	Add global prefix name on any custom properties. Default mg. Set to false for disable.

@use "@magnesium/theme" with (
    $prefix: "foo" // Set to `false` for disabled.
);

Mixins

emit-custom-props($theme, $prefix)

Emits CSS custom properties declarations from a user-provided theme's.

@use "@magnesium/theme";

$theme: (
    "text-color": darkcyan
);

.foo {
    @include theme.emit-custom-props($theme, "button");
}

Result

.foo {
    --mg-button-text-color: darkcyan;
}

Functions

emit-variable($theme, $token, $fallback, $prefix)

Emits CSS variable declaration from a user-provided theme's.

@use "@magnesium/theme";

$theme: (
    "text-color": darkcyan
);

.foo {
    color: theme.emit-variable($theme, "text-color", false, "button");
}

Result

.foo {
    color: var(--mg-button-text-color);
}

validation($reference, $tokens)

Validates a user-provided theme's token and throws an error if tokens are invalid.

@use "@magnesium/theme";

$reference: (
    "text-color": darkcyan
);

$theme: (
    "text-color": darkorange
);

$theme: theme.validation($reference, $theme); // Return `$theme` map if true or error if false.

Top-level config override

If variables are already configured on top-level using @use ... with, by another dependency for example, you can't use this solution anymore, because the module can only be setup once, this is a Sass restriction with Module System, but another solution exist for override the main configuration, with a mixin!

See official documentation about override configuration with mixins.

Mixin	Description
config($prefix)	Override top-level prefix configuration.

Configuration rule with theme.config()

The following Sass will configure new parameters:

@use "@magnesium/theme";

@include theme.config("fr");