Introduction

Building

To build the style guide, use Gulp!

gulp build-dashboard-styleguide

To rebuild the style guide whenever one of the source files changes, use:

gulp watch-dashboard-styleguide

The style guide will also be built whenever gulp build and gulp dash-build runs.

Colors

A list of colors is maintained in the colors.json file. Each color should have name and colorCode properties.

For example, the color entry for $black looks like this:

{
    "colorCode": "#000",
    "name": "$black"
}

Elements and Components

Each element or component should be in it's own partial.

Partials for components are located in the components/ directory. Elements are displayed in subcategories, so partials for elements are located in the appropriate subdirectory of the elements/ directory.

Here is a default component template:

<dl class="rj-styleguide__component-section" id="rj-form">
    <dt class="component-name">
        <a href="#rj-form"><h3 class="rj-heading--4">RJ Form <code class="rj-styleguide__component-class">.rj-form</code> </h3></a>
    </dt>
    <dd>
        <p>This is an error message typically used on integrations, signup, or login pages.</p>
    </dd>
    <dd class="rj-styleguide__playground">
      <button class="js-view-source">View Markup</button>
      <div class="rj-styleguide__preview rj-styleguide__codearea">
        <div class="rj-form-error-message" ng-message="email">This email address is not valid.</div>
      </div>
    </dd>
</dl>

See .rj-form__help-box for a component template with sub-components/modifiers.

When adding new element subcategories, make sure to update the template.html file.

Variables

Colors (By Hue)

Gray

  • $white #FFFFFF
  • $alabaster #F7F7F7
  • $mercury #E4E4E4
  • $nobel #B3B3B3
  • $gray #828282
  • $tundora #444444
  • $mine-shaft #262626
  • $black #000000

Blue

  • $solitude #E6F4FF
  • $curious-blue #2C92DB
  • $calypso #2A638C

Green

  • $snowy-mint #E6FFE8
  • $emerald #4DBF60
  • $forest-green #257D2D

Yellow

  • $champagne #FAEDC8
  • $supernova #FFC40D
  • $pirate-gold #AB8000

Orange

  • $karry #FFE9D9
  • $tango #F27E24
  • $magento-orange #EB5202
  • $rich-gold #A84E08

Red

  • $pippin #FFE6E6
  • $cinnabar #E33C39
  • $stiletto #A63432

Elements

Headings

Heading 1 .rj-heading--1

Get Started with Magento BI Essentials

ProximaNova-Regular / 32 px / 40 px Leading / #444444

This is a plain heading used on the data warehouse welcome page, for example.

Heading 2 .rj-heading--2

Your Update Cycle

ProximaNova-Semibol / 22 px / 30 px Leading / #444444

This is a plain heading used on the data warehouse welcome page, for example.

Heading 3 .rj-heading--3

Executive Overview

ProximaNova-Semibold / 18 px / 22 px Leading / #444444

This is a plain heading.

Heading 4 .rj-heading--4

Dashboard Options

ProximaNova-Bold / 17 px / 20 px Leading / #444444

This is a plain heading.

Heading 5 .rj-heading--5

Shared by Ben Garvey

ProximaNova-Semibold / 14 px / 20 px Leading / #444444

This is a plain heading.

Default Paragraph .rj-paragraph

Bulk Edit Reports

ProximaNova-Semibold / 14 px / 20 px Leading / #444444

This is a general paragraph.

Large Paragraph.rj-paragraph--large

Pricing is monthly and based on your store's Gross Merchandise Volume (GMV).

ProximaNova-Semibold / 14 px / 20 px Leading / #444444

This is a description.

Type

Helper Text.rj-helper-type

This is an explanatory type. It is used, for example, in the visual report builder to tell how many filters a metric has applied to it. The regular helper class is .rj-helper-type, error modifier class is .rj-helper-type--error.

This is regular helper text

This is error helper text

Buttons

Default Button.rj-button

Default/Primary Action Button .rj-button

This is a plain button from which other rj-buttons are extended. This button is reserved for primary actions.

Brand/Marketing Button.rj-button--brand

This button is reserved for brand specific functions such as on the login page and on branded modals.

Dangerous Action/Delete Button.rj-button--danger

This button is reserved for dangerous actions such as deletion.

Create/Add Button.rj-button--create

This button is reserved for call to actions. For example, adding a metric in the Visual Report Builder

Confirmation/Save/Apply Button.rj-button--confirm

This button is used for confirmation. It is used for saving and applying changes.

Secondary Action Button.rj-button--secondary

This is a button with a light background, used to indicate a separate action on a page. This is used in the Report Builder.

Secondary Selected Button.rj-button--secondary-selected

This is the selected state of the secondary button.

Disabled Button<button class="rj-button" disabled>

This is the disabled state of all rj-buttons. Use with disabled attribute set to get styles

Icon Button.rj-button--icon

This is a button that adjusts to the element length, useful for narrow icons. It can be used along with the other rj-button--* classes.

Plain Button.rj-button--plain

