CSS Styleguide

!! IN PROGRESS !!

Standards

• TODO: separate each bullet point into its own section

• 2 spaces per indent. No tabs.
• Avoid shorthand properties
  • background: lime; isn't the same as background-color: lime;
• CSS imports before all other content in stylesheet (including banner comments)
• Always quote URLs and attribute values.
• Use double-quote (matches HTML)
• No unit for 0 values.
• one selector per line
• one property per line
  • never on same line as a selector
• open block on same line as last selector
• close block on line after last property in block
• one space after colon. no space before.
• one space after comma. no space before.
• alphabetize property names

Custom Properties

(a.k.a. CSS Variables) Not all browser support custom properties, so you'll need to make sure you have a fallback property for legacy browsers.

IE	Edge	Chrome	Safari	Firefox	Opera
n/a	15+	49+	9.1+	31+	36+

.hxFoobar {
  /* legacy browsers */
  background-color: gray;
  /* modern browsers - overrides above, legacy browsers ignore it */
  background-color: var(--background-color, gray);
}

Modified ITCSS

draft

The design of this structure is to allow for CSS specificity to gradually increase as you read the CSS from top to bottom.

1. Configuration

• CSS Imports
  • Must be at the very top of the file to work properly across browsers.
• Global Variables (LESS or CSS variables)
  • Color Palette
  • Fonts
  • Spacing
  • etc.

example:

/* LESS Variables */
@border-radius: 2px;
@font-size: 16px;
@red-900: #d32f2f;
/* ... */

/* CSS Variables */
:root {
  --red-900: @red-900; // Generated CSS: "--red-900: #d32f2f;"
  /* ... */
}

2. Mixins

Declared immediately after variables to provide quick creation of CSS styles.

example:

.rounded-top() {
  border-top-left-radius: @border-radius;
  border-top-right-radius: @border-radius;
}

3. Resets

Levels the playing field across browsers.

example:

html {
  box-sizing: border-box;
}
*,
*::before,
*::after {
  box-sizing: inherit;
}

4. Base

CSS to define basic appearance of unclassified elements to come.

• Element Selectors ONLY
• No Class Selectors

example:

html {
  font-family: 'Roboto', sans-serif;
  font-size: @font-size;
}

5. Components

Though much of the styling for many custom elements will be embedded into their individual ShadowDOM, LightDOM styling may still be necessary.

Components that will not be made into custom elements will still have CSS defined using the BEM naming convention in this layer.

• Class Selectors ONLY
• NO Element Selectors

6. Helpers

CSS classes to aid consumers in building their site.

• Class Selectors ONLY
• NO Element Selectors

example:

.text-left { text-align: left; }
.text-right { text-align: right; }
.text-center { text-align: center; }

7. Overrides

There will be times where we'll need to use !important (though it should be extremely limited). This layer is where you'd add such styling.

• This is the ONLY level where !important should be seen.

Theming API

draft

ProMo

• Property
  • --borderColor
• Modifier
  • --borderColor--hover

Guidelines

• Use lowerCamelCase of CSS property name
  • backgroundColor not background-color
• Use Modifier for different states
  • Omit for default state
  • --backgroundColor--hover, --backgroundColor--focus, --backgroundColor--active

:root {
  --backgroundColor: black;
  --backgroundColor--hover: blue;
  --backgroundColor--active: navy;
  --backgroundColor--active-focus: cyan;
}

OTHER

• Mobile First Media Queries

DO

hx-custom-element { 
  // No other way around this. This is vanilla CSS. ^_^
}

.hxModifier { 
  /* 
    All CSS classes should act as modifiers to their applied element. 
    If you need something to differentiate a modifier from a block, 
    chances are you need to create a custom element.
  */ 
}

DON'T

.hx-block-element { 
  // Too similar to kebab-case-element selector
}

.hxBlockElement { 
  // You likely need a custom element.
}

.hxBlockElement--modifierClass { 
  /* 
    Class is too verbose, bloats HTML 
  */
}