Streamlining the Design x Engineering Partnership

A real-life roadmap for building a design system — Pt III

Kim Hart
JW Player Engineering

--

In parts one and two of this series, we took a deep-dive into the benefits of building and scaling a custom design library (Hook) and web component library (WUI & Atlas). This final chapter outlines how we’ve used these tools to improve design handoff and forge a strong partnership between designers and engineers as we roll out a new architecture for our enterprise dashboard.

Removing the Guesswork 🕵️‍♀️

A common pain point during a feature’s lifecycle often surfaces when the handoff of a design spec breeds assumptions from the designer and engineer alike. Design assumptions about feasibility or complexity can lead to questioning, debates, and overall time lost. Engineering assumptions about a design can lead to bugs, UX inconsistencies, tech debt-incurring workarounds. Fortunately, the introduction of Hook and WUI has alleviated a lot of the guesswork in both the design and engineering workflows.

Designers are now empowered to design with specific components in mind without worrying if the technical aspects are achievable or not. Loading, error, empty, and focus states are largely handled out of the box and just need to be wired up appropriately. Each state might not need to be detailed in a flowchart—a huge timesaver—because our components’ behaviors are consistent.

Here’s an example of how a traditionally tricky key-value input list handles itself in the context of a robust video detail page:

Feature vs component design specs

These reliable patterns reduce the cognitive load for all involved: both for the designer creating the spec and the engineer coding it into reality. Designs require less explanation, contain fewer holes & extraneous details, and are easier to defend. When a developer doesn’t require clarification on the little things, it leaves space and time to discuss the big things as a team — allowing us to build more intuitive products and reach smarter solutions for the more precarious user flows.

Forging a Partnership 🤝

Because the creation of Hook and WUI was born out of the needs of two different teams, a natural collaboration formed as the libraries grew and evolved into what they are today.

While the team that previously owned the dashboard mostly comprised full-stack-types whose prowess leaned toward backend API design rather than UI-building, our new dashboard coalition contains designers and frontend, backend, and test engineers. The squad approach—complete with brains from all areas of expertise—has allowed us to solve problems faster, create more complete roadmaps of features end-to-end, and have a more holistic understanding of the services we’re delivering.

Visual bugs have also largely met their match with the addition of a Visual Quality Assurance (VQA) step in our JIRA workflow. After code review and before (full) QA, each ticket’s work is deployed to a staging environment and passed back to a designer to review and confirm that their spec is matched appropriately.

Design-centric feature lifecycle

While the engineering team responsible for building our new dashboard UI also leans full-stack, the distinct passion and accountability for design and modern frontend technology is a noteworthy asset to the product as a whole.

Test Engineers Need Love Too 💘

Before WUI components and the new dashboard took flight, test engineering and the QA process largely took place in its own silo. Now, test engineers have a seat at the table in product strategy, design kickoffs, and ticket grooming. Thankfully, the design system has also introduced a dramatic improvement to our collaboration and engineer-to-QA handoff.

Challenges & Opportunity

Our old method of testing relied on targeting an element by its CSS class name or text in the element itself—a common yet cumbersome approach that would need bulldozing as we rewrote the dashboard and introduced components.

Here’s an example of a locator used to identify a nested and conditionally-rendered “Contact Us” link using the old process in the Angular dashboard:

Old test target for “Contact Us” link

Yikes. This isn’t just hard on the eyes; it’s also incredibly brittle. If we changed the HTML structure or the class .section-description, this test would break. This approach compounded across the entire dashboard lead to fragile tests and hesitation toward any form of design iteration.

With a clean slate ahead of us, we jumped at the opportunity to introduce new best practices for reliable targets in the form of unique, action-oriented IDs.

Test IDs as Data Attributes

Dashboard engineers are now responsible for applying these IDs in the form of data-test attributes on all interactive and non-static elements, including but not limited to:

  • Buttons & links
  • Form fields
  • Any element that renders data received from an API or text that changes based on user input

With a test ID, targeting our “Contact Us” link above can be as simple as:

To ensure that our new ID names don’t become just as messy as custom classes, we employ a kebab-case, verb-first, REST-like structure.

We do want to provide unique & descriptive names:

Example test IDs on various elements

🚫 We don’t want to apply vague IDs that match the text content or provide no further insight into the element’s action or data:

Example of a bad test ID application
This doesn’t help anyone!

Test IDs in the Wild

In the spirit of enhancing the QA process as a whole and making these IDs easier to find, I was inspired to build a Chrome extension called Scout that locates & highlights them at the flip of a switch:

Scout Chrome Extension

We’ve also created a custom eslint plugin that identifies missingdata-test attributes for each commit, and added a data-test PR checklist line item to ensure this step is covered by the time the work hits QA.

Overall, the restructuring of our process and introduction of test IDs have reduced frustration, improved code readability, increased test stability, and spawned a tighter collaboration with our test engineers.

Looking Ahead ☀️

The future is bright for the JW Player dashboard as it continues to grow and evolve into a modularized, component-based system driven by a design-focused squad. Shared ownership combined with a solid and iterative source of truth ensures that we can deliver high-quality features in a fraction of the time and measure them more effectively. Additional health check tools like automated Lighthouse performance audits are also on the horizon.

Our Hook design library, WUI component library, an API companion library (more on that someday!) has created a home for front-end excellence at JW Player and dramatically improved the designer, developer, and user experiences alike.

--

--

Kim Hart
JW Player Engineering

Front-end engineer | design enthusiast | ISFJ | west coast kid | Brooklyn, NY