Introduction

A React UI toolkit used in Yeldo to develop the company design system and reuse across FrontEnds.

After a few test & research, we found styling with SCSS the most effective way to work.

This approach has a few features we definitely wanted to have:

• Scoped classnames, to avoid unpredictable CSS interferences/redefinitions (our design choice is to use it only on component root)
• Readable code, with semantic and logical classnames, for easy evolution/mainteinance
• Keep the library components and sub-components easy to customize from the consumer app, if needed
• Optimization: the consumer app will only import the needed style, and tree-shaking is supported although not very granular
• Working SSR generation, including styles, the App will look the same with or without Javascript

(We will also try to take advantage of css variables)

The boilerplate for this library is 100% due to this Alex Eagleson's article. God bless you Alex!

Gotchas & limitations

This library makes the following assumptions:

• the consumer app is using Next.js
• Next.js is configured to transpile the library
• the consumer app is using SCSS and Bootstrap 5
• the consumer exposes bootstrap utility classes in the global scope
• the consumer app has a matching bootstrap customization (especially fluid font sizes)

The limitations are the following:

• Next.js transpilePackages is not refreshing properly changes to the packages, so cleaning the output folder is needed before every build

How to use

1. Install the library in your project as usual

yarn add @yeldo/components

2. configure next.config.js to transpile the library

  transpilePackages: ["@yeldo/components"],

3. Although the styled are scoped you still need to include a tiny global style in your main stylesheet to configure variables and fluid fonts in the consumer app.

@import "@yeldo/components/src/styles/style.scss";

4. In package.json make sure the build, dev, [...] commands always delete the output folder (next.config.js)

  "build": "rimraf out && next build",
  "dev": "rimraf out && next start",

Development

Storybook

To develop the library components, you can use Storybook.

yarn storybook

All set!

Preview in your project

For local development, if you want to preview your changes to the library inside your consumer app, it is reccomended to use Yalc to link the library it.

First, install Yalc globally if you haven't done so already:

yarn global add yalc

Then, navigate to the library directory and publish the package to the local Yalc store:

cd path/to/your/library
yalc publish

Navigate to the project directory where you want to use the library and link or add your package and add yalc to your .gitignore if it's not already there:

cd path/to/your/project

echo "yalc.lock" >> .gitignore
echo ".yalc" >> .gitignore

Note: add changes your package.json so be sure not to commit that change in your project.

cd path/to/your/project

# or: yalc add @your-library-name
yalc link @your-library-name

When you make changes to the library, you can update the package in the Yalc store and in your project with these commands:

cd path/to/your/library
yalc publish --push

or you can just publish, go to the project and update:

cd path/to/your/library
yalc publish

cd path/to/your/project
yalc update

Sample component structure

import React from "react";
import style from "./TestComponent.module.scss";

const TestComponent = () => {
  return (
    <div className={"ye-TestComponent " + style.root}>
      this is the component
      <div className="ye-frame">
        this is the frame
        <div className="ye-innerbox">this is the inside</div>
      </div>
    </div>
  );
};

export default TestComponent;

Sample SCSS structure

.root {
  :global {
    background: #ffeedd;
    padding: 1rem;
    .ye-frame {
      padding: 1rem;
      background: #55eedd;
      .ye-innerbox {
        padding: 1rem;
        background: #11dd00;
      }
    }
  }
}

commands

yarn install yarn storybook

to bump a new version: yarn version --new-version (patch|minor|major) commit & push npm publish

Dependency updates

yarn audit yarn upgrade-interactive yarn upgrade-interactive --latest

font sizes and distances

the library uses "rem" units, so every distance/size is calculated against the base html root font size.

To keep aspect ratio on every screen size, we use fluid font sizes where the "root" p font sizes are:

• Mobile: 18px (@390px)
• Desktop: 20px (@1920px)

If you have a size in px from the design, please use the formula to get the rem size: Rem size = px size / root px size

To make it all work fine, the consumer app should use fluid types too. This library exports a small CSS that can be imported to this extent:

[in _app.tsx] @import "yeldo-ui-library-next/dist/style.css"

Symbols

Icons are available through google fonts (Material Icons Sharp, v4.0.0), published in yeldo-storage on azure, and automatically included when needed via scss import.

Symbols can be styled as Text, the icon name (https://fonts.google.com/icons?icon.style=Sharp) must be placed in the tag content:

<Symbol weight="light" size="hHero" color="white">
  menu
</Symbol>