För utvecklare

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:

npm install @emotion/react@11.11.4 @emotion/styled@11.11.0 @mui/material@5.14.8 react@18.3.1 react-dom@18.3.1

Setup

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:

npm install @sj-ab/component-library.styles.themes @sj-ab/component-library.ui.theme-provider

Next, wrap your application code with a theme:

import React from "react";
import { lightTheme } from "@sj-ab/component-library.styles.themes";
import ThemeProvider from "@sj-ab/component-library.ui.theme-provider";

const App = () => {
  return (
    <ThemeProvider theme={lightTheme}>
      <App />
    </ThemeProvider>
  );
};

export default App;

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?

The full set of SJ Design tokens are stored in JSON format. The latest version can be found here. Design token values from the JSON are then imported into the Component Library, typed and spread into the Theme object and can be accessed wherever the theme is used.

Components use design tokens like this:

<Card sx={(theme) => ({ color: theme.designTokens.color.label.hostlov.value })}>

And like this in the theme:

MuiBackdrop: {
  styleOverrides: {
    root: {
      backgroundColor:
        privateTheme.designTokens.color.fill.backdrop.value,
    },
  },
},

How can I as a component consumer use design tokens?

All component styles should already be implemented with design tokens and do not require any further action.

If you need to override component styles in your app, you should always be using design tokens instead of setting fixed color 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?:
    | "textPrimary"
    | "textSecondary"
    | "error"
    | "disabled"
    | "hostlov"
    | "hostlov451"
    | "placeholder"
    | string;

<Typography color="textSecondary">Text using label.secondary </Typography>
<Typography color="hostlov">Text using label.hostlov </Typography>

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:

import { 
  getBackgroundColorStyles,
  getTextColorStyles,
  getHoverColorStyles,
  getRippleColorStyles,
  getAllColorStyles
} from "@sj-ab/component-library.styles.utils";

const theme = useTheme()

const myStyles = {
  ...getBackgroundColorStyles("morkHimmel", theme),
  ...getTextColorStyles("morkHimmel", theme),
  ...getHoverColorStyles("morkHimmel", theme),
  ...getRippleColorStyles("morkHimmel", theme),
  /* or you can get all-in-one: */
  ...getAllColorStyles("morkHimmel", theme)
}

return (
  <Box sx={myStyles} />
)

Refer to the Colors story in Storybook for more information.

Focus helper

We have a focus helper that generates CSS for our focus styling based on design tokens

import { focusStyle } from "@sj-ab/component-library.styles.utils";

const buttonStyles = {
  "&.Mui-focusVisible": {
    boxShadow: focusStyle(theme, true),
  },
}

Shadow helper

We also have a helper that takes a shadow value from design tokens and applies it in CSS:

import { boxShadow } from "@sj-ab/component-library.styles.utils";

const styles = {
  boxShadow: boxShadow(privateTheme.designTokens.shadow.default.value),
};

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:

import ThemeProvider from "@sj-ab/component-library.ui.theme-provider";
import { darkTheme, lightTheme } from "@sj-ab/component-library.styles.themes";

<ThemeProvider theme={preferredTheme === "dark" ? darkTheme : lightTheme}>

There is a helper hook to identify if you are currently in dark mode:

import { useIsDarkMode } from "@sj-ab/component-library.styles.utils";

const isDark = useIsDarkMode();

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.

By following these steps, you'll ensure that all dependencies are correctly managed by Bit and your development environment is properly set up.

1. Clone the Repository

git clone https://dev.azure.com/SJ-ADP/_git/DesignSystem

2. Install Bit Version Manager (BVM) and Bit

npx @teambit/bvm install

or

npm i -g @teambit/bvm
bvm install

👉 If you run into issues, please visit the BVM troubleshooting guide.

3. Install Project Dependencies

bit install

4. Set Up Husky for Managing Git Hooks

npm run prepare

5. Start Local Development Server (Storybook)

npm start

6. Done! 🎉

Pull Request Description Requirements

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

Namespace

namespace = ’ui’ | ’icons’ | ’assets’ | ’props’ | ’translations’ | ’utils’

<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

1. 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.

2. 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

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

Contact Cumulus if you are still having problems!