{{> theme}} {{> highlight}} {{> jquery}}

Basics

Important notes about this styleguide

This is a preliminar WIP of the new dashboard stylesheet, based on the naming conventions of suitcss and Medium’s CSS is actually pretty good.

General rules

  • All new elements added in this repository should have included a 'CDB-' namespace.
  • Don't create default styles for common elements (e.g. input { padding: 10px 0 }). It will make more difficult edit styles for the future custom elements and the !important use will grow.
  • Avoid creating new classes with only one attribute (e.g. .marginRight { margin-right: 10px } ). It is impossible to manage the amount of cases we would like to cover.

Table of contents

Components

Syntax: <ComponentName>[--modifierName|-descendentName]

ComponentName

The component's name must be written in camel case.

.MyComponent { /* … */ }
<article class="MyComponent">
  …
</article>

ComponentName--modifierName

A component modifier is a class that modifies the presentation of the base component in some form.

  1. Modifier names must be written in camel case and be separated from the component name by two hyphens.
  2. The class should be included in the HTML in addition to the base component class.
/* Core button */
.Btn { /* … */ }

/* Default button style */
.Btn--default { /* … */ }
<article class="Btn Btn--default">
  …
</article>

ComponentName-descendentName

  1. A component descendent is a class that is attached to a descendent node of a component.
  2. It's responsible for applying presentation directly to the descendent on behalf of a particular component.
  3. Descendent names must be written in camel case.
<article class="Tweet">
  <header class="Tweet-header">
    <img class="Tweet-avatar" src="{{src}}" alt="{{alt}}">
    …
  </header>
  <div class="Tweet-bodyText">
    …
  </div>
</article>

ComponentName.is-stateOfComponent

Use is-stateName to reflect changes to a component's state.

  1. The state name must be camel case.
  2. Never style these classes directly: they should always be used as an adjoining class.

This means that the same state names can be used in multiple contexts, but every component must define its own styles for the state (as they are scoped to the component).

Right:

.Tweet { /* … */ }
.Tweet.is-expanded { /* … */ }

<article class="Tweet is-expanded">
  …
</article>

Wrong:

.Tweet { /* … */ }
.Tweet.expanded { /* … */ }
<article class="Tweet expanded">
  …
</article>

We should always rely on the same terminology to express state of a component: i.e.: a common term for is-active, is-expanded, is-selected, is-highlighted, ...

JavaScript

Syntax: js-<targetName>

JavaScript-specific classes reduce the risk that changing the structure or theme of components will inadvertently affect any required JavaScript behaviour and complex functionality. It is not neccesarry to use them in every case, just think of them as a tool in your utility belt. If you are creating a class, which you dont intend to use for styling, but instead only as a selector in JavaScript, you should probably be adding the js- prefix. In practice this looks like this:

<a href="/login" class="Btn Btn-primary js-login"></a>

JavaScript-specific classes should not, under any circumstances, be styled.

A word on (Pre)compilers

Since we use Rails as a backend, we make use of Sprockets to make all the dirty work with stylesheets (and javascripts). Many of the stylesheets are constructed by simply writing require_directory —this is awesome, but it also kind of sucks.

Preferably we should use @import instead of require when possible. http://pivotallabs.com/structure-your-sass-files-with-import/

When using require we should list the required files in the order they must be applied, as an added control to avoid undesired behaviours.

Bad:

/*
*= require dashboard/header
*= require dashboard/table
*/

Worse:

/*
*= require_tree dashboard
*/

Good:

@import "dashboard/header";
@import "dashboard/tables";

Better:

@import
"dashboard/header",
"dashboard/tables";

Structure sample


.Btn {}

  .Btn--m {}

  .Btn--highlight {}

  .Btn--green {}

  .Btn.is-active {}

.Menu {}

  .Menu-item {}

  .Menu-link {}

