Paint

Paint is a collection of SCSS functions, mixins, placeholders and global styles that help us bootstrap our internal apps.

It also acts as an abstraction layer, keeping other frameworks / dependencies away from the applications. This makes structural changes (like removing a dependency or adding a new one) easier to implement.

Setup

Paint comes as a bower package (paint) and an npm package (as-paint).

To use the bower package, run bower install paint --save-dev.
For npm, run npm install as-paint --save-dev.

This is going to install all dependencies.

There are 2 ways to import paint into an application:

Out-of-the-box, without any theming / resets.
For that, just @import '/bower_components/paint/styles/paint' or @import '/node_modules/paint/styles/paint'
Allow theming and customising components. In this case, you need to load some components individually and create an app-specific paint-settings file (which will act as your theme file):

/// Paint Core
@import '/bower_components/paint/styles/core';

/// Application-specific Resets
@import 'paint-settings';

/// Import Paint Global Settings
@import '/bower_components/paint/styles/settings';

/// Paint Tools / Helpers
@import '/bower_components/paint/styles/tools';

/// Import Global Components
@import '/bower_components/paint/styles/global';

/// Import all Paint Components
@import '/bower_components/paint/styles/components';

To make any future changes easier, add all of the above in a paint-loader.scss file and import it in your main application stylesheet, before the app-specific dependencies and styles, e.g

/// application.scss
@import 'paint-loader';
@import 'styles';

/// paint-loader.scss
@import '/bower_components/paint/styles/core';
@import 'paint-settings';
@import '/bower_components/paint/styles/settings';
@import '/bower_components/paint/styles/tools';
@import '/bower_components/paint/styles/global';
@import '/bower_components/paint/styles/components';

/// styles.scss
@import 'components/custom-component1';
@import 'components/custom-component2';
...

Structure

Paint is separated into

Core
Settings
Tools
Globals
Components

Core

This contains a set of functions and mixins that are mandatory for the rest of the paint components to work properly. It includes:

- core/dependencies
  normalize-scss
  bourbon
- core/functions
  export
  map
  bound
- core/resets

Settings

This contains variables that are shared between globals, tools and components. Settings use the core functions, that's the reason why we need to load Core before.

Tools

A set of reusable styles that we want to share between the components and throughout the application.

- tools/functions
  color
- tools/mixins
  detached-border
  overlay
  bem
- tools/placeholders
  vertical-align

Global

This contains the most basic set of components.
Each component might have extra package dependencies that are not defined above.

- global/components
  icon
    font-awesome
  button
  grid
    neat (bower) / node-neat (npm)
  typography

Components

A set of components that are pretty common in all applications

- layout
- navigation
- label
- panel
- flip-panel
- side-panel
- tab
- table
- notification
- progress-bar
- form
- quick-jump
- modal
- dropdown
- step

Deprecation warning
Most of these components are going to be extracted into separate repos and refactored to make it easier to customise and more flexible to extend.

How to use Paint

[upcoming]

Customising Component Settings

[upcoming]

Usage Guidelines

Most coding style issues are taken care of automatically by the linter. There are though some things that are difficult to implement/not yet implemented in the linter and you should check manually.

[upcoming]

Contributing

We use git flow to manage feature/hotfixes/releases. The easiest setup is to clone the repository, then run:

cd paint
git branch master origin/master
git flow init -d
git flow feature start <your initials>/<feature name>

Then, do the work and commit your changes.

git flow feature publish <your initials>/<feature name>

When done, open a pull request for your feature branch. Make sure you branched-off develop not master.

Publishing process (internal)

After the review, merge to develop, then create a new release (vX.xx.xx).
Bump Paint version (bower / npm) bower patch && npm patch.
Npm might return an error, since the tag name might already exist. No worries, all good.
Push changes and tags
Finish the release, adding the release notes to the description:

## Changelog

* Feature
* Feature
...

Run npm publish on master.
Generate Documentation:

npm install -g sassdoc
npm install -g sassdocify
// run the above only the first time you do this

bin/docs

This is going to push documentation to a gh-pages branch that automatically updates http://alphasights.github.io/paint/

If the changes you made affect any ember-cli-paint component you also need to:

