Skip to main content

Add Pando to a Website

You don't have to build your whole project using Pando. Adding our base Themes and Typography doesn't require installation, only takes a minute, and lets you start using beautiful styles right away!

Adding Pando in one minute

Pando has been designed from the start for gradual adoption. There are many teams in today's world that operate with "Frankenstein apps". This guide shows you how to add the foundations of Pando to an existing setup.

If you would like to fully migrate to Pando, you can still use this guide! Just be sure to use the following steps after your current UI setup. When you are done - remove the old setup and you will have a pure Pando app!

Step 1: Add the fonts

In order to display and use the correct font, we need the browser to load it first. Hover over the code and click the copy button in the top right corner of the snippet.

<meta name="viewport" content="initial-scale=1, width=device-width" />
<link
  rel="preload"
  href="https://fonts.pluralsight.com/ps-tt-commons/v1/ps-tt-commons-variable-roman.woff2"
  as="font"
  type="font/woff2"
  crossorigin
/>

This code will tell the browser to preload the font assets, which will help boost performance in your application.

Pluralsight Commons is a variable font which means that styling requires different properties than an non-variable font.

Step 2: Add the normalize reset

Now that we have the fonts installed, paste the following into the same HTML page after the font installation:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@pluralsight/design-tokens/fonts.css"
/>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@pluralsight/design-tokens/npm/normalize/normalize.css"
/>

These links declare the font rules and add our "built-in" themes, resets, and typography styles.

You may notice breaking styles and weird UI results after doing this. This is normal when combining multiple CSS foundations into an existing app. The following steps are ways to approach fixing them.

Step 3: Update your typography

Once you've completed the first two steps, you may notice some weird styling conflicts if you are combining Pando with an existing UI library. Now is the time to update your typography to match what you need using semantic HTML.

- <div className="title">Some Page Title</div>
+ <h1>Some Page Title</h1>

If you are using typography components, replace them with semantic HTML:

- import { P } from '@pluralsight/ps-design-system-text'

- <P>Some body copy example using a component.</P>
+ <p>Some body copy example using semantic HTML</p>

With Pando, you don't have to worry about typography components or classes for most of the use cases (although we do offer "opt-in" classes for things like display headings and lists). All you have to do is use the correct HTML elements as they were intended.

Accessibility is our highest priority in Pando, and HTML text elements are naturally accessbile, so we've built our reset around this concept. Use the correct HTML and you will get both styling and Accessibility! 🎉

Using Pando Components

We have a growing list of components that you can use in your application. These components are built with our Headless-styles API and are designed to be as accessible as possible.

This section assumes you are familiar with package managers like NPM and Yarn.

Step 1: Install React, Headless-styles, & Icons packages

npm install @pluralsight/{react,headless-styles,icons}

Step 2: Replace Components

Now that you have the packages installed, let's try updating something like a Button!

- import { Button } from './components/Button'
+ import { Button } from '@pluralsight/react'

- <Button appearance={Button.appearances.secondary}>Cancel</Button>
+ <Button sentiment="danger" onClick={handleCancel}>Cancel</Button>

Diving Deeper with Headless Styles

If you are looking to full control of styling for your components and icons, it's time to bring in our Headless-styles library.

This section assumes you are familiar with package managers like NPM and Yarn.

Step 1: Install Headless-styles & Icons packages

npm install @pluralsight/{headless-styles,icons}

Step 2: Replace Icons

Most Icon libraries are pretty flexible. Pando Icons allow you to import three different types of Icons: React (default), Svelte, or SVG.

import { getIconProps } from '@pluralsight/headless-styles'
import type { IconOptions } from '@pluralsight/headless-styles/types'

interface IconProps extends IconOptions {
  icon: ReactElement;
}

export function Icon(props: IconProps) {
  const { icon, ...iconOptions } = props
  const El = icon
  return <El {...getIconProps(iconOptions)} />
}

Now, you have an easy to use Icon component that you can refactor your code with!

- import { CodeIcon } from '@pluralsight/ps-design-system-icon'
+ import { CodeIcon } from '@pluralsight/icons'
+ import { Icon } from './components/Icon'

- <CodeIcon size={CodeIcon.sizes.medium} />
+ <Icon icon={CodeIcon} />

Step 3: Replace Components

Now that you have a better feel for replacing a simple component, let's repeat the process for something like a Button!

import type { HTMLProps, PropsWithChildren } from 'react'
import { getButtonProps } from '@pluralsight/headless-styles'
import type { ButtonOptions } from '@pluralsight/headless-styles/types'

interface ButtonProps extends ButtonOptions, HTMLProps<HTMLButtonElement> {}

export function Button(props: PropsWithChildren<ButtonProps>) {
  const { children, onClick, ...btnOptions } = props
  const { button } = getButtonProps(btnOptions)

  return (
    <button {...button} onClick={onClick}>
      {children}
    </button>
  )
}

Now rinse and repeat, replacing the Buttons in your app!

- import Button from '@pluralsight/ps-design-system-button'
+ import { Button } from './components/Button'

- <Button appearance={Button.appearances.secondary}>Cancel</Button>
+ <Button sentiment="danger" onClick={handleCancel}>Cancel</Button>