Odyssey

Odyssey is Okta’s official design system that consists of reusable components to design and build products, websites, and features.

Table of Contents

• Getting Started
  • Running the Design System Docs
• Packages
  • Monorepo
  • Versioning
  • Development
    • Publishing a new version

Getting started

We use Yarn as our node package manager client. To install Yarn, check out their installation instructions.

# Clone this repo and navigate into it

git clone git@github.com:okta/odyssey.git
cd odyssey

# Install all package dependencies
yarn install

Running the design system docs

Want to see Odyssey in action? Our docs package contains a static website styled using Odyssey. Simply run the following command to launch it:

# Generates the design docs website
yarn docs

Once the website is built, visit http://localhost:8080/ in your browser.

Packages

Monorepo

This repository is managed as a monorepo using Yarn Workspaces for dev dependencies and Lerna for everything else. You can think of each package as a separate npm module - each with their own dependencies, package name, and versioned using Semantic Versioning.

Packages are parsed from the workspaces property in package.json, and adhere to this structure:

packages/
  docs/
  odyssey-icons/
  odyssey/
  vuepress-theme-nimatron/

Versioning

Package	Status	Description
odyssey		All necessary SCSS and fonts to utilize Odyssey, Okta's design system.

Development

Publishing a new version

Before publishing a new version, ensure the following steps are performed:

1. All changes our outlined in the package's CHANGELOG file. If there are breaking changes, attempt to create a migration guide.

2. Increment the package versions following Semantic Versioning.

   yarn lerna-version
   
   # Console output will appear similar to:
   ? Select a new version (currently 0.0.1) (Use arrow keys)
   ❯ Patch (0.0.2)
     Minor (0.1.0)
     Major (1.0.0)
     Prepatch (0.0.2-alpha.0)
     Preminor (0.1.0-alpha.0)
     Premajor (1.0.0-alpha.0)
     Custom Prerelease
     Custom Version

3. Commit your changes and submit the CHANGELOG for approval. Once approved, merge into master.

4. (Internal use only) Reach out in the #odyssey slack channel to promote the package to public NPM.