Pharos: JSTOR’s design system serving the intellectually curious

A detailed account of our journey of building a design system from the ground up

Pharos: JSTOR’s design system

We’re excited to share Pharos, JSTOR’s design system. Pharos is named after “The Pharos of Alexandria,” a large lighthouse that stood in the harbor near the Library of Alexandria — one of the largest libraries in human history, a name fitting for JSTOR, an online library for researchers to make new discoveries and connections.

The Pharos design system acts as a guiding light for our product teams to create cohesive, supportive, and beautiful experiences for the intellectually curious.

We’ve worked diligently over the last year and a half to build this new, powerful system for JSTOR’s products to ensure consistency and efficiency as we create impactful experiences for our users. We open sourced and are sharing our system publicly to help others in the design and product community learn from our experience, and to strengthen Pharos with their feedback and contributions. This article is a detailed account of our journey in creating a design system from the ground up.

About JSTOR

JSTOR is a digital library for understanding our world. We bring together scholarship, images, and primary sources for better research and learning. Millions of scholars, educators, and students around the world begin their research on JSTOR.

Why did we need a design system?

Expanding our offerings

Over the past few years, we’ve been expanding the types of content we offer beyond journals and books to include images and other primary sources. We are also using our platform to help libraries share their special collections with the world.

A refreshed brand

To support this growth in content and collaborators, the JSTOR brand needed to evolve. For more than 18 months, the brand team worked toward developing a fresh brand for JSTOR, and we needed a way to bring it to life in the product.

We refreshed all of JSTOR’s core brand elements, what we like to call our brand expressions: typography, color, logos, imagery and illustration.

Our previous style guide

We had an existing style guide for JSTOR called Bonsai, but we knew it wouldn’t live up to our growing needs. Through a set of interviews with 20+ people across disciplines, we uncovered Bonsai’s challenges and opportunities. Bonsai:

• Was treated as a one-off project with no governance or guidance
• Didn’t support new technology needs (components were built in jQuery)
• Failed to bring platform teams in as contributors
• Didn’t support our new brand needs

Ultimately, usage of Bonsai by product teams varied dramatically, and many teams either recreated components or went rogue with design and implementation.

For designers, the style guide in Sketch was no different. Designers mostly “borrowed” from it rather than integrating into their files. Inconsistent component and style implementations were repeated as designers duplicated files when designing new features or experiences, contributing to the greater consistency problem all the way through to production.

Our old “WIP-Master.sketch” file circa 2017.

Getting started

Let’s get in formation

Recognizing the value of a dedicated design system team, a group of us worked to make it a reality in 2019 by garnering buy-in from leadership, the “Blueprint” team was assembled. We were tasked with enabling our platform teams to build software more efficiently, consistently, and collaboratively. We first aligned on a mission and set of values to ground ourselves and create trust with our users.

Mission

Our promise is to create an effective, governed design system that can be adopted across products that is sustained with a dependable, predictable set of transparent processes.

Values

Our values still hold true today and have a fun acronym: “CODEBFF”

Create simple solutions for a consistent experience across products
We favor the elegance of simplicity over the flexibility of complexity. As we increase in complexity, we take care in how much of that complexity gets transferred to our users.

Operate transparently
We aim to work in the open. We’re not the only ones who know the status of the system and we encourage contribution.

Document effectively
Documentation is a tool that teaches how elements of a system can be used, and encourages contribution. Our solutions should drive efficiency through well-defined and reusable components.

Empower autonomy
We provide solutions to problems repeatedly faced by designers and developers so they can make decisions more easily and consistently for their own products.

Build for product adoption
We will measure our success on the level of adoption and usage of our tools. The value of the system isn’t realized until users actually use what we make.

Favor quality over quantity
The work we do is nothing if the quality is poor or below our standards.

Foster a community
We favor community over control. It’s important we collaborate, negotiate, and work well with others.

Audits and workshops

We leaned heavily on our past experiences and learnings with Bonsai and resources from the greater design system community to understand how to start off on the right foot.

We hosted a variety of workshops from Nathan Curtis:

Interface audit
We wanted to better understand the implementation of our current style guide and identify component and pattern needs. Instead of doing the component cut-up workshop, we audited each page together and documented our observations in Google Slides.

Our team audited each page of JSTOR’s product. Seen here is the “Workspace”, a place where users can save and organize useful content to return back to later.

“How do I?” activity
We used this activity to identify and prioritize future processes and their timing. It helped us determine what our focus was going to be for Q1 2020 and more loosely for the rest of the year.

