The Best Way to Document UX/UI Design https://www.uiprep.

com/blog/the-best-way-to-document-ux-ui-design

Design
Freebies Course Blog Subscribe
System

The Best Way to Document

UX/UI Design

Written By Read Time Last Updated

Jake Tsacudakis 8 min August 9, 2023

1 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

Our team at UI Prep creates several products each year and has discovered
the best UX/UI documentation strategies for happy and productive teams. In
this article I'll discuss our process; how we start by writing pitches, a
concept borrowed from Basecamp, and then create high fidelity designs in
Figma with our own lightweight, organized method. These strategies can be
applied to any website or product, large or small.

👉 Are you starting a new project or a redesign soon? Jump start your
design & documentation process with UI Prep's Design System. Learn
more about the design system here.

UX Documentation
Once the user research and strategy for a new product is complete, it's time
to start documenting the proposed UX concepts. Start by dividing the
product into 10-30 major areas or workflows (e.g. "dashboard" or
"onboarding") depending on the scope of work. Then, one-by-one, write a
pitch for each that explains why and how it should be created, with
considerations for both design and development. The pitches should mostly
rely on writing to explain their concepts but also use wireframes to help
others visualize the concepts.

Here at UI Prep, our team's UX documentation style is largely based on

Basecamp's method of product development from their book "Shape Up"
which you can find here for free.

Pitch writing
Pitches are written documents, with some visual aids, that describe each
area or major workflow within your product. These pitches are first used to
present concepts to the entire team to get buy-in, and are then used as a
living library of all documentation needed to design and build the website or
product. Each pitch will grow and evolve as designers and developers
weigh in and start using them.

Below is a pitch outline that can be used for any website or product:

2 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

Below is a pitch outline that can be used for any website or product:

1. Overview: Summary of the problem or motivation behind the pitch, and

the solution that is being suggested.
2. Lay of the land: High level description of what will be designed/built.
This often includes additional context needed to understand the finer
details in the rest of the pitch. For example, in a pitch about settings, this
section might describe how to access the settings page, where it lives
in the product, and what the general layout looks like.
3. Deep dive: Detailed explanation of an individual area, feature, or event
related to the solution. A pitch will likely have many "deep dive" sections
to cover everything that is needed. For example, in a pitch about
settings, there might be a section about "notifications", "profile" "admin
access", "billing", ect..
4. No-gos: Anything that is not within the scope of the pitch and should be
avoided. It's helpful to record decisions, even when the answer was
"no", for future reference and to reinforce boundaries for the team.
5. Product designs: This is where links to the production designs can be
added. This section will be left empty at first.

Wireframing
Use low fidelity wireframes as visual aids in your pitches to better
communicate the concepts being described. Each wireframe should be
specific to a section and show only what is required to communicate the
concept. Showing too much detail at this stage might limit design
exploration.

Our team prefers to create low fidelity wireframes in Whimsical and then
switch to Figma when we're ready to start mid/high fidelity design work.

Lay of the land wireframe

In the beginning of the pitch, it's important to include a high level wireframe
to show the general layout and how different pages/views/components
relate to one another. This wireframe will provide needed context for the
rest of the pitch. For example, a pitch about settings might show its access

3 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

point, the layout of the page, and maybe some high-level functionality.

Deep dive wireframe

Most deep dive sections should include a wireframe focused solely on the
area, feature, or event being described in that section. These wireframes
can contain a single view or a series of views depending on what needs to
be communicated. For example, a pitch about settings might do a deep dive
on viewing/editing a user profile. This wireframe should show general
layout and key actions like "save changes".

4 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

UI Documentation
Once some or all of the pitches have gotten buy-in from the team, start
designing and documenting the product's UI. These two things should be
done in tandem to make presenting and defending design decisions easier,
even in the very beginning. Early UI documentation is also important for
keeping the design file organized and ensuring all styles and components
are used consistently from the start.

Our team has experimented with many UI documentation methods and

through trial and error, found the most effective ones. The most unique
being our lightweight and organized approach to showing different
workflows. This, accompanied with the detailed pitches, is the best way to
document any project.

File structure
Creating and maintaining a well organized file makes a huge difference in
how well others will be able to understand your designs. Someone
unfamiliar with your file should be able to quickly navigate to a particular
design and understand its purpose and behaviors with relative ease.

Organizing your file starts by creating pages, with clear names, for different
design and documentation purposes. Below are example pages that can be
used for any website or product:

• Master Components
• Style Documentation
• Global Components
• Major Area A
• Major Area B
• Major Area C
Prototype A
5 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

• Prototype A
• Prototype B
• Prototype C

