The SJ Component Library constitutes a complete set of ui building blocks. Using the Component Library ensures that your projects' ui consistently follows SJ AB branding and design language.
The components are hosted on bit.cloud, allowing for easy access, collaboration, and sharing. You can install them using npm or yarn. Each component is version-managed separately, giving you the flexibility to pick and choose the versions you need for your project. This approach allows you to use only the components you need, without the overhead of unnecessary code, making your project more efficient and maintainable.
Prerequisites
The following packages are listed as peer dependencies for the Component Library and need to be installed in your application:
Setup
To be able to install components from the @sj-ab scope it needs to be configured as scoped registry:
The Component Library allows you to pick and choose which components to install and use in your project, however, themes and theme provider are required:
Next, wrap your application code with a theme:
Design tokens
What are design tokens?
Design tokens are a way to abstract design properties such as colors, typography, spacing, and other visual elements into reusable and consistent values. They are a set of variables that define the visual language of a design system and can be used across different platforms and products.
Among other things, design tokens can document light and dark variants of colors, enabling easy dark mode support.
How are design tokens implemented in the Component Library?
Design tokens are defined in a structured JSON file that contains all design values, such as colors, typography, spacing, and more. These tokens are then imported into the Component Library, where they are typed and integrated into the Theme object.
Once included in the Theme, the design tokens become accessible throughout the Component Library. Components can reference these tokens via the theme object, ensuring consistent styling across the application.
Here’s how components typically use design tokens through the theme object:
And like this in the theme:
How can I as a component consumer use design tokens?
All component styles are already implemented with design tokens and do not require any further action. The components automatically adapt to light and dark mode based on the theme.
If you need to override component styles in your app, you should always use design tokens instead of setting fixed values. Do this by accessing the designTokens object in the theme.
Typography
Typography has all label colors from design tokens built-in via the color prop:
Color helpers
We have four color helper utils to help you set background, text color, hover color and ripple color styles for a given design token color:
We have a focus helper that generates CSS for our focus styling based on design tokens
Shadow helper
We also have a helper that takes a shadow value from design tokens and applies it in CSS:
How does dark mode work?
Dark mode is handled automatically thanks to design tokens. Normally, the components and the apps do not need to do anything to enable dark mode support, except to use design tokens for all styling.
The Component Library exports two separate themes, lightTheme and darkTheme that each contain light versions or dark versions of our design tokens. To activate dark mode, pass the darkTheme to your ThemeProvider:
There is a helper hook to identify if you are currently in dark mode:
Contribute
Contributions to the component library are warmly welcomed and consumer teams are encouraged to participate in its development. While Team Cumulus is primarily responsible for maintaining and developing the library, input and code changes from other teams are highly valued.
Before creating a pull request (PR), please ping us in the Design System general channel on Teams and describe your issue or proposed change. This helps us stay informed about what you are working on and ensures we aren't already addressing the same issue.
Once you've discussed your change with us, feel free to create a PR. Team Cumulus will review all submissions to ensure they align with SJ Design System guidelines and rules, and to verify that the changes meet accessibility standards.
Your contributions help us maintain a robust and versatile component library, and we appreciate your collaboration in making it better for everyone.
Important!
This project uses Bit for dependency management. Running npm install may cause conflicts or inconsistencies with Bit-managed dependencies. Use bit install to install all project dependencies and any additional libraries.
By following these steps, you'll ensure that all dependencies are correctly managed by Bit and your development environment is properly set up.
To make contributions, i. e. change a component or add a new component, a feature branch based on the master branch is created. To have changes merged with master and released, the developer creates a Pull Request. Pull Requests for the Component Library utilize a pr description template to:
Make it easier for contributors to provide all the info needed.
Create extensive release notes for the Component Library storybook page here.
Enforce that the correct info is provided to make a new release of a component to Bit Cloud.
When using the template, please remove all boilerplate content but make sure to keep all the headings even if you don't provide any info under them since they are used to analyze the pr description.
To enforce that the correct info is provided for a component release to bit.cloud we use a format resembling patterns stipulated by Conventional Commits.
Type
type = ’fix’ | ’feat’
Type fix maps to semvers patch and will increment the third digit in the version number: 0.0.1 => 0.0.2
Type feat maps to semvers minor and will increment the second digit in the version number: 0.0.1 => 0.1.0
To denote a breaking change, suffix type with an exclamation mark (’!’). This maps to semver's major and will increment the first digit in the version number: 0.0.1 => 1.0.0
<namepspace> represents a category which the component belongs to, All namespaces can be viewed here in the left-side menu.
Component name
<component-name> represents the name of the component and correlates with the folder name directly in the namespace folder in the repo. Component names are written in kebab-case.
Description
A message is required for each component change. This will work as a change log for this version of the component on Bit Cloud.
We recommend trying to make as isolated changes as possible, meaning don’t update many components with unrelated changes. If you need to do unrelated changes, rather create multiple pull requests. If you have related changes in several components you'll need to separate them with a mark-down separator ***. Only add bit components to the Bit change log, no stories or other scripts are needed here. If the pull request concerns a large number of components you may mark it as a bulk release. Components in a bulk release will all get the same change log entry and the same version increment. Before considering a bulk release, please make sure this is fits the the changes in the PR.
Bulk Release
When applicable you can make a bulk release:
<type>(all): <description>
This requires all components in the PR to have changes that can be described with the same change log and version bump. There will be only one message and one incrementor for this release.
Example:
feat(all): Added test id
All components from this PR will get a minor change: 1.0.0 > 1.1.0 and their respective change log entries will be ‘Added test id’
Bit Changelog Examples
fix(ui/text-button): added negative margins
feat(icons/card): change fill value of 'black'
fix!(ui/typography): BREAKING CHANGE: change variant 'ingress' to 'inherit'
Bit Changelog Case: New Accordion Feature
Changes have been made to the Accordion component, and its latest release version on Bit.cloud is 1.0.0. A pull request (PR) with the following bit changelog entry was created:
fix(ui/accordion): Added functionality to close/open all accordion folds.
CI would push a new version of the component to Bit Cloud: 1.0.1. Note that the version increment is a patch. However, the following change description would be more accurate:
feat(ui/accordion): Added functionality to close/open all accordion folds
Experimental Component Versions
By running the Build experimental component versions pipeline from Azure Devops for a pull request you can create experimental component versions that will be published on a separate lane on bit-cloud. You may browse different lanes in the bit.cloud ui to find experimental component versions, also known as snaps. Once the PR is completed the changed components will be released and the lane with its snaps will be deleted.
Troubleshooting
This error will occur sometimes in VS Code. It can be fixed by performing a clean install (remove node_modules and package-lock and reinstall all dependencies.