This is a plain action button, which looks like a link.

Switch Button.rj-button-switch

This is a group of buttons in a div .rj-button-switch, usually two. All buttons have to have class .rj-button-switch__button applied to it. The first button requires class .rj-button-switch__button--first and the last requires class .rj-button-switch__button--last. The active button marks by class .rj-button-switch__button--selected. Since buttons function as one, styling is applied to them to have even widths. The switch will take up the entire width of its parent.

Form Elements

Form Error Message.rj-form-error-message

This is an error message that shows up on forms normally used outside of the product (i.e. Signup/login/reset-password forms).

Use .rj-form-error-message below the corresponding input to indicate that the value is invalid.

rj-inline-container .rj-inline-container and .rj-inline-container--*
This is an input field container. This is a <div> with <input>s in it. The .rj-inline-containter--* are different widths which you can mix and match to fit next to each other. They are designed to fint into a .rj-inline-form.

rj-inline-form .rj-inline-form
This is an input field container parent. This is a <div> with .rj-inline-container--*s in it. The .rj-inline-containter--* will then take up the appropriate amount of space. The last line uses .rj-inline-container--variable which allows for the input of form elements that are of variable widths. You can include elements such as .rj-buttons within it, although you may need to adjust the height of these form elements for consistency.

rj-select .rj-select

This is a basic select field with RJ styling

Make a selection:

Light Select Element .rj-select--light

This is a light version of the default select element. It is often used in .rj-form.

.rj-select--light must be wrapped in .rj-select-wrapper.

rj-text-box .rj-text-box

This is an input field which takes up the entire width of its parent. It has a light gray background and no border.

Always use a label with an input field. If it is not desirable to see the label text, use .rj-visually-hidden on the label.

Use the .error class on the input to indicate that the value is invalid.

rj-text-box--alt .rj-text-box--alt
This is an input field which takes up the entire width of its parent. The placeholder attribute text gives instruction. NOTE: Always use a label with an input field. This input is used in the data warehouse for example to create new columns. The placeholder text uses a placeholder mixin rj-placeholder to maintain consistency across browsers.
rj-text-box--light .rj-text-box--light

This is an input field which takes up the entire width of its parent. It has a light gray background and no border.

Always use a label with an input field. If it is not desirable to see the label text, use .rj-visually-hidden on the label.

Use the .error class on the input to indicate that the value is invalid.

Text Decorations

rj-form-identifier
.rj-form-identifier
Used to display a variable that represents the associated filter, input, etc.
A .rj-form-identifier
[A] .rj-form-identifier
[AB] .rj-form-identifier
rj-label
.rj-label
This is a set of styles which can be used to differentiate different items.
Success .rj-label--success Used to indicate success.
Warning .rj-label--warning Used to indicate a warning.
Error .rj-label--error Used to indicate an error.
Unavailable .rj-label--unavailability Used to indicate unavailability.
rj-warning-item
.rj-warning-item
This class can be set on any element which contains text. It will render the text in a color that indicates that there is some warning associated with the text, and displays an exclamation icon alongside the text.

Error

Something went wrong!

Icons

Font Awesome Images .rj-image--laptop-charts
This is scalable Font Awesome art. To use, select the art and then change the font size (only!) on the rj-image--* element. You must use all of the divs that are included in this markup sample. The rj-image--laptop-charts has optional asterisks surrounding it. Leave out the corresponding divs for an asterisk free experience.
Help Icon .rj-icon--help
The use of this class is a little different from the other icons. This class should be used on an <a> which takes the user to one of our Zendesk pages. It should include descriptive accessible text within the content of the <a>. Be sure to use the target="_blank" attribute to open the help page in a seperate page.
Help About This Topic
RJ Icons .rj-icon and .rj-icon--*
These are spans which use a class to put in a font or icon. They can be used in conjunction with buttons, other spans, etc. .rj-icon does not have an icon, rather serves as a base class for other icons.
.rj-icon
*--angle-down
*--angle-up
*--angle-right
*--file-o
*--files-o
*--plus
*--minus
*--times
*--plus-circle
*--minus-circle
*--refresh
*--envelope-o
*--plus-square
*--edit
*--help
*--exclamation
*--search
*--bell
*--lifesaver
*--th
*--card
*--ticket
*--users
*--user
*--user-plus
*--sign-out
*--gear
*--check
*--arrow-right
*--heartbeat
*--history
*--trash
*--spinner
*--play
*--pause
*--step-backward
*--step-forward
*--bug
*--compress
*--info-circle
*--save
*--pencil
*--question-circle-o
*--calendar
*--table
*--long-arrow-right
*--ban
*--circle
*--lock
*--unlock
*--filter
*--eye
*--clock
*--superscript
*--ellipsis-v
*--share-alt
*--warning
*--caret-down
*--list
*--binoculars
*--square-o
*--check-square-o
*--minus-square-o
*--expand
*--file-text
*--file-excel
*--cloud-download
*--globe
*--check-circle
*--check-circle-o
*--key
*--times-circle
*--ellipsis-h
*--building
*--frown-open
*--signal
*--percent
*--hdd
*--money-bill
*--paper-plane
*--chart-line
*--hashtag

