search

bbc / grandstand

BBC Grandstand is a collection of common CSS abstractions and utility helper classes
http://bit.ly/grandstandcss
MIT License
191 stars 9 forks source link

readme

Grandstand

A collection of common CSS abstractions and utility helper classes.
BBC Grandstand

What is this?

Grandstand is a scalable front end architecture and a lightweight Sass framework. Consisting of a collection of common CSS abstractions and utility helper classes, Grandstand allows you to quickly development components in a reusable, performant manner.

This library is built and maintained by the BBC Sport team and used by various components on BBC Sport website and within the BBC Live product.

Contents

Installation

Grandstand can be installed using Bower:

$ bower install --save bbc-grandstand
// your-app/main.scss
@import 'bower_components/bbc-grandstand/grandstand';

Script support

In addition to the Latin script defaults, Grandstand includes typographic and text direction overrides for a number of other scripts, including Arabic and Chinese.

The value of the $script SASS variable, if set, is used to determine whether any script-specific overrides are applied when Grandstand is imported. See the file _l10n.scss for allowed values.

Architecture

Grandstand has a number of key architectural points which when combined work together to produce CSS which is fast to develop, scalable, performant, DIY and reusable.

The architectural principles behind Grandstand are arguably more important than the code provided in this library. Without knowing and adhering to these architectural principles you will not get the full benefits of working with Grandstand. The code alone is not enough.

ITCSS

The overarching architecture of Grandstand is very much inspired by the great work of Harry Roberts, his ITCSS architecture and Inuit CSS.

ITCSS (Inverted Triangle CSS) is specifically designed for managing CSS at scale and is a diagrammatical representation of an entire projects CSS. The ITCSS structure is not rigid and can be adapted to suit different projects, with that in mind Grandstand uses the following architecture:

Grandstand ITCSS Architecture

Following this approach a component should be primarily constructed using common objects and abstractions, the GEL Foundations and utility classes. The purpose of the code this library is to manage these common styles. A component should then only require a small amount of bespoke styling.

Resources

BEM

We apply the Block, Element, Modifier naming convention when creating components with Grandstand.

Resources

Namespaces

Our approach to writing and applying CSS very much promotes adding classes in the DOM. This creates two distinct problems for other developers working with this code:

There is loads more information about this in Harry Roberts post about: More Transparent UI Code with Namespaces

We add specific namespaces to our classes to help alleviate the problems of working with multiple classes:

Namespace Examples

Here are a few examples of what these namespaces might look like in practice:

// our media object pattern
.gs-o-media {}
.gs-o-media__img {}
.gs-o-media__body {}

// a sample component
.gs-c-my-component {}
.gs-c-my-component--large {}
.gs-c-my-component__title {}

// visually hidden utility
.gs-u-vh {}

// apply the sport theme to a component
.gs-t-sport {}

Code

With sharing of code in mind, all classes and output within this library is prefixed with gs- prefix. This will help us mitigate any potential clash of classname within other products.

GS Sass Tools

Grandstand is built on top of Grandstand Sass Tools, a collection of common Sass variables, functions and mixins. This component has no CSS output, it exists purely to expose a number of tools for you to use when developing components following the Grandstand architecture.

If you are building your own component with component specific CSS then you should include the Sass Tools within your component to expose the tools contained within.

GEL Foundations

The GEL Foundations are an un-opinionated code implementation of the GEL Foundational guidelines. Grandstand is built on top of these foundations adding a layer of opinion about how they should be used.

Grandstand outputs helper utility classes for both the GEL Typography and GEL Grid libraries. For more information on either of these libraries refer to their respective README files.

Objects

Grandstand include a number of CSS abstractions allowing you to solve common layout and structural problems in a consistent way without duplicating code throughout your codebase.

Grandstand includes the following abstractions:

Usage recommendations

These abstractions are designed to follow the single responsibility principle and the open/closed principle. Where possible you should separate the concerns of objects and your components. This allows your styles to become much more predicable and less prone to bugs caused by as a result of trying to combine object styles with component specific style.

For example, instead of this:

<div class="my-component gs-o-media">
    <div class="my-component__image gs-o-media__img">

    </div>
    <div class="my-component__text gs-o-media__body">

    </div>
</div>

You could separate the concerns between your component specific styles and the objects:

<div class="my-component">
    <div class="gs-o-media">
        <div class="gs-o-media__img">
            <div class="my-component__image" />
        </div>
        <div class="gs-o-media__body">
            <div class="my-component__text" />
        </div>
    </div>
</div>

Whilst this does introduce slightly more markup the effect it would have on performance is negligible and the value you this brings you for a maintainability point of view is massive.

Utilities

Utilities are low level helper classes designed to solve common problems which do not warrant full object abstractions.

Commonly they will only apply a single declaration e.g. align text to the right: gs-u-align-right, or simple multiline patterns: e.g. hide an element visually: gs-u-vh.

The scope of utility classes is only ever one element i.e. utilities can't affect any child elements of the element they're being applied too.

As with Objects, utilities follow the single responsibility principle and the open/closed principle.

Grandstand includes the following helper utilities:

!important

All utility classes carry the !important tag on every property to ensure our utility classes always work.

Utility classes are very specific in their intentions. For example if you applied a utility class to add 8px margin on the bottom of an element you never want to override this. If you didn't want this behaviour, you should not have used the class in the first place.

The pro-active use of !important guarantees this way of thinking.

Why Grandstand?!?

This framework is named after Grandstand, a British television sport programme. Broadcast between 1958 and 2007, it was one of the BBC's longest running sports shows, alongside BBC Sports Personality of the Year.

Credits

License

The MIT License (MIT)

Copyright 2016 British Broadcasting Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.