Here’s Robb, Jayshree, and Dane working together to ponder some questions and when we should have them answered for our users with the “How do I” activity.

We added the activity results to a spreadsheet to account for our decisions and help us create an initial roadmap.

Pilot scorecarding from Dan Mall
This exercise is meant to find good potential candidates for a pilot, and evaluate them against a set of criteria used to determine a pilot’s potential efficacy.

Our pilot component score card to help us determine our first component.

User testing
The pilot scorecard helped us narrow in on a pilot component and a proof-of-concept implementation workflow. We tested the thoroughness and ease of use with each of our product teams before scaling an approach.

One of our teams successfully adding an “error” Alert to a page in JSTOR.

“Parts, Products and People” workshop
This workshop is meant to understand what components you want to build with the folks dedicated to helping achieve the work. We had our dedicated team in place already and a loose idea of our governance model, so we used this workshop to include our front-end colleagues in selecting Pharos’ first few components to build.

Blueprint invited developers and product designers from each of our product teams together for a “Parts, products, and people” workshop to determine Pharos’ first components.

Building Pharos

Prioritizing accessibility

Creating an inclusive experience was a top priority for us.

While rebranding, we carefully considered selections for our color and typography. Our colors were reflective of our brand, but also met the needs for contrast in the way we used them for text and interactive styles.

Each color was tested for color contrast against each other.

Our typefaces were also carefully selected for great legibility, as the letters had generous x-height, open apertures, clear terminals, and even spacing. JSTOR’s workhorse feature, search, called for great readability and scannability of a user’s results.

Our serif typeface, Ivar from Letters from Sweden, is strongly influenced by the construction of Times, one of the most popular typefaces of all time for its clarity and easy on screen readability. We selected Ivar for its beautiful shapes, contrasting terminals, and considerable x-height. It also reminded us of the filigree in our JSTOR logo.

Our sans-serif typeface, GT America from Grilli Type, a grotesque sans serif with more of a human touch than usual in the genre, leads to a much better performance in legibility and readability, especially on screens.

Components

We also baked in accessibility needs for each of our components and did manual testing to ensure that component behavior was expected, such as tab order, keyboard commands, and using a screen reader to verify information was read correctly. We also utilized Storybook’s accessibility add-on to ensure we met accessibility standards and ran axe-core on all components in our tests.

Examples:

Headings
We decoupled heading sizes and styling from the HTML elements, separating the semantic structure needs, or “levels,” from the styling needs, or what we call “presets.” This means the design choices aren’t directly associated with H1, H2, H3, and so on. In Pharos, the “level” prop designates the heading level needed to create a logical information hierarchy. The “preset” prop provides specific styling to create visual hierarchy for better scannability. This approach allows us to pair the desired styling with the correct heading level.

Hover and focus states
We wanted to provide greater contrasts between interactive states for our buttons and links, helping signify to users that their pointing device is within their boundaries, and that a click event will activate it. So we chose to use color plus another visual element to make the interactions — hover and focus — more obvious.

For example, for our primary buttons, on hover, the background color changes to white with a JSTOR Red, thicker 2px border, providing a 8.91:1 contrast ratio.

For links, we either display or remove the underline and pair it with a color change.

For most of our components, we allocate a styled focus state using a 2px “Glacier Blue” outline, rather than using the hover state styling or browser default, to clearly delineate between the different interaction states. It also creates an expected, distinct, and consistent styling for all of our components’ focus states.

Architecture

When architecting Pharos, our top priority was to meet the needs of our product teams and ensure it improved delivery of new experiences. Our teams are empowered to choose technology best suited to their skills and preferences. The primary JavaScript frameworks used by teams are Vue and React. Given the scope of needs, we built separate packages for each “flavor” of JavaScript, including vanilla JavaScript with HTML for applications that didn’t use either framework.

Web components
It became apparent that maintaining three separate versions of the same component was going to be burdensome and hinder the system’s effectiveness. This led us to consider other solutions to meet our teams’ technological requirements without sacrificing speed and maintainability.

We landed on using web components, a set of web standards for creating custom, reusable, and encapsulated HTML elements. As a web standard, web components help guarantee longevity because they are framework agnostic and relatively stable, unlike JavaScript frameworks that are frequently updated or become obsolete after a few years. Web components also provide an encapsulated “shadow” DOM tree. The shadow DOM renders separately from the main document DOM, which keeps the element’s features and styles private. Because a design system is opinionated in its representation of a brand, the ability to discourage adopters from overwriting styles supported our goal to ensure consistency on the platform.

Design tokens

We infused our brand and visual design decisions in named entities called design tokens, which helped us avoid repeating hard-coded values and carry new decisions forward everywhere they’re used.

Tokens provide a bridge between design and development to ensure everyone is using the same values, whether they’re designing or implementing experiences.They’re not simply “variables,” but powerful elements that establish and uphold our standards.

Although tokens capture high-level brand decisions like core color and typography choices, they’re also useful for capturing more granular decisions like border radii or padding for specific components, and can take the form of global, alias, or component tokens.

Global design tokens
Global design tokens are the truest form of a design element and can be used directly or be inherited by other tokens.

JSTOR Red is one of our global colors that acts as a basis for the color itself to be used as needed.

Alias design tokens
Alias tokens are abstractions of our global tokens, and are named for their intended use or context. We use them when their purpose (e.g., primary interactive color) can be applied in multiple use cases.

In this example, we created an alias token for our primary interactive color, as it’s used across several of our Pharos components to signify interactivity.

Here is an example of our primary interactive color being used with the default primary button, it’s hover state and also the hover state of our links.

Component Tokens
Component tokens are a platform-agnostic representation of how a component should be styled that utilize global and/or alias tokens.

For text inputs, we created a component token for the invalid or error state that is used across all of our form elements, including selects, radio buttons, checkboxes, etc.

By sharing the tokens to Storybook and the Pharos site, adopters could see the visual versions and values of the tokens rather than rely on design annotations or a giant compiled variables.scss file.

The first image shows how our spacing tokens appear along with their values and names. The second image shows a screenshot of the variables.scss file.

Adoption: The buddy system

In the early days, we tested the adoption of Pharos with a “buddy system” approach. Members of Blueprint paired with developers from each team for one sprint to onboard them to the Pharos implementation experience.

Our pairing sessions revealed:

• A positive developer experience.
• Unexpected issues and bugs that needed resolving.
• Pairing with Blueprint eased the learning curve of Pharos implementation

In this pairing session, one of the teams gave us feedback on their own implementation of one of our more complicated components, the layout component.

We also paired with each of the product designers to explain how to use our Figma UI Kit and its styles, and how to contribute or create a new component from scratch.

Contribution

The first contributions to Pharos from our community were planned, whereas subsequent contributions have happened organically as teams were building new experiences or revisiting old ones.

In Q2 2021, we focused on encouraging new contributions, working with our product teams to identify new Pharos needs at the beginning of the quarter. We even created a measurable goal:

Promote shared ownership via knowledge sharing leading to an increase in non-Blueprint GitHub contributors from 11 to 15.

Eventually, we’d like to start tracking and increasing repeat contributions from colleagues outside the Blueprint team.

Design contribution

There’s a fair amount of training when adding new components to our Figma UI Kit, so we employed the “buddy system.” We often design paired or held design jams to understand the possible needs for a component across experiences. We walked through the process of creating the exact variants in Figma and publishing to the shared library to ensure designers felt enabled and comfortable contributing new elements to Pharos.

Plotting out the variants for a toggle button group component with one of our designers.

Celebration

The Pharos GitHub repo showcases our contributors and their contributions, from design to documentation to component creation to accessibility.

Creating community

Tactics

Our Bonsai days taught us that being inclusive and transparent was going to be critical for our system’s success. We wanted to use the power of community building to scale and drive adoption and contribution. We employed a variety of communication tactics to share progress, educate, and establish trust.

Hands-on workshops and learning sessions
We hosted learning sessions to teach our teams about what a design system even is and its life cycle.

Our first learning session was “Design Systems 101” to create a baseline understanding of the purpose and function of design systems in general.

Weekly Slack posts
Slack helps us connect with our users and provide support. Additionally, we post weekly announcements that outline completed work, what’s coming up, relevant resources, and shoutouts.

Here’s an example of one of our Pharos weekly announcements in slack, outlining upcoming and past work from our last sprint.

“Bluesletter”: our quarterly email newsletter
Our quarterly newsletter, the Bluesletter, shares learnings and work with platform teams, encourages conversation, and promotes collaboration. We also have some good old-fashioned fun with it, like having “Friends”-themed subject lines.

The Bluesletter, “All the news that’s fit to Blueprint”

Community surveys
Surveys help us better understand our users’ experience with Pharos. It’s also one of our approaches to measuring Pharos’ success.

Pharos community survey results

Celebrating milestones together
When we open sourced Pharos, we invited our community to join us. It was great fun and showed us we were building something special, together.

Slack invitation to join us in open sourcing Pharos, the message reads, “Hi folks! I am proud to announce that Pharos will be going open source today. It’s been quite the journey but I am so excited for us to reach this next milestone. We will be having a release celebration today at 4 pm! React with {emoji} if you’d like an invite. All are welcome.”

