Barbican Reset

Introduction

The Barbican Reset is an NPM module created to maintain consistency between the various digital projects run by the Barbican.

Contents

1. Setup
2. Component library
3. SCSS documentation
4. JS documentation
5. Pattern library
6. Font library

1. Setup

You can install the Barbican Reset into any project by running npm i barbican-reset inside your project root folder.

You can then manually import a component using import { BrExample } from barbican-reset

SCSS Stylesheet

Vue.js: @import '~barbican-reset';

Use the ~ in Vue.js to import assets from the project root

Drupal: @import "../node_modules/barbican-reset/scss/index";

Spektrix iframe development: @import "../../node_modules/barbican-reset/scss/index.scss";

SCSS Mixins

Vue.js: @import "~barbican-reset/scss/helpers";

The Barbican ticketing site makes SCSS mixins globally available via the vue.config.js file

Drupal: @import "../node_modules/barbican-reset/scss/helpers/index";

2. Component library

The component library is currently only available to Vue.js apps.

Many components are available globally within the Barbican ticketing app. Check the main.js file to see which components are currently available. These won't need an additional import statement.

When manually importing components into Vue.js, be sure to declare the import as a Vue component as well

You can reference any of the following components:

| Component | Filename | SCSS Class | SCSS Mixin | Previously | | -------------------- | -------------------- | -------------------- | ---------------- | ------------- | | <br-alert> | br_alert.vue | .br-alert | br-alert--setup | - | | <br-anchor> | br_anchor.vue | .btn | setup-button | - | | <br-button> | br_button.vue | .br-checkbox | br-checkbox | - | | <br-confirm-done> | br_confirm_done.vue | - | - | - | | <br-confirm-email> | br_confirm_email.vue | - | - | - | | <br-container> | br_container.vue | .br-container--outer | - | - | | <br-footer-lower> | br_footer_lower.vue | .br-footer-lower | br-footer-lower | - | | <br-footer-upper> | br_footer_upper.vue | .br-footer-upper | br-footer-upper | - | | <br-form-block> | br_form_block.vue | - | - | - | | <br-form-password> | br_form_password.vue | .br-form-password | br-form-password | - | | <br-form-row> | br_form_row.vue | .br-form-row | br-form-row | - | | <br-form-update> | br_form_update.vue | .br-form-update | br-form-update | - | | <br-loader> | br_loader.vue | .br-loader | - | - | | <br-skiplink> | br_skiplink.vue | - | - | <skip-link> | | <br-wrap> | br_wrap.vue | .br-wrap | - | - |

The following component titles are deprecated. You can still use them, but they will migrate to the BR naming convention in future.

| Component | Filename | SCSS Class | SCSS Mixin | | ----------------- | ----------------- | ---------- | ---------- | | <account-title> | account_title.vue | - | - | | <card-display> | card_display.vue | - | - | | <event-summary> | event_summary.vue | - | - | | <fluid-iframe> | fluid_iframe.vue | - | - | | <help-row> | help_row.vue | - | - | | <placeholder> | placeholder.vue | - | - | | <payment-logo> | payment_logo.vue | - | - | | <related-card> | related_card.vue | - | - | | <related-title> | related_title.vue | - | - | | <related-row> | related_row.vue | - | - | | <type-text> | type_text.vue | - | - | | <video-content> | video_content.vue | - | - |

The BR naming convention imitates the Bootstrap example. This format is useful for two reasons:

1. It is immediately obvious that the component is imported from the Barbican Reset and is not native to the app.

2. It forces components to use a two word syntax, which is the recommended format for custom components. For example, <br-header> instead of <header>, which avoids clashing with native HTML5 components.

3. SCSS documentation

We use SassDoc to document our SCSS. Here's some useful commands for working with this documentation:

• To output the latest documentation and watch for changes to scss, run gulp watch:css
• To view the documentation, open the file sassdoc/index.html in your browser. You will need to refresh this page to view any additional changes that you make.

Most components have corresponding SCSS classes (and mixins) which allow us to implement consistent styling across our various frontends, irrespective of their HTML structure.

4. JS documentation

We use JSDoc to document our Javascript. Here's some useful commands for working with this documentation:

• To output the latest documentation and watch for changes to javascript, run gulp watch:js
• To manually output documentation using gulp, run gulp doc:js
• To manually output documentation using jsdoc, run jsdoc gulpfile.js
• To view the documentation, open the file out/index.html in your browser. You will need to refresh this page to view any additional changes that you make.

5. Pattern library

The Barbican Reset includes a pattern library. This provides a single source of truth for all the SCSS contained within and allows us to view a whole family of Barbican styles alongside each other.

Setup

If this is your first time viewing the pattern library, navigate to the patterns subfolder and run npm i

From the root folder, run npm run serve:patterns and visit https://localhost:3000 in the web browser

New pages

Begin instructions from the patterns subfolder.

To create a new page in the pattern library, navigate to the views subfolder.

Duplicate the index.pug file and rename it.

Extending layouts

The first line of your new page reads extends ../layouts/main

If you navigate to the layouts subfolder you will see a main.pug file. Pug syntax looks like abbreviated HTML markup but also includes block content. Blocks describe which areas the page can use to output content.

Layouts are useful for creating page templates, allowing pages to focus on content and removing the need for repetitive scafolding code.

Including components (mixins)

The second line of your new page reads include ../components/samples

If you navigate to the components subfolder you will see a samples.pug file. Pug syntax looks like abbreviated HTML markup but also includes mixin Samples(). Mixins can accept parameters, which they use to print HTML markup on the page.

To call the samples mixin from your new page, you might write +Samples('Contemporary','contemporary-music')

Mixins are useful for printing repetitive code, such as loops to the page. The parameters they accept are quite narrow though, so if you need more flexibility, it's best to extend a layout instead.

Future intent

The pattern library was created as a single source of truth for Barbican styles and components. Unfortunately the components are only compatible with Vue.js currently and so the HTML markup is duplicated.

6. Font library

The Barbican Reset includes a SCSS mixin called font-face which defaults font-face urls to https://www.barbican.org.uk/themes/barb22/fonts/. This means none of digital projects need to host additional font files.

If you do need to host fonts locally, you can overwrite the path parameter in the font-face mixin to point to a local asset.