Design documentation:
a key pillar for consistent and collaborative UI development
Clear and comprehensive documentation is vital in product design to maintain consistency and efficiency in a company’s design system. At Pennylane, a leading Fin-Tech company revolutionising accounting solutions, we actively embrace well-structured design system documentation.
As a Product Designer, I have witnessed firsthand the transformative impact of effective documentation on our app’s development and user experience. Pennylane’s design system documentation serves as an invaluable resource, enabling us to maintain a unified design language and accelerate the creation of intuitive interfaces.
One of the cornerstones of our design system documentation is the use of Notion, a versatile and collaborative workspace tool. With Notion’s rich functionalities like nested pages, databases, and robust search capabilities, we have seamlessly integrated our documentation within our workflows, fostering collaboration and ensuring up-to-date information is readily available to our team. Notion has become an indispensable asset, elevating our design system documentation experience at Pennylane.
In this article, we’ll cover:
- Classification properties for components in the Notion database
- Short introduction to the component
- Anatomy of the component based on its level
- Behaviour and interaction
- Difference between states and variations
- Do’s and Don’ts
By sharing our approach, we aim to inspire product designers and design teams to optimise their documentation practices, empowering them to create exceptional user experiences in the demanding landscape of accounting software. Let’s embark on this exploration of design system documentation and unlock remarkable design achievements in our organisations.
For the purpose of this article we will be using the example of the Checkbox component. Frequently used on Pennylane’s app, it’s a simple component, understood by everyone but that doesn’t mean the documentation should be disregarded.
Component Properties
Author
- The name of the person writing the documentation
We use this metric to acknowledge and attribute credit to the writers, as well as to identify the appropriate person to contact when updates are required for the component.
Category
- Selected amongst the following: Accordion, Badge, Button, Card, Chart, Empty State, Filter, Form, Messaging, Modal, Navigation, Notification, Patterns, Progress, Side Panel, Table, Tooltip, Upload
This tagging system allows us to classify components based on their respective groups.
Status
- Selected amongst the following: To Document, To Update, In Progress, To Validate, Essential, Fully documented
Thanks to this tag and Notion’s property-specific database sorting, we keep track of the state of the documentation.
Atomic Level
At Pennylane we use the atomic design methodology to build our components. This methodology promotes the idea of designing and developing interfaces by breaking them down into these modular components. By using atoms, molecules, and organisms, designers and developers can create consistent, reusable, and scalable user interfaces within a design system.
- Selected amongst the following: Atom, Molecule, Organism
Atom: smallest, indivisible building blocks of a user interface. (ie: buttons, input fields, labels, icons, and typography styles)
Molecule: a combination of atoms that work together to perform a specific function or create a more complex UI element. (ie: a search bar that consists of an input field and a search button)
Organism: a higher-level component that is composed of both atoms and molecules. (ie: navigation bars, forms, product cards, and modals)
Squad/Scope
This property is important when a component is used in a specific scope but since we aim for consistency most of them are global components.
Reviewers
When writing any type of documentation for your team it’s important to have reviewers (2 in our case), preferably working on different scopes and with different seniority to make sure the document is understood by everyone, contains all the necessary information and can be challenged.
Figma and UI kit links
One of the most important property, we store here the links to the component from the Design System and once developed, from the UI kit managed by the front-end engineers.
Introduction
This part usually answers the prompt: “In two sentences, explain to a non-designer what this component is.” Without going into too many details on the anatomy or behaviour (our next chapters), this definition should stand on its own.
Here’s the one from our example:
Checkboxes are used for one or multiple choices, not for mutually exclusive choices. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections.
Anatomy
The Anatomy section of a design system’s documentation provides a detailed breakdown of the various components and elements that make up a specific user interface (UI) element — in our case, the checkbox component. It aims to offer a comprehensive description of the different parts involved in the checkbox’s visual representation and functionality.
In the provided example, the checkbox component’s anatomy is explained in detail. It starts by outlining the primary elements:
- Title (optional): This refers to the title associated with the checkbox component, which communicates the purpose or context of the selection that follows.
- Checkbox input: This represents the interactive element of the checkbox, visually indicating the current state — either selected or unselected. In the active state, the checkbox has a white check or minus icon and is styled with the Primary700 colour. Conversely, in the unchecked state, it displays a Secondary300 stroke. By default, the checkbox starts as unselected.
- Checkbox label: The checkbox label provides descriptive text that explains the information or action associated with the checkbox. It typically appears as a paragraph or body text styled with Secondary900 colour.
Additionally, the example emphasises that checkbox labels are positioned to the right of their corresponding inputs. In cases where multiple checkboxes are grouped together, they can be arranged either vertically or horizontally based on the UI’s structure and use case. It is generally recommended to arrange checkbox and radio button groups vertically whenever possible, as this improves readability for users.
Overall, the Anatomy section of the design system documentation delves into the individual components that comprise a checkbox, ensuring that designers and developers have a clear understanding of the visual and functional aspects involved in implementing this UI element.
Behaviour
Within a design system’s documentation, the Behaviour section assumes the responsibility of shedding light on the diverse functionalities and interactions entwined with a particular UI element. Its purpose is to offer comprehensive knowledge about how the checkbox functions and the multitude of scenarios where it can be employed.
Drawing upon the provided example, let us explore the distinctive behaviours exhibited by the checkbox component:
1. Forms: The checkbox can be used within forms, whether they are displayed on a full page, within modals, or on side panels. This allows users to make selections or indicate their preferences as part of a form submission.
2. Filtering and batch action: Checkboxes are commonly employed to facilitate data filtering and perform batch actions. They can be used to filter data either on a page or within a dropdown, allowing users to refine their search results or perform bulk operations. In the context of a data table, checkboxes are utilised for batch editing purposes.
3. Terms and conditions: Checkbox inputs can be employed to signify agreement or disagreement with terms and conditions. By turning the checkbox on or off, users can indicate their acceptance or rejection of the specified terms.
4. Lists with sub-selections: When dealing with lists that have parent-child relationships, checkboxes offer a convenient way to manage selections. By using a parent checkbox, users can select or deselect all the items in the list simultaneously. Unchecking the parent checkbox will deselect all the child items as well. Alternatively, users can individually select child items when the parent checkbox is not selected. In such cases, the checkbox component may exhibit an indeterminate state, indicating that some child items are selected while others are not.
By documenting the behaviour of the checkbox component, the design system provides guidance to designers and developers on how to implement and utilise checkboxes effectively in various contexts. Understanding the specific behaviours of the checkbox component enables consistent and predictable user experiences across different parts of the interface.
States
Thanks to this section, we provide an overview of the various states that the checkbox component can assume during its lifecycle. These states encompass different visual and interactive aspects that communicate specific conditions or user interactions. Here are some of the key states associated with the checkbox component:
Here are the different states that the Checkbox component can have:
- Enabled: This represents the default state of the checkbox, allowing users to interact with it and make selections.
- Hover: When the user hovers the cursor over the checkbox, it enters the hover state, typically accompanied by a visual change to provide feedback and indicate interactivity.
- Focus: Upon receiving focus, usually through keyboard navigation or direct user interaction, the checkbox enters the focus state. This state helps users identify which element currently has their attention and may exhibit a distinct visual style.
- Disabled: The disabled state indicates that the checkbox is not available for interaction or selection. It is typically visually muted to communicate its inactive nature.
- Error: In the event of an error or invalid input, the checkbox can enter the error state. This state is often accompanied by an error message or visual indicator to highlight the issue and provide feedback to the user.
These states provide designers and developers with a clear understanding of how the checkbox component visually and interactively adapts to different user interactions and contextual conditions. By considering these states during the design and development process, a consistent and intuitive user experience can be achieved across various states of the checkbox component.
Variations
In the context of the design documentation for the checkbox component, it’s important to acknowledge that the product caters to two distinct sides: SME (Small and Medium Enterprises) and Accounting. Each side may have different UI/UX needs and considerations.
Considering the unique requirements of both SME and Accounting users, the variations section of the design documentation can include specific variations or customisation options that cater to the UI/UX needs of each side. This ensures that the checkbox component is tailored to the specific workflows, preferences, and visual aesthetics of both user groups.
For example, the SME side may prioritise a clean and user-friendly interface, with checkboxes that have a modern and approachable design. On the other hand, the Accounting side may require checkboxes that align with industry standards and conventions, ensuring familiarity and ease of use for accounting professionals.
By acknowledging the different UI/UX needs of SME and Accounting users, the design documentation can guide designers in creating variations of the checkbox component that best suit each user group. This approach ensures that the product provides a tailored and optimised user experience for both sides, enhancing overall usability and satisfaction.
“Do’s and Don’ts”
We determine a set of guidelines and recommendations for designers and developers to follow when creating a specific UI element and by dividing it in 2 categories we end up with the “Do’s and Don’ts”. This section aims to highlight the best practices that should be considered and the potential pitfalls that should be avoided during the design and implementation process.
The “Do’s” present positive recommendations and suggestions that designers should follow to ensure the checkbox component is effectively designed and meets user needs. These recommendations often cover aspects such as clarity of labels, appropriate visual cues, usability considerations, responsiveness, and accessibility.
On the other hand, the “Don’ts” outline common mistakes or pitfalls that designers should steer clear of. By highlighting these potential issues, the section helps designers understand what should be avoided to prevent user confusion, usability problems, or accessibility issues with the checkbox component.
The “Do’s and Don’ts” section serves as a practical guide, providing designers with valuable insights on what actions to take and what actions to avoid when designing and implementing checkbox components. By adhering to these guidelines, designers can create checkboxes that are intuitive, user-friendly, and aligned with best practices, ultimately enhancing the overall user experience of the interface.
High-quality design documentation is crucial for successful design implementation and collaboration. Well-done, regularly updated, and shared documentation establishes consistency in UI component implementation, ensuring a cohesive user experience. It serves as a central reference point, facilitating effective communication and collaboration between designers, developers, and stakeholders.
By streamlining the design process, providing guidelines, and fostering knowledge transfer, it enhances efficiency and accelerates project timelines. Additionally, regularly reviewing and updating documentation ensures its relevance and alignment with evolving design trends and user expectations. Making documentation accessible promotes inclusivity and enables a broader range of contributors to participate in the design process.
In summary, investing in robust design documentation enables teams to deliver exceptional user experiences while optimising workflows and maintaining design integrity. Here at Pennylane, we value the art of meticulous design documentation, fostering collaboration and crafting exceptional user experiences.
We’re always looking for new talents who share our passion for design integrity and want to be part of a team that creates meaningful impact through their work.
A story by Erica Scolaro, Product Designer at Pennylane
