The name "Pyxis" comes from a small constellation in the southern sky. It's the latin term for compass and we chose it to indicate the path to follow for the designs of Prima.
Pyxis is our Design System which helps developers and designers to create complex UIs and UXs by relying on a solid foundations of best-practices and recognizable colors and patterns.
Pyxis modules are abstraction which help your team to quickly prototype and build experiences without relying on low-level stuff in a common way through Prima organization.
Please note that Pyxis is strongly opinionated and maintained by the Pyxis Team.
This repository takes advantage of Lerna and its capabilities to handle multiple repositories inside a so-called monorepo.
By consequence you'll find out that Pyxis is made of different sub-packages:
Name | Source | Description |
---|---|---|
@pyxis/scss |
Source | Core Scss and CSS module. Mandatory usage. |
@pyxis/elm |
Source | Elm components and live documentation via Elmbook. |
@pyxis/react |
Source | React components and live documentation via Storybook. |
@pyxis/icons |
Source | Svg icon pack. |
@pyxis/tokens |
Source | A representation of Design Tokens which define some Pyxis' core aspects. |
By following this guide you'll learn how to install Pyxis and where to find the documentation for your project.
Pyxis is deployed on a JFrog Artifactory repository with npm
integration. By consequence you should install the JFrog cli in order to get things work.
You'll also need to ask DevOps for a JFrog Artifactory account in order to continue.
Now you want to instruct npm
to download the packages from Prima's Artifactory registry instance. To do that follow the steps below:
-
Configure the Artifactory registry for Pyxis by running the command below in your terminal.
$ npm config set @pyxis:registry https://prima.jfrog.io/artifactory/api/npm/pyxis-global/
-
From JFrog User Profile generate an
ApiKey
. This will be used to authorize your profile when pushing/pulling from JFrog. -
In your terminal run:
curl -u <JFROG_USER>:<JFROG_APIKEY> https://prima.jfrog.io/artifactory/api/npm/auth >> ~/.npmrc ## Usage example with user="aturing" apikey="3n1gm4?3n1gm4!3n1gm4?" ## curl -u aturing:3n1gm4?3n1gm4!3n1gm4? https://prima.jfrog.io/artifactory/api/npm/auth >> ~/.npmrc
-
Your
.npmrc
should now look like this:## File: .npmrc ## This line instruct npm to retrieve @pyxis packages from Artifactory. @pyxis:registry=https://prima.jfrog.io/artifactory/api/npm/pyxis-global/ always-auth=true _auth="a-very=very_very-long_auth_token=" [email protected]
⚠️ We're aware about Artifactory's ability to handle third-part dependencies itself. This feature will be available in future releases according to DevOps. -
Save and close the file. You should now be able to use Pyxis npm modules like this:
$ npm i @pyxis/scss # Or # npm i @pyxis/react # npm i @pyxis/icons
⚠️ This isn't suitable for Pyxis Elm package. -
You're now ready to use Pyxis in your application. Follow the Documentation in order to learn how to use Pyxis.
Before diving into documentation you should choose between using Pyxis' precompiled CSS and Pyxis' SCSS source.
Infact the use of Pyxis stylesheet is mandatory. You cannot do anything with Pyxis without relying on its core (foundations & components).
Once you chosen the solution which fits the best for your project you can go ahead with learning Pyxis.
Package | Live documentation | Readme | Mandatory |
---|---|---|---|
SCSS | https://prima.design/ | Readme | X |
Elm | https://elm.prima.design/ | Readme | |
React | https://react.prima.design/ | Readme | |
Icons | n/a | Readme | |
Tokens | n/a | Readme |
Pyxis was built as a single repository with development simplicity in mind.
We use Yarn workspaces for handling dependencies and Lerna to manage versioning and publishing.
Run the following commands to setup your local dev environment:
# Install `yarn`, alternatives at https://yarnpkg.com/en/docs/install
$ brew install yarn
# Clone the `pyxis` repo
$ git clone [email protected]:primait/pyxis.git
$ cd pyxis
# Install dependencies
$ yarn install
# Run React live-documentation dev server
$ yarn storybook:serve
# Run Elm live-documentation dev server
$ yarn elmbook:serve
For more in-depth instructions, development guidelines etc., see the README files for each sub-repository.
Pyxis also includes @pyxis/icons
, a repository which contains all of our SVG icons.
Automatic code generation lets us turn these icons into React components and Elm functions, by running the following command:
$ yarn generate:icons
Pyxis foundations is a set of constants derived from the design token entities.
To generate fresh tokens, run the following command:
$ yarn tokens:build