Animated Icons

Spinning Icon.rj-icon--spin

This causes the icon to spin.

Stuttered Spin Icon.rj-icon--pulse

This causes the icon to spin with a stutter.

.rj-image--* .rj-image--*

While .rj-icons are small enough to be suitable for display alongside (and at the same size as) text, .rj-images are assets which are too large to display alongside text, such as logos, and which should be displayed more prominently on the page.

Each icon should have a size class and a background image class.

There are three predefined size classes. The heights of each are as follows:

  • .rj-image--small: 32px
  • .rj-image--medium (or .rj-image): 64px
  • .rj-image--large: 128px

The width of each icon is proportional to the height.

The following are all available background image classes. Images intended for display on dark backgrounds have an --inv suffix.

.rj-image--contact
.rj-image--documentation
.rj-image--contact--inv
.rj-image--documentation--inv

Components

rj-action-box .rj-action-box

This is a <div> with a body within it and and action confirmation section within it. The body usually has a form, and the bottom usually has error messages/warnings and Cancel / Save buttons. It has a light gray background to differentiate the action from other areas.

.error-info can be used to show an error message associated with a form element.

Add a New Feature

Description about feature

This is extra information about the input or about something else happening in this action box.

Alert: You must input a name before saving.

rj-action-list .rj-action-list
This is a table view with checkboxes

Checkbox in header is used as a Select/Toggle all action and indicator

  • rj-icon--square-o if NONE of the list elements are selected
  • rj-icon--minus-square-o if SOME of the list elements are selected
  • rj-icon--check-square-o it ALL of the list elements are selected

Status
Edit
Name Secondary Name
Data Type
Location
Synced
item_id
INT(11)
From Your Database
Synced
order_id
INT(11)
From Your Database
This is an empty list
Nothing here
rj-action-table .rj-action-table

This is a component well-suited for displaying a list of items with multiple properties.

This style should only be applied to <table> elements.

Since this is a table, the widths of the columns will automatically be sized appropriately for the content, however using the .fixed-narrow, .fixed-medium, and .fixed-wide classes will change the width biases of the columns and thus influence their overall display widths.

The .fixed-action class is well-suited for plain buttons and checkboxes, and has a narrow width and centered alignment.

Status Edit Name Data Type Location
Synced item_id INT(11) From Your Database
Synced total_cost DECIMAL(10,2) From Your Database

Breadcrumbs.rj-breadcrumbs

This is used to style a breadcrumbs path.

Use rj-breadcrumbs__path to style the path sections.

rj-breadcrumbs__path can be used on a, button or span elements.

rj-callout .rj-callout
This is a <div> with differring sections within it. These include a heading to describe the function of the callout. Callouts are areas that are differentiated from the rest of the page. They can be used for status updates.

Data Warehouse Summary

Status Update
In progress for 6 hours
Total Synced Rows
167,901 (Synced)

Default Card .rj-card

This is the default code box used in our app.

It is normally used to wrap a form and can be used with or without sections.

Card section.rj-card__section

This subcomponent class allows the card to be separated into different sections.

Default Card

This is our standard card with sections.

Default Card

Default Code Box .rj-code-box

This is the default code box used in our app.

It's used on the Magento signup flow connections page when encryption type is SSH.

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQChZMqbjzSn9EVyTWuflb4Rs7ZMFiXGXcxNaFA3kUKMlTWdR58edKrLvmkPhzxTVY7H60bJsUl2bJc7XA8QG9L3rhQD7MCBmJl6LZGl6r6UrZweuts8BaNQmURiq60rwzktGhI0JnVTlqdYvFrFWF7zBydfMjf0+mtAMHrZiTLWUyVm8gcSCJwKBBzQsBhAa/Q5X6gSqAfJ9dfKQJynxsejNZzH3h2EiPR3IkWbbHxAVwHSd4L3sKl/wZxc8IedjTGCW/sMfh0dAf8yWUN8AHwZXQ6XdyEiutlBgB3VaRzCNLs9dWuWK5r8w2FdG7Z5RhHUCkmD62w8cXljCF2GXokd vagrant@vagrant
rj-dropdown .rj-dropdown
rj-dropdown-menu .rj-dropdown-menu
rj-dropdown-menu--right .rj-dropdown-menu--right
rj-dropdown-menu--side .rj-dropdown-menu--side
rj-dropdown-menu--diamond .rj-dropdown-menu--diamond

This is a <div> with <button> which has a class of .rj-button--* and a <ul> The <ul> follows the component structure for .rj-dropdown-menu. In this example, we are using a .rj-button--secondary for the dropdown, but any button will work and will apply the dropdown icon. There is also an option for a multi-column menu. This allows multiple columns within the menu. It is achieved by placing the class .multi-column-menu on the .rj-dropdown-menu. Add .scrolling-section to the part of the menu which you wish to scroll. It adds an overflow-y and a max-height of 400px.

