❤
npm
Sign UpSign In

@unumux/willow

1.1.1 • Public • Published

Willow

Introduction

Willow is a library of reusable user interface components built with front-end code (HTML and SCSS) to allow for faster, more consistent product development.

The library consists of semantic and accessible markup for a variety of components that can be paired with your own custom theme or a provided theme to give components a consistent and branded appearance.

Willow is...

  • written to meet UnumUX CSS/SCSS and Accessibility Standards
  • influenced by the principles of:
    • Atomic Design : small, independent - atomic - parts, can be combined into larger molecular structures. Molecular structures can be combined into larger organisms, which can then serve as the foundation for templates and full pages
    • BEM : a naming convention that makes front-end code easier to read, understand, work with, maintain and scale

Browser Support

Willow is built to work with modern browsers

  • Internet Explorer 10, 11 and Edge
  • Chrome, Safari, Firefox

Installation and Usage

Willow components come styled with default colors and font stylings, so the library can be installed and utilized without a theme. Using Willow without a theme will produce components styled in grayscale colors and simple/common fonts - somewhat like a wireframe.

There are 2 methods for installing and using Willow in a project

Method 1: As an NPM Package: SCSS Files

Notes

  • Requires node and a tool to compile the SCSS into CSS, such as Gulp, Webpack or Grunt.
  • Allows single components imports instead of the entire library

Installation

  • Install Willow as a development dependency in your project. 
    npm install --save-dev @unumux/willow
  • Optional: To install a provided theme, you will need the theme's name: 
    npm install --save-dev @unumux/theme-name-goes-here

Usage

  • Include the entire library by importing Willow's stylesheet in your primary SCSS file. 
    @import "node_modules/@unumux/willow/styles";
  • Include single components by importing the component's stylesheet in your primary SCSS file. 
    @import "node_modules/@unumux/willow/components/banner/styles/banner";
@import "node_modules/@unumux/willow/components/breadcrumbs/styles/breadcrumbs";
  • Optional: To use a provided theme, include the theme's stylesheet in your primary SCSS file BEFORE the line that imports Willow: 
    @import "node_modules/@unumux/theme-name-here/styles";
@import "node_modules/@unumux/willow/styles";

Now as you add Willow components to your HTML your compiler should run and you will see styled components in your browser.

Method 2: As Compiled and Minified CSS Files

Installation

  • To use Willow without a theme, download Willow's minified CSS file and add it to your project's styles folder
  • To add a theme, download a theme's minified CSS file, and add it to your project's styles folder. You can delete the Willow CSS file if you previously included it.

Usage

  • After you include a minified CSS file in your styles folder, you can reference it in your index.html file

    <!-- If using Willow without a theme -->
<link rel="stylesheet" href="styles/willow.min.css">
    <!-- If using a theme you only need to include the theme's min file -->
<link rel="stylesheet" href="styles/theme-name.min.css">

Now as you add Willow components to your HTML file they will inherit styling

Minified CSS Downloads

File CSS Download
Willow willow.min.css
Unum Theme theme-unum-default.min.css
Colonial Life Theme theme-coloniallife-default.min.css

Need Installation Help

Do you have questions or need help with setup? Did you run into errors while following these instructions? Feel free to open an issue here:

Open An Issue

Components

Layout

Navigation

Calls to Action and Alerts

Other

Page Layout

Basics

Willow uses a combination of the willow-page-container and Bootstrap's fluid container to handle page layouts.

willow-page-container makes the page a flex column which gives the ability to apply the .flex-grow utility class to any component or row to make it fill extra page height. willow-page-container also allows a max-width for styling such as background-colors and images.

The Bootstrap fluid container contains a page's content to a certain width and provides a grid system for page columns.

To utilize these layout helpers, start your page with <div class="willow-page-container"></div> and place all of your content for the page inside of this component.

Creating Page Columns

To create page columns, use the Bootstrap <div class="container-fluid"> element and add <div class="row"></div> and <div class="col"></div> as needed. Note: you will need to determine the correct col class name to use Bootstrap documentation.

A common example of a column layout would be a page section contains secondary navigation and content. On a mobile device the secondary navigation needs to be above the content, and on desktop the pieces should be next to each other.

<div class="willow-page-container">
  <main class="willow-page-content" id="" role="main">
    <div class="container-fluid">
      <h1 class="willow-page-content__heading">Heading for content</h1>
      <div class="row">
        <div class="col-lg-3">
          <!-- insert secondary nav -->
        </div>
        <div class="col-lg-9">
          <!-- insert willow-page-content component -->
        </div>
      </div>
    </div>
  </main>
</div>

Customizing the Bootstrap Grid

Bootstrap provides documentation about customizing the grid

