Skip to content


Repository files navigation

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

🗒️ Create an Issue

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

👩‍💻 Contributing

Conventional Commits

This repository utilizes the Conventional Commits Standard. Utilizing this standard allows us to automatically version our software during the Continuous Integration process and generate 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:

$ yarn bridge:kajabi-products:destroy

Update kajabi-products to the latest Sage version

The Version Bump Process is documented in this wiki article.

Local Scripts

The following scripts can be run by typing yarn <script_name> in the root of this repository. ⭐'s have been added to signify typical user-initiated tasks.


Proxy for the Lerna bootstrap command. This will install all dependencies and link any cross-dependencies of the monorepo.


This command creates a local "bridge" between your local Sage packages and the Kajabi Products repo. Use this bridge when you want to locally edit changes in Sage and see them live in Kajabi Products.


Displays the status of the local bridge link


Destroys the bridge created by bridge:kajabi-products


Runs all build:* based scripts


One time build of the @kajabi/sage-assets package


One time build of the @kajabi/sage-react package


One time build of the @kajabi/sage-system package


Utilize Commitizen to generate a commit message following the Conventional Commit Standard


Start the documentation site from the docs/ folder. Will be located at http://localhost:4000/


Run bundle install on the docs/ folder.


Initialize the docs site. Install all gems/packages


Destroy any local link between the Sage Rails gem and the internal Sage Packages


Determine the current required "bump type" for the Sage Rails gem. This value is based on the current version value of the npm package it is associated with. (null|patch|minor|major|ect.)


Run all lint:* scripts


Lint the @kajabi/sage-assets package


Establish a local link between the Sage Rails gem and the internal Sage Packages


Run the SassDoc server from the @kajabi/sage-assets package.


Run the initial setup scripts


Install local packages for the main repository and docs/ path


Continually compiles packages on changes and starts the applications.


Launch "storybook" from the @kajabi/sage-react package


Run all test:* scripts


Run the test suite on the @kajabi/sage-react npm package


Get the current version of the @kajabi/sage npm package


Get the current version of the sage_rails gem


Get the current version of the @kajabi/sage-assets npm package


Get the current version of the @kajabi/sage-react npm package


Get the current version of the @kajabi/sage-system npm package


Run all watch:* scripts


Continually watch and build the @kajabi/sage-assets npm package


Continually watch and build the @kajabi/sage-react npm package


Continually watch and build the @kajabi/sage-system npm package





CI/CD, Releases, and Versioning



The gem is available as open source under the terms of the MIT License.