Use the class .non-button-option on <li>s which don't have a button. A good example is the save dropdown in the report builder.

The .rj-dropdown-menu--right should be used for sub-menus within dropdown menus. It can be applied to a <li>. An excellent example of this is in the report builder under "Add Metric" and hovering over GA options.

The .rj-dropdown-menu--right requires .side-menu-toggle as a parent on the element with a .options-list.

The .rj-dropdown__fixed-light class is applied to a button or a that needs to take up a full fixed width. Use it in conjunction with .rj-button--secondary. It also adjust the caret so that it's absolutely positioned. The width it takes up is determined by its parent container.

A Heading in the Menu

This is a description or some sort of helper text.

  • Another option

  • Empty Option - no result seen here

Another Heading in the Menu

This is a description or some sort of helper text.

A Heading in the Menu

This is a description or some sort of helper text.

Another Heading in the Menu

This is a description or some sort of helper text.

This is a description or some sort of helper text.

A Heading in the Menu

This is a description or some sort of helper text.

Another Heading in the Menu

This is a description or some sort of helper text.

This is a description or some sort of helper text.

rj-dropdown-placeholder .rj-dropdown-placeholder
Use this component to display a message regarding why a dropdown is empty. This component is not meant as a standalone component and should be used inside a <div> with the class .rj-dropdown-menu.
rj-expand-info-list .rj-expand-info-list

Component used to display list of items with detailed information hidden until expanded. Can be used grouped or ungrouped.

Example usage can be seen in Dashboard application Metrics and Filtersets managment pages.

Group 1 Name Action
Item 1
Detail:

Detailed Info about the item.

Options
Item 2

Options
Group 2 Name Action
Item 1

Options
Item 2

Options
rj-expand-list .rj-expand-list
Add description here
    • Thing 1
    • Thing 1
    • Thing 2
    • Thing 3
    • A really long thing that's going to take up more room and wrap
    • Second Example Sub-Menu
    • Thing 2
    • Thing 3
    • A really long thing that's going to take up more room and wrap
rj-expander .rj-expander

Allows content to be selectively hidden and shown.

Should contain two children: a <button> with .expander-button, and the content to be hidden or shown, with .expander-content. The content can be any element, not just a list.

The expander is hidden by default. Setting the .expanded class on the .rj-expander element will cause the content to become visible.

<div class="rj-expander expanded">
  <button class="expander-button"><!-- ... --></button>
  <div class="expander-content">
    <!-- ... -->
  </div>
</div>
rj-filters-form .rj-filters-form
Add a description here.
[A]
rj-flat-list .rj-flat-list

This is a basic <ul> which allows the user to select form a list of items.

Each <li> can contain either <button>s or <a>s.

Use .selected to indicate the element is currently selected.

Use .emphasis to display the contents of the <li> in bold text, to emphasize certain elements.

Use the disabled attribute to prevent an element from being selected.

<ul class="rj-flat-list">
  <li>
      <button class="selected">...</button>
  </li>
  <li>
      <button>...</button>
  </li>
  ...
</ul>

RJ Form .rj-form

This is a regular form typically used on integrations, signup, or login pages.

Each field should be wrapped in a fieldset with a class of .rj-form__field.

Inputs should be wrapped within a label tag with a class of .rj-form__label. Labels should be in sentence case.

.rj-form-error-message can be used with this form for error messaging.

To place multiple fields on one line, wrap those fields in .rj-form__row and those fields will become inline with the same width.

.rj-form__info can be used with this form for below field descriptions.

Form Help Boxes .rj-form__help-box

Default .rj-form__help-box

Should be used for general information within .rj-form.

Warning .rj-form__help-box--warning

Should be used for warnings within .rj-form.

RJ Helper .rj-helper

Should be used for side section help messages.

Notification .rj-notification

Success .rj-notification--success

Should be used for success notifications that appear at the top of the page.

New metric created!
×

Warning .rj-notification--warning

Should be used for warning notifications that appear at the top of the page.

Don't go there: too much information.
×

Error .rj-notification--error

Should be used for error notifications that appear at the top of the page.

Temporary issue: the connection failed. We will reattempt shortly.
×

Info .rj-notification--info

Should be used for info notifications that appear at the top of the page.

Metrics are built from columns in your data tables and are use to create reports.
×

Form notifications .rj-notification--form

This is the default code box used for form server messaging/notifications and should be placed at the top of an .rj-form.

It's used on the Magento signup flow connections page.

Use .rj-notification--error for the error version of the notification.

Notification Title
Notification Error or Success Message

Popover .rj-popover

This is a popover use on the Integrations page.

Integration Options

Progress List .rj-progress-list

Should be used for indicating progress in a horizontal form.

Use .rj-progress-list__item--complete for a completed step.

Use .rj-progress-list__item--complete-final for the completed final step.

rj-sidebar .rj-sidebar

This element is intended to display secondary content alongside primary content—for example, filter options alongside a table of data—and works well at narrow resolutions.

