Install the Pharos design system using one of the following commands:

# yarn
   yarn add @ithaka/pharos
   

   # npm
   npm install @ithaka/pharos

Once installed, the node_modules/ directory should contain directories similar to following structure:

@ithaka/pharos/lib
      ├── assets/
      │   ├── icons            // Pharos icons (used with the icon component)
      ├── components/          // Folder containing web components
      ├── react-components/    // Folder containing React components
      ├── styles/
      │   ├── _variables.css   // Commonly used tokens for styling
      │   ├── fonts.css        // CSS to have fonts available to use
      │   ├── typography.scss  // CSS styles to apply fonts and styles to root elements
      └── ...

Pharos uses Web Components to remain compatible with modern JavaScript frameworks, such as Vue or React. To accomodate patterns of each framework, the implementations vary slightly.

You will first need to provide the scoped custom element registry to your application. This is generally achieved by including this script tag in the head of your application.

<script src="https://cdn.jsdelivr.net/npm/@webcomponents/scoped-custom-element-registry@0.0.3/scoped-custom-element-registry.min.js"></script>

You then need to register components on the custom element registry for them to be usable in your code. To register components, you can use theregisterComponents utility to define all the Pharos components your application uses, with a consistent scoping prefix:

import {PharosAlert, PharosButton, PharosIcon} from '@ithaka/pharos';
        import registerComponents from '@ithaka/pharos/lib/utils/registerComponents';

        registerComponents('homepage', [PharosAlert, PharosButton, PharosIcon]);

To manually register a component, import the classes you wish to use in your application's entrypoint and define the custom element with a tag name in the form of {app / bundle}-pharos-{component} and a trivial subclass that extends the Pharos class wrapped in the PharosComponentMixin:

import {PharosAlert} from '@ithaka/pharos';
        import PharosComponentMixin from '@ithaka/pharos/lib/utils/mixins/pharos-component';

        customElements.define('homepage-pharos-alert', class extends PharosComponentMixin(PharosAlert) { });

To demonstrate the usage in both Vue and React, you'll next see how to use the Button component.

The following code shows how to use Pharos's button component with React to produce a basic button, as seen below the code

import {PharosButton} from '@ithaka/pharos/lib/react-components';
          ...

        <PharosButton>
          React button
        </PharosButton>

Similarly, the following code shows how to use Pharos's button component with Vue to produce a basic button, as seen below the code

<template>
          ...
          <pharos-button>
            Vue button
          </pharos-button>
        </template>

The props for each component control various parts of the component, from style to function. Learning which props are available for each component, along with how they interact with the component, is crucial in using the Pharos design system. Pharos components are fully documented to allow IDEs to take advantage of intellisense features, which in turn allows you to browse through props.

For a more interactive approach to understand props, Pharos provides a Storybook. Our Storybook stories demonstrates the usage of props for each component, while providing the code used in the demonstration. Many components' stories allow you adjust the values of different props to preview and understand the impact of those props.

As part of the package, Pharos includes a few curated fonts that are integrated into components. To allow consistency between components and other elements, you should use these fonts for other parts of the site. If you want to read more about Pharos' typography, including guidelines for font usage scenarios, head over to the typography page.

To use the correct fonts, start by importing them by importing @ithaka/pharos/lib/styles/fonts.css at the top level of your web app. Once imported, set the root body font and styles by importing @ithaka/pharos/lib/styles/typography.scss. If there are places where the body font is being overwritten, apply the font wherever the style is being overwritten by setting the font-family property to include either GT America Standard (generally for body) or Ivar Headline (generally for headers).

The following examples use inline styling, but the same principles remain for other methods of styling.

<script>
          import "@ithaka/pharos/lib/styles/fonts.css";
          import "@ithaka/pharos/lib/styles/typography.scss";          
        </script>

        <template>
          <div class="text">
            This is an example of text with Pharos fonts.
          </div>
        </template>

        <style lang="scss">
          .text {
            font-family: GT America Standard;
          }
        </style>

import "@ithaka/pharos/lib/styles/fonts.css";
        import "@ithaka/pharos/lib/styles/typography.scss";

        const styleObject = {
          fontFamily: "GT America Standard"
        }

        ...  //in render method
        <div style={styleObject}>
          This is an example of text with Pharos fonts.
        </div>
        ...

Pharos components use design tokens to keep values consistent for all facets of design, including spacing, size, and colors. These design tokens are also provided to developers using Pharos in order to provide assistance in creating a consistent look and feel in pages where both Pharos components and other elements exist.

To start using the design tokens, import the @ithaka/pharos/lib/styles/_variables.scss file and use the desired token in the styles for your web app. You can inspect the imported file to see all the tokens and their corresponding values.

To use Pharos efficiently, you should understand the principles and structure surrounding the design system. Start by getting familiarized with Code structure and Conventions. The anatomy of components covers the general structures and how-tos of components, stories and styles.

Going through the change log will help you stay up-to-date on important changes.

Learn more about JSTOR's visual language and brand expressions that create consistency and clarity across our experiences.

Interested in contributing to the design system? Pharos is the result of collective contributions of code, design, and guidance—we'd love to hear your input and ideas!