.Header {}

  .Navbar {}

    .Navbar-header {}

      .Navbar-brand {}

      .Navbar-searchField {}

      .Navbar-searchButton {}

    .Navbar-menu {}

      .Navbar-menuItem {}

      .Navbar-menuLink {}

.Dashboard {}

  .Dashboard-header {}

    .Dashboard-avatar {}

    .Dashboard-title {}

    .Dashboard-menu {}

  .Dashboard-subHeader {}

    .Dashboard-subMenu {}

      .Dashboard-subMenuItem {}

      .Dashboard-subMenuLink {}


.Block {}

  .Block-thumbnail {}

  .Block-title {}

  .Block-description {}

  .Block-tags {}

  .Block-status {}

  .Block-footer {}

Colors

colors.scss

Syntax: $c<colorName>

Sample

// Colors
// --------------------------------------------------
// Paragraphs
$cTypography-headers:           rgba(#333, 1);
$cTypography-paragraphs:        rgba(#666, 1);
$cTypography-secondary:         rgba(#999, 1);
$cTypography-help:              rgba(#CCC, 1);
$cTypography-headersOverBlack:  rgba(#FFF, 1);
$cTypography-link:              rgba(#0090D7, 1);
$cTypography-linkHover:         rgba(#62B4E3, 1);
$cTypography-linkSelected:      rgba(#333, 1);

// Structure
$cStructure-mainBkg:  rgba(#FFF, 1);
$cStructure-mainLine: rgba(#DDD, 1);
$cStructure-grayBkg:  rgba(#F9F9F9, 1);
$cStructure-softLine: rgba(#EEE, 1);

// Highlight
$cHighlight-main:     rgba(#0090D7, 1);
$cHighlight-positive: rgba(#8FB83F, 1);
$cHighlight-negative: rgba(#C74B43, 1);
$cHighlight-alert:    rgba(#C67B44, 1);

Don't use named colors, try to use meaningful names.

Z-Index

z-index.scss

// Z-Index Scale (private vars)
// --------------------------------------------------
@zIndex-1:   100;
@zIndex-2:   200;
@zIndex-3:   300;
@zIndex-4:   400;
@zIndex-5:   500;
@zIndex-6:   600;
@zIndex-7:   700;
@zIndex-8:   800;
@zIndex-9:   900;
@zIndex-10: 1000;

z-index file use

// Z-Index Applications
// --------------------------------------------------
@zIndex-1--screenForeground:        @zIndex-1;
@zIndex-1--followUpVisibility:      @zIndex-1;
@zIndex-1--prlWelcome:              @zIndex-1;
@zIndex-1--appImageDropdown:        @zIndex-1;
@zIndex-1--surfaceUnder:            @zIndex-1;
@zIndex-1--blockGroup:              @zIndex-1;

(…)

@zIndex-9--zoomOverlayTarget:       @zIndex-9;
@zIndex-9--navOverlayTouch:         @zIndex-9;
@zIndex-9--overlay:                 @zIndex-9;
@zIndex-9--dialog:                  @zIndex-9;
@zIndex-9--tooltip:                 @zIndex-9;

Formatting

From: https://gist.github.com/fat/a47b882eb5f84293c4ed

The following are some high level page formatting style rules.

Property: value

There should be a blank space between a property and a value:

Right:

.content-edit { background: red }

Wrong:

.content-edit {background:red}

If you have to define an only one property, leave blank spaces between brackets.

Spacing

CSS rules should be comma seperated but live on new lines:

Right:

.content,
.content-edit {
  …
}

Wrong:

.content, .content-edit {
  …
}

CSS blocks should be seperated by a single new line. not two. not 0.

Right:

.content {
  …
}
.content-edit {
  …
}

Wrong:

.content {
  …
}

.content-edit {
  …
}

Quotes

Quotes are optional in CSS and LESS. We use double quotes as it is visually clearer that the string is not a selector or a style property.

Right:

background-image: url("/img/you.jpg");
font-family: "Helvetica Neue Light", "Helvetica Neue", Helvetica, Arial;

Wrong:

background-image: url(/img/you.jpg);
font-family: Helvetica Neue Light, Helvetica Neue, Helvetica, Arial;

Colors

When implementing feature styles, you should only be using color variables provided by colors.css.scss.

When adding a color variable to colors.css.scss, using RGB and RGBA color units are preferred over hex, named, HSL, or HSLA values.

Right:

rgb(50, 50, 50);
rgba(50, 50, 50, 0.2);

Wrong:

#FFF;
#FFFFFF;
white;
hsl(120, 100%, 50%);
hsla(120, 100%, 50%, 1);

Things to add to the guide

  1. Define a type scale (variables for font-sizes, weights, letter-spacing, line-heights, etc.).
  2. .u- prefixed class name for single purpose utility classes like .u-underline, .u-capitalize, etc. (not sure about this one)
  3. Don't use compass predefined functions, create a mixin in new mixins.css.scssfile.
  4. No more clearfix or layout hacks, use flexbox:

CSSComb config

   "config": {

        // Whether to add a semicolon after the last value/mixin.
        "always-semicolon": true,

        // Set indent for code inside blocks, including media queries and nested rules.
        "block-indent": "  ",

        // Unify case of hexadecimal colors.
        "color-case": "lower",

        // Whether to expand hexadecimal colors or use shorthands.
        "color-shorthand": true,

        // Unify case of element selectors.
        "element-case": "lower",

        // Add/remove line break at EOF.
        "eof-newline": true,

        // Add/remove leading zero in dimensions.
        "leading-zero": false,

        // Unify quotes style.
        "quotes": "single",

        // Remove all rulesets that contain nothing but spaces.
        "remove-empty-rulesets": true,

        // Set space after `:` in declarations.
        "space-after-colon": " ",

        // Set space after combinator (for example, in selectors like `p > a`).
        "space-after-combinator": " ",

        // Set space after `{`.
        "space-after-opening-brace": "\n",

        // Set space after selector delimiter.
        "space-after-selector-delimiter": "\n",

        // Set space before `}`.
        "space-before-closing-brace": "\n",

        // Set space before `:` in declarations.
        "space-before-colon": "",

        // Set space before combinator (for example, in selectors like `p > a`).
        "space-before-combinator": " ",

        // Set space before `{`.
        "space-before-opening-brace": " ",

        // Set space before selector delimiter.
        "space-before-selector-delimiter": "",

        // Set space between declarations (i.e. `color: tomato`).
        "space-between-declarations": "\n",

        // Whether to trim trailing spaces.
        "strip-spaces": true,

        // Whether to remove units in zero-valued dimensions.
        "unitless-zero": true,

        // Whether to align prefixes in properties and values.
        "vendor-prefix-align": true,

        // Sort properties in particular order.
        "sort-order": [
            "position",
            "top",
            "right",
            "bottom",
            "left",
            "z-index",
            "display",
            "float",
            "width",
            "min-width",
            "max-width",
            "height",
            "min-height",
            "max-height",
            "-webkit-box-sizing",
            "-moz-box-sizing",
            "box-sizing",
            "-webkit-appearance",
            "-moz-appearance",
            "appearance",
            "padding",
            "padding-top",
            "padding-right",
            "padding-bottom",
            "padding-left",
            "margin",
            "margin-top",
            "margin-right",
            "margin-bottom",
            "margin-left",
            "overflow",
            "overflow-x",
            "overflow-y",
            "-webkit-overflow-scrolling",
            "-ms-overflow-x",
            "-ms-overflow-y",
            "-ms-overflow-style",
            "clip",
            "clear",
            "src",
            "font",
            "font-family",
            "font-size",
            "font-weight",
            "font-style",
            "font-variant",
            "font-size-adjust",
            "font-stretch",
            "font-effect",
            "font-emphasize",
            "font-emphasize-position",
            "font-emphasize-style",
            "font-smooth",
            "-webkit-hyphens",
            "-moz-hyphens",
            "hyphens",
            "line-height",
            "color",
            "text-align",
            "-webkit-text-align-last",
            "-moz-text-align-last",
            "-ms-text-align-last",
            "text-align-last",
            "text-emphasis",
            "text-emphasis-color",
            "text-emphasis-style",
            "text-emphasis-position",
            "text-decoration",
            "text-underline-position",
            "-webkit-text-decoration-style",
            "-moz-text-decoration-style",
            "text-decoration-style",
            "-moz-text-decoration-color",
            "text-decoration-color",
            "-moz-text-decoration-line",
            "text-decoration-line",
            "text-indent",
            "-ms-text-justify",
            "text-justify",
            "text-outline",
            "-ms-text-overflow",
            "text-overflow",
            "text-overflow-ellipsis",
            "text-overflow-mode",
            "text-shadow",
            "text-transform",
            "text-wrap",
            "-webkit-text-size-adjust",
            "-moz-text-size-adjust",
            "-ms-text-size-adjust",
            "text-size-adjust",
            "letter-spacing",
            "-ms-word-break",
            "word-break",
            "word-spacing",
            "-ms-word-wrap",
            "word-wrap",
            "-moz-tab-size",
            "-o-tab-size",
            "tab-size",
            "white-space",
            "vertical-align",
            "list-style",
            "list-style-position",
            "list-style-type",
            "list-style-image",
            "pointer-events",
            "-webkit-touch-action",
            "-ms-touch-action",
            "touch-action",
            "cursor",
            "visibility",
            "zoom",
            "flex-direction",
            "flex-order",
            "flex-pack",
            "flex-align",
            "table-layout",
            "empty-cells",
            "caption-side",
            "border-spacing",
            "border-collapse",
            "content",
            "quotes",
            "counter-reset",
            "counter-increment",
            "resize",
            "-webkit-user-select",
            "-moz-user-select",
            "-ms-user-select",
            "user-select",
            "nav-index",
            "nav-up",
            "nav-right",
            "nav-down",
            "nav-left",
            "background",
            "background-color",
            "background-image",
            "-ms-filter:\\'progid:DXImageTransform.Microsoft.gradient",
            "filter:progid:DXImageTransform.Microsoft.gradient",
            "filter:progid:DXImageTransform.Microsoft.AlphaImageLoader",
            "filter",
            "background-repeat",
            "background-attachment",
            "background-position",
            "background-position-x",
            "-ms-background-position-x",
            "background-position-y",
            "-ms-background-position-y",
            "-webkit-background-clip",
            "-moz-background-clip",
            "background-clip",
            "background-origin",
            "-webkit-background-size",
            "-moz-background-size",
            "-o-background-size",
            "background-size",
            "border",
            "border-width",
            "border-style",
            "border-color",
            "border-top",
            "border-top-width",
            "border-top-style",
            "border-top-color",
            "border-right",
            "border-right-width",
            "border-right-style",
            "border-right-color",
            "border-bottom",
            "border-bottom-width",
            "border-bottom-style",
            "border-bottom-color",
            "border-left",
            "border-left-width",
            "border-left-style",
            "border-left-color",
            "-webkit-box-decoration-break",
            "box-decoration-break",
            "-webkit-border-radius",
            "-moz-border-radius",
            "border-radius",
            "-webkit-border-top-left-radius",
            "-moz-border-radius-topleft",
            "border-top-left-radius",
            "-webkit-border-top-right-radius",
            "-moz-border-radius-topright",
            "border-top-right-radius",
            "-webkit-border-bottom-right-radius",
            "-moz-border-radius-bottomright",
            "border-bottom-right-radius",
            "-webkit-border-bottom-left-radius",
            "-moz-border-radius-bottomleft",
            "border-bottom-left-radius",
            "-webkit-border-image",
            "-moz-border-image",
            "-o-border-image",
            "border-image",
            "-webkit-border-image-source",
            "-moz-border-image-source",
            "-o-border-image-source",
            "border-image-source",
            "-webkit-border-image-slice",
            "-moz-border-image-slice",
            "-o-border-image-slice",
            "border-image-slice",
            "-webkit-border-image-width",
            "-moz-border-image-width",
            "-o-border-image-width",
            "border-image-width",
            "-webkit-border-image-outset",
            "-moz-border-image-outset",
            "-o-border-image-outset",
            "border-image-outset",
            "-webkit-border-image-repeat",
            "-moz-border-image-repeat",
            "-o-border-image-repeat",
            "border-image-repeat",
            "outline",
            "outline-width",
            "outline-style",
            "outline-color",
            "outline-offset",
            "-webkit-box-shadow",
            "-moz-box-shadow",
            "box-shadow",
            "filter:progid:DXImageTransform.Microsoft.Alpha(Opacity",
            "-ms-filter:\\'progid:DXImageTransform.Microsoft.Alpha",
            "opacity",
            "-ms-interpolation-mode",
            "-webkit-transition",
            "-moz-transition",
            "-ms-transition",
            "-o-transition",
            "transition",
            "-webkit-transition-delay",
            "-moz-transition-delay",
            "-ms-transition-delay",
            "-o-transition-delay",
            "transition-delay",
            "-webkit-transition-timing-function",
            "-moz-transition-timing-function",
            "-ms-transition-timing-function",
            "-o-transition-timing-function",
            "transition-timing-function",
            "-webkit-transition-duration",
            "-moz-transition-duration",
            "-ms-transition-duration",
            "-o-transition-duration",
            "transition-duration",
            "-webkit-transition-property",
            "-moz-transition-property",
            "-ms-transition-property",
            "-o-transition-property",
            "transition-property",
            "-webkit-transform",
            "-moz-transform",
            "-ms-transform",
            "-o-transform",
            "transform",
            "-webkit-transform-origin",
            "-moz-transform-origin",
            "-ms-transform-origin",
            "-o-transform-origin",
            "transform-origin",
            "-webkit-animation",
            "-moz-animation",
            "-ms-animation",
            "-o-animation",
            "animation",
            "-webkit-animation-name",
            "-moz-animation-name",
            "-ms-animation-name",
            "-o-animation-name",
            "animation-name",
            "-webkit-animation-duration",
            "-moz-animation-duration",
            "-ms-animation-duration",
            "-o-animation-duration",
            "animation-duration",
            "-webkit-animation-play-state",
            "-moz-animation-play-state",
            "-ms-animation-play-state",
            "-o-animation-play-state",
            "animation-play-state",
            "-webkit-animation-timing-function",
            "-moz-animation-timing-function",
            "-ms-animation-timing-function",
            "-o-animation-timing-function",
            "animation-timing-function",
            "-webkit-animation-delay",
            "-moz-animation-delay",
            "-ms-animation-delay",
            "-o-animation-delay",
            "animation-delay",
            "-webkit-animation-iteration-count",
            "-moz-animation-iteration-count",
            "-ms-animation-iteration-count",
            "-o-animation-iteration-count",
            "animation-iteration-count",
            "-webkit-animation-direction",
            "-moz-animation-direction",
            "-ms-animation-direction",
            "-o-animation-direction",
            "animation-direction",
            "-webkit-text-orientation",
            "-moz-text-orientation",
            "-o-text-orientation",
            "text-orientation",
            "-ms-writing-mode",
            "text-rendering",
            "-webkit-font-smoothing",
            "-moz-osx-font-smoothing",
            "font-smoothing",
            "direction",
            "unicode-bidi"
        ]
    }
{{#each sections}}

{{section}}{{#if heading}}/{{heading}}{{/if}}

{{{comment}}}
{{#if code}}
{{{code}}}
{{/if}} {{#if markup}} 
{{{markup}}}
{{/if}}
{{/each}}