design-tokens |
fractal |
|---|---|
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.
Before anything, start by cloning the repository:
git clone [email protected]:snowball-tech/fractal.gitIf 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 fractalBefore 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
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 ~/.zshrcIf you are using Bash as your default shell, run:
touch ~/.bash_profileThese commands may give you an error if the files already existed. You can ignore it.
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
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bashNote 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 usecurl -L https://bit.ly/n-install | bashThen 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 nAnd 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 autoThis 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 --activateYou 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 --versionThis should output a 4.x.x version (e.g. "4.5.1").
There is an automated setup process that will handle all the steps for you (dependencies, configuration, ...):
yarn && yarn setup && yarn huskyYou are now ready to start working on Fractal.
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.mddocumentation for more information about the mono-repository management with Yarn workspaces.
This repository is organized around two major directories:
fractal
|-- apps
|-- packages
|-- ...
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 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.
See the dedicated CONVENTIONS.md and
TOOLING.md documentations.
See the dedicated CONVENTIONS.md and
TOOLING.md documentations.
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.
See the dedicated TOOLING.md documentation.
See the dedicated TOOLING.md documentation.
See the dedicated CONTRIBUTING.md documentation.
See the dedicated CONVENTIONS.md documentation.
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.