Guidelines for writing scalable and maintainable style-sheets
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
images
.gitignore
Changelog.md
Readme.md
package.json

Readme.md

PCSS

ver. 1.2.2

Pragmatic CSS is a collection of guidelines for writing scalable and maintainable style-sheets. PCSS divides the whole UI into portable and reusable components. Every component is described in a separate CSS (SASS/LESS/etc) module. PCSS's naming convention makes it easier to locate a module corresponding to a problem and encourages developer on producing optimized object-oriented CSS.

PCSS is standing on the shoulders of giants. It borrows Base, State and Theme rules from SMACSS, element and subclass (modifier) naming conventions from BEM, the idea of common OOP principles in CSS (inheritance, OCP, SRP) from OOCSS, context-independent cascading from Modular CSS naming conventions

Contents

Component

Class Location
.panel ./component/panel/_index.scss
.nav-bar ./component/nav-bar/_index.scss

Component is a reusable module of UI (e.g. nav-bar, panel, form). Component consists of elements (e.g. form__title) and can be extended by subclasses.

Element

Class Location
.panel__header ./component/panel/_index.scss

Component is built of elements. Elements is an integral parts of a component and cannot be reused outside of component scope.

Subclass

Class Location
.panel--primary ./component/panel/_primary.scss

Following OOP practices, we inherit from a base component to a subclass For example, when we are required of a dialog window, we create ./component/dialog/_index.scss where we put the base styles for any dialogs in the application. Then we add ./component/dialog/_alert.scss where we set the extending styles for the concrete modal window. Now we refer to a concrete component in the HTML like that:

<div class="dialog dialog--alert">..</div>
<div class="dialog dialog--prompt">..</div>

Subclasses and elements

Elements are styled in scopes of subclasses:

.shopping-cart {
// Base styles
}
.shopping-cart--default {
  .shopping-cart__heading {
    color: $color-white;
  }
}
.shopping-cart--inverse {
  .shopping-cart__heading {
    color: $color-block;
  }
}

Here we have an abstract component .shopping-cart extended by .shopping-cart--default and .shopping-cart--inverse where the first has white heading and the second black one.

Component Example

HTML

<div class="progressbar progressbar--big">
	<output class="progressbar__status">
		Install is 70% complete
	</output>
	<progress class="progressbar__progress" value="70" max="100"></progress>
	<div class="progressbar__actions">
		<div class="icon icon--pause">pause</div>
		<div class="icon icon--play is-hidden">resume</div>
	</div>
</div>

./component/progressbar/_index.scss

.progressbar {
  position: relative;
}
.progressbar__progress {
  border: 0;
  position: absolute;
  width: 100%;
  bottom: 0;
  left: 0;
  appearance: none;
  &::-webkit-progress-bar {/*..*/ }
  &::-webkit-progress-value {/*..*/ }
  &::-moz-progress-bar {/*..*/ }
}
.progressbar__status {
  display: flex;
  position: relative;
  font-size: 1rem;
}
.progressbar__actions {
  position: absolute;
  bottom: 0;
  right: 0;
  > .icon { /*..*/ }
}

./component/progressbar/_big.scss

.progressbar--big > .progressbar__status {
  font-size: 1.6rem;
  text-transform: uppercase;
  padding: 16px;
}

./component/progressbar/_small.scss

.progressbar--small > .progressbar__status {
  font-size: 1.1rem;
  text-transform: lowercase;
  padding: 11px;
}

Top

State

States are toggable sets of rules that:

  • describe component/element states: .is-expanded, .is-hidden, .has-error.
  • alternate presentation: .is-uppercase, .is-sticky, .is-pointer.

State CSS classes usually consist of a few rules. Unlike components they do not represent entities, but modify object state.

HTML
<div class="main has-error">
<aside class="sidebar is-hidden">...</aside>
</div>
./component/_main.scss
.main {
  /* default style */
  &.has-error {
    /* state modified style */
  }
}
./base/_global-state.scss
/* Global state */
.is-hidden {
  display: none !important;
}

Top

Theme

Theme classes used to alternate the style of a component depending on the context.

