README.md

March 12, 2024 · View on GitHub

sage design system logo

Sage Design System

The Sage Design System is our single source of truth, providing everything you need to build great products for our customers. It is the culmination of designers and developers working together to give teams the ability to ship high-quality products faster.

📚 Documentation

To use Sage in your application, see our Documentation Site
To view the documentation for contributing to Sage, see our internal Wiki

🗒️ Create an Issue

Do you have an issue, bug, or suggestion you would like to add to the Design System? Create an issue!

This repository utilizes the Conventional Commits Standard. Utilizing this standard allows us to automatically version our software during the Continuous Integration process and generate CHANGELOG.md files for each package.

Unsure how to format your commit message?

Use yarn commit to launch a wizard to walk you through with Commitizen

A commit-msg hook has been added to the repository to enforce this behavior. Ensure you have read over the convention and understand it before making a Pull Request.

Repo Structure

There are five total packages in the monorepo:

Package	Description	Location	README	CHANGELOG
@kajabi/sage	Gem with Rails components and a documentaiton site of the same	`./docs`	README	CHANGELOG
@kajabi/sage-assets	Styles and a Sassdoc site of the same	`./packages/sage-assets`	README	CHANGELOG
@kajabi/sage-packs	Packs `sage-assets`, `sage-system`, and `sage-react` for use in Rails applications.	`./packages/sage-packs`	README	CHANGELOG
@kajabi/sage-react	React component library and Storybook for documentation	`./packages/sage-react`	README	CHANGELOG
@kajabi/sage-system	JS scripts for use with the Rails components	`./packages/sage-system`	README	CHANGELOG

Outside of these packages is a dictionary of tokens built using Style Dictionary. This provides a central location for storing constant values and component configurations that is distributed to each respective package. Learn more

Lerna Mono-Repository

The Sage Design System is a Lerna Mono-Repository (or a monorepo for short). From the Lerna README:

Splitting up large codebases into separate independently versioned packages is extremely useful for code sharing. However, making changes across many repositories is messy and difficult to track, and testing across repositories becomes complicated very quickly.

To solve these (and many other) problems, some projects will organize their codebases into multi-package repositories (sometimes called monorepos). Projects like Babel, React, Angular, Ember, Meteor, Jest, and many others develop their packages within a single repository.

Lerna is a tool that optimizes the workflow around managing multi-package repositories with git and npm.

Lerna can also reduce the time and space requirements for numerous copies of packages in development and build environments - usually a downside of dividing a project into many separate NPM packages.

Adding Packages

This repository utilizes Yarn Workspaces, which allows for the setup of multiple packages in such a way that you only need to run yarn install from the root of the repository, and all packages will be updated. In addition, the syntax is provided to target installation towards specific packages or the entire suite. Below are examples of adding packages:

# Adds the module-1 package to the packages in the 'prefix-' prefixed folders
$ yarn lerna add @kajabi/sage-assets packages/sage-*

# Install @kajabi/sage-assets in @kajabi/sage-react
$ yarn lerna add @kajabi/sage-assets --scope=@kajabi/sage-react

# Install @kajabi/sage-assets in @kajabi/sage-react as a devDependency
$ yarn lerna add @kajabi/sage-assets --scope=@kajabi/sage-react -D

# Install @kajabi/sage-assets to @kajabi/sage-react as a peerDependency
$ yarn lerna add @kajabi/sage-assets --scope=module-2 -P

# Install @kajabi/sage-assets in all modules except @kajabi/sage-assets
$ yarn lerna add @kajabi/sage-assets

# Install babel-core in all modules
$ yarn lerna add babel-core

Local Development

Getting Started

Run the Setup script:

$ yarn setup

If this is your first time using Sage you will be prompted to provide a GitHub Personal Access token. This token will be placed in your global ~/.npmrc file, if it exists, or an ~/.npmrc file will be created for you. If the Sage installer identifies a GitHub Access token in your ~/.npmrc you will not be prompted. You can find more information on obtaining a token here.

Start the suite:

$ yarn start

To visit the primary documentation site: http://localhost:4000/

To visit the Storybook (React components) site: http://localhost:4100/

To visit the Sassdocs (Sass documentation) site: http://localhost:4200/

Bridging Kajabi Products

The Kajabi Products repository needs to be locally linked to your Sage repository in order to have live reloading of your changes during your development cycle. This process is natively handled by Sage:

$ yarn bridge:kajabi-products

If this is your first time using yarn bridge you will be prompted to provide your path to your local Kajabi Products repository. This path can be absolute (~/home/me/code/kajabi-products) or relative (../kajabi-products). The value you enter will be inserted into your local .env file. If a .env file does not exist one will be created for you based on the .env.dist file in this repository.

Note: In the event you mistype your repository path or its location changes, you can edit its value in the .env file

When running the bridge, you must have yarn start running in this repository for your changes to be actively compiled.

Within your Kajabi Products repository, run the project as you usually would and in tandem also run Kajabi-Products' webpack-dev-server. For Kajabi Products to watch changes within your local Sage repo webpack-dev-server needs to be running.

$ bin/webpack-dev-server

Destroying the Kajabi Products Bridge

From time to time you will need to destroy your Kajabi Products Bridge and utilize the production version of the packages on the branch. To destroy the bridge: