@uob-web-and-digital/uob-components

University of Birmingham Component Library

This is the frontend component library for the University of Birmingham website utilising Styled Components

Contents

• Installation and setup
• Working locally on the project
• Creating Components

Installation and setup

Before setting up the UoB component library it is required that you setup Prettier to format JS.

Node and NPM Compatibility

Node: ^16.6.2

NPM: ^7.20.3

*Supported version last updated: 09/12/2021

Setting up Prettier in VSCode

Launch VS Code Quick Open (Cmd+P for Mac, Ctrl+P for Windows) and paste the following command, and press enter.

ext install esbenp.prettier-vscode

Once the extension is installed you can then configure VSCode to automtically format JS upon saving by adding the following to your VSCode settings.json file:

"editor.defaultFormatter": null, // (Optional) it is possible to set this as "esbenp.prettier-vscode" for everything but not recommended
"[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
}

Setting up the project locally

1. Clone the repo from Github: git clone [e-mail]:Mixd/uob-components.git
2. Install NPM Node Modules by running npm install from the project root

Working locally on the project

Run npm run storybook from the project root. This will run a new instance of Storybook JS that can be accessed from localhost:6006.

Changes made locally are automatically compiled and the browser instance of Storybook will automaticaly refresh, hot-loading changes very quickly where possible.

Creating components

Components should always be created within the src/components folder.

Naming components

Each component should have a name that describes what it is as generically as possible and shouldn't factor in its expected location. A good example of this would be a component called 'accordion', the name is short and describes its function. A not so great name would be news-accordion because it loses semantics when used outside of the news section.

Naming component folders

Once a component has a good name you can create a new folder within src/components that is based on the name. The format of this folder name should always be lowercase, with multiple words being seperated by dashes i.e. content-sidebar-group.

Component file structure

Within the component folder you must create the following 3 files:

component-folder
 |_ {ComponentName}.js
 |_ {ComponentName}.stories.js
 |_ Styles.js

Files within the folder should be named in PascalCase which means that each word in the name should have a capital first letter i.e. MyCoolComponent.

{ComponentName}.js

This file is where the Component Structure is defined.

{ComponentName}.stories.js

This file allows developers to pass in mockup content to the component that will render within Storybook. More information is available in the Storybook docs Storybook JS - Defining Stories

Styles.js

this is where component styling is defined using Styled Components. Note: Styled components not only define the CSS styling but actually create the markup for elements within the component.