Summary:
While most designers write design specifications, few do so effectively. To address this, I created a scalable framework that covers the why, when, how, and what of design specs, helping designers think critically about complex use cases. This approach improves the design handover process within the product development lifecycle. The article outlines the thought process behind developing this framework and how it was introduced to the team, focusing on its scalability and practical application.
[1] Prelude: It started with a simple receipt
Writing design specifications is akin to creating a detailed recipe for someone else to cook a meal you've already prepared. I was introduced to the practice by Greta - my first mentor and manager - when I joined Honestbee as a young designer many years ago. The experience left a profound impact on shaping my eye for detail thereafter.
As the designer for the Grocery business unit back then, my task was to redesign the grocery order receipt by incorporating Malaysia’s new service tax requirements within the billing items. It was my first project that involved writing design specifications before handing over to the developers. Additionally, it required us to study the law to ensure that the right billing information was included in the receipt. Her training was meticulous and thorough - requiring me to indicate all the technical details, guidelines, and expectations needed to ensure that developers can faithfully reproduce or build upon the design.
I remembered questioning Greta about the redundancy of the practice, and she explained the importance of learning how to be thorough in such details, before learning to judge when enough detail is enough. She also explained how most miscommunications and errors in development occurred when designs were not specified enough. When important details are left up to interpretation, more often than not that would lead to a less than ideal user experience, especially when the team happened to take the designs for granted.
My rigorous training in Honestbee
[2] How did writing design specifications become a thing in Ninja Van?
When I moved to Ninja Van in 2019, I brought with me the lessons learned from Honestbee and continued refining my approach to writing thorough design specifications. Over time, I realized that effective specs need to go beyond technical details to also account for edge cases and error handling. Without this level of detail, handovers can lead to frequent back-and-forths between designers and developers, ultimately delaying timelines.
Between 2020 and 2021, as Ninja Van's design team grew rapidly, it became clear that different business units’ designers exhibited varying levels of design maturity. This led to inconsistent documentation and slower-to-market speed. Design leads began focusing on improving team-wide practices, and design specifications emerged as a key area for enhancement due to their direct impact on execution and delivery.
As the sole designer in the Commercial team, my approach to writing specs was recognized for its meticulousness and became a benchmark for quality. However, with the team scaling, I saw an opportunity to transform this individual practice into a more structured, scalable framework. Under the mentorship of senior designer Dex and my manager Fred, I worked through a process to refine my approach, creating a system that was not only digestible but also reproducible across the team to drive consistency and speed in delivery.
[3] Understanding existing practices
How does one begin to create a system? Like all design processes, I started with a research study to better understand our designers’ pain points in writing effective design specs and its impact on the handover processes:
Understanding the designers' perception and knowledge about design specs
Understanding the team's maturity in writing design specs
Understanding the current state of union wrt the collaboration between designers and PMs, Devs, QA wrt communication of design
These insights then helped inform the principles behind structuring the design specs system, with the goal of ensuring consistent practices and better documentation processes across the team.
// Research insightsThe insight 1: Lack of design rationale and legacy documentation
Pain point: There is a gap in documenting design rationales for past decisions, particularly for legacy work, which may lead to confusion or reliance on outdated practices.
Opportunity: The system should include clear explanations and examples of how design decisions and discussions can be documented.
"I know how to write design specs... I think?"
The insight 2: Difficulty in specifying edge cases
Pain point: Designers often struggle to identify and specify all potential scenarios, particularly edge cases, leading to mental blocks and incomplete documentation.
Opportunity: The system should include a framework that’s replicable and context agnostic, so that the designers can refer to it while brainstorming about design specs.
"Brain fart - I can't think of any other cases to write ):"
The insight 3: Inefficient back-and-forth with developers and QAs
Pain point: The clarification process between designers, developers, and QAs is often time-consuming and fragmented, leading to frustration and delays, despite the willingness to collaborate on missed scenarios. This clarification only happens after the high-fidelity design has been handed over, and further design changes are often costly to the designers.
Opporutnity: The system should recommend designers ideal timelines to share their design specs with their cross-functional team. Timeliness and collaboration is key to identifying problems early.
[4] Creating the framework: The system behind design specs
Part 1: The “What”
// Defining the practiceArmed with the research insights, I began setting expectations on what are design specs, taking into account its usage in Ninja Van’s context.
Definition: Design specification is a form of detailed documentation that notes down the specifics and/or reasonings behind a design choice. This is written and owned by designers. In Ninja Van's context, they are not just the vague acceptance criteria written in a JIRA ticket (by PMs or devs).
Design specifications are meant to supplement the acceptance criteria with more information to ensure that products meet users' requirements. They are intentional, and not meant to specify everything repeatedly or excessively. Their level of granularity should mirror the progress of the product life cycle.
Part 2: The “Why, who, where, when”
// Emphasising the impactIntroducing new processes can be daunting for teams, especially when they’re accustomed to established ways of working. Our goal was to seamlessly integrate the design specs practice into Ninja Van’s existing Scrum processes, ensuring that it complemented the workflows of designers, developers, and QAs. To achieve this, we emphasized that the role of design specs should serve several key purposes:
Extend acceptance criteria by covering more extensive use cases, ensuring the design addresses all relevant scenarios.
Support every cross-functional role in their specific jobs-to-be-done (JTBD). For example, QAs can create more detailed test scenarios, PMs can clarify design decisions and provide justification, and developers can generate solutions and spark meaningful discussions.
Prevent compromises in product quality by setting clear expectations for design solutions.
Impact of thorough design specs on QA test scenarios
We also identified late-stage low-fidelity to mid-fidelity wireframing as the optimal point to start writing design specs. By doing so early in the process, misalignments can be detected by developers and QAs before they become costly issues. Additionally, this stage encourages more frequent cross-functional team reviews, helping to align everyone on design expectations and ensuring smoother collaboration moving forward.
Visualisation of Ninja Van’s product development cycle and where design specs fit in
Part 3: The “How”
// How do we teach designers to start thinking about design specs?Through a process of trial and error, we developed a framework to help designers think through varying levels of specification granularity. We organized these levels into a bull’s eye diagram, which visually ranked each level of detail by priority, making it easy to grasp:
How to start thinking about design specs
At the core, designers are encouraged to start by focusing on the fundamental elements within a page or screen. This includes key components such as interaction design, gesture controls, state transitions, and copywriting—essential for meeting basic design standards and ensuring functional clarity.
Next, designers should expand their scope to consider the role of the screen within the larger user flow. This step accounts for interaction pattern exceptions—elements that can’t be fully visualized on the screen, particularly those that depend on the context of preceding or subsequent steps in the flow.
Further out, we encourage designers to examine the user flow within the broader system or application. This involves addressing often-overlooked details such as language, date formats, currencies, and contact information (e.g., addresses, phone numbers) that, while supported by default settings, can vary significantly across users and regions.
Finally, where applicable, designers should factor in the device’s settings and platform-specific exceptions. This includes considerations for hardware features like sensors, biometric capabilities, or any other platform-dependent attributes that could impact the user experience.
How to evaluate a page / screen systematically
// How do we teach designers to write about design specs in a predictable and scalable format?We focused on providing a design spec format that goes beyond the typical action-reaction descriptions designers often gravitate towards. Our goal was to ensure each specification included enough context when written in full sentences, not only to describe what happens, but to explain the reasoning behind the design. This approach aimed to achieve three key objectives that were distilled from the three research insights from above:
Objective 1: Improve design documentation and rationale transparency
Pain Point: Lack of design rationale and legacy documentation
Objective: Establish a system that ensures design rationales are consistently documented, especially for legacy work, so that future design decisions are informed by clear explanations. This documentation will help prevent confusion and reliance on outdated practices, providing a reference point for both current and future team members.
Objective 2: Streamline edge case identification and documentation
Pain Point: Difficulty in specifying edge cases
Objective: Develop a replicable, context-agnostic framework that helps designers systematically identify and document all potential scenarios, including edge cases. This framework should serve as a helpful reference during brainstorming sessions, minimizing mental blocks and ensuring comprehensive, detailed design specs.
Objective 3: Enhance cross-functional collaboration and timely feedback
Pain Point: Inefficient back-and-forth with developers and QAs
Objective: Implement a system that promotes early and frequent collaboration between designers, developers, and QAs. The system should include recommended timelines for sharing design specs during the design process, enabling the team to catch potential issues early and reduce costly revisions after high-fidelity designs are handed over.
The format included key elements such as:
Exceptional Conditions (if applicable): Describing unique scenarios or edge cases that may require special handling.
User Action / System Event: Detailing the user's interaction with the system or any system-triggered events.
Response & Information: Specifying how the system should respond to the user action, including any feedback or data presented.
Design Justification / System Logic: Explaining the reasoning behind the design choice and any relevant system logic that informs it.
Design specs writing format
To demonstrate the effectiveness of the framework, we referenced real-world examples from Commercial’s design specs documentation. These examples helped illustrate how the framework could be applied in practice, ensuring a clear and consistent approach to design detail.
Commercial’s design specs on parcel search on Ninja Biz App
Additionally, we expanded on how and where to integrate the design specifications within the Scrum process, ensuring a smooth handoff to developers and QAs. This not only streamlined collaboration but also ensured that design quality was maintained throughout the development lifecycle.
Visualisation of design specs in a user flow
[5] Sharing the framework: Equipping designers with the new system
Once the system was ready, I led a training session (slides in link) for our 9-12 designers, incorporating interactive exercises designed to help them immediately apply what they had learned. It was insightful to observe the varying levels of granularity each designer explored during the exercise, reflecting the diverse ways they engaged with the framework.
Miro board of the training session (excluding training slides)
🟢 I gathered feedback from the team to assess the session's effectiveness in raising design standards. The response was overwhelmingly positive, with designers expressing that they had learned new methods for enhancing their design specs.
“Engaging and well-balanced session. Very informative”
“Good delivery on information and importance of design specs in practice.”
“Framework is really helpful to get started!”
“Exercise showed how the framework can be adopted differently”
🟠 Many also shared valuable suggestions for improving the session, particularly around ensuring better knowledge retention and introducing more structure to the design specs system for better standardisation.
“Slightly more time to do practice and share during the exercise portion to get a better understanding of how others would write specifications given more time.”
“Maybe instead of immediate exercise, can you do a live demo on how you would approach design spec writing from 0-100?”
“I think having a standardised format might be helpful? I see some designers writing it out as a whole chunk, and other writing per screen”
“I also agree with some structure/format for design specs. Maybe a simple confluence doc/miro board etc. to show examples.”
Following the training, the designers continued to integrate the framework into their daily work. As a result, I became the go-to consultant for design specs, providing ongoing support to help team members refine their writing skills and apply the system more effectively. This ongoing guidance helped solidify the framework as a key part of our team's design process.
[6] Design specs: 2023 and beyond
As the designer headcount grew beyond 20, I transitioned into a managerial role and cascaded down this system to ensure consistency and quality. I shared this system with my team of 4 designers, making it a core part of our workflow. This shift not only raised the overall design quality within the team but also established a higher standard that all designers were expected to meet. As a result, the team's output became more refined, aligned, and efficient, contributing directly to the success of our projects.
PSA: Interested to improve your design specs writing skills? Let’s have a chat over coffee or bubble tea (: I’ll be more than happy to share this framework with you! 🍵☕️