Customizing Design System

For convenient use of the Steroids framework, it is recommended to customize the design system according to your project. There are several ways to customize the Steroids design system:

• Adjusting scss variables.
• Overriding the view part of components.
• Creating your npm package for ui-kit based on @steroidsjs/bootstrap.
• Customizing the layout design in Figma (we provide open layouts).

Let's go through each method separately.

Adjusting SCSS Variables

Styling components in Steroids is based on scss variables, allowing you to fully customize them for your specific project.

1. Connecting Custom Variables

First, create a file structure to add custom variables. Here's an example structure:

└── src
1    └── style
2        ├── custom-variables
3        │   ├── colors.scss - file with color variables
4        │   ├── media.scss - file with variables for media queries
5        │   ├── typography.scss - file with typography variables
6        │   └── index.scss - file to include all custom variable files
7        └── variables.scss - scss variables (already present in the boilerplate)

In the variables.scss file, import custom variables like this:

@import '~@steroidsjs/bootstrap/scss/mixins';
1@import '~@steroidsjs/bootstrap/scss/variables';
2@import './custom-variables';

Now, just add the necessary variables to the corresponding files.

2. Overriding Application Colors

Colors in Steroids are defined through root variables, and these values are then assigned to scss variables. Root variables allow dynamically changing colors for different application themes (e.g., dark and light). The code only uses the corresponding scss variables.

To override primary and secondary colors, add the following structure to the custom-variables/colors.scss file:

:root {
1  --primary: red;
2  --secondary: blue;
3}

If your project has a dark theme, add another structure to override colors for that theme:

html[data-theme="dark"] {
1    --primary: orange;
2    --secondary: purple;
3}

Later in the project code, you can use color variables like this:

@use "style/variables";
1
2.Block {
3    color: variables.$primary; // переменной $primary в Steroids присваивается значение var(--primary) - и так со всеми цветами
4}

3. Adding and Overriding Color Themes for Buttons

For styling the Button component in Steroids, the scss variable $color-themes is used. It denotes four main colors for the button:

• color: background color of the button.
• color-light: background color in the active state.
• color-dark: background color in the hover state.
• text-color: text color in the button.

You can override or create new color themes using the custom variable $color-themes. To override the primary theme and add a sub-button theme, add the following to the custom-variables/colors.scss file:

@use "sass:map"; // This line is necessary for the scss function map.merge() to work
1@use "~@steroidsjs/bootstrap/scss/variables"; // Using color variables from Steroids as needed
2
3$color-themes: (); // Definition of the color-themes variable (following scss rules when assigning a variable using map.merge())
4$color-themes: map.merge(
5                (
6                        "primary": (
7                                "color": red,
8                                "color-dark": red,
9                                "color-light": orange,
10                                "text-color": white,
11                        ),
12                        "sub-button": (
13                                "color": variables.$blue,
14                                "color-dark": variables.$blue-dark,
15                                "color-light": variables.$blue-light,
16                                "text-color": white,
17                        ),
18                ),
19                $color-themes
20);

Note that the variable $color-themes is completely overwritten. This means that with the above construction, only two button themes, primary and sub-button, will be defined in the project.

4. Typography Customization

For typography components like Text and Title, there is a type prop that sets not only the HTML tag but also specific styles. The scss variables $text-types and $title-types control these styles. To override them, add corresponding constructions to the custom-variables/typography.scss file:

@use "sass:map";
1@use "~@steroidsjs/bootstrap/scss/variables";
2
3$title-types: ();
4$title-types: map.merge(
5    (
6        "h1": (
7            "font-size": variables.$font-size-2xl,
8            "font-weight": variables.$font-weight-lg,
9            "line-height": variables.$line-height-2xl,
10            "color": variables.$text-color,
11        ),
12        "h2": (
13            "font-size": variables.$font-size-xl,
14            "font-weight": variables.$font-weight-lg,
15            "line-height": variables.$line-height-xl,
16            "color": blue,
17        ),
18        "sub": (
19            "font-size": 14px,
20            "font-weight": variables.$font-weight-lg,
21            "line-height": variables.$line-height-lg,
22            "color": blue,
23        ),
24    ),
25    $title-types
26);

This way, you can create custom types for text and headers. Usage of types in code would be like this:

<Title
1    type='custom-title'
2    content='some content'
3>

Styles that can be assigned to text and header types include:

• font-family
• font-size
• font-weight
• line-height
• color
• text-align
• text-transform
• text-decoration

Additionally, you can add the prefixes mobile or tablet to determine property values on different screen sizes. For example, adding the mobile prefix applies properties in the media query @media (max-width: media.$mobile-width), where $mobile-width can be set directly in the project.

5. Overriding Variables for Media Queries

To override media variables, you can add them to the custom-variables/media.scss file, for example:

$mobile-width: 500px;
1$tablet-width: 1023px;

Now, all scss variables are customized for your project. For more precise customization of component display, you can use other methods of design system customization.

Overriding View Parts of Components

To change the appearance of a component, you need to replace its view part, namely the *.scss and *.tsx files. You can replace both files or just one of them, depending on the changes needed in the component's appearance.

1. Overriding *.scss Files.

All style files are imported in the src/style/index.scss file. To override a style, you need to change the import of the desired component, for example:

// Before
1@use '~@steroidsjs/bootstrap/form/Button/ButtonView';
2// After
3@use './custom-bootstrap/ButtonView';

As a result, the project will have the following structure:

└── style
1   ├── index.scss - main styles file, where 'ui/index.scss' is imported
2   └── variables.scss - scss variables
3   └── custom-bootstrap
4       └── ButtonView.scss

2. Overriding *.tsx Files.

If changing styles is not enough and you need to modify the tsx code of a component, the entire *.tsx file of the component is copied. These files are imported in src/ui/bootstrap.ts. The resulting structure:

└── ui
1   ├── bootstrap.tsx - main file, where the component import is overridden (e.g., ButtonView)
2   └── form - group of components where the modified component is located
3       └── Button - name of the component
4           └── ButtonView.tsx - file with the overridden component

Creating an npm Package for UI Kit Based on Steroids

To create your npm package for the UI kit of your project, you need to:

1. Clone the Steroids Repository

All files for displaying components are stored in the react-bootstrap repository.

2. Modify the Component Files

In the react-bootstrap repository, the architecture is as follows:

└── src
1    └── content/ - folders with groups of components
2    └── form/
3        └── Button/ - component folder
4            ├── ButtonView.tsx - file with the component's markup, where changes can be made
5            └── ButtonView.scss - file with the component's styles, where changes can be made

Changing the view files of components will not affect their logic.

3. Publish the Resulting Repository as a npm Package

You can find more information on how to do this in the article Creating Node.js modules.

Customizing Layout Design in Figma

A detailed guide on customizing the layout design is available at this link.