Shadows ReadyTheme Documentation

Introduction

The framework is designed to be used as a foundation for building custom websites or your own ReadyThemes. While the core of the framework is a tested, CSS base, we also include quality tested JavaScript functionality and extensions like tabs, accordions, carousels, and more.

What's New in Shadows v2.0.0

We examined the way ReadyThemes worked with the core software and wanted a tighter integration. To that end, Shadows is now the default Framework installed in any new Miva store. While working on this, we made some improvements to the original version of Shadows.

Cleaned and trimmed up the HTML, CSS, and JavaScript code.
Improved accessibility for better user inclusivity.
Compliant with Googles latest Web Vitals metrics.
Improved overall Page Speed Metrics.

Additionally, you now have the option to use a developer version of Shadows, Shadows DE, for your site builds.

Native support of CSS custom properties (variables).
Native support for SCSS.
Gulp build process to output a single CSS file and a single JS file.

Extensible

Includes the necessary building blocks to create many of the common UX design patterns. Unique components can easily be created by extending the framework.

BEM-IT-ECSS

Developed with the BEMIT methodology in mind. BEM promotes component modularity, IT helps control the architecture, and ECSS helps to make extending the framework more manageable.

Modern Layout

Shadows is an evergreen-browser framework with a modern Flexbox layout system. No more having to remember to clear your floats or use conditional classes.

Accessibility/Inclusivity

With the importance of inclusivity in website layout in mind, Shadows ships with passing grades, as of August 2020, for Web Content Accessibility Guidelines 2.1 Level A and Level AA as well as Section 508 standards for accessibility as tested through ARC by The Paciello Group, Axe by Deque, and WAVE by WebAIM.

Browser Support

While every effort has been made to make sure Shadows performs across a variety of devices and browsers, there is only so much shimming that can be done without sacrificing performance. Shadows uses current coding structures and standards. This framework may not be best suited for you if you are looking to support legacy browsers.

Chrome (latest 2)
Firefox (latest 2)
Safari iOS/MacOS (latest 2)
Versions of Safari lower than 11 have minimal support, this theme may not work in versions lower than 10. Generally, the site will operate, however there are layout inconsistencies due to the way the browsers supports flex-box and sizing calculations
Opera (latest 2)
Edge (latest 2)
Internet Explorer 11 has minimal support. It will operate, however there are layout inconsistencies due to the way the browser supports flex-box and sizing calculations.

Shadows Version 1

This documentation is for the current release of Shadows which ships with Miva 10. If you are looking for the previous version, v1.0.x, you can access that documentation here.

Installation

Shadows is a versatile development framework which lays a solid foundation for you to build your responsive Miva store upon. It provides the perfect starting point to develop a full-featured enterprise ecommerce store in a fraction of the time of building from scratch.

Shadows was created expressly to support highly flexible and scalable ecommerce stores. The CSS utilizes Block, Element, or Modifier (BEM) structure and strict naming conventions to support enterprise-class development.

There are two ways to get started with Shadows. Choose the method that is most appropriate to your project and environment. You can download the framework and install it directly into your store through the administration portal. Or, if you would like to use the developer edition, you can clone the repository from GitHub:

git clone https://github.com/mivaecommerce/readytheme-shadows.git

CSS

Shadows is structured based on ITCSS, we split the framework in to several layers:

base - This layer contains the global reset for HTML markup. Shadows utilizes Normalize.css as well as a small set of additional resets. Properties for legacy browsers have been excluded.
elements - Shadows provides normalization for many of the standard markup elements such as html, table, or h1.
objects - Objects is the first layer containing class-based selectors, we prefix objects with o-. It should contain any non-cosmetic design patterns styling such as .o-container. They are vital for layout and structure.
components - The Components layer is where the majority of the CSS is written. Components handle the cosmetic design patterns and UI elements such as .c-table or .c-button. These specific patterns are designed to be as modular and extensible as possible.
utilities - The Utilities layer is reserved for styling which will take precedence over other classes. These are generally utilities such as .u-inline-block which sets an element to display: inline-block or .u-text-center which forces text-align: center. These are helper classes that can speed up your development and reduce CSS property declarations. The utility classes do not contain any !important declarations. If you require such overrides you may want to take a second glance at your code to see if something can be refactored first.