Caption: A screengrab of a video call with several members of the Pharos community joining Blueprint while we were opening sourcing Pharos.

“Show and Tells”
ITHAKA hosts Show and Tells every two weeks to allow teams to share quick stories of how what they’re building provides value to end users. We often take advantage of these to share announcements, learnings, implementations, successes, and failures. In the early days, we often paired with other teams in sharing their implementation experience of Pharos.

One of our show and tells reviewed our newest Pharos design tokens.

Creating an advocacy group

While Pharos gained more adoption and contribution, we began to notice a trend. Though Slack was a useful tool for our users to report issues, pose questions, or express suggestions, our community saw Blueprint as the core makers, fixers, and publishers rather than feeling empowered or motivated enough to help themselves and others. The process became bottlenecked, inadvertently, by Blueprint. To achieve the shared ownership we intended, we created an advocacy group called the “Wickies,” a nickname for lighthouse keepers.

We reached out to past Pharos contributors to join the crew, and they have become an invaluable resource for our community, as they help answer questions, triage and address issues, review design and dev work, advocate for contribution and adoption, and generally perform similar duties people reached out to Blueprint for previously. Within the first month after launching the Wickies, Blueprint reduced our Pharos support tickets by 48%.

Where we’re at now and what’s ahead

Over the past year, we’ve worked to create a robust, full library of reusable elements so teams can create products more efficiently and consistently. Were we successful? In Q2 2021, we focused on how to measure the system’s success, starting with a survey that led us to new goals.

Our survey showed us that consumers are satisfied with Pharos, but there are opportunities for improvement:

• There’s a learning curve for QA writing integration tests, so we’re working on QA contribution guidelines.
• Design and developer collaboration via different tools is a bit difficult, but design tokens help. We’re planning workshops focused on design tokens and highlighting how to use each other’s tools more efficiently.
• There’s trepidation about being the first to implement a component because of unexpected results, causing work to slow down or be blocked.
• Workarounds are still needed for more complex features, like dropdowns.

We also received positive feedback:

• For the most part, adopting components is seamless and painless
• Greatly reduces amount of design and coding work necessary to build UIs
• More confidence in building consistent products
• As Pharos has matured, it has become more comfortable to work with

“When a component is already built and ready in Pharos it makes our lives sooo much easier. It’s also a pleasure to use these components and watch the page/feature come to life so quickly.”

“I believe Pharos has made our lives, as frontend devs, easier to ensure visual consistency in the product; at same time making it simple to implement UI components.”

“We sometimes feel lost when we need to go in and make significant changes in Pharos. Usually because of unfamiliar technologies and processes. That said though, I think there is sufficient documentation and blueprint devs are always available to help!”

“The beginning was rough due to the lack of support for automated testing. I was also unfamiliar with Shadow DOMs so there was a learning curve. While following the curve, we figured out how to work with Pharos components and overcame some problems…today, there is very little friction when working with Pharos.”

With this feedback, we know that we’re on the right track, with more work ahead. We’re encouraged by the full adoption across each of our product teams, with work in progress toward removing old dependencies like Bonsai slowly, but surely.

We also fully open sourced Pharos to share our approach and encourage feedback and contribution from the greater design system community.

We’re also working our way toward creating an autonomous design system. We want to decentralize and move toward a more federated governance model as we scale. We also plan to continue improving and understanding how Pharos impacts user experiences.

Come build with us at ITHAKA

JSTOR is part of ITHAKA, a not-for-profit dedicated to expanding access to knowledge and education worldwide. Our staff makes us who we are. We’re hiring for a wide range of positions, from user researchers to frontend engineers.

Learn what it’s like to work at ITHAKA and check out our career opportunities.

Our team

Blueprint consists of a band of merry people including Robb Niznik, Dane Hillard, Elham Islam, and Sayem Quazi (frontend development), Jayshree Bhakta (product owner and QA), Josh Dahlberg (agile coach), and Kelsey Cavitt (product designer).

Shoutouts

Thanks to Giovanni Garcia and Lori Lundy for their eagle eye editing prowess on the creation of this article. And to our stakeholders and collaborators Liza Pagano, Matt MacQueen, Sarah Glasser, Heidi McGregor, Shucha Grover, Justin Alexander, and Cameron Heard for their input and direction.

Also special thanks to all of our JSTOR frontend and UI teams for adopting, contributing, and supporting Pharos from the very beginning. We 💙 our community. #weareallpharos