search

studiometa / scss-toolkit

A small and configurable SCSS Toolkit to boost your project! 🚀
MIT License
5 stars 0 forks source link
scss scss-toolkit toolkit

readme

SCSS Toolkit

NPM Version NPM Beta Version Dependency Status devDependency Status

A small and configurable SCSS Toolkit to boost your project! 🚀

Table of contents

Installation

Install it with Yarn:

$ yarn add @studiometa/scss-toolkit

Or with NPM:

$ npm install @studiometa/scss-toolkit

Usage

Simple Usage

Import the toolkit in your project to have access to all helpers functions, mixins, variables and classes:

@import '~@studiometa/scss-toolkit';

If your current Sass implementation does not support @imports from Node modules, have a look at the node-sass-magic-importer custom importer.

Advanced usage

If you need to specify a custom configuration — you probably will, the best way to use the micro framework in your application is to create a separate _config.scss file which will override the configurations of the framework.

_config.scss

/*==========================================================================*\
   Global SCSS configuration
\*==========================================================================*/

// Colors definition
$colors: (
  'red': #f00,
  'green': #0f0,
  'blue': #00f,
);

// Import SCSS Toolkit after the configuration overrides
@import '~@studiometa/scss-toolkit';

You can then import your _config.scss file wherever you need to access a function, mixin or variable from the toolkit. You can import both your configuration file and the SCSS Toolkit package in your main SCSS file with a variable $has-classes set to true to import all the class helpers from the toolkit.

app.scss

/*==========================================================================*\
   Main styles
\*==========================================================================*/

// Import dependencies:
// - _config.scss to override the SCSS toolkit's defaults
// - @studiometa/scss-toolkit/components/reset to get some nice defaults
@import './config';
@import '~@studiometa/scss-toolkit/components/reset';

// Import your project files
@import './components/foo';
@import './components/bar';
// ...

// Import the toolkit latst with the `$has-classes` variable set to `true`
// for the functions, mixins and classes helpers. Importing it last will let
// you use the classes without the `--force` modifier to override some
// of your components behaviours.
$has-classes: true;
@import '~@studiometa/scss-toolkit';
$has-classes: false;

⚠️ We reset the $has-classes variable to false right after the toolkit import to make sure future import in any SCSS file will only import the mixins, functions and variables declarations without the class helpers.

Documentation

Framework

The micro-framework is composed of 8 different files which defines each a set of variables, mixins, functions and classes. Find below what each file is responsible for.

framework/_breakpoints.scss

Definitions

Defaults

$breakpoints: (
  'xxs': 0,
  'xs': 480,
  's': 768,
  'm': 1024,
  'l': 1280,
  'xl': 1440,
  'xxl': 1920,
) !default;

$breakpoints-height: (
  'xxs': 0,
  'xs': 360,
  's': 576,
  'm': 768,
  'l': 960,
  'xl': 1080,
  'xxl': 1440,
) !default;

Usage

.foo {
  display: none;

  // Media queries
  @media #{media('s')} { // @media (min-width: 48em) { ... }
    display: block;
  }

  @media #{md('xs', 'max')} { // @media not all and (min-width: 48em) { ... }
    display: flex;
  }

  @media #{md('s', 'min', 'em', 'height')} { // @media (min-height: 36em) { ... }
    min-height: 50vh;
  }

  // Using Sass ArgList
  @media #{md((breakpoint: 's', orientation: 'height')...)} { // @media (min-height: 36em) { ... }
    min-height: 50vh;
  }
}

framework/_colors.scss

Definitions

Defaults

/** @type {Boolean} Do we need the `--force` modifiers? */
$colors-with-force: false !default;

/** @type {Boolean} Do we need the `--<breakpoint>` modifiers? */
$colors-with-breakpoints: false !default;

/**
 * Map of color names and values
 *
 * @type {Map}
 */
$colors: (
  'white': #fff,
  'black': #000,
) !default;

Usage

Example usage for the color($color) function:

.foo {
  color: color('white');
}

.bar {
  background-color: c('black');
  color: c('white');
}

Example usage of the helper classes:

<p class="color-white">
  Eveniet neque velit <span class="color-black">asperiores</span>. Dolores…
</p>

<svg version="1.0" xmlns="http://www.w3.org/2000/svg">
  <path d="M…" class="fill-white stroke-black" />
</svg>

framework/_displays.scss

Definitions

Defaults

