npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ungic-sass-theme

v1.1.3

Published

Dart Sass module for working with colors and creating themes

Downloads

28

Readme

Ungic SASS Theme module

This module was created to manage the colors and styles of SASS projects.

Features

  • Store colors in a separate theme config file
  • Methods for quickly manipulating theme colors
  • Own technique for creating shades, tints of given theme colors with a flexible configuration
  • Maintaining a balance between light and dark theme color (text color and background color)
  • Flexible customization of the theme color palette
  • Simultaneous support for light and dark theme (Inverse theme). Correct theme inversion is performed automatically when switching the inverse-mode theme configuration parameter
  • Generate projects with different configuration themes (with different colors) without changing styles
  • Greyscale functionality that automatically calculates gray color based on background and text colors of current theme, and provides methods for dealing with grayscale from darkest to lightest relative to main theme colors (background and text)
  • Works with css colors and css vars! Just choose your preferred method
  • Integrate into any SASS framework that supports dart sass build

Everything you need to work with colors in your sass projects is here!

Demo

Get Started

First, you can look at the ready-made demo project.

New project

Add ungic-sass-theme npm package to your project

npm install ungic-sass-theme

Manual configuration (Sass only)

And use it in your sass files, but first you need to configure this module!

  1. Create your first theme configuration file:

You can see an example of theme configuration file here

// myproject/themes/default.scss 