The .rj-sidebar should contain at least one .sidebar-section, and may contain multiple. The .rj-sidebar can also contain .rj-heading--5 elements.

Elements which work well inside .rj-sidebar:

  • .rj-button-switch
  • .rj-button--primary-*
  • .rj-button--secondary
  • .rj-flat-list
  • .rj-expander
  • .rj-text-box
<div class="rj-sidebar">
  <h5 class="rj-heading--5">Filters</h5>
  <div class="sidebar-section">
    <input class="rj-text-box" type="text" placeholder="Search">
  </div>
  <div class="sidebar-section">
    <ul class="rj-flat-list">
      ...
    </ul>
  </div>
  ...
</div>

Filter

Select A Table

rj-summary-list .rj-summary-list
Use this when listing summary information about a set of resources. When there are two summary titles, use .summary-titles-thirds and .summary-actions-thirds.
  1. Metric Name
  1. Export API Key
    IP Addresses with Access*
  2. f63258d999sd000sbf
    127.0.0.254
    127.0.0.83

Default Table .rj-table

This is a default table used on the Integrations page.

Use .rj-table__header for the table header.

Use .rj-table__row for rows.

Use .rj-table__cell for cells.

Name Position Start Date
Britney Account Manager June 8, 2008
Todd Sales Associate July 22, 2010
Connie Developer October 12, 2009
rj-tabs .rj-tabs
This is a <ul> with <li>s containing either<buttons>s or <a>s. It will take up 100% of its parent container as it is meant to emulate the look of actual tabs. The children of the <li>s take the class .rj-button--plain
rj-title-form .rj-title-form

This is a <div> with an<input> and <buttons>s and/or <a>s. It will take up 100% of its parent container. The buttons and the input are flexed so that they take up as much space on the right and left side as possible. If the title becomes too long, it will have an ellipsis indicating that it is truncated. An example of this is the Save Figure Directive, which is used in the Report Builder. The Save button can have a dropdown associated with it (as is its use case in the Report Builder).

In the directive, on click, the title changes into an input. for style guide purposes, both of those variations are shown below.

In case there's an error, that will appear below the title are of the input.

A report with this name already exists.
Untitled Report
with a Cumulative metric perspective

RJ Tooltip .rj-tooltip

This is a standard CSS only tooltip for simple messages. It is used for tooltips on filters in the report builder.

This is popup content"
Something that has a popup
rj-well .rj-well

This is a component used to display alerts.

It can be used on its own, or with a modifier class.

This is a well with no modifiers.

This is a well with the .rj-well--success class set.

This is a well with the .rj-well--info class set.

This is a well with the .rj-well--warning class set.

This is a well with the .rj-well--error class set.

Magento Onboarding Wizard .rj-wizard

This is the onboarding wizard component used in the Magento Basic Tier signup flow.

1

(1/3) Create your account

2

(2/3) Set your preferences

3

(3/3) Connect your database

Layouts

rj-dismissible-box .rj-dismissible-box

This takes up the entire width of its parent. Can be used on a list or on a div. The last child of the box gets the rj-dismissible-box__dismiss class and the applicable styles with it.

This is currently used to case the rj-selection-box--little which houses a tour for the application in the help dropdown.

  • empty list item inside a ul, no padding, no nothing
simple div inside the box, no padding, no nothing
rj-grid-layout .rj-grid-layout

Provides a layout for multiple columns, each of which has a width proportional to the width of the parent.

Column widths are in units equal to 1/12th of the parent width, and the class name corresponds to the width: thus, .col-12 corresponds to a width of 12 units, and .col-1 corresponds to a width of 1 unit.

The .rj-grid-layout class does not have any padding between rows or columns.

.col-12
.col-6
.col-6
.col-4
.col-4
.col-4
.col-3
.col-3
.col-3
.col-3
.col-2
.col-2
.col-2
.col-2
.col-2
.col-2
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-4
.col-8
.col-3
.col-6
.col-3
.col-11
.col-1

The .rj-grid-layout--padded class has padding of 20px between rows and columns.

.col-12
.col-6
.col-6
.col-4
.col-4
.col-4
.col-3
.col-3
.col-3
.col-3
.col-2
.col-2
.col-2
.col-2
.col-2
.col-2
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-1
.col-4
.col-8
.col-3
.col-6
.col-3
.col-11
.col-1

Layout Helper Classes

Center Inline Elements.l-inline-center

This can be used to center inline elements.

This inline element is centered.

rj-modal .rj-modal

Currently, this overrides the Bootstrap modal styling with something more consistent with the direction our styling is moving, but this could potentially be a self-contained component in the future.

This takes care of removing the border radius from the modal, and positioning the modal in the center of the screen. It has a fixed with of 600px, and the height expands to fit the content.

The %rj-modal placeholder should be extended for modals of different sizes.

When using Angular's $modal, the class can be added by setting the modalClass property

  modal = $modal(
    modalClass: 'rj-modal'
    ...
  )