Our CSS classes follow theBEM structure:

.namespace-block[__element][--modifier]

Some examples of suitable class names:


.c-tile {...}

.o-container--wide {...}

.is-hidden--large {...}

.c-form-list__item--for {...}

We should NEVER use the following class names:


.c-block--modifier__element {...}

.c-block__element__element {...}

.c-block@medium--modifier {...}

CSS Coding Style Guide

We have established a CSS coding style guide which helps promote a greater degree of standardization in our code.

JavaScript

For the broadest functionality and developer ease, Shadows ships with jQuery. The much of the JavaScript used in Shadows is "vanilla" in nature. We have found this to perform well and work cross-browser.

While you can create and call JavaScript function using the familiar $('#some_ID') or $('.some_CLASS') way, the preferred way in Shadows is to use a data attribute called hook, $.hook('some_data_hook'). Using data-hook allows for having multiple possible elements, like when using a class.

Set a data-hook on an element to be called by your function.

Use it in your JavaScript


$.hook('do-something-cool).on('click', function () {
	//DO SOMETHING
}

Although the core of Shadows may not be updated often, it is recommended that all theme based functionality be added to the themes/STORE_ID/THEME_NAME/ui/js/theme.js file within the proper page function call.

Style Guide

Typography

Primary Font-Family: "Poppins",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif

Secondary Font-Family: "Apple Garamond","Baskerville","Times New Roman","Droid Serif","Times","Source Serif Pro",serif

Font-Weight Regular

Font-Weight Bold

Font-Weight Boldest

Headings

For an h1 display, use c-heading-alpha
c-heading-alpha subheading

For an h2 display, use c-heading-bravo
c-heading-bravo subheading

For an h3 display, use c-heading-charlie
c-heading-charlie subheading

For an h4 display, use c-heading-delta
c-heading-delta subheading

For an h5 display, use c-heading-echo
c-heading-echo subheading

For an h6 display, use c-heading-foxtrot
c-heading-foxtrot subheading

Colors
These colors are for the "bg", "border", and "color" utility classes.

hex: #ee0020
u-**-red

hex: #f9ed1f
u-**-yellow

hex: #003b6f
u-**-blue

hex: #0d8670
u-**-green

hex: #000
u-**-black

hex: #222
u-**-gray-50

hex: #595959
u-**-gray-40

hex: #9f9f9f
u-**-gray-30

hex: #c0c0c0
u-**-gray-20

hex: #eaeaea
u-**-gray-10

hex: #fff
u-**-white

hex: #3d70b2
u-**-primary

hex: #5aaafa
u-**-secondary

hex: #008571
u-**-tertiary

hex: #f9ed1f
u-**-highlight

hex: #3cc
u-**-accent

Iconography
You can use these utility classes to add icons to your pages.

u-icon-error

u-icon-warning

u-icon-question

u-icon-info

u-icon-gift

u-icon-settings

u-icon-protected

u-icon-secure

u-icon-envelope

u-icon-truck

u-icon-globe

u-icon-history

u-icon-balance

u-icon-remove

u-icon-cart-add

u-icon-chevron-up

u-icon-chevron-down

u-icon-chevron-left

u-icon-chevron-right

u-icon-triangle-up

u-icon-triangle-down

u-icon-triangle-left

u-icon-triangle-right

u-icon-arrow-up

u-icon-arrow-down

u-icon-arrow-left

u-icon-arrow-right

u-icon-subtract

u-icon-add

u-icon-cross

u-icon-check

u-icon-zoom-out

u-icon-zoom-in

u-icon-search

u-icon-credit-card

u-icon-heart-empty

u-icon-heart-full

u-icon-star-empty

u-icon-star-full

u-icon-home

u-icon-user

u-icon-phone

