https://github.com/dsheiko/pcss
Guidelines for writing scalable and maintainable style-sheets
https://github.com/dsheiko/pcss
bem css naming-conventions styleguide
Last synced: 6 months ago
JSON representation
Guidelines for writing scalable and maintainable style-sheets
- Host: GitHub
- URL: https://github.com/dsheiko/pcss
- Owner: dsheiko
- Created: 2015-02-19T13:50:25.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2018-04-27T16:04:14.000Z (over 7 years ago)
- Last Synced: 2025-03-29T06:41:21.800Z (6 months ago)
- Topics: bem, css, naming-conventions, styleguide
- Size: 469 KB
- Stars: 18
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- Changelog: Changelog.md
Awesome Lists containing this project
README
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](https://smacss.com/),
element and subclass (modifier) naming conventions from [BEM](https://en.bem.info), the idea of common OOP principles in CSS (inheritance, OCP, SRP)
from [OOCSS](http://oocss.org/), context-independent cascading from
[Modular CSS naming conventions](http://thesassway.com/advanced/modular-css-naming-conventions)
# Contents
* Key concepts
* [Component/Element/Subclass](#component)
* [State](#state)
* [Theme](#theme)
* [File Structure Example](#a-fs)
* [Naming Conventions](#a-nc)
* [Selector Conventions](#a-sc)
## 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:
```
..
..
```
### Subclasses and elements
Elements are styled in scopes of subclasses:
```sass
.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
```html
```
#### ./component/progressbar/_index.scss
```sass
.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
```sass
.progressbar--big > .progressbar__status {
font-size: 1.6rem;
text-transform: uppercase;
padding: 16px;
}
```
#### ./component/progressbar/_small.scss
```sass
.progressbar--small > .progressbar__status {
font-size: 1.1rem;
text-transform: lowercase;
padding: 11px;
}
```
## 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
```html
...
```
##### ./component/_main.scss
```css
.main {
/* default style */
&.has-error {
/* state modified style */
}
}
```
##### ./base/_global-state.scss
```css
/* Global state */
.is-hidden {
display: none !important;
}
```
## Theme
Theme classes used to alternate the style of a component
depending on the context.
##### HTML
```html
...
```
##### ./component/sidebar/_index.scss
```css
.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:
```sass
@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`:
```sass
$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
```html
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor