NYPL Reservoir Design System
- Accessibility
- Documentation
- React
- Storybook
- Typescript
- UX design
- Visual design
The NYPL Reservoir Design System is the base for the UI/UX design and front-end development of the NYPL web applications. As the sole design technologist at NYPL, I organize and contribute to all aspects of the design system, including product planning, UX and visual design, development, and writing detailed documentation.
Links
Background
While I am highly effective working closely with designers and engineers across the organization to create and enhance the design system, I find that what requires the most effort is getting all parties to fully embrace and adopt the system. Building effective components and evangelizing benefits like consistency and improved ROI is not enough. In an environment where the design system is new and somewhat unknown, vigilance and thoughtful consideration is required to help stakeholders understand the design system can be a catalyst for effective team development and not an impediment.
Ease of use
If a system is not easy to use, it will not be used voluntarily. Furthermore, if designers and engineers are forced to use tools by way of a mandate, the potential for resentment and pushback will be high. With that in mind, to foster interest, trust, and curiosity, I go out of my way to meet users where they are and provide tools that allow for independent discovery and resources that illustrate benefits. Through their own exploration, designers and engineers can see what it takes to implement and utilize the design system.
Delivery
Utilizing Figma for the visual design side of the Reservoir Design System allows for shared design libraries with automated and asynchronous distribution of assets, including dynamic components, styles, and design tokens. I mentor product designers about Figma functionality and best practices to ensure that the design team is comfortable with the system and free to focus on design problems, not technical problems.
For web app development, the React component library is delivered through the ubiquitous npm public registry, making the design system easily accessible. The design system utilizes standard semantic versioning to publish updates to the React library code base and consuming apps can easily pull in new versions of the design system as needed and on their own schedule. Developers of consuming apps also have access to the design system's GitHub repo and can contribute updates and improvements as needed.
Resources
Providing comprehensive documentation empowers designers and engineers with the ability and drive to learn about and understand the philosophy, guidelines, patterns, and components that make up the design system. With that, the design system can be used freely and with confidence.
End-to-end processes like component creation and QA testing are mapped out and described with governance processes that define when and how things get done within the design system. Designers and engineers, and more importantly leadership teams and indirect stakeholders, can quickly see where a project stands and, with responsibilities clarified, easily understand how it will move forward.
Every component in the design system has a written source of truth referred to as a specification document, or spec doc. The spec doc is a compilation of UX expectations, accessibility guidance, functional specifications, and technical notes detailing the React component, including prop definitions and data structures. The spec doc is used as a resource for both component visual design and React development.
The display page for a component in Reservoir's visual design library not only shows all of a component's variants, it also includes specifics from the spec doc to detail use cases and explain accessibility. Designers have direct access to a component's intended use and best practices, as well as a direct link to the coded version of a component in Storybook, the front-end display for Reservoir's React component library.
Similarly, the documentation for each component in the design system explains how a component is intended to be used, detailing the UX and accessibility standards. It also provides code examples and in-depth details about engineering specs to aid developers in implementing components in consuming apps.
While the docs in Storybook house technical details specific for engineering, they are also the home of information that guides the overall direction and implementation of the Reservoir Design System, including a mission statement and charter, the NYPL web style guide and pattern library, and overarching accessibility standards and guidelines.
Relationships
Creating relevant components and providing thorough documentation creates a strong base for a design system and provides a source of truth that an organization can rely on. Nevertheless, what really makes a design system excel is the corporate culture around a design system and the relationships that develop between the teams that use it.
Partnering
I oversee UX exploration for the design system components, including stakeholder interviews, heuristic evaluation, competitive analysis, and user research. Partnering with and assisting UX designers allows me to guide the UX process and goals, but more importantly, I have insight into how designers are working and the unique idiosyncrasies of the apps that are using the design system. With these perspectives, I tailor Figma components and workflow processes to fit the needs of the designers and their projects. I also judge comfort level and trust, which aids with planning the schedule and scope of larger design system changes that may impact the design workflow.
Empathy
I have a close working relationship with engineers who are using the design system in their web apps. Understanding the basic architecture of the consuming apps and hearing directly from front-end developers about the design patterns they are using or possible pain points in implementing design system components boosts empathy and sensitivity when considering the specs and intended use cases for a new component. For example, extending the level of composibility was necessary across the design system as it was increasingly being used in an app running React on top of a headless CMS.
Feedback
If a design system is planned and implemented in a vacuum without insight into how its elements are ultimately being used, it is impossible to know if it is solving the problems or attaining the goals that were defined when the decision was made to create the design system. Is it making design and development easier? Harder? Is it even being used? Is the design system a waste of time? Hearing from design system users is vital.
The direct relationships I have with the designers and engineers throughout NYPL provide one-on-one opportunities for discussions and feedback, but that is only one of many methods available for evaluations and bug reporting.
The Agile ceremonies that I run during a standard sprint lifecycle (planning, refinement, standups, retrospective, and demo) offer group settings for designers and engineers to speak openly about the design system. In addition, the design system team runs retrospective meetings after consuming apps have adopted versions of the design system that include significant updates. For example, major version updates or new components.
That being said, having a chat about the design system is not always convenient nor applicable for some issues. There are times when it is earlier to write out the details. Or perhaps someone is not comfortable discussing a problem directly. For those cases, other avenues for feedback are provided. Design system stakeholders and users are encouraged to utilize our Jira ticketing system as needed. Engineers are also asked to submit PRs to the design system's GitHub repo when it is more effective to illustrate an improvement or bug with a working example. If anonymous reporting is required, a standalone feedback form is available and, if necessary, it is understood that leadership may be approached.
Company culture
I am a proponent of open communication between individuals and teams. I work to remove the often unacknowledged wall between designers and engineers and I encourage the individuals within the two disciplines to work closely and communicate throughout a project lifecycle. This open atmosphere fosters the qualities—including communication, respect, and trust—that continuously improve the NYPL Reservoir Design System.