Enter Some Info

Enter a name before continuing.

Selection List .rj-selection-list

This is a list of options which includes: an icon, a heading, a description, and a call to action button. A prime example of this list is when selecting which report builder to use.

The .rj-selection-list will take up the entire width of its parent element.

This element can be modified so that it is reponsive in future iterations of the application.

  • Visual Report Builder

    The Visual Report Builder is the easiest way to visualize your data. Create charts, add metrics, and segment your data all with a few clicks. Learn More.

    Create Report

  • Cohort Report Builder

    The easiest way to analyze and identify behavioral trends of similar user groups over the course of their life cycles. Learn More.

    Create Report

Little Selection List .rj-selection-list--little

This is a list of options which includes: an icon, a heading, a description, and a call to action button. A prime example of this list is when selecting which report builder to use.

The .rj-selection-list will take up the entire width of its parent element.

This element can be modified so that it is reponsive in future iterations of the application.

  • Visual Report Builder

    The Visual Report Builder is the easiest way to visualize your data. Create charts, add metrics, and segment your data all with a few clicks. Learn More.

    Create Report

  • Cohort Report Builder

    The easiest way to analyze and identify behavioral trends of similar user groups over the course of their life cycles. Learn More.

    Create Report
rj-sidebar-layout .rj-sidebar-layout

A layout for displaying primary content alongside a menu containing secondary content—for example, table filter options alongside a table.

The width of the sidebar is fixed at 185 pixels, while the content will expand to fill the parent element.

The .rj-sidebar-layout element should contain two children:

  • .sidebar-layout-sidebar containing the content to display in the sidebar (this does not necessarily need to be an .rj-sidebar element).
  • .sidebar-layout-content for displaying the primary content.
<div class="rj-sidebar-layout">
  <div class="sidebar-layout-sidebar">
    ...
  </div>
  <div class="sidebar-layout-content">
    ...
  </div>
</div>

Filter

Add a New Feature

This is extra information about the input or about something else happening in this action box.

Alert: You must input a name before saving.

Default Title Bar .rj-title-bar

This is the default title bar used for subpages in our app.

It is normally used to wrap an `rj-heading--3` containing the title of the page.

Account Settings

Code

Coffeescript
  • Try to keep functions under 40 lines
  • Use coffeescript conditional operators 
    # Don't do this
if status == 'complete'
  console.log 'complete'

# Do this
if status is 'complete'
  console.log 'complete'

# Use is instead of == or ===
# Use isnt instead of != or !==
# Use and instead of &&
# Use or instead of ||
# Use not instead of !
  • Use comprehensions instead of for loops 
    # Don't do this
for(i=0; i<items.length; i++)
  doSomething(items[i])

# Do this
for item in items
  doSomething(item)

# Even better
doSomething(item) for item in items
  • Even though coffeescript lets you omit parenthesis in function calls, use them anyway for clarity 
    # Don't do this
"Do I match?".match "Do"

# Do this
"Do I match?".match("Do")
  • Omit parenthesis, brackets, and returns everywhere else unless you feel it needs further clarity
    • # Don't do this
processData = (data) =>
  if data is 100
    data
  else if data is 200
    200
  300

# Do this, although it's still pretty ugly
processData = (data) ->
  result = 300
  if data is 100
    result = data
  else if data is 200
    result = 200
  return result

# Best
processData = (data) ->
  switch data
    when 100 then data
    when 200 then 200
    else 300

# Don't do this when writing promises
somePromise.get(id).then (response)->
    console.log response

# Do this when using then and other promise chaining. It's clearer where the code will execute
somePromise.get(id).then( (response) ->
    console.log response
  )

# Another bad example that is valid coffeescript
setInterval () ->
  console.log "tick"
, 1000

# Do this. It's clearer
setInterval( () ->
    console.log "tick"
  , 1000)

# Best
tick = () ->
  console.log "tick"

setInterval(tick, 1000)
  • Use the single arrow when declaring functions, not the double arrow 
    # Don't do this, as it preserves the scope of the parent function
processData = (data) =>
  console.log data

# Do this
processData = (data) ->
  console.log data

Sparkline<sparkline sparkline-data=""><sparkline>

This is a directive used to create a sparkline graph. It is used within a table cell to show how a measurement has changed over time. This is a <sparkline> with the attribute sparkline-data in it, where the value is a string of comma-separated numbers that will be used as the data for your graph. 

        <sparkline sparkline-data="45, 67, 83, 25, 34"></sparkline>
git add

