Styles module

When a website becomes large, there is no more place for crafting individual pages. It's just not scalable.

Besides that, it is always a good idea to keep the user experience in the consistency: similar colors, shapes, or controls should convey the similar information or represent the same kind of action (for instance, “red” color often stands for irreversible actions like “delete”). Otherwise, it leads to users’ confusion and frustration.

Having said all the above, it is safe to assume that a website is getting heaviest in-place customizations only around essential pages like Home, About or Pricing. All the blog posts or news will most likely look the same, have a similar content structure, navigation, etc.

Therefore, having a centralized place to manage styles is critical for keeping the look and feel and structure consistent across the website. Here at Paperbits we use a well-known concept of Style Guide which is, essentially, a document containing all the stylable UI components that make up a theme.

Theme building blocks

Paperbits styling system consists of Primitives, Properties, Components, and Variations. Similarly to all the other types of content, they have their own JSON representation and a contract with at least two fields: “key” and “displayName”.

Primitives

Primitives are the smallest configurable parts of styles, e.g. colors, fonts, shadows, gradients, animations, etc.

"colors": {
    "defaultBg": {
        "displayName": "Default background",
        "key": "colors/defaultBg",
        "value": "#fff"
    }
}

Properties

Properties describe how particular elements of a UI component look like. It can be typography, background, padding, margin, etc., and the often reference primitives.

For example, a background property points to a color:

"background": {
    "colorKey": "colors/defaultBg"
}

Components

Components are buttons, headings, paragraphs, pictures and so on, - basically, what the entire content (of pages, blog posts, emails) consists of.

"button": {
    "default": {
        "displayName": "Normal button",
        "key": "components/button/default",
        "background": {
            "colorKey": "colors/defaultBg"
        },
        "typography": {
            "colorKey": "colors/default",
            "fontStyle": "normal"
        }
    }
}

Variations

Each component has one or more variations in one or more different categories. For example, a regular button may have variations like "danger" and "large":

"danger" - a variation of a button style in category "appearance", which applied to buttons causing irreversible action.

"large" - a variation of a button style in category "size", that might be applied whenever a button needs to stand out, like a "call to action".

"button": {
    "default": {...},
    "danger": {...},
    "large": {...}
}

A component may apply more than one variation at the same time, but only if they are in different categories:

<button class="button button-primary button-large">Subscribe now!</button>

A variation may be global - usually listed on Style Guide, and local - used in a specific instance of a widget residing in a particular piece of content (i.e. footer of a page).

Style inheritance

Paperbits styling system has a concept of inheritance which is very similar to the way Cascade Style Sheets (CSS) rules work. Almost every property of a component inherits its values from a default component unless it is specifically set/overwritten in a variation (applicable to both global and local ones).

Bindings/directives

There is a special binding (or a directive, depending on the UI framework you use) that helps to assign the right CSS class(es) to a stylable HTML element:

Knockout

<button data-bind="styled: style">OK</button>

Vue

<button v-bind:styled="style">OK</button>

Angular

<button [styled]="style">OK</button>

Here “style” parameter is either a Style object or a string containing style key.