Update paint's version in ember-cli-paint index.js and bower.json
Release a new version of ember-cli-paint
- npm version major | minor | patch
- npm publish

Labels

variables

label-default-settings

Since v0.8.27

$label-default-settings: (
  padding: 5px 10px,

  styles: (
    base: color(border),
    primary: color(primary),
    secondary: color(secondary),
    alert: color(alert),
    error: color(alert),
    warning: color(warning),
    success: color(success),
    info: color(info)
  ),

  sizes: (
    tiny: .6,
    small: .8,
    base-size: 1,
    large: 1.2
  )
);

Description

Default settings

Example

span.default-label {
  @extend %label-base;
}

span.primary-tiny {
  @extend %label-primary;
  @extend %label-tiny;
}

span.info-base {
  @extend %label-info;
  @extend %label-base-size;
}

h1 > span.label {
  @extend %label-base;
  @extend %label-large;
}

mixins

[private] label-style

Since v0.8.27

@mixin label-style() { ... }

Description

Generates background color and text color

Parameters

None.

Used by

[mixin] label-placeholders

[private] label-size

Since v0.8.27

@mixin label-size() { ... }

Description

Generates font size from label settings

Parameters

None.

Used by

[mixin] label-placeholders

[private] label-placeholders

Since v0.8.27

@mixin label-placeholders() { ... }

Description

Generates label style and size placeholders

Parameters

None.

Requires

[mixin] label-style
[mixin] label-size
[placeholder] label

placeholders

[private] label

Since v0.8.27

%label { ... }

Description

Basic label styles

Used by

[mixin] label-placeholders

label-ellipsis

Since v0.8.27

%label-ellipsis { ... }

Description

Label modifier - ellipsis. Extend to enable text-ellipsis when having long text items

Layout

variables

layout-default-settings

Since v0.8.29

$layout-default-settings: (
  selectors: (
    main: '.application',
    content-wrapper: 'main',
    content: '> .content'
  )
);

Description

Default settings

layout

Since v0.8.29

$layout: () !default;

Description

Global application layout styles

Example

Usage

<body>
  <div class="application">
    <div class="main-navigation">
       // ...
    </div>

    <main>
      <div class="content">
        //...
      </div>
    </main>
  </div>
</body>

variables

mixins

[private] modal-size

Since v0.8.5

@mixin modal-size($size: large, $use-content-size: false) { ... }

Description

Calculate the size of the modal based on the screen size

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$size`	Screen size	`Value`	`large`
`$use-content-size`	Set to `true` to resize based on the modal content	`Boolean`	`false`

Used by

[mixin] modal-panel

[private] modal-panel

Since v0.8.5

@mixin modal-panel($use-content-size: false) { ... }

Description

Modal panel styles, including responsive media queries

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$use-content-size`	Set to `true` to resize based on the modal content	`Boolean`	`false`

Requires

[mixin] panel-background
[mixin] modal-close-button
[mixin] modal-size

Used by

[mixin] modal

modal

Since v0.8.5

@mixin modal($use-content-size: false) { ... }

Description

Modal Component

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$use-content-size`	Set to `true` to resize based on the modal content	`Boolean`	`false`

Example

Usage

.custom-modal {
  @include modal;
}

<div class="modal [active]">
  <div>
    <header>
      <h1>Modal Title</h1>
      <button class="close"></button>
    </header>

    <div class="content">
      //..
    </div>
  </div>
</div>

Requires

[mixin] modal-panel

variables

navigation-default-settings

Since v0.8.34

$navigation-default-settings: (
  height: 60px,
  height-negative: -60px,
  logo-width: 28px,
  icon-class-selector: '[class^="icon-"]',
  selector: '.main-navigation',
  z-index: 100,

  topbar: (
    background-color: color(white),
    hover-background-color: color(black),
    hover-color: color(border, light),
    border-color: color(border),
    text-color: #191c1f,
    text-hover-color: #191c1f
  ),

  sidebar: (
    selector: '.sidebar',
    background-color: #191c1f,
    hover-color: lighten(#191c1f, 10%),
    active-color: lighten(#191c1f, 5%),
    text-color: #a5a5a5,
    submenu-text-color: darken(#a5a5a5, 20%),
    min-width: 60px,
    width: 280px,
    transition-duration: .3s,
    delay-in: .175s,
    delay-out: 0s,
    subnav-delay-in: .175s,
    subnav-delay-out: 0s
  ),

  sidebar-footer: (
    included: false,
    actions-selector: '.actions',
    avatar-selector: '.avatar',
    title-selector: '.title'
  )
);

Example

Topbar and Sidebar Navigation Example

<div class="application with-topbar with-sidebar">
  <div class="main-navigation with-topbar">
    <div class="item with-sidebar">
      <a class="logo"><span>Paint</span></a>

      <input id="sidebar-toggler" class="sidebar-toggler" type="checkbox" />
      <label for="sidebar-toggler"></label>

      <nav class="sidebar part-open">
        <header>
          <a class="logo"><span>Paint</span></a>
        </header>

        <div class="scroller">
          <ul class="menu">
            <li>
              <a href="#" class="icon-dashboard">Menu Item</a>
              <ul class="submenu">
                <li><a href="#" class="icon-dashboard">Submenu</a></li>
              </ul>
            </li>
          </ul>
        </div>
      </nav>
    </div> <!-- .item -->

    <div class="item"><a class="icon-cog" href="#"><span>Top Item</span></a></div>
  </div> <!-- .main-navigation -->
  <main>
    <div class="content">
    </div>
  </main>
</div> <!-- .application -->

Sidebar-only Navigation Example

<div class="application with-sidebar">
  <div class="main-navigation">
    <div class="item with-sidebar">
      <a class="logo"><span>Paint</span></a>

      <input id="sidebar-toggler" class="sidebar-toggler" type="checkbox" />
      <label for="sidebar-toggler"></label>

      <nav class="sidebar part-open">
        <header>
          <a class="logo"><span>Paint</span></a>
        </header>

        <div class="scroller">
          <ul class="menu">
            <li>
              <a href="#" class="icon-dashboard">Menu Item</a>
              <ul class="submenu">
                <li><a href="#" class="icon-dashboard">Submenu</a></li>
              </ul>
            </li>
          </ul>
        </div>
      </nav>
    </div> <!-- .item -->
  </div> <!-- .main-navigation -->
  <main>
    <div class="content">
    </div>
  </main>
</div> <!-- .application -->

Topbar-only Navigation Example

<div class="application with-topbar">
  <div class="main-navigation with-topbar">
    <div class="item">
      <a class="logo"><span>Paint</span></a>
    </div>
    <div class="item"><a class="icon-cog" href="#"><span>Top Item</span></a></div>
    <div class="item"><a class="icon-cog" href="#"><span>Top Item</span></a></div>
    <div class="item"><a class="icon-cog" href="#"><span>Top Item</span></a></div>
  </div> <!-- .main-navigation -->
  <main>
    <div class="content">
    </div>
  </main>
</div> <!-- .application -->

Sidebar With Footer Example

<div class="application with-sidebar">
  <div class="main-navigation">
    <div class="item with-sidebar">
      <a class="logo"><span>Paint</span></a>

      <input id="sidebar-toggler" class="sidebar-toggler" type="checkbox" />
      <label for="sidebar-toggler"></label>

      <nav class="sidebar part-open">
        <header>
          <a class="logo"><span>Paint</span></a>
        </header>

        <div class="scroller">
          ...
        </div>

        <footer>
          <div class="actions">
            <button class="settings"></button>
          </div>

          <div class="avatar">
            <img src="" />
          </div>

          <div class="title">Footer Title Text</div>
        </footer>
      </nav>
    </div> <!-- .item -->
  </div> <!-- .main-navigation -->
  <main>
    <div class="content">
    </div>
  </main>
</div> <!-- .application -->

Example of delayed transition settings

$navigation: (
  sidebar: (
    delay-in: .475s,
    delay-out: .8s,
    subnav-delay-in: .8s,
    subnav-delay-out: .4s
  )
);

[private] sidebar-part-open

Since v0.8.34

$sidebar-part-open: '.part-open';

Description

Use custom classes for the partially open sidebar and fully open one. By default the sidebar opens fully on hover

mixins

[private] navigation-logo

Since v0.8.34

@mixin navigation-logo($hover-background-color: topbar hover-background-color) { ... }

Description

Logo properties

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$hover-background-color`	The logo hover color - useful for when the topbar logo is different than the sidebar one	`Value`	`topbar hover-background-color`

Requires

[mixin] navigation-header-title

Panels

variables

flip-panel-default-settings

Since v0.8.43

$flip-panel-default-settings: (
  header-height: panel-settings(header-height),
  footer-height: panel-settings(footer-height),
  icons: (
    back: long-arrow-left,
    forward: long-arrow-right
  ),
  transition-settings: .3s ease-in-out
);

Example

Usage

.flip-panel {
  @include flip-panel;
}

Default Markup

<div class="flip-panel [flipped]">
  <div class="front">
    <header>
      <h1>Flip Panel Front</h1>
    </header>

    <div class="content">
      <section>
        Flip panel front section content
      </section>
    </div>

    <footer>
      <span><a>More information</a></span>
    </footer>
  </div> <!-- .front -->

  <div class="back">
    <header>
      <h1><a><i class="back-icon"></i> Back to Front</a></h1>
    </header>

    <div class="content">
      <section>
        <p>Flip panel back content</p>
      </section>
    </div>
  </div> <!-- .back -->
</div>

Custom panel style and back face with footer

Pass option `$with-footer: true` to `flip-panel`. It is advised to specify a min-height for the panel as well.

Usage

.custom-flip-panel {
  @include flip-panel(primary, $with-back-footer: true, $min-height: 400px);
}

Animation

Toggle class `.flipped` on the main selector to trigger the flipping animation

panel-default-settings

Since v0.8.43

$panel-default-settings: (
  header-height: $h1-font-size + $column-gutter,
  footer-height: $h1-font-size + $column-gutter / 2,
  styles: (
    default: color(border, light),
    primary: color(primary),
    link: color(link),
    success: color(success),
    warning: color(warning),
    alert: color(alert),
    info: color(info, light)
  ),
);

Example

Usage

.custom-panel-widget {
  @extend %panel-widget;
}

Custom Panel Styles

// paint-settings.scss
$panel: (
  styles: (
    success: color(success, dark),
    info: color(info)
  )
);

// Custom stylesheet
.fancy-green-panel {
  @extend %panel-success;
}

mixins

[private] flip-panel-icons

Since v0.8.43

@mixin flip-panel-icons() { ... }

Description

Generate icons used for the panel header

Parameters

None.

[private] flip-panel-scroll-content

Since v0.8.43

@mixin flip-panel-scroll-content($with-header: true, $with-footer: false) { ... }

Description

Create the scrollable content block based on the presence of header and footer

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$with-header`	Specify if the panel has a header	`Boolean`	`true`
`$with-footer`	Specify if the panel has a footer	`Boolean`	`false`

Used by

[mixin] flip-panel

flip-panel

Since v0.8.43

@mixin flip-panel($with-front-header: true, $with-front-footer: true, $with-back-header: true, $with-back-footer: false, $min-height: false) { ... }

Description

Mixin that generates the flip-panel styles

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$with-front-header`	Specify if the panel front has a header	`Boolean`	`true`
`$with-front-footer`	Specify if the panel front has a footer	`Boolean`	`true`
`$with-back-header`	Specify if the panel back has a header	`Boolean`	`true`
`$with-back-footer`	Specify if the panel back has a footer	`Boolean`	`false`
`$min-height`	Specify a fixed height for the panel	`Value`	`false`

[private] panel-background

Since v0.8.43

@mixin panel-background($background-color: color(border, light)) { ... }

Description

Panel header background

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$background-color`	Sets the panel header background to a gradient and sets the text color dynamically based on the color brightness.	`Color`	`color(border, light)`

Used by

[mixin] modal-panel
[mixin] flip-panel
[mixin] panel-placeholders

[private] panel-placeholders

Since v0.8.43

@mixin panel-placeholders($styles: panel-settings(styles)) { ... }

Description

Generates all panel variation placeholders defined in the settings

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$styles`	The style variations map	`Map`	`panel-settings(styles)`