Styling Guidelines

  • Purpose / Introduction

    Going forward, all CSS should follow these guidelines and legacy CSS should be updated as time and necessity allows. Each new CSS element, component, and layout pattern must be added to the style guide.

    Updates to the Coding Standards Are highly encouraged! There are many ways to write CSS and consistency is really the most important goal here. If you have any ideas, suggestions for changes, additions, or just questions in general, please, join in on the conversation in the #front-end-eng channel on Slack and come ready to discuss your proposed changes at one the the front-end meetings.

  • Guidelines

  • Property Order

    There are quite a few ways to order properties in style blocks. The most popular way is grouping by type, which makes it easier to view styles that affect each other (for example, adding together pixels of padding, margin, and width). We group by type. Below is the order of properties in your style blocks.

    Box Model
    • Display and Positioning
      • display
      • position
      • top
      • right
      • left
      • bottom
      • z-index
    • Margins and Padding
    • Width and Height
    • Borders
    • Text
      • Text
      • Font
      • Whitespace
    • Other
      • background
      • background-image, etc.
      • overflow
      • transform
      • content
  • Nomenclature, Nomenclature Standards, BEM, and Semantics

    • Classes should be used as styling hooks.
    • Other attributes including IDs should not be used.
    • Since we follow an OOCSS, styles should be as reusable as possible.
    • IDs are unique and styling for them cannot be reused 

            
// Bad (because it’s not reusable):
#input-filter-logic {
  width: 206px;
  padding: 5px 3px;
}
// Good:
  .rj-button—-secondary—selected {}
// Note: This component has two modifiers on it: “secondary” and “selected”

    All RJ specific components will have the rj- prefix. This helps differentiate third party styles and allows for easier understanding of customized components. 

            
.rj-selector {}

    Any modifiers to components will be separated by two dashes. This is a variation of the BEM syntax model (see references.)

    BEM Primer

    BEM stands for BLOCK-ELEMENT-MODIFIER After the RJ prefix, we add the block code. In the example above, the word "selector" is the block.

    If the Block needs to be modified in some way, say there's a version of it we're using that's larger, that Modifier is preceded by --.

    BEM element code is identified with preceding __ and is never nested. 

            
// Example of a Block and Modifier

// Block
.rj-selector {
  display: block;
  color: $selector-color;
}

// Modifier
.rj-selector--brighter {
  display: block;
  color: $modifier-color;
}

// Element
.rj-selector__confirmation-button {
  border-radius: 10px;
}

// BAD: this gives the selector button a higher weight, and makes it harder to overwrite
.rj-selector {
  .selector-button {
    border-radius: 5px;
  }
}

    In BEM then both of those classes would be added to the modified element. Names should be meaningful and descriptive. Do not be afraid of long ugly looking class names.

    BEM allows for great OOCSS without nesting. 

            
<!-- Example of HTML Markup -->
<div class="rj-selector">Some text</div>

<!-- Example of Modifier -->
<div class="rj-selector rj-selector--brighter">Some modified text</div>


<!-- Example of Modifier with Element-->
<div class="rj-selector rj-selector--brighter">Some modified text
  <button class="rj-selector__confirmation-button">Click</button>
</div>

    DO NOT name anything by an existing element or pseudostate 

            
// BAD
.active {
  color: $active-color;
}

// GOOD
.rj-selector--is-active {
  color: $selector-active-color;
}
  • All HTML should be semantic and valid

    Refer to W3C for info

    Examples:

    • HTML should follow an outline form. Be wary of unnecessary nesting especially of <div>s which can result in "div soup".
    • do not put a <div> inside a <span> or a <p>
    • ol/ul should only contain li
    • dl should only contain dt followed by dd
    • If an action changes the URL in the address bar, it should be an anchor. If an action does not change it, it should be a button. A good example of this is a dropdown menu.
    • if it’s not really a list (such as a menu in a header) it may be more appropriate to use some other element - use your best judgement
    • if it’s a term with descriptions, a dl may be the most appropriate
    • Images

      An image that has informational value should be a part of the markup (think of the markup as an outline) Inline, an <image>, or as an <ng-include> if it’s an SVG icon (put the SVG in the correct partials folder!) If an image is purely decorative (such as a textured background), then background image is appropriate

  • Whitespace (literal whitespace, not the property name :D )

    Indents for styles will be set as spaces/soft tabs at 2 spaces. In Sublime Text, you can see spacing on the bottom right corner of the text editor.

    • Each selector should be on its own line.
    • There should be a space before {curly braces} for style blocks
    • Place a space after the “:” in style declarations
    • No trailing whitespace after selectors

            
// Whitespace Example 
// NO, VERY BAD:
.rj-comment-box+input,.rj-heading-1,rj-heading-2, .rj-heading-3, .rj-heading-4{ 
  font-family:Arial; 
} 
   
// YES:
.rj-comment-box + input,
.rj-heading-1,
.rj-heading-2,
.rj-heading-3,
.rj-heading-4 {
  font-family: Arial;
}
  • Numbers and measurements

    Any decimal between -1 and 1 must have a preceding zero to prevent mistakes.

    Any measurement that is zero should not have a unit designation. This is for readability and an easy way to save bytes in your CSS.

    Use appropriate units: px, em, rem or a designated mixin unless you’re styling a stylesheet for print, do not use cm or in For ease of specificity, legibility, and easy byte savings use shorthand to define values 

            
