Unicornix - themeable and accessible color palette generation

1. Think color, any color
2. Select it from the list
3. 🦄 🌈 🚀
4. Done!

Get light and dark semantic design color tokens are ready in any required format!

Available formats:

• JSON
• Javascript
• CSS
• CSS variables in JS
• SCSS/SASS
• Design Tokens (W3 group)
• Tokens Studio (Figma)
• Style Dictionary
• Style Dictionary V3 (legacy)
• Tailwind

CLI Usage (recommended)

Uni-Command operation:

npx unicornix

CLI Options

• --init (-i) - Initialize / re-initialize Unicornix, allows to create customizable config.
• --config (-c) - Specify local path to existing configuration file, i.e. unicornix -c ./config/unicornix.js.
• --output (-o) - Specify local path to the output folder, i.e. unicornix -o ./tokens.
• --help (-h) - Show help text.

Note, CLI options will have higher priority over local configuration

Init Launch

Init launch allows to create Unicornix configuration from scratch.
You will be prompted with several checkbox-like and occasionally input-like questions,
that help you to build and customize the theme to your liking AND output a config for the future runs.

Config Launch

You can further on customize the config file (see options below) and run generator with your settings.
Depending on your system, config file can be named either unicornix.config.(js|ts|mjs|mts) (type: module) or unicornix.config.(js|ts|cjs|cts).
If location and/or name of the file is different from the default (./unicornix.config.*), make sure to specify the --config path.

Unless --output location is not specified, output build will be produced in the .unicornix folder in the same location.

Example Config

The following example demonstrates a minimalistic config,
that allows to produce RGB theme colors in CSS (along with JS references) and Tailwind output formats,
using magenta as the dominant color and colder gray for neutral tints along with the reasonable defaults.

export default {
  theme: {
    accent: 'magenta',
    neutral: 'gray_colder',
  },
  output: {
    color: 'rgb',
    format: ['css', 'cssref', 'tw'],
  },
  options: {
    cssNamespace: 'myds',
  },
};

Config Options

theme

The theme object allows you to specify the color palette for various elements of your theme.
Each property accepts a string representing a color. Available colors:

Main Palette

• magenta
• purple
• violet
• indigo
• blue
• sky
• aqua
• mint
• emerald
• green
• lime
• acid
• yellow
• amber
• orange
• fire
• red
• ruby
• pink

Neutral Palette

• gray_colder
• gray_cold
• gray
• gray_warm
• gray_warmer

Muted Palette

• red_muted
• orange_muted
• yellow_muted
• green_muted
• sky_muted
• blue_muted
• purple_muted

Example:

{
  theme: {
    neutral: "gray_cold",
    accent: "pink",
    safe: "green",
    info: "sky",
    warning: "amber",
    alert: "red",
    content: "gray_cold",
    background: "gray_cold"
  }
}

output

The output object allows to specify the export characteristics, specifically file and color formats.

output.format

The format array allows you to specify the formats in which the themes output should be generated.
At least one format is required. The available options are:

• json - default - themes object
• js - javascript object
• css - custom properties aka CSS variables in theme scope
• cssref - javascript references of CSS variables, output in .js
• scss - SCSS (SASS) variables for all themes
• dtg - design tokens W3 Group format, output in .json
• studio - Figma Tokens Studio format, output in .json
• dict - Style Dictionary format, output in .json
• dict3 - Style Dictionary legacy (v3) format, output in .json
• tw - javascript object to use in Tailwind theme configuration

Example:

{
  output: {
    format: ['json', 'css', 'cssref'];
  }
}

output.color

The color property allows to configure the output color format:

• hex - default - Hexadecimal representation, i.e. #ff0000
• rgb - Red Green Blue notation, i.e. rgb(255, 0, 0)
• hsl - Hue Saturation Lightness color space, i.e. hsl(0, 100%, 50%)
• lab - CIELAB color space, i.e. lab(53.23% 80.11% 67.22%) (it's red)
• lch - Lightness Chroma Hue color space, i.e. lch(54.29% 106.84 40.86) (also red)
• hwb - Hue Whiteness Blackness color model, i.e. hwb(0 0% 0%)

Example:

{
  output: {
    color: 'lch';
  }
}

options

The options object allows you to configure additional settings that are applied to specific output formats.

• cssNamespace: (Optional) Namespace for (S)CSS variables. Only applies to css and scss formats
• cssColorPrefix: (Optional) Prefix for (S)CSS variables. Only applies to css and scss formats
• cssDataSelector: (Optional) Data selector for CSS variables. Only applies to css format
• cssSelector: (Optional) Additional CSS selector. Only applies to css format
• scssVariableCase: (Optional) Case format for SCSS variables. Only applies to scss format.
  The available formats are:
  • kebab: Example: $my-variable
  • camel: Example: $myVariable
  • snake: Example: $my_variable
• twTheme: (Optional) Theme to be used as primary in Tailwind output. Only applies to tw format.

Example:

{
  options: {
    cssNamespace: "awsm",
    cssColorPrefix: "color",
    cssDataSelector: "theme",
    cssSelector: "",
    scssVariableCase: "kebab"
    twTheme: "light"
  }
}

build

The build object allows to configure essential build output parameters.

• outputPath: (Optional) Same as --output flag with lesser priority

Example:

{
  build: {
    outputPath: "./tokens"
  }
}

Helper Constants

For more convenient and less error-prone experience,
you can take advantage of the exported constants.

Note that you would need to install unicornix as a dev dependency (see Installation).

import { COLOR } from 'unicornix';

export default {
  theme: {
    neutral: COLOR.gray_cold,
    accent: COLOR.pink,
    safe: COLOR.green,
    info: COLOR.sky,
    warning: COLOR.amber,
    alert: COLOR.red,
    content: COLOR.gray_cold,
    background: COLOR.gray_cold,
  },
};

Also available:

• THEME - dictionary for available themes, i.e. THEME.dark
• COLOR - dictionary for available colors to use in theme, i.e. COLOR.gray_cold
• OUTPUT_FORMAT - dictionary for the format option, i.e. OUTPUT_FORMAT.studio
• OUTPUT_COLOR - dictionary for the color option, i.e. OUTPUT_COLOR.hsl
• OPTION_CASE - dictionary for the variable text case, i.e. OPTION_CASE.kebab

Typescript Support

Ensure even more streamlined experience with Typescript.

Note that you would need to install unicornix as a dev dependency (see Installation).

import { COLOR, OUTPUT_FORMAT, type Config } from 'unicornix';

export default {
  theme: {
    accent: COLOR.pink,
    neutral: COLOR.gray_warm,
  },
  output: {
    format: [OUTPUT_FORMAT.css, OUTPUT_FORMAT.cssref],
  },
  options: {
    cssNamespace: 'myds',
  },
} satisfies Config;

Module Usage

Installation

npm i -D unicornix

Colors

light: ColorGamma
dark: ColorGamma

type ColorGamma = {
  '50': ColorValue;
  '100': ColorValue;
  '200': ColorValue;
  '300': ColorValue;
  '400': ColorValue;
  '500': ColorValue;
  '600': ColorValue;
  '700': ColorValue;
  '800': ColorValue;
  '900': ColorValue;
  '950': ColorValue;
};

Example:

import { light, dark } from 'unicornix';

const lightPinkAccent = light.pink[700]; // #941548
const darkMintSoft = dark.mint[200]; // #012d26

Palette

getPalette(color, theme): ColorPalette

Parameters:

• color (string): The color name for which to retrieve the palette.
• theme (string): The theme name ('light', 'dark').

Returns: (Object): An object containing palette values for the specified color and theme.

type ColorPalette = {
  backdrop: ColorValue;
  surface: ColorValue;
  soft: ColorValue;
  border: ColorValue;
  tone: ColorValue;
  strong: ColorValue;
  base: ColorValue;
  accent: ColorValue;
  subtle: ColorValue;
  muted: ColorValue;
  content: ColorValue;
  contrast: ColorValue;
  gamma: ColorGamma;
  alpha: ColorAlphaGamma;
};

Example:

import { getPalette, COLOR, THEME } from 'unicornix';

const darkLimePalette = getPalette(COLOR.lime, THEME.dark);
const { strong, contrast } = darkLimePalette; // #547f13, #ffffff

Themes

createThemes({ accent, ... }: CollectionColorsMap): ThemeCollection

type ThemeCollection = Record<'light' | 'dark', ColorTokens>;

interface ColorTokens {
  neutral: ColorPalette;
  accent: ColorPalette;
  safe: ColorPalette;
  info: ColorPalette;
  warning: ColorPalette;
  alert: ColorPalette;
  content: ColorContent;
  background: ColorBackground;
}

License

This project is licensed under the MIT License