/willow

HTML and SCSS for common UI components built by the Unum UX team

Primary LanguageCSSGNU General Public License v3.0GPL-3.0

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