Kaizen Design System follows a federated, open-source model. All teams contribute Issues and Pull Requests (PRs) to grow Kaizen together.
An issue is a way to track ideas, enhancements and bugs.
Before creating an issue, search existing Issues to see if any relevant issues already exist.
To create a new issue for changes to design documentation or missing documentation:
- Visit Issues and click the "New issue" button.
- Give the issue a title framed as a problem, e.g. "There's no date picker guidance".
- Give the issue a description that provides enough information that people can act on it without including any sensitive information, e.g. "As a designer, I want to know how to position coach marks because I'm designing an onboarding workflow."
- Click Submit. Add a "Label" of "content" for design system content and "discussion" if you want feedback.
You can edit Kaizen Site documentation using GitHub's interface.
- Find: Find the page's file in GitHub by clicking "Find file", typing the name of the guideline, component or page and
.mdxto filter the results down to only Markdown files, which we use for documentation files. This page should have the same content as you see live on the Kaizen Site. - Edit: Click the pencil icon to "Edit this file".
- Preview: Makes your changes to the content and click "Preview changes" to see how they look.
- Commit:
- Under "Commit changes", write a commit message starting with
docs:, such asdocs: update typography documentation. - Create a new branch for this commit and start a pull request, e.g.
di/update-typography-guidelines. - Click the "Commit changes" button. This will start a pull request.
- Under "Commit changes", write a commit message starting with
- Create PR: Click the "Create pull request" button. Add someone as a reviewer or let #prod_design_systems know.
- PR description and branch preview:
- Give your PR a description to help reviewers quickly understand why you've made the changes you have made and give feedback.
- Where it says "No description provided", look for an "Edit" action (in the unlabeled icon dropdown).
- If there is an open Issue for your changes, link to it in the description by writing
#and writing the number or title of the Issue. You can find the Issue number or title by searching for it in Issues. - It's convenient for reviewers if you add a link to your "branch preview", which shows how your changes will look on the Kaizen Site after it has automatically been built (within a few minutes of opening the PR). The branch preview link will use your branch name like this: https://dev.cultureamp.design/(branch-name), which you can find in the "Checks" section of the page (likely under "Show all checks" > Branch preview: "Details").
Once it's approved, click "Squash and merge" to publish your changes. Share the link to the updated documentation on #updates_design_systems for awareness.
Every contribution must be design reviewed and communicated.
- Kaizen Site changes use
docs:at the start of the first commit message and PR title. - New features in components use
feat:at the start of PR titles. For 1 commit, usefeat:in the commit message too. - Fixes in components use
fix:at the start of PR titles. For 1 commit, usefix:in the commit message too. - Breaking changes that are not backwards compatible use feat or fix as above and include
BREAKING CHANGE:in the body of a commit message. - Design token changes… let's talk about that.
Every code contribution must have:
- A design review from a designer
- Semantic versioning and conventional commit PR titles: see Releasing packages
- Communications: share your new component or changes on Slack and at relevant Front End Practice meetings
Every code contribution should strive to have:
- Basic level of unit tests
- New or updated Storybook stories
To update a component in code:
- Ask for a code review from a design systems advocate (an "advocado"), #prod_design_systems, or someone in your team who is experienced with Kaizen*
- Notify the front-end engineering practice (#pract_front_end_eng) of any possible breaking changes
- Notify the QA practice of any possible breaking changes
* If you're new to Kaizen, please ask #prod_design_systems to set up an onboarding session to get you up to speed. If you have an urgent PR to merge before that happens, it is safest to ask #prod_design_systems to review it to catch any issues.
See the design tokens package.
To learn more about what browsers and devices we support in Kaizen Component Library, Culture Amp employees can see the Browser Support wiki page.
To strengthen the Kaizen Design System, we encourage engineers to take a component-first development approach. By concentrating on developing Kaizen components in Storybook, we are likely to improve the API design and achieve good separation of concerns, avoiding components tightly coupled to specific applications. If, however, you want to test a component in the context of another front-end codebase, you can yarn link your local version of @kaizen/component-library with your other front-end codebase.
Step 1: Make your local copy of @kaizen/component-library available.
# Navigate to code source
$ cd ./packages/component-library
# Register package for linking
$ yarn link
# Build in watch mode
$ yarn build:watchStep 2: Link @kaizen/component-library to your other front-end codebase.
# Navigate to code source
$ cd <your_code>/cultureamp/YOUR_FRONT_END_CODEBASE
# Link repo to locally registered package
$ yarn link @kaizen/component-libraryYour local Kaizen changes will now show in your other front-end codebase.
Step 3: Unlink
When you are done, unlink the package from your front-end codebase:
yarn unlink @kaizen/component-library
You can also clean up generated files in your @kaizen/component-library repo:
yarn clean
Automated releases to the npm public registry are triggered for all pull requests containing modifications to one or more npm packages (found in the /packages/ directory). The information required to determine the version update for each release is taken from the title and content of the pull request.
To release a new version of a package, create a pull request that:
- Modifies only the package(s) you wish to release (see below)
- Has a conventional pull request title (see below)
- If there is only one commit, it has a commit message which matches the pull request title
Once that pull request is merged into main, an automated release will be triggered, and the newly published package version will be available on the npm public registry.
All npm packages follow strict semantic versioning (or semver). Semantic versioning gives specific meaning to changes in version numbers, as follows:
Given a version number
MAJOR.MINOR.PATCH, increment the:
MAJORversion when you make incompatible API changes,MINORversion when you add functionality in a backwards compatible manner, andPATCHversion when you make backwards compatible bug fixes.
Note that we do not update package version numbers directly, but instead depend on a Conventional Commit workflow which will version and release packages according to the content of our pull requests.
Our pull requests need to be structured in a certain way for the CI pipeline to correctly update version numbers when releasing packages. By following the release workflow outlined above, our pull requests will result in a Conventional Commit to the main branch when merged (see the Conventional Commit 1.0.0 spec).
This workflow requires that all pull requests have a title formatted as follows:
<type>: <description>
To help you, we have commitizen installed, so you can run yarn commit and follow the prompts and commitizen will format your commit for you.
The description should be a short (less than ~60 characters) summary of changes introduced in the release. This summary will be included in the CHANGELOG (see the releases page), along with the commit type, a link to the pull request which triggered the release, and a detailed summary of any breaking changes.
Note that since the description will be included in the CHANGELOG — and may be the only summary of the changes that your colleagues will encounter — it is helpful for you to include a concise summary of how the package is different following the release, written in the imperative mood. For example fix: Address accessibility bug in the Gizmo component.
The commit type is used to indicate the type of update (i.e. PATCH or MINOR in Semantic Versioning) that was included in the release, as well as the context in which that update was made. There are a number of valid commit types (e.g. style, build, refactor, test etc.) — for a detailed list of commit types used in this repository, refer to the Angular convention docs.
Most commit types describe changes which do not modify the behaviour of the published package, and will result in a PATCH version update, along with an entry in the CHANGELOG noting that the package implementation has not changed. For example:
-
docs— indicates that documentation has been updated, e.g. editing a README that corresponds to a component's documentation on the Kaizen Site -
chore— indicates that some otherwise-unspecified work has been performed on the package with no consequence on the published code, e.g. updating package metadata inpackage.json
However, two commit types have special meaning for the purpose of versioning package releases, and signify changes in the behaviour or implementation of published code which may affect consumers of the package. These are:
-
fix— indicates that a change addressed a bug or security concern in the published code, but otherwise had no consequence for the released package's features or API (corresponding to a PATCH version) -
feat— indicates that a change added something new to the released package's API or features without affecting existing functionality (corresponding to a MINOR version)
In addition to feat and fix releases, if a pull request includes changes which modify existing behaviour or APIs in a way that is not backwards compatible, that change needs to be marked with a BREAKING CHANGE: <description> line (including a description as above) somewhere in the commit body of the merged commit to main. Doing so will trigger a MAJOR version update in the corresponding release, irrespective of the commit type.
Since we are using a squash-and-merge strategy for our pull requests, we recommend that you introduce breaking changes in their own commits, each with a commit summary in the format BREAKING CHANGE: <description>, with any additional notes in the commit body.
Note: Pull requests for branches containing a single commit are a special case, and should contain a commit with a conventional commit message (and a matching pull request title), with any
BREAKING CHANGEannotations included in the commit body. To avoid this edge case, you can push an additional commit to your branch! (you can usegit commit --allow-emptyif you don't have any code to add). Note that merge commits don't count, so you will still need to do this if there are two commits but one is a merge commit.
For example, a pull request might have the title feat: Add color option to Gizmo component, and include the following commit in the branch for the pull request (including additional detail in the commit body):
BREAKING CHANGE: Add a compulsory color option to the Gizmo API
There is no default color for Gizmos, so one needs to be provided.
As well as triggering a major version update, this will make breaking changes clearly visible from the pull request summary in GitHub, and provide detailed information in the CHANGELOG (including any additional notes from the body of the BREAKING CHANGE commit), clearly documenting all breaking changes to our published APIs.
Note that in the case that a pull request touches files from more than one package, all of those packages will be released to the npm registry with the specified update. Sometimes this might be desirable (e.g. when performing a bulk update to package docs), but in general, be on the lookout for pull requests which touch more than one package, and break those changes up into separate pull requests!
Canary releases create a way to test changes in production-like environments, and are a great way to reduce the risk of proposed changes to a package. Use canary releases when you're working on a significant refactor, experimenting with new technology, or making other large scale changes.
Any merged pull request into the (protected) canary branch will create a canary release, publishing a pre-release version of any packages touched by that branch. Only repo admins are able to directly push to the canary branch without a pull request.
For example, opening a pull request to merge a branch containing feat: Even more glitter into the branch canary will release e.g. @kaizen/[email protected] to npm. This pre-release package version will then be available elsewhere for testing those changes prior to a full release.
To use a newly released version of the Kaizen Component Library (or any other package) in a front-end codebase, run yarn upgrade --latest <scoped package name> (e.g. yarn upgrade --latest @kaizen/component-library).
Remember to always check the CHANGELOG (e.g. /packages/component-library/CHANGELOG.md or the releases page) for any package you wish to upgrade, paying extra attention to any breaking changes which have been introduced since the last version used in your project.
To learn more about contributing components, see the Kaizen Site: components overview.
Refer to the docs folder for code guidelines and patterns.
To generate a new component and package, new component within an existing package, or a subcomponent, run the following command and follow the prompts:
yarn plop