Requires

[mixin] panel-background
[placeholder] panel

placeholders

panel

Since v0.8.43

%panel { ... }

Description

The placeholder that holds the base panel styles

Used by

[mixin] panel-placeholders

Progress Bars

variables

progress-bar-default-settings

Since v0.8.34

$progress-bar-default-settings: (
  background-color: color(border, light),
  border: 0,
  border-radius: $global-radius / 2,
  padding: 0,
  meter: (
    selector: '> div'
  ),

  styles: (
    base: color(success, light),
    primary: color(primary),
    secondary: color(secondary),
    alert: color(alert),
    error: color(alert),
    warning: color(warning),
    success: color(success),
    info: color(info)
  ),

  sizes: (
    small: 1px,
    base-size: 3px,
    large: 10px
  )
);

Description

Default settings, styles and sizes

Example

Basic usage

// Default classes
.progress-bar {
  @extend %progress-bar-base;
}

// Custom usage
.project-progress-bar {
  @extend %progress-bar-[base, primary, secondary, alert ...] ;
  @extend %progress-bar-[small, base-size, large];
}

Basic markup

<div class="project-progress-bar">
  <div style="width: 30%"></div>
</div>

mixins

[private] progress-bar-style

Since v0.8.34

@mixin progress-bar-style() { ... }

Description

Generates background color

Parameters

None.

Used by

[mixin] progress-bar-placeholders

[private] progress-bar-height

Since v0.8.34

@mixin progress-bar-height() { ... }

Description

Generates bar height from settings

Parameters

None.

Used by

[mixin] progress-bar-placeholders

[private] progress-bar-placeholders

Since v0.8.34

@mixin progress-bar-placeholders() { ... }

Description

Generates progress-bar style and size placeholders

Parameters

None.

Requires

[mixin] progress-bar-height
[mixin] progress-bar-style

Steps

variables

step-default-settings

Since v0.8.33

$step-default-settings: (
  height: $button-small-height,

  colors: (
    inactive-background: color(border, light),
    inactive-border: color(border),
    inactive-count: color(border),
    highlighted-background: color(info, light),
    highlighted-border: color(gray),
    highlighted-count: color(gray),
    active-background: color(primary, light),
    active-border: color(primary),
    active-count: color(primary, dark),
  ),

  selectors: (
    highlighted: '.highlighted',
    active: '.active'
  )
);

Example

Steps with border and icons

<ol class="steps with-border with-icons">
  <li><a>First Step</a></li>
  <li class="highlighted"><a>Second Step</a></li>
  <li class="active"><span>Current</span></li>
  <li><span>Inactive</span></li>
  <li><span>Inactive</span></li>
  <li><span>Inactive</span></li>
</ol>

Steps with border and counts

<ol class="steps with-border with-counts">
  <li class="highlighted with-pre"><span>10</span><a>First Item</a></li>
  <li class="highlighted with-pre"><span>8</span><a>Second Item</a></li>
  <li class="active"><span>Current</span></li>
  <li class="with-post"><span>Inactive Item</span><span>0</span></li>
  <li class="with-post"><span>Inactive Item</span><span>0</span></li>
  <li><span>Inactive</span></li>
</ol>

Custom steps

.basic-breadbrumb,
.border-steps,
.icon-steps {
  @extend %steps;
}

.icon-steps {
  @extend %steps-with-icons;
}

.border-steps {
  @extend %steps-with-border;
}

placeholders

steps

Since v0.8.33

%steps { ... }

Description

Default steps placeholder, acts like a breadcrumb

Used by

[placeholder] steps-with-icons
[placeholder] steps-with-border
[placeholder] steps-with-counts

steps-with-icons

Since v0.8.33

%steps-with-icons { ... }

Description

Steps extention placeholder, allows use of icons

Requires

[placeholder] steps

steps-with-border

Since v0.8.33

%steps-with-border { ... }

Description

Steps extention placeholder, adds a border around elements

Requires

[placeholder] steps

Used by

[placeholder] steps-with-counts

steps-with-counts

Since v0.8.33

%steps-with-counts { ... }

Description

