Guide
Comparing to @vuepress/plugin-palette
, this plugin allows you to:
- Derive related styles based on user configuration
- Provide style customization similar to theme in plugins
- Group applications across multiple plugins or themes via id option
Before using the plugin, you need to understand the id option, as well as three styling concepts: configuration, palette and generator.
ID Option
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.
All aliases and module names have an ID prefix, which means you can use a set of style variables within your plugins (or theme) to unify your styles without being affected by other plugins (or themes).
Users can configure all color variables, breakpoints, and other style configurations in the same file and have them automatically applied on themes and plugins with the same ID.
Example
vuepress-theme-hope
and other related plugins use the same IDhope
to call the plugin, so the styles configured by the user in the theme will automatically take effect in all 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
and${id}-paleete
.Example
vuepress-theme-hope
is using ID"hope"
, and just imagine avuepress-plugin-abc
is using"abc"
. They can get their own variables with module namehope-config
hope-palette
andabc-config
abc-palette
.Calling the plugin with the same ID has no side effects.
example
vuepress-theme-hope
and other related plugins use the same IDhope
to call the plugin.
Config
Config file is used for Sass variable only. It holds Sass variables which can be used via ${id}-config
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
Imagine you are invoking the plugin with the following options in vuepress-plugin-abc
:
useSassPalette(app, {
id: 'abc',
defaultConfig: 'vuepress-plugin-abc/styles/config.scss',
})
User config file:
$navbar-height: 3.5rem;
Default config file:
$navbar-height: 2rem !default;
$sidebar-width: 18rem !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.$navbar-height; // 3.5rem
@debug abc-config.$sidebar-width; // 18rem
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 manually import the module with @use "@sass-palette/${id}-config";
.
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
Imagine you are invoking the plugin with the following options in vuepress-plugin-abc
:
useSassPalette(app, {
id: 'abc',
defaultPalette: 'vuepress-plugin-abc/styles/palette.scss',
})
If users are setting:
$color-a: red;
And you are providing a default palette file with:
$color-a: blue !default;
$color-b: green !default;
Then the below CSS variables will be available under root selector:
:root {
--color-a: red;
--color-b: green;
}
Like config file, palette file provides a module named ${$id}-palette
(also including generator values), and it is also limited by additionalData
option, so you should import the module manually if you want to use it in other Sass files.
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 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 you will get:
:root {
--text-color: #222;
--bg-color: #fff;
}
[data-theme='dark'] {
--text-color: #999;
--bg-color: #1e1e1e;
}
Allowed Variable Types
Only colors (or color map for light/dark mode), 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';
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
A generator file is facing developers to generate derived values based on palette file variables.
You can access variables from palette file directly in this file and generate new values based on them.
Variables in generator file will be also injected as CSS variables like palette, and they will be available in palette 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-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;
You can also generate values based on variables provided by config files by importing it:
// generator with id "abc"
@use 'sass:color';
@use '@sass-palette/abc-config';
@use '@sass-palette/helper';
$code-c-bg: abc-config.$highlighter == 'shiki'? #fff: #f8f8f8;
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.
Tips
@sass-palette/${id}-style
is an alias to user style file, and you can import it in JS/TS/SASS.