Introduction

The Magnesium Sass Framework helps you easily develop your Web Design System.

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($tokens, $prefix)

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

@use "@magnesium/theme";

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

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

Result

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

Functions

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

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

@use "@magnesium/theme";

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

.foo {
    color: theme.emit-variable($tokens, "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
);

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

$tokens: theme.validation($reference, $tokens); // Return `$tokens` 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");