u-icon-facebook

u-icon-twitter

u-icon-pinterest

u-icon-google

u-icon-instagram

u-icon-vimeo

u-icon-youtube

u-icon-flickr

u-icon-print

u-icon-wallet

u-icon-document

u-icon-menu

u-icon-calendar

u-icon-bag-empty

u-icon-bag-full

u-icon-cart-empty

u-icon-cart-full

u-icon-location

Layout

Grid-like layout mechanism for arranging components. When you combine this with our grid or width utility classes, you can create fluid and responsive page layouts.

.o-layout is the outer block class which adds offsets to counter the outer gutters, used similarly to the row classes found in other frameworks.
.o-layout__item is the element used for layout items which sets gutter spacing and essential styling. This can be augmented using the grid or width utilities in order to create layout structures sized accordingly. The .o-layout__item class is used similarly to .col classes in other frameworks.

All direct child elements of .o-layout must be .o-layout__item elements.



<div class="o-layout">
	<div class="o-layout__item">
		<div>Some Content</div>
	</div>
	<div class="o-layout__item">
		<div>Some More Content</div>
	</div>
	<div class="o-layout__item">
		<div>Still More Content</div>
	</div>
</div>

Example

Some Content

Some More Content

Still More Content

To reverse the layout direction, use .o-layout--row-reverse.

Example

Some Content

Some More Content

Still More Content

Use .o-layout--column to set the flex items vertically.

Example

Some Content

Some More Content

Still More Content

To reverse the column direction, use .o-layout--column-reverse.

Example

Some Content

Some More Content

Still More Content

Have smaller gutters between items.

Example

Some Content

Some More Content

Still More Content

Have larger gutters between items.

Example

Some Content

Some More Content

Still More Content

Have no gutters between items.

Example

Some Content

Some More Content

Still More Content

Include vertical gutters on layout items.
If we've chosen to change the size of the horizontal gutters, the vertical gutters will change accordingly.

Example

Some Content

Some More Content

Still More Content

There are additional layout object modifiers you can use to adjust the horizontal and vertical alignments of the layout items as well as specifying if an item should be the first or last in the order.


/* Vertical alignment modifiers.
 * The align-items property vertically aligns the flexible container's items
 * when the items do not use all available space on the cross-axis.
   =========================================== */
/**
 * Items are positioned at the top of the container.
 */
.o-layout--align-top {
	align-items: flex-start;
}

/**
 * Items are positioned at the center of the container (vertically).
 */
.o-layout--align-center {
	align-items: center;
}

/**
 * Items are positioned at the bottom of the container.
 */
.o-layout--align-bottom {
	align-items: flex-end;
}

/**
 * Items are positioned at the baseline of the container.
 */
.o-layout--align-baseline {
	align-items: baseline;
}

/**
 * Default value. Items are stretched to fit the container.
 */
.o-layout--align-stretch {
	align-items: stretch;
}





/* Horizontal alignment modifiers.
 * The justify-content property horizontally aligns the flexible container's
 * items when the items do not use all available space on the main-axis.
   =========================================== */
/**
 * Default value. Items are positioned at the beginning of the container.
 */
.o-layout--justify-start {
	justify-content: flex-start;
}

/**
 * Items are positioned at the center of the container.
 */
.o-layout--justify-center {
	justify-content: center;
}

/**
 * Items are positioned at the end of the container.
 */
.o-layout--justify-end {
	justify-content: flex-end;
}

/**
 * Items are positioned with space before, between, and after the lines.
 */
.o-layout--justify-around {
	justify-content: space-around;
}

/**
 * Items are positioned with space between the lines.
 */
.o-layout--justify-between {
	justify-content: space-between;
}





/* Flex ordering modifiers.
 * Set an item to be first or last in grid.
   =========================================== */
.o-layout__first {
	order: -1;
}

