Bulb Design

Welcome to the Bulb Design repository!

This repo contains;

• 📚 our pattern library
• 📸 our visual regression tool
• 📦 our patterns package which is used by our other frontend codebases.

Viewing the pattern library

The latest version of the library is published at http://patterns.bulb.co.uk where you can browse the library and try new pattern arrangements in the playgrounds.

Consuming the patterns package

To use the patterns in your project, first, add the @bulb/design package.

Note: this is a private package, and you will need a login to NPM and be added to the Bulb organisation.

yarn add @bulb/design

You can then simply import the components you wish to use, if you're using the full project.

Importing old components

import { Button } from '@bulb/design';

<Button {...props} />;

Typescript components

import { AppLinks } from '@bulb/design/modules/AppLinks';

<AppLinks {...props} />;

Local Development

Running the library locally

To run the library locally run the following command.

yarn run start

This will run it in a hot mode and will update any browser windows (on modern browsers) with any changes you make locally. For older browsers such as ie10 you will need to manually refresh the browser window following local changes.

Note: currently for the non typescript components, static assets such as images and icons are included in the compiled file, but this may change in the future so it doesn't make the file so large.

Creating Patterns

You can create new module patterns by using the yarn new command. It will ask for the module name and create a new pattern in the src/modules/{name}/ directory.

If you create a pattern manually, it should either be in the src/modules or src/styles directory, and have the following structure,

/{pattern group}
+- /ComponentName
|  +- index.tsx
|  +- index.test.tsx
|  +- index.vr-test.tsx
|  +- README.md

Updating components

When updating components, we update the adjacent CHANGELOG.md file with an entry describing the change where appropriate.

This helps us when consuming components that have been changed by one another to see why and how components have changed.

For breaking component changes prefix we prefix the changelog entry with [BREAKING] or [MAJOR] to communicate the new behaviour.

example changelog structure

# CHANGELOG

* [BREAKING] short description of breaking change
* short description of non breaking change
  // ...previous changes

Pattern Documentation

We utilise an internal library tool to create a great visual reference to all the patterns we've built in here.

When you add a new pattern to this repo, the README.md should be filled with details of this pattern.

It is generally the same Markdown as with Github, with the addition of Specimens - read about those over here to make your documentation amazing. While we don't use catalog anymore, the api for our tool is based on it.

// TODO add documentation for library tool

Static Variables and Values

Static values and CSS variables are in the src/styles directory.

In your components, you can import these,

import { palette } from '../../styles/ts-palette';

Testing

The test command is simply

yarn test

You can add any of the Jest CLI options to test specific files.

Your tests should cover any interactions your component may have.

Visual regression tests

The test command is simply

yarn vr-test

Visual regression tests require machine setup to run, see the Testing Document for deatils about how to set these up and use them to test your components.

Running the library locally

yarn start