@antoniogross/vanilla-essence v0.2.7

Vanilla Essence

Vanilla Essence is a library that builds upon Vanilla Extract and includes key features of Tailwind CSS and Stylex. If you currently use Vanilla Extract, you can easily switch to Vanilla Essence by updating your library and imports.

Getting Started:

To use Vanilla Essence, you must create a config-file and call the initStyle method. This method provides you with a typed modified style and themeSprinkles method. You can place the file anywhere you want, but a good option is to create a file named style.config.css.ts in the globals style folder of your application. This file must be a .css.ts file, otherwise it will not work.

The easiest way to set everything up is as follows:

import { initStyle } from '@antoniogross/vanilla-essence';
import defaultConfig from '@antoniogross/vanilla-essence/src/config/default';

export const { style, themeSprinkles, pickColor, onDarkMode } =
  initStyle(defaultConfig);

Vanilla Essence includes several key differences from Vanilla Extract's style API:

• Rem Conversion: This automatically converts numeric values to rem values for properties such as fontSize, letterSpacing, and lineHeight. These settings can be customized in config.remPropList and it can be enabled for any value using "*".

• Magic Values: This adds custom CSS properties such as paddingX, paddingY, marginX, and marginY. You may already know this from the sprinkles API. There it is called shorthands. These settings can be customized in config.magicProps.

• Magic Utils: Works the same as Magic Vaules, but with the ability to add custom methods instead of CSS properties. This helps to simplify properties when they are frequently used in a project. These settings can be customized in config.magicUtils.

initStyle({
  // ...
  magicUtils: {
    backdropBlur: (val) => ({
      backdropFilter: `blur(var(--backdropBlur))`,
      vars: {
        ['--backdropBlur']: typeof val === 'number' ? `${val}px` : val,
      },
    }),
  },
});

• Pseudo-elements: This automatically adds content: '' when the modifiers before and after are used. Of course, only if it is not specified with a different value.

• responsive API: This allows for easy implementation of responsive styling using the same breakpoints as Tailwind CSS. These settings can be customized in config.breakpoints.

const responsiveClass = style({
  backgroundColor: 'grey',
  paddingX: 12,
  '@responsive': {
    sm: {
      backgroundColor: 'red',
    },
    md: {
      backgroundColor: 'blue',
      paddingX: 16,
    },
    lg: {
      backgroundColor: 'green',
      paddingX: 20,
    },
  },
});

themeSprinkles API:

The themeSprinkles API allows you to define your own colors and font-family/font-weight settings using the same syntax as in Tailwind CSS. The colors must be specified using hexadecimal values, which will be automatically converted to RGB values. This allows you to adjust the opacity when using these colors in your design. The defined colors will be available as backgroundColor, color, and borderColor. These settings can be customized in config.colors, config.opacities, config.fontFamilies and config.fontWeights). Colors can be configured exactly as in Tailwind CSS. Also the Color object syntax with a DEFAULT key will work.

Dark mode is enabled by default based on the operating system preference, but you can also use a custom class to enable it. Additionally, dark mode can be disabled by setting the type to disabled.

const themeStyle = themeSprinkles({
  backgroundColor: 'gray-700',
  backgroundColorOpacity: {
    default: 50,
    darkMode: 25,
  },
});

The config.opacities, config.fontFamilies, and config.fontWeights settings determine the available options for colors, font families, and font weights in your design. Dark mode settings can be customized in config.darkmode.

pickColor method:

Sometimes themesSprinkles is not enough to define a color at a specific point. This method makes it easy to access color outside of themeSprinkles. This can be useful in situations where you need to style a pseudo-element or apply a color in a way that is not covered by the themesSprinkles object.

You can use the pickColor method to access any color available in the themesSprinkles object. Simply pass the name of the color as the first argument, and the desired opacity as the second argument. The method will return a string representing the requested color with the specified opacity applied.

import { style, pickColor } from './style.config.css';

const block = style({
  boxShadow: `0 10px 10px ${pickColor('tahiti-light', 50)}`,
});

onDarkMode method:

The onDarkMode method allows you to set different styles for an element when dark mode is enabled.

import { style, onDarkMode } from './style.config.css';

const block = style({
  background: 'red',
  ...onDarkMode({
    background: 'blue',
  }),
});

useful methods:

This library provides useful methods to improve readability and type safety.

• defineSize: To create the CSS functions clamp, min, max or minmax more easily.

  import { style } from './style.config.css';
  import { defineSize } from '@antoniogross/vanilla-essence';
  
  const title = style({
    fontSize: defineSize({
      min: 12,
      max: 36,
      ideal: '40vw',
    }),
  });

Preflight CSS / Reset CSS:

To reset your CSS, simply import the @antoniogross/vanilla-essence/src/css/preflight.css file. This file is based on Tailwind's preflight file.

Known, currently necessary workarounds:

• If you are having issues with the media query order in the CSS output, you can try creating an initResponsiveStyle at the top of your application. This style does not need to be used anywhere, and can help fix incorrect media query order. Here is an example of how to create an initResponsiveStyle:

const initResponsiveStyle = style({
  '@responsive': {
    sm: { display: 'block' },
    md: { display: 'block' },
    lg: { display: 'block' },
    xl: { display: 'block' },
    '2xl': { display: 'block' },
  },
});