$colors: (
    primary: #07f857,
    secondary: #3d3931,
    success: #cce678,
    danger: #e6787d,
    info: #4bafee,
    warning: #eee84b,
    system: (#C6530C, #ef8646),
    text-color: (#192d20, #fff9ea),
    background-color: (#fff9ea, #192d20)
);

$config: (
    brightness: (
        offset-brighten: 0,          // List type possible
        offset-dim: 0,               // List type possible
        saturation-brighten: (0, 0),  // List type possible
        saturation-dim: (0, 0)        // List type possible
    ),
    relative-light-limit : true,
    gray: (
        saturation: 5%,   // List type possible
        hue: blue       // List type possible
    )
);

$palettes: (
    primary: (
        lighten: #e8f2c7,
        darken: #4c5d15
    ),
    secondary: (
        lighten: #f5f3e6,
        darken: #2a2925
    )
); 


// Inverse mode
$inverse-mode: false;

// Colors mode
$colors-vars-mode: true;
  1. Configure the ungic-sass-theme module and pass it the configuration we created
// myproject/theme.scss

@use "sass:meta";

@use "./themes/default" as theme-config; // Get your theme configuration

@use "ungic-sass-theme" with (
    $theme: meta.module-variables(theme-config) // and pass it to ungic-sass-theme module
);

@forward "ungic-sass-theme";
  1. Use your configured module!
@use "./theme" as theme; // our configured module, also you can use as *

body {
    background-color: theme.color(background-color); // or theme.bgc()
    color: theme.color(); // or theme.color(text-color)
}

.btn {
    color: theme.primary();
    border: 2px solid theme.color(primary); // the same as theme.primary();
    &:hover {
        /*
        * Create a tint 20% lighter or darker relative to the primary colors (text and background colors) and also, relative to the current theme (light or dark), 
        * the light theme will have a lightening, 
        * the dark theme will darken!
        */
        color: theme.primary(.2);

        /*
        * There are also tools that help you set values relative to the theme type.
        * subs(valueForLightTheme, valueForDarkTheme), see documentation for details
        * subs(NUMBER); - inverts the number for the opposite theme type
        */
        border-color: theme.primary(theme.subs(2));
    }
}

Theme inversion

To generate a theme inversion, just switch the inverse-mode theme configuration parameter (sass var)

// myproject/themes/default.scss 

...

$inverse-mode: true;

and rebuild your project.

Would you like to add both versions to your project? See below

Multiple themes

Only one theme and one theme type (light or dark) can be built per project build, but wait, don't go, as always there is a way!

To get started, to generate another theme, just pass another configuration file to the ungic-sass-theme module

// myproject/theme.scss

@use "sass:meta";

@use "./themes/my-other-theme" as theme-config; // Your other theme
@use "ungic-sass-theme" with (
    $theme: meta.module-variables(theme-config)
);

@forward "ungic-sass-theme";

And now about how to add multiple themes and inversion to your project!

First of all, you need to understand that we cannot generate colors for everything at once in one build, only if you want to use my ungic framework .. which imitates this behavior...

Therefore, we can generate styles by extracting colors from common css styles and prefixing the selector with the name of our theme or theme type. For this I have created the postcss-colors-extractor plugin

postcss-colors-extractor

This is a postcss plugin that extracts colors into separate css rules and adds the desired prefix to the selector, and can extracts such rules into separate .css files

use it like other postcss plugins


const colorExtractor = require("postcss-color-extractor");
...
    {
        loader: "postcss-loader",
        options: {
            postcssOptions: {
                plugins: [
                    colorExtractor({
                        extract: input => {
                            console.log(input.toResult(), input.source?.input?.file);
                        }
                    })
                ]
            }
        }
    }

Webpack configuration

The second way to inject a theme into your sass using webpack:

// Webpack configuration
const additionalDataProvider = require('ungic-sass-theme');

module: {
    rules: [
        {
            test: /\.scss$/,
            use: [
                "style-loader",
                "css-loader",
                {
                    loader: "sass-loader",
                    options: {
                        additionalData: additionalDataProvider({...}) // types.ProviderOptions
					}
                }
            ],
        },
    ],
}

Documentation

Usage

@use "sass:meta";

@use "./themes/my-other-theme" as theme-config; // Your other theme
@use "ungic-sass-theme" as theme with (
    $theme: meta.module-variables(theme-config)
);

.color {
    color: theme.color(primary); // Methods
}

@debug theme.$inverse-mode; // Vars

$inverse-mode

  • Type: variable

  • Usage:

    Contains the status of inversion build mode

    :::tip Use the get method instead

    @use "ungic.theme" as theme;
    
    @debug get(inverse-mode);

    :::

$colors

  • Type: variable

  • Usage:

    Contains the colors of the current project theme

    :::tip Use the color method instead :::

$config

  • Type: variable

  • Usage:

    Contains the config of the current project theme

$palettes

  • Type: variable

  • Usage:

    Contains the palettes of the current project theme

    :::tip Use the palette method instead :::

    :::tip The palette method also used in the color method as the second parameter! :::

$theme-type

  • Type: variable

  • Usage:

    Theme type, dark or light

    :::tip Use the get method instead

    @use "ungic.theme" as theme;
    
    @debug get(theme-type);

    :::

has-palette

  • Type: function

  • Parameters:

    • $color-name - theme color name
    • $tint-name, Default: null - color tint name (optional parameter to generate more detailed error in logs)
    • $silent, Default: false - error output to console
  • Usage: theme.has-palette($color-name, $tint-name: null, $silent: false)

    Checks if the theme color has a palette

has-palette-tint

  • Type: function

  • Parameters:

    • $color-name - theme color name
    • $tint-name - color tint name
    • $silent, Default: false - error output to console
  • Usage: theme.has-palette-tint($color-name, $tint-name, $silent: false)

    Checks if the color of the palette has a specific color tint

palette

  • Type: function

  • Parameters:

    • $color-name - theme color name
    • $tint-name - color tint name
    • $hue-offset, Default: 0 - offset the hue of color using the color.adjust sass method
  • Usage: theme.palette($color-name, $tint-name, $hue-offset: 0)

    Get color tint of theme color with hue offset

lighten

  • Type: function

  • Parameters:

    • $color - theme color name
    • $intensity - Number - must be a number from 0 to 1 or percentage from 0 to 100%
  • Usage: theme.lighten($color, $intensity)

    Custom color lighten method, works in relation to the main colors (text-color, background-color) of the theme.

darken

  • Type: function

  • Parameters:

    • $color - color or theme color name
    • $intensity - Number - must be a number from 0 to 1 or percentage from 0 to 100%
  • Usage: theme.darken($color, $intensity)

    Custom color darken method, works in relation to the main colors (text-color, background-color) of the theme.

lightness

  • Type: function

  • Parameters:

    • $color - color or theme color name
    • $intensity - Number - must be a number from -1 to 1
  • Usage: theme.lightness($color, $intensity)

    A method that lightens or darkens a color depending on the type of theme.

    • if theme is light - a positive number increases light in color and a negative number decreases the amount of light in color
    • if theme is dark - a positive number decreases the light in color, and a negative number increases the amount of light in a color

brightness

  • Type: function

  • Parameters:

    • $color - color or theme color name
    • $intensity - Number - must be a number from -1 to 1
    • $hue-offset - Default: 0 - offset the hue of color using the color.adjust sass method
    • $saturation - Default: 0 - offset the saturation of color using the color.adjust sass method
  • Usage: theme.brightness($color, $intensity, $hue-offset: 0, $saturation: 0)

    Works like lightness method but also adjusts the hue and saturation of color

dim

  • Type: function

  • Parameters:

    • $color - color or theme color name
    • $intensity - Number - must be a number from -1 to 1
    • $hue-offset - Default: 0 - offset the hue of color using the color.adjust sass method
    • $saturation - Default: 0 - offset the saturation of color using the color.adjust sass method
  • Usage: theme.dim($color, $intensity, $hue-offset: 0, $saturation: 0)

    Used in the brightness method to darken the color

brighten

  • Type: function

  • Parameters:

    • $color - color or theme color name
    • $intensity - Number - must be a number from -1 to 1
    • $hue-offset - Default: 0 - offset the hue of color using the color.adjust sass method
    • $saturation - Default: 0 - offset the saturation of color using the color.adjust sass method
  • Usage: theme.brighten($color, $intensity, $hue-offset: 0, $saturation: 0)

    Used in the brightness method to lighten the color

tint

  • Type: function

  • Parameters:

    • $color - color or theme color name
    • $offset - Number
  • Usage: theme.tint($color, $offset)

    Generate color tint

    // Theme module
    @use "ungic.theme"as theme;
    
    @for $i from 1 through 10 {
    	.tint-#{$i} {
    		padding: 10px;
    		background-color: theme.tint(red, ($i / 10));
    	}
    	.tint-reverse-#{$i} {
    		padding: 10px;
    		background-color: theme.tint(red, ($i / 10) * -1);
    	}
    }

theme-config

  • Type: function

  • Parameters:

    • $key - config option name
  • Usage: theme.theme-config($key:'')

    Get theme config option

get

  • Type: function

  • Parameters:

    • $key - name of the requested variable
  • Usage: theme.get($key:'')

    Get data belonging to the current project theme

    // Theme module
    @use "ungic.theme"as theme;
    
    @debug theme.get(name); // default

subs

  • Type: function

  • Parameters:

    • $light - if the theme is light will return the given value
    • $dark - Defaut: null if the theme is dark will return the given value.
  • Usage: theme.subs($light, $dark: null)

    :::warning The second argument is optional only if the first parameter passed is a number! If the first passed parameter is a number, and the second parameter is not specified, then the number will be inverted during inversion!

    @use "ungic.theme"as theme;
    
    // will return 1 if the theme is not 
    // in inversion mode, and vice versa, 
    // in inversion mode will return -1
    
    @debug theme.subs(1); 

    :::

    Get value relative to theme type (light or dark theme)

    // Theme module
    @use ".core"as this;
    
    @include this.component {
    	color: subs(dark, white);
    }

colors

  • Type: function

  • Parameters:

    • $color - theme color name
  • Usage: theme.colors($color: '')

    Return all colors in sass map format or a specific color of the current theme. If the color does not exist will return a transparent.

gray

  • Type: function

  • Parameters:

    • $offset Number (from -1 to 1) or String
  • Usage: theme.gray($offset:0)

    • If the value for $color-name is a number then the number must be between -1 and 1 the given number will be passed to brightness method as $intensity.

    • If the value for $color-name is a string then this value will be interpreted as the name of the tint of palette

    Function for generating gray color. Gray color is computed between the main colors of the theme (text-color, background-color). :::tip Gray is 50% of the light between text-color and background-color! :::

    Offset can be used to shift the gray scale to one side or the other from the middle of the color light. Lightening and darkening gray depends on the type of theme!

    // main colors of our theme:
    // text-color: (#000, #CCC), 
    // background-color: (#FFF, #444)  
      
    @use "ungic.theme" as theme;
    
    // #867a7a - if light theme 
    // (50% of light because it is the middle of light between #000 and #FFF colors)
    
    // #8e8282 - if dark theme 
    // (53% of light because it is the middle of light between #444 and #CCC colors)
    @debug theme.gray(); 
    
    // Lightening by 50% relative to main colors
    // 	#c3bcbc - if light theme (75% of light)
    //	#6b6161 - if dark theme (40% of light)
    @debug theme.gray(.5);

color

  • Type: function

  • Parameters:

    • $color-name - theme color name Required
    • $color-tint - Number, List, String
    • $hue-offset - offset of hue
    • $saturation - offset of saturation
  • Usage: theme.color($color-name, $color-tint: 0, $hue-offset: 0, $saturation: 0)

    Returns the theme color and applies the brightness method to it.

    • If the value for $color-name is number then the number must be between -1 and 1 the given number will be passed to brightness method as $intensity.
    @use "ungic.theme" as theme;
    
    @debug theme.color(primary, .9);
    • If the value for $color-name is a list then the first item in the list is the name of the palette tint for this color, and the second item of the list can be passed as default value (if the tint is missing from the palette).
    @use "ungic.theme" as theme;
    
    @debug theme.color(primary, (lighten, .9));
    • If the value for $color-name is a string then this value will be interpreted as the name of the tint of palette
    @use "ungic.theme" as theme;
    
    @debug theme.color(primary, lighten);
    • If the value for $color-name is a "gray" or "grey" then the gray method will be applied!
    @use "ungic.theme" as theme;
    
    @debug theme.color(gray, .5); // the same as theme.gray(.5);

color-var

  • Type: function

  • Parameters:

    • $color-name - theme color name Required
    • $color-tint - Number, List, String
    • $hue-offset - offset of hue
    • $saturation - offset of saturation
    • $rgb-list - Default: false save var as rgb list
  • Usage: theme.color-var($color-name, $color-tint: 0, $hue-offset: 0, $saturation: 0)

    Works like color method, but return a css variable instead of a color

color-rgb

  • Type: function

  • Parameters:

    • $color-name - theme color name Required
    • $color-tint - Number, List, String
    • $hue-offset - offset of hue
    • $saturation - offset of saturation
    • $rgb-list - Default: false save var as rgb list
  • Usage: theme.color-rgb($color-name, $color-tint: 0, $hue-offset: 0, $saturation: 0)

    Works like color method, but return a css variable whose value is a rgb list of color

gray-var

  • Type: function

  • Parameters:

    • $offset Number (from -1 to 1) or String
  • Usage: theme.gray-var($offset:0)

    Works like gray method, but return a css variable instead of a color

gray-rgb

  • Type: function

  • Parameters:

    • $offset Number (from -1 to 1) or String
  • Usage: theme.gray-var($offset:0)

    Works like gray method, but return a css variable whose value is a rgb list of color

as-color

  • Type: function

    Same as color but always returns the value as a color, even if the colors-vars-mode is enabled

as-gray

  • Type: function

    Same as gray but always returns the value as a color, even if the colors-vars-mode is enabled

primary, secondary, bgc, extra, warning, success, danger, system, info

  • Type: function

    Quick helpers that wrap the color method

    @function primary($color-tint: 0, $hue-offset: 0, $saturation: 0) {
        @return color(primary, $color-tint, $hue-offset, $saturation);
    }

is-inverse

  • Type: mixin, @content required

  • Using: @include theme.is-inverse {...}

    Apply css rules in inversion mode only!

skip-inverse

  • Type: mixin, @content required

  • Using: @include theme.skip-inverse {...}

    Apply css rules in not inversion mode only!

is-type

  • Type: mixin, @content required

  • Parameters:

    • $type: - String the value must be dark or light
  • Using: @include theme.is-type($type) {...}

    Apply css rules relative to theme type (dark or light). This mixin will only save css rules for a specific theme type!

is-dark

  • Type: mixin, @content required

  • Using: @include theme.is-dark {...}

    Apply css rules exclusively for dark theme.

is-light

  • Type: mixin, @content required

  • Using: @include theme.is-light {...}

    Apply css rules exclusively for light theme.

hsl

  • Type: function

  • Returns:

    HSL SASS List of values

  • Parameters:

    • $color - Color to split
    • $strip-unit - Strip unit
    • $asmap - return as sass map (list by default)
  • Specification: hsl($color, $strip-unit: true, $asmap: false)

    Split $color to hsl map.

lightest

  • Type: function

  • Specification: lightest($color1, $color2)

    Returns the lightest color

darkest

  • Type: function

  • Specification: darkest($color1, $color2)

    Returns the darkest color

is-darker

  • Type: function

  • Parameters:

    • $this-color - if this color is darker than the second
    • $than-this-color - second color
  • Specification: is-darker($this-color, $than-this-color)

    Checks if the first color is darker than the second

render-vars($selector: ':root')

  • Type: mixin

    Render color variables. Must be used at the end of the file!