Major Areas
Major Area pages are the main event. They contain most of the actual
design work and are where both designers and developers will spend the
majority of their time. Each major area of a website or product (ie.
"dashboard" or "invoices") should be given their own page and then further
broken down into smaller workflows or categories if needed. Everything
related to these workflows and categories should be grouped together and
housed on a large frame. Each frame will contain a small number of
example views, showing full designs, and then a breakdown of each
individual component.

For example, if you're designing an invoices page and want to show every
filter state, document the filter states separately rather than showing an
entire page view for each. This will make the design file more focused and
easier to maintain.

Example views

On the appropriate frame, add a small number of example views showing

the design layout, where all the components live and how they related to
one anther. Included should be at least one default view and a few other
key views if needed. Additional key views are only needed if an event
impacts the entire view or multiple components.

6 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

Product using the UI Prep design system

Component documentation

Next to the example views, neatly document every component that is

specific to that workflow or category. Every possible state and variant of
these components should be found here with a short description explaining
when, why, and how they are used. Documenting all component states
directly next to their example views, rather than on a separate page, makes
them both easy to find and easy to understand.

Product using the UI Prep Design System

Global components
The Global Component page should display all components that are not tied
to a specific workflow (e.g. buttons, inputs, avatars, ect.). Because these
components are so common and non-specific, they need their own
dedicated page so they can be easily found and referred to.

Each category of components should be given its own frame with a brief

7 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

description for each category and sub category within.

Product using the UI Prep Design System

Pro tip: Sometimes when you make a holistic system of components (e.g.
buttons), not every state or variant is used in the production designs. To
save your developers time, document these component categories twice.
First with all the possible states and variations that could be used now or in
the future. And second, with all the states and variants that are currently in
use. This is especially helpful for younger websites/products as you don't
want any precious development time being waisted on components that
aren't needed. For example, don't ask your developers to build every
possible tertiary button and their states when only one type is currently in
use.

Style guide
Even though most your styles are accessible in Figma's design panel, it's
still important have a dedicated page where you can layout each style and
add additional descriptions or context when needed. This is necessary
because some styles can not be captured in the style panel (e.g. when to
use which corner radius), and some descriptions need to describe a family
of styles, rather than a specific style (e.g. when to use any variant of an

8 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

of styles, rather than a specific style (e.g. when to use any variant of an
accent color).

The Style page should be broken down into different frames, one for each
category (e.g. color palette, elevations, corner radius). Each category
should have a brief description, and each style, or family of styles, should
have their own description.

Product using the UI Prep Design System

Pro tip: Similar to global components, often when you create a holistic color
palette, not every color created will actually be used in the production
designs. Save your developers time by documenting the color palette twice.
First, with all the possible colors that could be used now or in the future.
And second, with all the the colors that are currently in use. This way
everyone will understand the color palette logic and know exactly what
colors are needed right now.

Prototype
The Prototype pages are where designers and developers can visualize
entire workflows. This type of documentation is so important because it
helps teams stay on the same page and will often lead to UI questions and
discoveries that would not otherwise come up.

Deciding which workflows to document with a prototype should be chosen

carefully as they can make your file boated and can be time consuming to

9 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

build and maintain. Select workflows who's functionality are core to the
project, or who's difficult to communicate with only static designs.

Bring it all together

Once the UI documentation is ready to be shared, add it to the appropriate
pitch with Figma links. This way, anyone reviewing a pitch can quickly
navigate to the production ready designs and their related documentation.

How to link to a Figma frame in your pitch:

1. Select a workflow frame inside of Figma

2. Copy the URL
3. Paste the URL into your pitch

Jump start your next project

Skip the hours (days?) needed to set up your design file before you can
start actually designing, with UI Prep's design system. It has all the
components and styles you need to get started and can be completely
customized in less than 2 minutes.

We use it as the starting point for every new project we work on, and so can
you!

🧠 Learn More about UI Prep Design System

👉 Demo UI Prep Design System

10 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

Want more design

insights like this?
View All Articles
See our full catalog of articles
covering Figma tips and Design
System best practices.

11 of 12 01/04/25, 3:25 pm
The Best Way to Document UX/UI Design https://www.uiprep.com/blog/the-best-way-to-document-ux-ui-design

Resources Follow Molly

Newsletter Twitter
Join 20,000+ designers and get 5
Design System
tips every Friday Youtube

Freebies
LinkedIn

Course

Blog

Subscribe Free

Including designers from..

© 2023 UI Prep. All rights reserved. Privacy Policy UI Kit License

12 of 12 01/04/25, 3:25 pm