cascading-color-systems
Advanced tools
Generate dynamic and themable color palettes using CSS custom properties, and allow (persistent) user-adjustments with a bit of light-weight JS.
We provide both the Sass, and a pre-built CSS file. Both allow adjustments to default settings -- but only the Sass files can change how many colors are generated.
Download the files from GitHub, or install using npm or yarn:
npm install cascading-color-systems --save-dev
yarn add cascading-color-systems --dev
The default configuration can be used as plain CSS:
/* css */
@import '<path-to>/cascading-color-systems/css/ccs.css';
<!-- html -->
<link src="<path-to>/cascading-color-systems/css/ccs.css" rel="stylesheet" />
You can copy that file anywhere you want, and it works without dependencies.
If you want to use the Sass features,
you will need Dart-Sass v1.23+
(which may still be in Beta).
This was partially an experiment
in the latest Sass feature: Modules.
Import using the new module import syntax:
@use '<path-to>/cascading-color-systems/' as ccs with (
/* configuration options */
);
Both imports generate core configuration options as CSS custom properties (set by Sass when applicable):
[data-ccs='root'] {
--ccs-prime--config: #{$prime-hue or 330};
--ccs-accent--config: #{$accent-hue or null};
--ccs-lightness--config: #{$lightness or null};
--ccs-saturation--config: #{$saturation or null};
--ccs-contrast--config: #{$contrast or null};
--ccs-fade-background--config: #{$fade-background};
}
This also configures a light/dark-mode toggle, and fallback values for both modes:
// fallback values, in case variables are not supported
[data-ccs='root'] {
background-color: $fallback-light;
color: $fallback-dark;
@media (prefers-color-scheme: dark) {
background-color: $fallback-dark;
color: $fallback-light;
}
}
Add the data-ccs='root' attribute to your html element
in order to make your Cascading Colors configuration
available to an entire page.
This attribute will also be used by JavaScript
to apply dynamic user settings globally.
Custom properties only re-calculate
where they are defined --
so we've created a
[data-ccs-colors] attribute,
which can be applied anywhere
new colors are needed.
This attribute provides your base colors as custom properties:
--ccs-prime, --ccs-accent:
Prime and accent hues, with base lightness and saturation--ccs-neutral:
The neutral hue gets base lightness
and full-contrast saturation--ccs-<prime | accent | neutral >--fg-full :
All three hues get a full-contrast foreground--ccs-<prime | accent | neutral >--bg-full :
All three hues get a full-contrast background--ccs--bg-full white or black, depending on light/dark mode--ccs--fg-full white or black, depending on light/dark modeWe also provide the color attributes needed to generate a larger palette:
--ccs-h--prime:
the calculated primary hue,
based on user-settings, theme-settings, and global configuration--ccs-h--accent:
the calculated accent hue,
based on theme-settings, and global configuration
(there is currently no direct user input for accent hue)--ccs-h--neutral:
the calculated neutral hue,
based on theme-settings and global configuration;
generally either --ccs-h--prime (the default)
or --ccs-h--accent--ccs-contrast:
the calculated contrast range
based on theme, user, and global settings--ccs-l, --ccs-l--<fg | bg>-contrast:
the calculated base lightness (user, theme, global)
and full-contrast fg/bg values--ccs-s, --ccs-s--<fg | bg>-contrast:
the calculated base saturation (user, theme, global)
and full-contrast fg/bg values--ccs-mode:
the calculated light (1) or dark (-1) mode
(user, theme, html, or system preference)--ccs-mode--invert the opposite of CCS-modeYou can pass explicit light/dark mode overrides in html by including a value with the attribute:
<section data-ccs-colors="light">
<!-- light background, dark foreground -->
<div data-ccs-colors="invert">
<!-- invert the colors (can't be nested multiple times) -->
</div>
</section>
<section data-ccs-colors="dark">
<!-- dark background, light foreground -->
</section>
More complex color palettes have to be generated in Sass,
based on the number of $steps desired
to get from the base colors to their full-contrast versions.
If you import the static CSS file,
we generate a palette based on the default settings,
with 4 steps in either direction.
Each step is named --ccs-<hue>--<direction><step>,
eg --ccs-prime--fg1, or --ccs-accent--bg3.
Themes can be used to pre-set any color values
(especially the accent hue),
and even show/hide user customization controls.
We provide several built-in themes,
and you can add your own
using the [data-ccs-theme] attribute:
[data-ccs-theme='complement'] {
/* set the accent color 180 degrees off the primary color */
--ccs-accent--theme: calc(var(--ccs-h--prime) + 180);
}
[data-ccs-theme='triad'] {
/* triad logic */
}
In most cases,
you'll want to define the $prime-hue,
and possibly a few other options --
and then trigger a build from the module itself.
Here's the code from one of my sites:
@use "../../node_modules/cascading-color-systems/" as ccs with (
$prime-hue: 0,
$saturation: 70%,
$contrast: 48%,
$steps: 6,
$fade-background: 15%,
$fades: 0.75,
$build: true,
);
The $build: true configuration
will generate CSS output based on your settings.
I recommend that for most use-cases,
but you can leave that out
and apply individual mixins:
[data-ccs-colors] {
@include colors;
}
The provided JS
can be hooked up to a form
to accept user-input,
generate custom properties based on their input,
store their preferences in localStorage,
or revert back to the configured site defaults.
Use the dist.js UMD module directly in a browser:
<script type="text/javascript" src="dist.js"></script>
<script type="text/javascript">
ccs.default();
</script>
Or import and use index.js,
if you have a modern build system with ES Module support:
import ccs from 'cascading-color-systems';
ccs();
We provide several hooks for the JS to use
[data-ccs="root"]:
where user settings should be applied[data-ccs="menu"]:
if you hide the settings by default,
we'll show them when the JS is available[data-ccs-input="mode"]:
a button to toggle light/dark modes[data-ccs-input="unset"]:
a button to unset all user preferences
and clear related local storage[data-ccs-input="theme"]:
Allow users to select from available theme options[data-ccs-input="hue"]:
Allow users to change the primary hue[data-ccs-input="saturation"]:
Allow users to adjust the baseline saturation[data-ccs-input="lightness"]:
Allow users to adjust the baseline lightness[data-ccs-input="contrast"]:
Allow users to adjust the contrast rangeThemes can also use the [data-ccs-field] on wrappers,
to show and hide inputs/labels directly in the CSS
based on a given theme.
For example, a high-contrast theme
might not accept contrast input:
[data-ccs-theme='contrast'] {
--ccs-contrast: 200%; /* override all other contrast settings */
--ccs-custom-contrast: none; /* hide [data-ccs-field="contrast"] */
}
0.1.0-beta.8 - 2019/11/29
background-color
rather than background shorthand--ccs-custom-display and --ccs-field-display variables
for more customized control of CCS menu field displaybackground-color and color on all [data-ccs-colors],
with both fallback values and variables defaulting to
--ccs-neutral--(fg/bg)-full--ccs-background and --ccs-color override the default
[data-ccs-colors] background and text$neutral-hue and --ccs-neutral--config for setting neutral hues$neutral-saturation and --ccs-s-neutral--config
override contrast-based saturation on neutral paletteLICENSE => LICENSE.md (and fix in package.json)FAQs
generate dynamic color palettes with custom properties
The npm package cascading-color-systems receives a total of 0 weekly downloads. As such, cascading-color-systems popularity was classified as not popular.
We found that cascading-color-systems demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Create React App is officially deprecated due to React 19 issues and lack of maintenance—developers should switch to Vite or other modern alternatives.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.