Overview & Challenge

As Judi’s product ecosystem scaled, design decisions were becoming increasingly inconsistent across teams.

Teams were making design decisions based on individual interpretation instead of shared standards, leading to repeated debates, inconsistent experiences, and unnecessary custom solutions across the platform.

The existing handbook had become difficult to trust, difficult to scale, and too dependent on tribal knowledge to support efficient product decisions.

What looked like a documentation problem was really an operational one: the team didn’t need better pages, they needed a clearer system for how product decisions were made.

Role

I owned the initiative strategy, framework definition, and adoption plan alongside one peer designer, with leadership oversight.

This included defining the decision framework, establishing governance across patterns and components, aligning with engineering and design systems on implementation feasibility, and creating contributor standards to support long-term scale.

What I needed to learn first

Before proposing solutions, we audited:

• where documentation currently lived

• what content types were actually useful

• where people got stuck

• what patterns were repeatedly debated

• how both designers and engineers referenced documentation in real work

This included reviewing:

• the existing handbook

• developer documentation modules

• design system references

• recurring design review friction points

• feedback from design leads and engineers

The same issues kept surfacing:

• Unclear component usage and decision-making around actions and controls

• Inconsistent interaction patterns across shared product behaviors

• Documentation discoverability and navigation challenges

• Gaps in writing standards and content guidance

• Inconsistent accessibility expectations across teams

• Lack of clear ownership and standards for recurring design patterns

The problem became:

How do we create a shared decision-making system people will actually use?

Defining Templates

We intentionally limited interactivity for MVP and prioritized clarity over complexity.

Rather than building highly custom documentation pages, we focused on reusable templates for:

• component usage rules

• do / don’t callouts

• considerations and exceptions

• codified examples paired with explanatory guidance that would encourage designers to inspect the page thus bridging the gap in developer-designer communication

We also made a deliberate decision to avoid creating new documentation components where existing ones could be adapted.

The goal was consistency, not more maintenance.

This meant:

• modifying existing components instead of inventing new ones

• reducing duplicate patterns

• making documentation easier to scale over time

The system needed to be lightweight enough to adopt and strong enough to govern decisions.

We divided ownership across patterns and components, working page by page to define:

• approved usage and variants

• do’s and don’ts

• considerations and exceptions

• implementation notes

• writing standards

• related component relationships

Doing the work

Once the framework and templates were established, the real work began: auditing components, defining rules, and translating design decisions into scalable guidance.

Each page had to answer a simple question:

Can a designer make the right decision using this alone?

If the answer was no, the guidance wasn’t done.

The goal was not completeness for the sake of documentation—it was clarity for real product decisions.

This required constant review of:

• existing component behavior

• legacy patterns already in production

• known exceptions and edge cases

• engineering constraints

• future scalability across teams

That meant challenging unnecessary customization, identifying patterns that needed to be standardized, and recommending updates where the current system created avoidable friction.

In several cases, the work required requesting component changes rather than simply documenting current behavior, because documenting bad patterns would only scale the problem.

This shifted the work from documentation into product standardization.

Keeping up with change

The hardest part of the project was that the design system itself was still evolving while we were documenting it.

Design language, palettes, tokens, and component standards were actively changing, which created constant back-and-forth with the design system team.

Originally, we approached documentation using highly technical language:

• exact property names

• token references

• developer terminology

It was precise, but difficult for designers to use consistently and too fragile for a system still evolving. Additionally, it would have been redundant and slightly veered out of our lane. The main audience was the designer. We didn’t need to tell developers how to code, we just needed to ensure the development was consistent with our guidelines.

We shifted toward:

• plain language

• behavior-based guidance

• directive writing

• clear do / don’t decision frameworks

Instead of:
“Use the actionContent property with tertiary.large.unpadded”

We documented:
“Use a tertiary button when a related action is needed.”

This made the guidance significantly easier to adopt while keeping it flexible enough to scale as technical specifications evolved.

Some patterns also had to be created from scratch, requiring design lead alignment and design system collaboration before documentation could even begin.

This created delays, but it also made the work more valuable:
we weren’t just documenting decisions—we were helping define them.

Testing

At around 50% completion, we shared the handbook with design leads and used it during active design validation to test whether it could function as a real decision-making tool.

The goal was simple:

Could leads effectively use this to review work?

They could.

Feedback was minimal and iteration needs were low, which validated that the structure was working.

At around 80% completion, we released the Figma file to the full design team and asked designers to begin using the updated standards in live product work.

Again, adoption was strong and revisions were minimal because the guidance was already solving real friction points.