What's New in v5

v5 is a full API rewrite focused on making every call stateless and explicit. Here are the highlights.

New: theme() mixin

Validates tokens against a reference schema and emits custom properties in a single call — no need to call validation() then emit() separately.

scss

@use "@magnesium/theme";

$refs: (
    "text-color": darkcyan,
    "font-size": 1rem
);

.button {
    @include theme.theme($refs, ("text-color": darkorange), "button");
}

css

.button {
    --mg-button-text-color: darkorange;
}

New: ref() function

Returns a var() reference for a token by name, using the configured prefix. Useful for aliasing tokens across namespaces without hardcoding the prefix.

.button {
    background: theme.ref("sys-primary");
    // → var(--mg-sys-primary)
}

New: $layer on emit() and theme()

Wrap any token emission in a named CSS cascade layer with the $layer parameter. See emit().

New: $selector and $layer on scheme()

Scope a color scheme to an explicit CSS selector instead of a @media query — useful for user-controlled theme switching — and wrap it in a named cascade layer so light and dark declarations share the same layer. See scheme().

New: $namespace replaces $prefix / $component

All functions and mixins now use a consistent $namespace parameter (without the global prefix) instead of the previous $prefix or $component names.

Compat layer

All v4 APIs are still available via the compatibility layer during migration. See the migration guide.