Fractal - Snowball's design system

`design-tokens`	`fractal`
	$fractal$
	$fractal-dependants$
	$fractal-downloads$
	$fractal-score$

Quality on `main` branch	Security on `main` branch	Release on `main` branch	Chromatic on `main` branch

The open-source mono-repository for the design reference, components libraries and documentations of Fractal, Snowball's design system.

Setup

Before anything, start by cloning the repository:

git clone git@github.com:snowball-tech/fractal.git

If you haven't setup any SSH key to your GitHub account, you will need to do so. Check out the documentation on how to connect with SSH. Alternatively, you can also use HTTPS to clone the repository (but this is not recommended):
git clone https://github.com/snowball-tech/fractal.git

Note that you can also use the GitHub CLI to clone the repository:
gh repo clone snowball-tech/fractal

When cloned, go into the repository directory:

cd fractal

Pre-requisites

Before setting up this repository and start using it/contributing to it, you'll need to make sure you have some tools installed on your machine.

Click here to see the details

MacOS only

Click for more information

If you are on MacOS, you will need some extra things to make the steps below easier.

Homebrew

First of all, you will need HomeBrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

You can always check the official documentation if you have any question or issue

Shell

You are probably using Zsh as your default shell.

Some steps below are updating the .zshrc file in your home directory. So we have to make sure this file exists:

touch ~/.zshrc

If you are using Bash as your default shell, run:

touch ~/.bash_profile

These commands may give you an error if the files already existed. You can ignore it.

NodeJS

To be able to work with this repository, you will have to have a working version of NodeJS.

You can simply install the latest version of the 18.x.x or LTS 20.x.x build.

To do so, it's recommended to use a Node Version Manager like NVM or N

NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

Note that you may check on the official installation documentation if a newer version is available.

You can always check the official documentation if you have any question or issue

Then restart your terminal (on MacOS you have to completely quit the Terminal application before restarting it).

Then you can make NVM automatically select the appropriate NodeJS version for the repository:

nvm use

N

curl -L https://bit.ly/n-install | bash

Then restart your terminal (on MacOS you have to completely quit the Terminal application before restarting it).

Alternatively, on MacOS you can also run:
brew install n
And then restart your terminal by completely quitting the Terminal application and restarting it.

You can always check the official installation documentation and the official documentation if you have any question or issue

Then you can make N automatically select the appropriate NodeJS version for the repository:

n auto

Yarn

This mono-repository is base on Yarn Workspaces. So you'll have to have Yarn on its 4.x.x version.

When having NodeJS installed, simply run:

corepack enable
corepack prepare yarn@stable --activate

You can always check the official installation documentation if you have any question or issue

Then make sure you have the latest 4.x.x version installed:

yarn --version

This should output a 4.x.x version (e.g. "4.4.1").

Installation

There is an automated setup process that will handle all the steps for you (dependencies, configuration, ...):

yarn && yarn setup && yarn husky

There you go

You are now ready to start working on Fractal.

Usage & Development

It's recommended to regularly update the dependencies and the environment on your local copy of the repository:
yarn

This repository is a mono-repository. This means that it contains multiple packages and applications all together in a single Git repository.

Each of these packages and applications contains their own documentation in their own README.md file.

See the dedicated TOOLING.md documentation for more information about the mono-repository management with Yarn workspaces.

File structure

This repository is organized around two major directories:

fractal
  |-- apps
  |-- packages
  |-- ...

Applications

Applications are located in the apps directory.

This directory contains applications made to be published publicly as documentation support for the whole design system.

There are currently *no applications in Fractal repository.

Packages

Packages are located in the packages directory.

This directory contains packages made to be published in a public NPM repository (https://www.npmjs.com) and used in other packages and/or apps.

There are currently 2 packages available in Fractal:

design-tokens: the list of design tokens defining the design system and to be used in all the apps (web, mobile, ...) and packages throughout the organization;
fractal: the React component library, made of components, styles, icons, ... based on Radix-UI and PandaCSS and to be used in web (React) applications.
It also contains the Storybook documentation that is uploaded to Chromatic and the main documentation webiste.

TypeScript

See the dedicated CONVENTIONS.md and TOOLING.md documentations.

Linting & Formatting

See the dedicated CONVENTIONS.md and TOOLING.md documentations.

Dependencies

Always remember to add dependency if you really need it to avoid cluttering the packages and degrading the performance both in the developers and users side.

It is your duty as a member of the Snowball's engineering team to help mainting the dependencies up to date. This means that you are expected and should help reviewing, testing and merging dependencies updates PRs on a regular basis.

The best way to do so is to regularly check the Renovate dashboard and the list of Pull Requests, for example every morning at the beginning of your day.

Also, see the dedicated TOOLING.md documentation for more information.

Environment variables

See the dedicated TOOLING.md documentation.

Tooling

See the dedicated TOOLING.md documentation.

Contributing

See the dedicated CONTRIBUTING.md documentation.

Conventions

See the dedicated CONVENTIONS.md documentation.

Help and feedback

If you have any questions or feedback, feel free to reach out to us using this repository issues or discussions.

You can also use the internal #engineering Slack channel if you are a member of the Snowball tech team.

You can also check the dedicated TROUBLESHOOTING.md documentation for frequently asked question and troubleshooting.