Pharos: JSTOR’s design system serving the intellectually curious
A detailed account of our journey of building a design system from the ground up
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.
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.
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.
“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.
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.
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.
“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.
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.
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.
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.
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.
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.
Component Tokens
Component tokens are a platform-agnostic representation of how a component should be styled that utilize global and/or alias tokens.
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.
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
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.
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.
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.
“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.
Community surveys
Surveys help us better understand our users’ experience with Pharos. It’s also one of our approaches to measuring Pharos’ success.
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.
“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.
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