Note: To update bootstrap grid variables, you have to do this before you import a Willow theme.

// file: my-project/styles/styles.scss
$grid-columns: 10;

//theme import
@import "node_modules/@unumux/theme-name-here/styles";

Understanding Themes

Themes for Willow only contain SCSS variables. These variables are then used in the Willow library components which makes them theme-able.

Willow comes with default settings for all necessary variables, so the library can be installed and utilized without a theme. Using Willow without a theme will produce components styled in grayscale colors and simple/common fonts - somewhat like a wireframe. You can choose to override these styles by importing a theme or by creating your own them that sets new values for the variables.

There are 3 groups of variables:

  • Constants

    • These variables are a fixed value, that is not expected to change and that is not abstracted. Primarily used for color and font settings. 
      // theme-name/variables/constants/_colors.scss file
$color-white: #fff;
$color-bahama-blue: #285a83;
$color-razzmatazz: #f22672;

// theme-name/variables/constants/_fonts.scss file
$font-family-primary: "Ubuntu", "helvetica", "arial", "sans-serif" !default;

  • Theme-Specific

    • These variables are assigned values from Constant variables and begin the processes of giving purpose and priority to our colors and abstracting the variables. 
      // theme-name/variables/_theme-specific.scss
$theme-base: $color-white;
$theme-primary: $color-bahama-blue;
$theme-action: $color-bahama-blue;
$theme-action-negative: $color-razzmatazz;
$theme-text-inverse: $color-white;

  • Component-Specific

    • These variables are used in the SCSS for a component. They are assigned values from the Theme-Specific variables, and their variable name describes the property being effected. 
      // theme-name/variables/component-specific/_base.scss file
$component-body-background-color: $theme-base !default;
$component-link-color: $theme-primary !default;

// theme-name/variables/component-specific/_page-header file
$component-page-header-background-color: $theme-primary !default;

// theme-name/variables/component-specific/_button.scss file
$component-button-background-color: $theme-action !default;
$component-button-negative-background-color: $theme-action-negative !default;

Available Themes

Theme Name Documentation
theme-unum-default docs
theme-coloniallife-default docs

Customizing

Recommended SCSS Directory Structure For Your Project

So you need to make a new component

So you need to customize a component

So you need to change a theme

Recommended SCSS Directory Structure For Your Project

We recommend you setup your project's styling folders and files using this project pattern.

So you need to customize a component

You can customize Willow components via two methods

Method 1: Change the look of a component globally

Example 1: You want to change the size of all willow-buttons everywhere they appear

  • In your SCSS/CSS, select the component's class name and add the styling you want
  • Note: This method may require targeting multiple component versions such as willow-button and willow-button--primary
// file: my-project/styles/components/overrides/willow/button/_button.scss
.willow-button,
.willow-button--primary,
.willow-button--positive,
.willow-button--negative,
.willow-button[disabled],
.willow-button[data-disabled="true"] {
  padding: 30px 45px;
}

Example 2: You want to change the background color of positive buttons

  • You would accomplish this by overriding a 'component-specific' variable for the positive buttons
  • Find the variable you want to override by looking at the component's _default-variables.scss file located in the styles folder in every component folder. Willow Repo
  • Override the value of that variable in your _styles.scss file above the import for the theme 
    $my-color: #37c0e3;
$component-button-positive-background-color: $my-color;

@import "node_modules/@unumux/theme-name-here/styles";

Method 2: Change the look of only one instances of a component

Example: I want to change just the willow-button that is in my willow-modal

  • Add a unique class to the specific component(s) you want to change then select that class and add your styling
<button class="willow-button modal-button">
// file: styles/components/overrides/willow/button/_button.scss
.modal-button {
  background-color: orange;
}

So you need to make a new component

You can make your own components and utilize variables from Willow to make your component have the same look and feel.

So you need to change a theme

Themes are made with !default flags to allow you to override the values with your own SCSS.

Note: Changes to theme variables are used across many components, so tread lightly.

  • In your project's SCSS
    • we recommend the my-project/styles/theme/variables/theme-specific/theme-specific.scss file

Main Variables That Can Be Overridden

...

Issues and Feedback

Found an issue of have an idea for enhancement? Open an issue.

Glossaries

Readme

Keywords

none

Package Sidebar

Install

npm i @unumux/willow

Repository

github.com/unumux/willow

Homepage

github.com/unumux/willow#readme

Weekly Downloads

2

Version

1.1.1

License

GPL-3.0

Unpacked Size

229 kB

Total Files

199

Last publish

Collaborators

  • unumux_admin
  • keale2
  • chuckhendo
  • slkennedy
  • townivan
Try on RunKit
Report malware