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
+input { padding: 10px 0 }). It will make more difficult edit styles for the future custom elements and the !important use will grow..marginRight { margin-right: 10px } ). It is impossible to manage the amount of cases we would like to cover.Table of contents
+ +Syntax: <ComponentName>[--modifierName|-descendentName]
The component's name must be written in camel case.
+ +.MyComponent { /* … */ }<article class="MyComponent">
+ …
+</article>A component modifier is a class that modifies the presentation of the base component in some form.
+ +/* Core button */
+.Btn { /* … */ }
+
+/* Default button style */
+.Btn--default { /* … */ }<article class="Btn Btn--default">
+ …
+</article><article class="Tweet">
+ <header class="Tweet-header">
+ <img class="Tweet-avatar" src="{{src}}" alt="{{alt}}">
+ …
+ </header>
+ <div class="Tweet-bodyText">
+ …
+ </div>
+</article>Use is-stateName to reflect changes to a component's state.
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, ...
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.
+ +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";
+
+.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 {}
+Syntax: $c<colorName>
// 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 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 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;
+From: https://gist.github.com/fat/a47b882eb5f84293c4ed
+ +The following are some high level page formatting style rules.
+ + + +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.
+ + + +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 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;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);.u- prefixed class name for single purpose utility classes like .u-underline, .u-capitalize, etc. (not sure about this one)mixins.css.scssfile. "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"
+ ]
+ }
+