README.md

@volverjs/style

backgrounds border colors aspect ratios typography
easings animations sizes borders z-indexes media-queries
layout spacing flexbox grid custom properties scss

maintained with ❤️ by

Install

# pnpm
pnpm add @volverjs/style

# yarn
yarn add @volverjs/style

# npm 
npm i -s @volverjs/style

Usage

/* css */
@import '@volverjs/style';

/* scss */
@use '@volverjs/style/scss';

or cherry pick what you want

/* css */
@import '@volverjs/style/reset';
@import '@volverjs/style/props/layout';
@import '@volverjs/style/utilities/layout';
@import '@volverjs/style/components/vv-button';

/* scss */
@use '@volverjs/style/scss/reset';
@use '@volverjs/style/scss/props/layout';
@use '@volverjs/style/scss/utilities/layout';
@use '@volverjs/style/scss/components/vv-button';

Principles

👌 Zero Specificity

Everything is defined with :where() so you can override all definitions easily.

🎨 Custom properties

All attributes have a custom properties (CSS variables) for easy theming.

😱 Utility-first + BEM

You can style utility-first (with tailwindcss syntax) and use components (vv-* for ex. vv-button) written with BEM.

Basic personalization

Custom props

@import '@volverjs/style';
@import url('https://fonts.googleapis.com/css2?family=Open+Sans');

:root {
  /* custom color brand */
  --color-brand-hue: 149deg;
  --color-brand-saturation: 56%;
  --color-brand-lightness: 53%;

  /* custom font sans */
  --font-sans: 'Open Sans', sans-serif;
}

SCSS

@use '@volverjs/style/scss/context' with (
  // custom color brand 
  $color-brand: #45cb85,
  //custom font sans
  $font-family-sans: 'Open Sans', sans-serif
);
@use '@volverjs/style/scss';

@import url('https://fonts.googleapis.com/css2?family=Open+Sans');

Relative Color Syntax Mode

By default, @volverjs/style uses CSS Relative Color Syntax for generating color shades. This reduces the number of CSS variables and improves browser DevTools performance.

@use '@volverjs/style/scss/context' with (
  // Enable/disable Relative Color Syntax mode (default: true)
  $use-color-mix: true
);
@use '@volverjs/style/scss';

With this mode enabled, color shades are generated using:

/* Brand colors use proportional scaling (multiplication) */
--color-brand-lighten-1: hsl(from var(--color-brand) h s calc(l * 1.1));
--color-brand-darken-1: hsl(from var(--color-brand) h s calc(l * 0.9));

/* Surface/word colors use fixed steps (addition) */
--color-surface-1: hsl(from var(--color-surface) h s calc(l - 2));
--color-word-1: hsl(from var(--color-word) h s calc(l + 12));

To use the legacy HSL-based system with separate hue/saturation/lightness variables:

@use '@volverjs/style/scss/context' with (
  $use-color-mix: false
);

Browser support

The browserslist field of package.json is the baseline the compiled CSS is written against: Chrome and Edge 133, Firefox 128, Safari and iOS Safari 16.4.

Two features set it. Relative Color Syntax (hsl(from ...)), the default for colour shades, needs Safari 16.4 and Firefox 128, and can be turned off with $use-color-mix: false. The lh unit, which several components use to size an icon or a marker to the line box it sits on, needs Chrome 133 and cannot be turned off: it is how the library avoids restating a line height as a number, and a component that reads it stays correct when a consumer changes line-height with a utility class.

Deep override

All components are written through SCSS maps. Root attributes style the component, submaps state, element, and modifier generates BEM selectors.

@use 'sass:map';
// import volverjs default settings, functions and mixins
@use '@volverjs/style/scss/context';

// override vv-button map
context.$vv-button: map.deep-merge(
  context.$vv-button,
  (
    // change default button background
    background: #ddd,
    state: (
      hover: (
        // change default button background on hover
        background: #aaa
      )
    ),
    modifier: (
      // add a custom modifier
      my-error: (
        background: red
      )
    )
  )
);

// import volverjs style
@use '@volverjs/style/scss';

<button type="button" class="vv-button vv-button--my-error">Error</button>

Documentation

To learn more about @volverjs/style, check its documentation.

For coding agents, the documentation publishes llms.txt, an index of its pages, and llms-full.txt, the whole reference of the agent skill in one file. The skill installs with npx skills add volverjs/style.

License

MIT