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:

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 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".

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
• 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.

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.

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 description for each category and sub category within.

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 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.

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 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