.o-layout__last {
	order: 1;
}
	
	
	@media screen and (min-width: 40em) {
		.o-layout__first--m {
			order: -1;
		}
		
		.o-layout__last--m {
			order: 1;
		}
	}
	
	
	@media screen and (min-width: 60em) {
		.o-layout__first--l {
			order: -1;
		}
		
		.o-layout__last--l {
			order: 1;
		}
	}
	
	
	@media screen and (min-width: 90em) {
		.o-layout__first--w {
			order: -1;
		}
		
		.o-layout__last--w {
			order: 1;
		}
	}

Lists

Default list element.

Example

List Item 1
List Item 2
List Item 3

The o-list-bare object strips list-like appearance from lists by removing their bullets, and any indentation.

Example

List Item 1
List Item 2
List Item 3

The o-list-block displays any list of items into stacked blocks.

Example

List Item 1
List Item 2
List Item 3

The o-list-inline object simply displays a list of items in one line.

Example

List Item 1
List Item 2
List Item 3

Inline list items can have smaller margins.

Example

List Item 1
List Item 2
List Item 3

Inline list items can have larger margins.

Example

List Item 1
List Item 2
List Item 3

Tables

Slightly more opinionated and structural styles for table elements.

Example

First Name	Last Name	Age
Roger	Waters	73
Nick	Mason	73
David	Gilmour	71

The table cell widths can be fixed using o-table--fixed.

Example

First Name	Last Name	Age
Roger	Waters	73
Nick	Mason	73
David	Gilmour	71

Wrapper

These are large class selectors that can hold many other structures and components.

.o-wrapper can be used to constrain the container to the maximum site width variable while including the right and left padding.

.o-wrapper--full to .o-wrapper will set the container to 100vw.

Buttons

A button is used to bring attention to key interactions on the page.

Buttons should be labelled in a way that gives the user a clear and concise understanding of what will happen when they are pressed.

Example

Control Groups

To group related buttons and/or inputs together, you can use the .c-control-group wrapping element. This will bunch the related elements together and remove the spacing between them.

Example

Divider

Divider component to provide more prominent horizontal rules between other elements.

Example

Standard Divider

Top Divider

Forms

Forms are the standard way of receiving user inputted data, and therefore are an integral and crucial aspect of our interaction with customers.

Forms should utilise a fieldset, descriptive legend (visually hidden but announced by screen readers) and a form list. Form fields should be presented in a list so that they are easier to navigate using a screen reader and, if CSS fails to load for any reason, the user is still presented with a well-formatted list of fields.

Example

Default Form Layout

Custom Form Layout

Keyline

Simple keyline component to provide horizontal rules between other elements.

Example

Simple menu layout component.

Example

Simple navigation layout component.

Example

Tables

Example

Simple Table
The simple table offers easy to read data with a horizontal divider between rows.

First Name	Last Name	Age
Roger	Waters	73
Nick	Mason	73
David	Gilmour	71

Stripped Table
The stripped table offers easy to read data with alternating background rows.

First Name	Last Name	Age
Roger	Waters	73
Nick	Mason	73
David	Gilmour	71

Typography

In order to divorce our semantic decisions from our stylistic ones, we only define opinionated typographical styles against classes, NOT against typographic HTML elements.

Shadows uses a fluid typographic scale for all screen sizes between 640px and 960px. This allows for a smooth transition of written content across an infinite number of devices.

Example

Heading Alpha Subheading

Heading Bravo Subheading

Heading Charlie Subheading

Heading Delta Subheading

Heading Echo

Heading Foxtrot

Body Copy

Borders

Utility classes to adjust element borders.

Example

Borders have been highlighted for better visualization.

Clear Fix

Class-based implementation of the 'clearfix hack'.

Colors

Utility classes to adjust element colors inline. .u-bg-***, .u-border-***, and .u-color-*** work for each color class. See the Style Guide for color swatches.

Display

The display property is the most important CSS property for controlling layout. The display property specifies if / how an element is displayed.