/** @type {Boolean} Do we need the `--force` modifiers? */
$displays-with-force: false !default;

/** @type {Boolean} Do we need the `--<breakpoint>` modifiers? */
$displays-with-breakpoints: false !default;

/** @type {List} List of display values to use */
$displays: (none, block, inline, inline-block) !default;

Usage

Example usage for the display-hidden-accessible mixin:

.foo {
  @include display-hidden-accessible; // Hide this element while keeping it accessible
}

Example usage for the helper classes:

<!-- Display an inline element as a block -->
<span class="display-block"></span>

<!-- Force an inline display on an element -->
<div class="display-inline--force"></div>

<!-- Hide an element on small screen, display it as a block on bigger ones -->
<div class="display-none--xxs display-block--m"></div>

framework/_easings.scss

Definitions

Defines a set of defaults easing variables, from $in-quad to $in-out-back.

Defaults

$in-quad: cubic-bezier(0.55, 0.085, 0.68, 0.53) !default;
$out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94) !default;
$in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955) !default;

$in-cubic: cubic-bezier(0.55, 0.055, 0.675, 0.19) !default;
$out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1) !default;
$in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1) !default;

$in-quart: cubic-bezier(0.895, 0.03, 0.685, 0.22) !default;
$out-quart: cubic-bezier(0.165, 0.84, 0.44, 1) !default;
$in-out-quart: cubic-bezier(0.77, 0, 0.175, 1) !default;

$in-quint: cubic-bezier(0.755, 0.05, 0.855, 0.06) !default;
$out-quint: cubic-bezier(0.23, 1, 0.32, 1) !default;
$in-out-quint: cubic-bezier(0.86, 0, 0.07, 1) !default;

$in-sine: cubic-bezier(0.47, 0, 0.745, 0.715) !default;
$out-sine: cubic-bezier(0.39, 0.575, 0.565, 1) !default;
$in-out-sine: cubic-bezier(0.445, 0.05, 0.55, 0.95) !default;

$in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035) !default;
$out-expo: cubic-bezier(0.19, 1, 0.22, 1) !default;
$in-out-expo: cubic-bezier(1, 0, 0, 1) !default;

$in-circ: cubic-bezier(0.6, 0.04, 0.98, 0.335) !default;
$out-circ: cubic-bezier(0.075, 0.82, 0.165, 1) !default;
$in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86) !default;

$in-back: cubic-bezier(0.6, -0.28, 0.735, 0.045) !default;
$out-back: cubic-bezier(0.175, 00.885, 0.32, 1.275) !default;
$in-out-back: cubic-bezier(0.68, -0.55, 0.265, 1.55) !default;

Usage

.foo {
  transition: transform 0.6s $in-out-expo;
}

framework/index.scss

Definitions

Imports all the framework files with the $has-classes variable set to false !default.

Usage

// Import all the framework files at once
@import '@studiometa/scss-toolkit';

framework/_layers.scss

Definitions

Defaults

/** @type {Boolean} Do we need the `--force` modifiers? */
$layers-with-force: false !default;

/** @type {Boolean} Do we need the `--<breakpoint>` modifiers? */
$layers-with-breakpoints: false !default;

/**
 * Map of layer names and values to use
 *
 * @type {Map}
 */
$layers: (
  goku: 9000,
  default: 1,
  limbo: -999,
) !default;

Usage

Example usage of the functions:

.foo {
  z-index: layer('goku');

  &[aria-hidden="true"] {
    z-index: l('limbo');
  }
}

.bar {
  z-index: l('default', 2); // z-index: 3;
}

Example usage of the helper classes:

<!-- Apply the `modal` layer value -->
<div class="modal layer-modal"></div>

framework/_spaces.scss

Definitions

Defaults

The default spaces values are based on the power of two, with a base unit starting at 8px (0.5rem).

/** @type {Number} The base value of all spacings */
$spaces-base: 8px / 16px * 1rem !default;

/** @type {List} List of all space factors */
$spaces: (0, 1, 2, 4, 8, 16, auto) !default;

Usage

$spaces-base: 0.5rem;
$spaces: (0, 1, 2, 4, 8, 16, auto);

// SCSS
.foo {
  margin: space(4); // 4 * 0.5rem
}

// CSS
.foo {
  margin: 2rem;
}

// SCSS
.baz {
  margin-right: s(auto);
  margin-left: s(auto);
}
<!-- Horizontal padding of 2 times the base unit and 4 times on bigger screens -->
<div class="space-px-2 space-px-4--s"></div>

