@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
• Deploying changes to the public Storybook
• Publishing changes to the NPMJS package library
• Creating Components
• Checklist for deploying and exporting new components
• Styling - working with styled-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-new.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.

Deploying project changes to the public Storybook

The visible Storybook for sharing changes is accessed at https://bham-storybook.mixd.co.uk/.

This is automatically deployed and built when changes are pushed to the development branch of the GitHub repository.

As this is likely to be ahead of the published package, any new changes that are anticipated to be published separately should be developed in separate feature branches to allow for merging into development and master separately.

Publishing changes to the NPMJS package library

The repository will need publishing to the NPMJS package library https://www.npmjs.com/package/@uob-web-and-digital/uob-components before it can be used in the UoB website.

When the library in ready for a new release of the NPM package, you will need to increase the version number in the package.json and run a npm install to ensure the project gets updated with this version. You will need to be logged into NPM in order to publish a new package. This can be done easily by running npm login in your terminal, then follow the instructions to login. Once logged in, you will be able to run the following command to release your new version, ready for Birmingham to use: npm publish

As this is a manual process, ensure that the master branch of the repository is always in sync with the currently published package.

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.

Checklist for deploying and exporting new components

Deploying

• Have you run npm run build to ensure that Webpack has compiled the components with no issues?
• Has the feature branch been merged into development?

Exporting

• Has the new component been added to the src/index.js file? -Has the new component been added into the applicable src/exports folder to ensure that code splitting runs with Webpack?
• Has the version number been increased in package.json to make sure a new version can be published?
• Have you run npm install to ensure that the project has been updated with the new version number?
• Have you run npm publish to release the new package?

Styling

styled-components

The component library utilises styled-components, which is a library built for React that allows you to use a mixture of JavaScript and CSS (a technique called CSS-in-JS). Styling is considered to be tied to a specific component. An important feature of this library is that it generates unique class names for the styling. Therefore, generally for this project, class names should not be applied to any elements.

You should define an element within the {ComponentName}.js file, and import this in from the Styles.js file to create the markup. For example:

{ComponentName}.js

import React from "react";
import PropTypes from "prop-types";
import { Wrapper, Title } from "./Styles"; // These must be defined as named imports, therefore require curly braces wrapped around them

const Example = ({ title }) => {
    return (
        <Wrapper>
            <Title>
                {title}
            </Title>
        </Wrapper>
    );
};

Example.propTypes = {
    title: PropTypes.string.isRequired
};

export default Example;

Styles.js

import styled from "styled-components";

// Create a Title component that'll render a <h1> tag with some styles
const Title = styled.h1`
    font-size: 1.5em;
    text-align: center;
    color: palevioletred;
`;

// Create a Wrapper component that'll render a <section> tag with some styles
const Wrapper = styled.section`
    padding: 4em;
    background: papayawhip;
`;

NOTE: styled-components has a lot of advanced capabilities, including being able to style an element dependent on a prop the component has received. It will be important to read up on their documentation to familiarise yourself with these features.

Global and theme variables

Global and theme variables have been defined for use across the project. This is mainly for the project’s design tokens: colours, font families, font weights, font sizes and spacing values. These can be referenced in the components as CSS variables, e.g. color: var(--color-black);. You will be able to find references of all token names in the Design Tokens section on the front-end of the Component Library, or within the /src/theme/GlobalStyles.js file in the code. The theme variables are also defined in an object in the /src/theme/ThemeVariables.js file for when JavaScript is needed to be used in particular instances. However, CSS variables should always take preference where possible.