HTML
<html class="theme-foo">
  <div class="l-main">
  <aside class="sidebar">...</aside>
  </div>
</html>
./component/sidebar/_index.scss
.sidebar {
/* default style */
}
.theme-foo .sidebar {
/* alterntive style */
}

Programmatic Theming

If we need components to change styles according to a set theme (.theme-baz and .theme-qux), we can use a mixin like:

@mixin theme-dialog($theme) {
  $bg: get-theme-style($theme, "bg");
  .theme-#{$theme} .dialog {
    background-color: #{$bg};
  }
}
@each $theme in $themes {
  @include theme-dialog($theme);
}

Where we have in ./base/_defenitions.scss:

$themes: baz qux;
@function get-theme-style($theme, $key) {
  $baz-map: (
    "bg": $baz-bg
  );
  $qux-map: (
    "bg": $qux-bg
  );
  @if $theme == "baz" {
    @return map-get( $baz-map, $key );
  }
  @if $theme == "qux" {
    @return map-get( $qux-map, $key );
  }
  @return map-get( $baz-map, $key );
}

Theme Example

<div class="theme-foo">
  <article class="entry">
    <h2 class="entry__heading">Lorem ipsum dolor</h2>
    <time datetime="2008-02-14 20:00" class="entry__time">2 hours ago</time>
  </article>
  <article class="entry">
    <h2 class="entry__heading">Lorem ipsum dolor</h2>
    <time datetime="2008-02-14 20:00" class="entry__time">2 hours ago</time>
  </article>
  <article class="entry">
    <h2 class="entry__heading">Lorem ipsum dolor</h2>
    <time datetime="2008-02-14 20:00" class="entry__time">2 hours ago</time>
  </article>
</div>

<div class="theme-bar>
...
</div>

Top

File Structure

Styles
├───component
│   ├───btn
│   │   _index.scss
│   │   _primary.scss
│   │
│   └───form
│       │   _index.scss
│       │
│       ├───auth
│       │       _index.scss
│       │       _login.scss
│       │
│       └───nav
│               _index.scss
│               _search.scss
│
└───base
    │   _h5b-normalize.scss
    │   _base.scss
    │   _definitions.scss
    │   _global-state.scss
    │   _animations.scss
    │
    └───mixin
            _media.scss


Top

Naming Conventions

  • Class name represents source location. Let's say styles for .form--nav--search is expected in the file component/form/nav/_search.scss File Structure).
  • State classes are prefixed with is- or has- (e.g. .is-hidden, .has-success).
  • Theme classes are prefixed with theme-.
Class Entity
.btn, .main-nav a component (only hyphen delimited names)
.main-nav__title element (subcomponent)
.btn--primary, .main-nav--landing-page subclass
.is-hidden, .has-success a state
.theme-default, .theme-garland a theme
Further readings

Top

Selector Conventions

Keep selectors short

Remember that browser reads selectors from right to left, long selectors may give it an extra workload. Besides it is a unwanted contribution to production style-sheet file size. Deep nesting in CSS-preprocessor sources may cause the described problems even without your awareness. So, keep nesting no more than 3-4 levels.

Avoid excessive @extend-ing in SASS/LESS. It adds a long CSS selectors in a compiled code.

Use classes for styling, IDs and data-attributes to bind JavaScript

IDs can be used in HTML for fragment identifiers and JavaScript hooks, but IDs should never be used in CSS. Functional element attributes can be quite handy for styling (e.g. input[disabled]), but we rather avoid styling via custom attributes (data-attr) for a better separation of concerns. When you use only classes for styling and keep IDs and attributes for JavaScript binding you get much more flexibility in moving styles across the document.

Loose Coupling (Tag Independence)

Avoid qualified selectors (prepended with tag). Thus you will gain additional agility in moving classes around components.

Loose Coupling (Location Independence)

Avoid long selectors with descendant/child combinators (.feed nav ul li h2). Long selectors besides harmful affect on selector performance mean that style rule-set is tied to particular location in the DOM. Independent selectors allow us to move components around our markup more freely.

Top

Further Reading

Analytics