Guide

About 4 min

This plugin is basically facing plugins and theme development.

ID

To get started, you should understand that this plugin is designed to take across plugins and theme (unlike the official one only for theme).

We are providing id option to do that, and using this plugin (by calling useSassPalette) with same ID won't have any side effects. Also, all the alias and module names have an ID prefix.

This will allow you to:

Share same style system across your plugins (or themes) using same ID without any side effects.
This means you can use same style variables across your plugins (or themes) to get your style unify.
Example
vuepress-theme-hope and all its plugins are invoking this plugin with same ID hope, so that all the color variables, breakpoints and other style configuration can be done at same file and be unified across theme and plugins.
With different ID, plugins and theme won't affect others. We recommend you to set the id variable with your plugin name.
With the default settings, users will set your plugin style under .vuepress/styles directory with Sass files starting with your ID prefix. And you can access the variables you need with ${id}-config.
Example
vuepress-theme-hope is using ID "hope", and just imagine a vuepress-plugin-abc is using "abc". They can get their own variables with module name hope-config and abc-config.

Styles

We have three style concepts here: config, palette and generator.

Config

Config file is used for Sass variable only. It holds Sass variables which can be used in other files later.

You can specify a file (probably in .vuepress/styles/ directory) as user config file. So you can get the module containing every variable later in Sass files. Also, you are able to provide a default config files where you can place fallback values for variables with !default.

An example

Here you are invoking the plugin with the following options:

useSassPalette(app, {
  id: "abc",
  defaultConfig: "vuepress-plugin-abc/styles/config.scss",
});

If the user sets:

$colorA: red;

And you are providing a default config file with:

$colorA: blue !default;
$colorB: green !default;

You can get the following variables in the plugin Sass files:

// <style lang="scss"> block in vue sfc or scss file directly imported in scripts
@debug abc-config.$colorA; // red
@debug abc-config.$colorB; // green

Limitations

We are using additionalData options to let ${id}-config module available in your styles, but this has some limitations.

additionalData only works on Scss entry, so ${id}-config is available only in :

<style lang="scss"> block in component files
Scss files imported by script files directly (e.g.: import "./a-scss-file.scss" in client app enhance file).

If the Scss file is not imported directly, but is imported through @use or @import api, the module won't be available. So that in this case, you should import the module yourself using @use "@sass-palette/${id}-config";.

Preserved Variables

$dark-selector is preserved for darkmode selector. You are expected to set this variable if you want your plugin or theme support darkmode. This variable will be used later in palette files.

Tips

If you are developing a plugin, you may set $dark-selector: html.dark !default; in default config files, as @vuepress/theme-default is doing that.
Your plugin will work with default theme, and users are allowed to change this selector in config file if they are using a third-party theme with different dark selector.
If you are developing a theme, you may set $dark-selector in default config files with your darkmode selector without !default, so that users cannot override it.

Palette

Palette files are used for CSS variable injection, where each variable will be injected in to root with kebab-name of variable name.

You can specify a file (probably in .vuepress/styles/ directory) as user palette file, and the default filename is ${id}-palette.scss. Also, you are able to provide a default palette files where you can place fallback values for variables with !default.

An example

Here you are invoking the plugin with following options:

useSassPalette(app, {
  id: "abc",
  defaultPalette: "vuepress-plugin-abc/styles/palette.scss",
});

If users are setting:

$colorA: red;

And you are providing a default palette file with:

$colorA: blue !default;
$colorB: green !default;

Then the below CSS variables will be available under root selector:

:root {
  --color-a: red;
  --color-b: green;
}

Color Settings

Since the default theme is providing darkmode, so you probably want different colors under lightmode and darkmode.

To achieve that, you should set color variables with a map containing light and dark keys. Later, the plugin will read $dark-selector in your config and generate different colors for you.

An example

// User palette
$text-color: (
  light: #222,
  dark: #999,
);

// Default palette
$text-color: (
  light: #2c3e50,
  dark: #9e9e9e,
) !default;
$bg-color: (
  light: #fff,
  dark: #1e1e1e,
) !default;

Then if $dark-selector has a value "html.dark" in config files, you will get:

:root {
  --text-color: #222;
  --bg-color: #fff;
}

html.dark {
  --text-color: #999;
  --bg-color: #1e1e1e;
}

Allowed Variable Types

Only colors (or color map), length and strings are allowed in palette. Any other type will be dropped.

Why only allow color and length besides strings

In common situations, you probably only want to make calculations with color and length. So it's quite safe to drop other type support, because any other value you want can be converted to string.

Example

If you want a --move-transition with width 0.3s ease, you can use strings:

// this will be regarded as a list with (length, time, function) by Sass
// and will trigger a warning and be dropped by plugin
$moveTransition: width 0.3s ease;

// this will get what you want
// :root {
//   --move-transition: width 0.3s ease
// }
$moveTransition: "width 0.3s ease";

Available in config module

Same as config file, any variables in palette will be injected into ${id}-config module, just in case you want to use them in Sass files.

Helper

We are exposing internal functions which vuepress-plugin-sass-palette uses, as a helper module.

You can use this helper with @sass-palette/helper alias and call its function to achieve similar features yourself.

Generator

Generator file is facing developers to generate derivative values with config or palette file variables.

Generator variables will be also injected as CSS variables like palette, and also they are available in config module.

Example

You may want a $theme-color-light based on $theme-color. So you can write a generator like this:

@use "sass:color";
@use "sass:list";
@use "sass:map";
@use "@sass-palette/helper";

$theme-color-light: (
  light: color.scale(helper.get-color($theme-color), $lightness: 10%),
  dark: color.scale(helper.get-dark-color($theme-color), $lightness: 10%),
) !default;

User Styles

If you are a theme developer, you may probably want to provide your users a way to custom your theme or the site.

In this case you should set style option as the user style file when using this plugin.

Later, you should manually include user style file by importing @sass-palette/${id}-style after your theme styles.

Note

@sass-palette/${id}-style is an alias to user style file, and you can import it in JS/TS/SASS.

Alias

Available alias are:

config: @sass-palette/${id}-config (based on id)
palette: @sass-palette/${id}-palette (based on id)
style: @sass-palette/${id}-style (only available when style option is set)
helper: @sass-palette/helper