Class	Description
.u-hide-visually	Visually hides content leaving it accessible to screen-readers.
.u-hidden	Completely hides content both visually and from screen-readers
.u-invisible	Hidden visually but maintains the layout.
.u-flex	Displays an element as an block-level flex container.
.u-block .u-shown	Displays an element as a block element.
.u-inline	Displays an element as an inline element.
.u-inline-block	Displays an element as an inline-level block container.
.u-visible	The element is visible.

Grids

The .u-grids- utility classes give you the ability to create an automatic number of columns based on the class used; media breakpoints are included.

Example

Cell One

Cell Two

Cell Three

Cell Four

Cell Five

Iconography

This contains the @font-face call needed to add the ReadyTheme Icons Font package to your site. You can use these utility classes to add icons to your pages.

To use the generated font in desktop programs, you can install the TTF font, download here. See this guide for more info: https://icomoon.io/#docs/local-fonts You can import 'selection.json' back to the IcoMoon app using the 'Import Icons' button (or via Main Menu → Manage Projects) to retrieve your icon selection.

u-icon-error

u-icon-warning

u-icon-question

u-icon-info

u-icon-gift

u-icon-settings

u-icon-protected

u-icon-secure

u-icon-envelope

u-icon-truck

u-icon-globe

u-icon-history

u-icon-balance

u-icon-remove

u-icon-cart-add

u-icon-chevron-up

u-icon-chevron-down

u-icon-chevron-left

u-icon-chevron-right

u-icon-triangle-up

u-icon-triangle-down

u-icon-triangle-left

u-icon-triangle-right

u-icon-arrow-up

u-icon-arrow-down

u-icon-arrow-left

u-icon-arrow-right

u-icon-subtract

u-icon-add

u-icon-cross

u-icon-check

u-icon-zoom-out

u-icon-zoom-in

u-icon-search

u-icon-credit-card

u-icon-heart-empty

u-icon-heart-full

u-icon-star-empty

u-icon-star-full

u-icon-home

u-icon-user

u-icon-phone

u-icon-facebook

u-icon-twitter

u-icon-pinterest

u-icon-google

u-icon-instagram

u-icon-vimeo

u-icon-youtube

u-icon-flickr

u-icon-print

u-icon-wallet

u-icon-document

u-icon-menu

u-icon-calendar

u-icon-bag-empty

u-icon-bag-full

u-icon-cart-empty

u-icon-cart-full

u-icon-location

Print

Shadows includes a basic print style sheet.

Typography

Below you can find list and a short overview of the most commonly used text semantics.

Font Families

.u-font-primary - Primary Font Family
.u-font-secondary - Secondary Font Family

Alignment

.u-text-left
.u-text-center
.u-text-right
.u-text-justify

Sizing

.u-font-tiny
.u-font-small
.u-font-medium
.u-font-large
.u-font-huge

Weight, Transformation, and Decorations

.u-text-regular
.u-text-bold
.u-text-italic
.u-text-lowercase
.u-text-uppercase
.u-text-caps
.u-text-strike
.u-text-underline

Vertical Alignment

Widths

A series of utility classes that give a fluid width to whichever element they are applied to, media breakpoints are included.

Example

Cell One

Cell Two

Cell Three

Z-Index

Utility classes to set display relevance on the 'Z' axis.

Collapsing Breadcrumbs

This extension is a variation on the Priority+ navigation pattern where extra links will be hidden behind a trigger when they do not fit into the allotted space. With collapsing breadcrumbs, we are hiding the links at the start of the list, instead of at the end.

Shadows, and Shadows-based ReadyThemes, ship with the Collapsing Breadcrumbs extension included. The CSS is part of /themes/%STORE_ID%/THEME_NAME/extensions.css and the JavaScript is in /themes/%STORE_ID%/THEME_NAME/extensions.js. If you want to make styling changes, it is recommended you add them to your /themes/%STORE_ID%/THEME_NAME/theme.css file. The HTML for this extension can be accessed by navigating to User Interface -> Global Settings -> Settings -> Smart Breadcrumbs.

If you are using Shadows DE, you can modify the CSS or JavaScript in build/extensions/breadcrumbs/collapsing-breadcrumbs/ and update as part of your build process.