<!-- Centering an element -->
<div class="space-mx-auto"></div>

framework/_typography.scss

Definitions

Defaults

/**
 * A map to define all type-sizes and their corresponding line-heights, the
 * first value is the font-size, the seconde the line-height.
 *
 * @type {Map}
 */
$type-sizes: (
  display-1: (
    size: 32px,
    line-height: 48px,
    weight: 700,
  ),
  display-2: (
    size: 24px,
    line-height: 36px,
    weight: 700,
  ),
  body: (
    size: 16px,
  ),
  small: (
    size: 12px,
  ),
) !default;

/** @type {String} The path to the webfonts directory */
$type-webfont-dir: '/static/fonts/' !default;

/** @type {String} The value for all `font-display` properties */
$type-webfont-display: auto !default;

/**
 * A map to define all font-families specifications which we might refer to by a
 * named identifier. The map is formatted as follow:
 *
 * (
 *   <identifier>: (
 *     name: <font-family-name>,
 *     stack: <font-family-stack>,
 *     webfonts: (
 *       (
 *         filename: <webfont-filename>,
 *         weight: <webfont-weight>,
 *         style: <webfont-style>,
 *       ),
 *     ),
 *   ),
 * )
 *
 * @type {Map}
 */
$type-fonts: (
  serif: (
    name: Georgia,
    stack: 'Georgia, serif',
    webfonts: (
      (
        filename: 'georgia-regular',
        weight: 400,
        style: normal,
      ),
    ),
  ),
  sans-serif: (
    name: Arial,
    stack: 'Arial, sans-serif',
    webfonts: (
      (
        filename: 'arial-regular',
        weight: 400,
        style: normal,
      ),
    ),
  ),
) !default;

/** @type {List} List of alignment values to use */
$type-alignments: (left, center, right) !default;

/** @type {List} List of font weights values to use */
$type-weights: (300, 400, 700) !default;

/** @type {List} List of letter spacings values to use */
$type-spacings: (25, 50, 100, 200) !default;

/** @type {List} List of text transform values to use */
$type-transforms: (uppercase, lowercase, capitalize) !default;

/** @type {List} List of text decoration values to use */
$type-decorations: (none, underline) !default;

Usage

.title {
  @include fz('display-1');
  @include type-antialiased;
}
<!-- Adjust the size of a title on different breakpoints -->
<h1 class="type-display-1--xxs type-display-2--s">Foo Bar</h1>

<!-- Center a text -->
<p class="type-align-center">Lorem ipsum dolor…</p>

Components

This toolkit come with some useful components : a grid, a reset and a debug helper.

components/debug.scss

Definitions

This component defines colored outlines on every HTML element, useful to debug layout on a page.

Usage

To use it, simply import the component in your project:

// You can import it globally
@import '@studiometa/scss-toolkit/src/components/debug';

// Or locally to enable debug only on a component
.my-component {
  @import '@studiometa/scss-toolkit/src/components/debug';
}

components/grid.scss

Definitions

Defaults

$grid-columns: 12 !default;
$grid-gutter: space(4) !default;
$grid-breakpoints: $breakpoints !default;

Usage

<!-- One column on mobile, two on tablets and three on desktop -->
<div class="grid">
  <div class="grid__row">
    <div class="grid__col-12--xxs grid__col-6--s grid__col-4--l">…</div>
    <div class="grid__col-12--xxs grid__col-6--s grid__col-4--l">…</div>
  </div>
</div>

<!-- A nested grid in a centered main column -->
<div class="grid">
  <div class="grid__row">
    <div class="
      grid__col-12--xxs
      grid__col-10--xs
      grid__push-1--xs
      grid__col-8--m
      grid__push-2--m
      grid__col-6--l
      grid__push-3--l
    ">
      <div class="grid grid--nested">
        <div class="grid__row">
          <div class="grid__col-6--xxs">…</div>
          <div class="grid__col-6--xxs">…</div>
        </div>
      </div>
    </div>
  </div>
</div>

components/reset.scss

Definitions

The reset component only import the classic reset.css.

Contributing

This project uses Git Flow as a branching model and a combo of Stylelint and Prettier to lint the SCSS files. You can lint your modifications when contributing with the following commands:

# Lint all files in the src/ folder
$ yarn lint
# or
$ npm run lint

# Try to fix all lint errors/warnings
$ yarn fix
# or
$ npm run fix