@cultureamp/kaizen-component-library

Kaizen Component Library

Culture Amp’s Component Library

Documentation

Detailed component API documentation and working examples can be found on the Kaizen Site.

---

Contents

• Introduction
• Getting started
  • Prerequisites
  • Usage
• Draft components
  • Draft Component Process
  • Draft Component Checklist
  • Draft Component Status
• Development
  • Browser Support
  • Local Development with Murmur
  • Usage with Flow
  • Contributing

---

Introduction

The Kaizen Component Library is one of three parts of the Kaizen Design System (the other two are the Kaizen UI Kit and Kaizen Site). It is a collection of all the reusable components that we use to make things here at Culture Amp.

Getting started

Prerequisites

This guide assumes you have already cloned the big-frontend-repo (BFR) and have followed the Getting Started guide. This should provide all the information you will need to start using the Kaizen Component Library on your local development machine.

Usage

You can import a Kaizen Component Library component from the /kaizen-component-library folder inside your application, e.g.

React

import { Button } from "@cultureamp/kaizen-component-library"

Elm

import Kaizen.Button.Button as Button

(For Elm components, we have used Kaizen to namespace them because the source directories that are specified in elm.json are all pulled into the same namespace, creating potential conflicts.)

⬆ back to top

---

Draft components

Draft components are reusable components (i.e. not a snowflake) that can be used live in production, but have not yet met all the requirements of a Kaizen Component Library component. All “draft” components are imported explicitly from the /kaizen-component-library/draft folder:

import { MyExperimentalComponent } from "@cultureamp/kaizen-component-library/draft"

We encourage you to create new draft components. When you add a new draft component, we need to make sure that the component fits in with our overall design vision, so it is important to show it to a designer to make sure they are happy with it. After you have committed the code please announce it via the preferred slack channel/s (#design_systems_team and #pract_front_end_eng) and also at the fortnightly Front End Practice meeting for visibillity, peer review and feedback.

Draft Component Process

All new component proposals live inside kaizen-component-library/draft folder (this applies for all Design Systems Team (DST) and Product team initiated components).

Draft Component Checklist

Product teams are responsible for ensuring all draft checklist items have been completed for components that they introduce.

• Design review from a designer
• Basic level of unit tests
• Introduce new draft components at the Front End Practice meeting

The Design Systems Team will be responsible for finalising components that are in the draft components folder as they are prioritised.

Draft Component Status

Following is a list of components currently in draft status. If you would like to see if a specific component is "ready" to use for your project, check below.

Component
TextField	Status
ToggleSwitchField	Status
TitleBlock	Status
LoadingPlaceholder	Status
Modal	Status

⬆ back to top

---

Development

We use React Storybook to create isolated prototypes of our components and test component variants and configurations, which are known as "stories" in Storybook.

To start using Storybook, type the following command in the BFR repo:

bfr storybook kaizen-component-library

For documentation on creating stories for Elm components, see the comments in ElmStorybook.elm and loadElmStories.tsx

It is important that all Kaizen Component Library components have accompanying stories in our Storybook. This enables engineers to easily understand how a component works, test any new changes, and work on components in isolation.

Browser Support

All components need to work on the browsers below.

Browser	Version	Platform	Engine
Internet Explorer	11	Windows 8.1	Trident
Edge	Latest	Windows 10	EdgeHTML
Firefox	Latest	OS X	Gecko
Firefox	Latest	Windows 10	Gecko
Chrome	Latest	OS X	Blink
Chrome	Latest	Windows 10	Blink
Safari	Latest (11)	OS X	WebKit
Chrome		pixel 7.1
Chrome +1
Safari +1
Firefox +1

https://cultureamp.atlassian.net/wiki/spaces/Prod/pages/1572948/Browser+Support+and+Stats

Local Development with Murmur

To develop Kaizen Components locally and see the changes reflected inside of Murmur you will need to "symlink" you local version of @cultureamp/kaizen-component-library with your local copy of Murmur.

step 1. Make your local copy of @cultureamp/kaizen-component-library available.

# Navigate to code source
$ cd code/cultureamp/big-frontend-repo/packages/kaizen-component-library

# Register package for linking
$ yarn link

# Build in watch mode
$ yarn build:watch

step 2. Link @cultureamp/kaizen-component-library to Murmur.

# Navigate to code source
$ cd code/cultureamp/murmur

# Register package for linking
$ yarn link @cultureamp/kaizen-component-library

step 3. You can now run Murmur locally and any changes you make will be reflected locally.

When you are finished developing locally you can clean up the generated files using the command yarn clean and to unlink the npm package use yarn unlink @cultureamp/kaizen-component-library from the terminal running Murmur.

More information on Yarn link here

Usage with Flow

This library ships with flow type definitions. These are not yet publicly available through the flow-typed repo so to get the types working please add the following line to your .flowconfig under [libs].

[libs]
./node_modules/@cultureamp/kaizen-component-library/flow-typed/definitions/npm

⬆ back to top

Contributing

Take a look at our detail contributing guide for details.

⬆ back to top

---

The Kaizen Design System is maintained by the #team_design_systems.