sass-palette

Provide advanced styling capabilities for plugin and theme developers, based on @vuepress/plugin-palette.

Compared to the palette plugin, it offers:

• Derived styles: generate related styles based on the user config.
• Theme-like customization: allow plugins to provide style customization similar to themes.
• Style isolation and sharing: group the style system of plugins and themes with the id option.

Usage

npm i -D @vuepress/plugin-sass-palette@next

The useSassPalettePlugin function must be invoked when your plugin is initialized:

import { useSassPalettePlugin } from '@vuepress/plugin-sass-palette'

export const yourPlugin = (options) => (app) => {
  useSassPalettePlugin(app, {
    id: 'your-plugin',
  })

  return {
    // your plugin api
  }
}

Guide

To use the plugin, you should understand the id option, and the three concepts: Config, Palette and Generator.

Id

Unlike the palette plugin which is restricted to themes, this plugin works for both plugins and themes. The id option is the key to this: useSassPalettePlugin sets up a style system scoped by the id, and all generated aliases and module names are prefixed with it.

It allows you to:

• Share the style system

  Using the same id, multiple plugins (or a theme and its plugins) share the style variables, so that users can configure the variables, breakpoints and other settings in a single file, and have the changes applied everywhere.

  For example, vuepress-theme-hope and its related plugins all use the id hope, so the styles the user configures for the theme are also applied to those plugins.

• Isolate the styles

  Using different ids, plugins do not affect each other. You should set the id to your plugin name.

  By default, the user configures your styles with the Sass files prefixed with the id, and you access the variables via the ${id}-config and ${id}-palette modules.

  For example, vuepress-theme-hope using the id hope and a plugin using the id abc are fully independent, they access their own variables via hope-config/hope-palette and abc-config/abc-palette.

• Avoid side effects

  Calling the plugin multiple times with the same id is safe.

Config

The Config file only contains Sass variables, which are available via the ${id}-config module.

You provide a default config file with the defaultConfig option, where the variables should be marked with !default so that the user config can override them.

$navbar-height: 2rem !default;
$sidebar-width: 18rem !default;

$navbar-height: 3.5rem;

// in a `<style lang="scss">` block or a directly imported Sass file
@debug abc-config.$navbar-height; // 3.5rem
@debug abc-config.$sidebar-width; // 18rem

Palette

The Palette file contains CSS variables. Every variable is converted to kebab-case and injected into the root stylesheet.

You provide default values with the defaultPalette option, also marked with !default.

$color-a: blue !default;
$color-b: green !default;

$color-a: red;

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

To support the light and dark modes, a color variable can be a map with light and dark keys, then the CSS variables of both modes are generated.

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

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

[data-theme='dark'] {
  --text-color: #999;
}

Only colors (including light/dark maps), lengths and strings are allowed in the palette, other types are discarded to keep the generated CSS variables valid. Complex values should be strings.

// ❌ Regarded as a Sass list, triggers a warning and is dropped
$moveTransition: width 0.3s ease;

// ✅ :root { --move-transition: width 0.3s ease; }
$moveTransition: 'width 0.3s ease';

The palette module is named ${id}-palette, which also includes the values from the generator, and shares the same import limitation as the config module.

Generator

The Generator file generates derived values based on the palette and config variables. Its variables are injected as CSS variables like the palette, and are also available in the palette module.

For example, you may want a lighter version of the user's theme color:

@use 'sass:color';
@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;

Config variables are also available:

@use 'sass:color';
@use '@sass-palette/abc-config';
@use '@sass-palette/helper';

$code-c-bg: abc-config.$highlighter == 'shiki' ? #fff : #f8f8f8;

Helper

The internal Sass functions of the plugin are exposed via the @sass-palette/helper module.

Options

Alias

The following aliases are available for import:

• config: @sass-palette/${id}-config
• palette: @sass-palette/${id}-palette
• helper: @sass-palette/helper