Skip to content

PaulHMason/themie

Repository files navigation

Themie is a CSS variable theming library that can be used to easily create Material Design themes for web applications.

Quick Start

1) Install

Install Themie from NPM:

npm i themie --save

2) Import Themie

import { themie } from 'themie/themie.js';
import { MaterialTheme } from 'themie/material-theme.js';

3) Create a Theme

/*
primary, lightPrimary, darkPrimary, secondary, lightSecondary, darkSecondary,
onPrimary, onLightPrimary, onDarkPrimary, onSecondary, onLightSecondary, onDarkSecondary,
surface, background, error, notification, 
onSurface, onBackground, onError, onNotification,
textPrimary, textSecondary, textDisabled, 
divider
*/
const blueTeal = new MaterialTheme('#6002ee', '#9c47ff', '#0000ba', '#00bfa5', '#5df2d6', '#008e76', 
                           '#FFFFFF', '#FFFFFF', '#FFFFFF', '#000000', '#000000', '#FFFFFF',
                           '#FFFFFF', '#FAFAFA', '#B00020', '#323232', 
                           'rgba(0, 0, 0, 0.87)', 'rgba(0, 0, 0, 0.87)', '#FFFFFF', 'rgba(255, 255, 255, 0.87)',
                           'rgba(0, 0, 0, 0.87)', 'rgba(0, 0, 0, 0.54)', 'rgba(0, 0, 0, 0.38)', 
                           'rgba(0, 0, 0, 0.20)');

4) Register the Theme

themie.register('blue-teal', blueTeal);

5) Apply the Theme

A theme can be applied globally (to the document).

themie.apply('blue-teal');

Or to a DOM node (and its children).

const el = document.getElementById('something');

themie.apply('blue-teal', el);

6) Use the Theme

Since a theme is just a bunch of CSS variables, you use them in CSS selectors as normal.

.something {
    color: var(--theme-on-primary-color);
    background: var(--theme-primary-color);
    border: 1px solid var(--theme-divider-color);
}

Different themes can be applied to different nodes, and a theme applied to a child node will override any inherited theme.

Themes

Themie currently supports Material Design themes only, but any object can be used to register a theme. The generated CSS variable names are based on the camelCase property names, which are converted to snake-case with a --theme- prefix and -color suffix. For example, you could do something like this:

import { themie } from 'themie/themie.js';

const customTheme = {
    main: 'cornflowerblue',
    accent: 'lightgreen',
    text: 'black'
}

themie.register('custom-theme', customTheme);
themie.apply('custom-theme');

And use the theme like this:

.main {
    color: var(--theme-text-color);
    background: var(--theme-main-color);
}

.accent {
    color: var(--theme-text-color);
    background: var(--theme-accent-color);
}

Material Theme Variables

To use the Material Design theme object, import MaterialTheme from material-theme.js. The constructor parameters are shown in the table below.

import { MaterialTheme } from 'themie/material-theme.js';
Parameter Variable Description
primary --theme-primary-color The primary color
lightPrimary --theme-light-primary-color A light variant of the primary color
darkPrimary --theme-dark-primary-color A dark variant of the primary color
secondary --theme-secondary-color The secondary or accent color
lightSecondary --theme-light-secondary-color A light variant of the secondary color
darkSecondary --theme-dark-secondary-color A dark variant of the secondary color
onPrimary --theme-on-primary-color The text/icon color on a primary color background
onLightPrimary --theme-on-light-primary-color The text/icon color on a light primary color background
onDarkPrimary --theme-on-dark-primary-color The text/icon color on a dark primary color background
onSecondary --theme-on-secondary-color The text/icon color on a secondary color background
onLightSecondary --theme-on-light-secondary-color The text/icon color on a light secondary color background
onDarkSecondary --theme-on-dark-secondary-color The text/icon color on a dark secondary color background
surface --theme-surface-color The background color for container surfaces, such as dialogs, etc.
background --theme-background-color The background color for application windows
error --theme-error-color The background color for error containers, or error/validation text color
notification --theme-notification-color The background color for notifications, such as toast or tooltips
onSurface --theme-on-surface-color The text/icon color on a surface color background
onBackground --theme-on-background-color The text/icon color on a background color background
onError --theme-on-error-color The text/icon color on an error color background
onNotification --theme-on-notification-color The text/icon color on a notification color background
textPrimary --theme-text-primary-color The color of primary text on (usually) surface backgrounds
textSecondary --theme-text-secondary-color The color of secondary text on (usually) surface backgrounds
textDisabled --theme-text-disabled-color The color of disabled text on (usually) surface backgrounds
divider --theme-divider-color The color of dividers on (usually) surface backgrounds

Predefined Themes

There's a couple of predefined themes in the themes.js modules. To use theme just import the theme(s) you want and register them (you can use whatever name you want to register the predefined themes).

import { themie, Theme } from 'themie/themie.js';
import { blueTeal, darkOrange } from 'themie/themes.js';

themie.register('blue-teal', blueTeal);
themie.register('dark-orange', darkOrange);

themie.apply('blue-teal');

These are the currently available predefined themes.

Theme Type Description
blueTeal Material Design A light theme with blue primary and teal secondary colors
darkOrange Material Design A dark theme with brown primary and orange secondary colors

These predefined themes are still a work in progress.

About

A CSS variable theming library

Resources

License

Stars

Watchers

Forks

Packages

No packages published