@guillaumeferber/ui-kit v0.0.22

UI/UX Kit

UI/UX Kit is a lightweight and flexible CSS front-end component kit based on ITCSS architecture and built with Sass.

UI/UX Kit does its best to provide zero cosmetic styling. That means UI/UX Kit can be used on any and all types of project without suggesting a look-and-feel.

Browser support

All modern browsers are supported (except Internet Explorer).

Installation

You can use UI/UX Kit in your project by installing it using a package manager (recommended):

npm:

$ npm install @guillaumeferber/ui-kit -D

Philosophy

Architecture

UI/UX Kit follows a specific folder structure based on ITCSS, which you should follow as well in your own CSS directory:

• settings/: Used with Sass and contain global variables, colors definitions, etc.
• tools/: Globally used mixins and functions.
• generic/: Reset and normalize styles.
• elements/: Unclassed HTML elements (like <h1>, <a>, etc.).
• objects/: Class-based selectors which define undecorated design patterns.
• components/: Specific UI components. Because UI/UX Kit does no cosmetic styling, it is up to you to author this layer. To get ready-to-use recipes with components, see section demo
• utilities/: Helper classes with high-specificity.

Methodology and namespaces

UI/UX Kit is written using BEM (Block, Element, Modifier) methodology for building component-based user interfaces.

It also provides some classes with specific namespace:

• .o-: Signify that something is an Object, and that it may be used in any number of unrelated contexts to the one you can currently see it in.
• .c-: Signify that something is a Component. This is a concrete, implementation-specific piece of UI.
• .u-: Signify that this class is a Utility class. It has very specific role and should not be bound onto or changed. It can be reused and is not tied to any specific piece of UI.

Every class in either of these three directories (layers) gets the appropriate prefix in its class name. Be sure to follow this convention in your own code as well to keep a consistent naming convention across your code base.

Getting started

Importing

As much as possible, avoid modifying UI/UX Kit's core files. The best way to do this is to import UI/UX Kit's source Sass files in your own project.

You have two options : include all of UI/UX Kit, or pick the parts you need.

We encourage the latter, though be aware that settings/ and tools/ folders are required.

// Settings (required)
@import 'node_modules/@guillaumeferber/ui-kit/scss/settings/colors';
@import 'node_modules/@guillaumeferber/ui-kit/scss/settings/global';

// Tools (required)
@import 'node_modules/@guillaumeferber/ui-kit/scss/tools/functions';
@import 'node_modules/@guillaumeferber/ui-kit/scss/tools/mixins';

// Generic (optional)
@import 'node_modules/@guillaumeferber/ui-kit/scss/generic/normalize';
@import 'node_modules/@guillaumeferber/ui-kit/scss/generic/box-sizing';
@import 'node_modules/@guillaumeferber/ui-kit/scss/generic/reset';
@import 'node_modules/@guillaumeferber/ui-kit/scss/generic/shared';

// Elements (optional)
@import 'node_modules/@guillaumeferber/ui-kit/scss/elements/root';
@import 'node_modules/@guillaumeferber/ui-kit/scss/elements/page';
@import 'node_modules/@guillaumeferber/ui-kit/scss/elements/heading';
@import 'node_modules/@guillaumeferber/ui-kit/scss/elements/forms';
@import 'node_modules/@guillaumeferber/ui-kit/scss/elements/tables';

// Objects (optional)
@import 'node_modules/@guillaumeferber/ui-kit/scss/objects/container';

// Utilities (optional)
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/position';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/display';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/flex';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/alignment';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/float';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/clear';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/sizing';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/spacing';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/overflow';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/colors';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/text';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/visibility';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/cursors';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/reset';
@import 'node_modules/@guillaumeferber/ui-kit/scss/utilities/helper';

Theming

Every Sass variable in UI/UX Kit includes the !default flag allowing you to override the variable's default value in your own Sass file without modifying UI/UX Kit's source code. Your overrides must come before you import UI/UX Kit's setting files.

Overriding variable

To modify an existing variable $container-max-width, add the following to your custom Sass file:

$container-max-width: 96rem;

Overriding map

To modify an existing key in our $spacers map, add the following to your custom Sass file:

$spacers: (
  'base': 2rem,
);

To add a new key and value to $spacers map, add the following to your custom Sass file:

$spacers: (
  'custom-spacer': 1rem,
);

To remove an existing key from $spacers map, add the following to your custom Sass file:

$spacers: (
  'base': null,
);

Using generated classes in your templates

Pro Tips

UI/UX Kit also provides some features and tools that should be of great help to you.

CSS Custom properties

CSS custom properties allow you to store and retrieve values from properties you define yourself.

They follow the same rules as other CSS properties, so you are able to define and use them at multiple levels, following standard CSS cascading and specificity rules.

For example, this Sass map:

$spacers: (
  'lg': 4.8rem,
  'base': 2.4rem,
  'sm': 1.2rem,
);

will automatically add these custom properties in the root element:

:root {
  --spacer-lg: 4.8rem;
  --spacer-base: 2.4rem;
  --spacer-sm: 1.2rem;
}

You can now retrieve these custom properties like this:

.c-custom-component {
  margin: var(--spacer-base);
  padding: var(--spacer-sm);
}

Responsive breakpoints

You may have noticed that UI/UX Kit provides a default map of breakpoint values:

$breakpoints: (
  'phone': 47.9375em,
  'tablet': 64em,
);

Like any other UI/UX Kit's variables, it is possible to override this Sass map to modify, add or remove some responsive breakpoint keys:

$breakpoints: (
  'phone': null,
  'tablet': null,
  'sm': 47.9375em,
);

It is even possible to delete all responsive breakpoint keys if your website doesn't require to be responsive:

$breakpoints: ();

These responsive breakpoints are available via Sass mixin @mixin media($keys...) by adding optional suffixes: -up or -down.

It is important to note that the suffix -up is exclusive while the suffix -down is inclusive.

This Sass mixin with ($key) name:

@include media('tablet') {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

will generate these responsive breakpoints:

@media (max-width: 64em) and (min-width: 48em) {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

This Sass mixin with ($key-up) name:

@include media('tablet-up') {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

will generate this responsive breakpoint:

@media (min-width: 64.0625em) {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

This Sass mixin with ($key-down) name:

@include media('tablet-down') {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

will generate this responsive breakpoint:

@media (max-width: 64em) {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

This Sass mixin with multiple ($key1, $key2) names:

@include media('phone', 'tablet-up') {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

will generate these responsive breakpoints:

@media (max-width: 47.9375em) {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

@media (min-width: 64.0625em) {
  .c-custom-component {
    margin: var(--spacer-base);
  }
}

Summary table (UI/UX Kit's default settings)

Authors

Guillaume Ferber - Initial work - guillaumeferber.