// Number example
.rj-selector {
  margin:  0 0 10px 5px;
  padding: 0 5px 10px; // leave off last value if it's the same as the second one!
  font-size: 0.4em;

  // NOT:
  margin-right: 0;
  margin-left: 0;
  margin-top: 10px;
  margin-bottom: 15px;
  font-size: 7cm;
}
  • File Order
    1. File Setup
    2. utilities folder (this includes your colors, your mixins for prefixed properties or sprite sheets for example, variables, etc.)
    3. a components folder which would be directly linked to the style guide (this includes styled rj-dropdown, rj-dropdown--alt, rj-button, rj-button--large, for example)
    4. a views folder (this includes specific page views that combine the components together and take care of view-specific styles. (For example, if in the report builder view the rj-dropdown needs to be more compact because of view limitations, this is where the rj-dropdown would be modified to have a smaller width). Especially with sass, it's advantageous to have more files which are easy to look through and more manageable than a huge file with a LOT of styles.
    5. Sass (scss) files will then we concatenated and compiled into one css file.
  • Objects in CSS (OOCSS)
    • CSS should be “Object Oriented”
    • Separate structure from skin
    • Stressed reusability and DRYness
    • Advantages include performance and maintainability
    What is Object Oriented CSS?

    It means thinking of your site design and breaking it down in terms of objects. For example, a box with a gray border and a "dismiss" at the bottom may appear in a number of ways in our app. This containing div with a gray border should be its own object (check out rj-dismissible-box). If there is a similar box except it has a darker gray border, that can be a modifier on that component, just changing that one thing - the color.

    Views and Components are separate

    A view is specific to the particular part of the site the user is on, for example:

    the report builder view.

    In views, components can get minor adjustments to make sure they properly fit together in that particular perspective, for example:

    In the report builder, because of an added column, rj-comment-box needs to be smaller, so it is adjusted in the .rj-report-builder-view

    Every component on the site is its own object much like in a house: the doors in a house are very similar or even same even though one leads to the bathroom and one leads to the bedroom. These are analogous to objects. Adjusting the hardware on the doors based on which room they're in is analogous to adjusting the object in the view.

    Following BEM principles, these adjustments should all be done using the view class and adding that class in the markup.

  • Comments
    General
    • All comments should be on their own separate line.
    • Comments should be meaningful and should add clarity to styles that may seem obtuse.
    • use // in Sass, which will not compile and, therefore, will not increase load time.
    • Use comments generously, but keep them informative.

    If something needs updating, avoid putting it in the comments because it gets forgotten about. Instead, create a Trello ticket for it. 

            
// BAD ex.
// I have no idea what this does
// BAD ex.
// TODO: Update these styles!

// GOOD ex.
// .rj-dropdown needs higher z-index in this view to make sure .rj-warning-message appears below it

    Comments to differentiate components should be in a block to make them easy to see and find

    View files should begin with a comment block describing what is being affected by this particular file 

            
// Block Comment Example:

//*******************************
// Comment Box Component
//*******************************

// Single Line Comment Example:

// z-index modified so menu appears above .rj-comment-box
  • Preprocessor Basics

    Follow standards set here: CSS Tricks Sass style guide

    Variables

    Colors and fonts should be declared as variables in _vars.scss. Colors must be updated in colors.json

    Colors should be named in a global colors section:

    Shades of gray (or grayish colors) should be named by suffixing the name gray--  with the average value of the RGB components divided by 16 and rounded to the nearest integer. (As an example, the hex color #555555 should be named be gray--9.) Base 10 should be used for the suffix (so #CCCCCC would be gray--13).

    Other colors should be named in a global colors section by using the color name result from Color Hexa

    Names for variables should be $kebab-case. Old bootstrap styles are in $camelCase.

    Color variable names should then be set as functional color names for variables. 

            

//*********************** 
// Global Colors 
//*********************** 
$moderate-violet:    #9138be; 
 
//*********************** 
// Functional Colors 
//*********************** 
 
$comment-box-border-color:   $moderate-violet;
  • Mixins

    Mixins are useful for small chunks of reusable code.

    @extend should ONLY be used on placeholder components and placeholder components should only ever be declared ONCE. 

            
// NO - Improper use of color and no reusable code.
.rj-comment-box { 
  border: 1px solid #9138be;
  font-size: 16px; 
}
// YES - Reusable component and color in a variable
%rj-comment-box { 
  border: 1px solid $comment-box-border-color;
  font-size: 16px; 
}
.rj-comment-box {
  @extend %rj-comment-box;
}
.rj-comment-box--alt {
  @extend %rj-comment-box;
  font-size: 12px;
}
  • Nesting

    DO NOT nest CSS selectors.

    DO nest similar properties in Sass for ease of legibility (this doesn’t count as a nesting penalty) 

            
// Good Nesting of CSS Properties
.rj-selector {
  font: { 
    family: $serif-font; 
    size: 16px; 
    weight: bold; 
  }
}
// Bad Nesting of Selectors
.rj-selector {
  .selection-button {
    .funny-icon {
      font-family: $icon-font;
    }
  }
}
  • References