Steps extention placeholder, allows adding pre or post content

Requires

[placeholder] steps
[placeholder] steps-with-border

Tabs

variables

tab-default-settings

Since v0.8.18

$tab-default-settings: (
  active-class: '.active',
  active-tab-selector: a,
  background-color: color(white),
  border-color: color(border),
  border-color-active: color(link),
  border-height: 3px,
  height: 60px,
  text-color: color(text, small),
  text-color-active: color(text),
  text-size: $h4-font-size,
  padding: 0 $column-gutter / 2,
  margin: 0 $column-gutter / 2,
  transition-duration: $global-transition-duration / 2
);

Example

Usage

.my-tabs {
  @include tabs;
}

Default Markup

<section class="tabs">
  <nav>
    <ul>
      <li><a>First Tab</a></li>
      <li><a class="active">Second Tab</a></li>
      <li><a>Third Tab</a></li>
    </ul>
  </nav>

  <div class="content">
    ...
  </div>
</section>

mixins

tabs

Since v0.8.18

@mixin tabs() { ... }

Description

Main tabs mixin, to be applied to the tabs wrapper

Parameters

None.

Requires

[mixin] tabs-nav

[private] tabs-nav

Since v0.8.18

@mixin tabs-nav() { ... }

Description

Tab Nav Group

Parameters

None.

Requires

[mixin] tab-item

Used by

[mixin] tabs

[private] tab-item

Since v0.8.18

@mixin tab-item($active-selector: a) { ... }

Description

Tab Nav Item

Parameters

parameterName	parameterDescription	parameterType	parameterDefault value
`$active-selector`	Sets the active state selector, can be `a` or `li`	`Value`	`a`

Used by

[mixin] tabs-nav

placeholders

tabs

Since 0.9.15

%tabs { ... }

Description

Tabs placeholders

Example

BEM Structure

%tabs
  %tabs__nav

%tabs-nav
  %tabs-nav__item
    %tabs-nav__link

%tabs-nav--fluid-widths
%tabs-nav--fluid-widths__item

Usage

@include bem-block('custom-tabs') {
  @extend %tabs;

  @include bem-element('nav') {
    @extend %tabs__nav;
  }
}

@include bem-block('custom-tabs-nav') {
  @extend %tabs-nav;
  // @extend %tabs-nav--fluid-widths; // optional

  @include bem-element('item') {
    @extend %tabs-nav__item;
    // @extend %tabs-nav--fluid-widths__item; // optional
  }

  @include bem-element('link') {
    @extend %tabs-nav__link;
  }
}

Usage

<div class="newtabs">
  <nav class="custom-tabs__nav">
    <ul class="custom-tabs-nav">
      <li class="custom-tabs-nav__item"><a class="custom-tabs-nav__link" href="#">Item</a></li>
      <li class="custom-tabs-nav__item"><a class="custom-tabs-nav__link active" href="#">Item</a></li>
      <li class="custom-tabs-nav__item"><a class="custom-tabs-nav__link" href="#">Item</a></li>
    </ul>
  </nav>
</div>

tabs-nav

Since v0.8.18

%tabs-nav { ... }

Description

Block: tabs-nav Elements: item, link Modifiers: fluid-widths - affects item

Paint

Setup

Structure

Core

Settings

Tools

Global

Components

How to use Paint

Customising Component Settings

Usage Guidelines

Contributing

Publishing process (internal)

Dropdowns

variables

Description

Labels

variables

Description

Example

mixins

[private] label-style

Description

Parameters

Used by

[private] label-size

Description

Parameters

Used by

[private] label-placeholders

Description

Parameters

Requires

placeholders

[private] label

Description

Used by

Description

Layout

variables

Description

Description

Example

Modals

variables

Description

mixins

[private] modal-size

Description

Parameters

Used by

Description

Parameters

Used by

[private] modal-panel

Description

Parameters

Requires

Used by

Description

Parameters

Example

Requires

Navigation

variables

Example

[private] sidebar-part-open

Description

mixins

[private] navigation-header-title

Description

Parameters

Used by

[private] navigation-logo

Description

Parameters

Requires

[private] navigation-item-icon

Description

Parameters