Creating Context for Design Systems: A Comprehensive Approach to Documentation
You’ve heard of design systems.
You likely have one. And if you don’t, you probably should.
But along for the ride are other names that may have been reasonably well defined within the context of your project, client or organization. They even have solid definitions outside – across the industry. Names like: frameworks, software design guides, pattern libraries, component systems, UI kits, style guides, and design tokens.
There are no universal and agreed upon definitions. And there’s a lot of grey areas, overlaps, and gaps between them. However, there is at least a widely accepted premise that the phrase “design system” is intended to be the highest level all-inclusive descriptor.
Let’s explore how to close the gaps with a more complete structure for the design system and its supporting documents.
Minding the Gap
Here’s the general hierarchy of the typical design system that I encounter:
Design System
- Principles
- Accessibility
- UI
• Global Styles
• Templates
• Components
• Styles
But that’s not always enough. We need to dive much further than just the surface of our product. For example, for certain elements, we should also define:
- Document structure and nesting
- Appropriate parent container elements
- Attributes, roles or microformats
- Text web standards and accessibility criteria
- Considerations for translation and localization
UI design alone is not a basis for a design system.
It’s actually more of an output of the system. The system therefore, must have inputs. Those inputs provide context for decisions.
Include them. Some decisions may have been well-informed through research. Other decisions may need no explanation. Still, others may be difficult to articulate and defend. But all are important to document.
“[looks at all products] …and then design this one single design system for everything. However, once you start diving into why those decisions were made, they often reveal local knowledge that your design system doesn’t solve.” — Rune Madsen
Pulling Up One Level: Describing Full Context of a Design System
Any design system is also greatly influenced by contextual inputs like:
- The institutional knowledge, legacy, culture, beliefs and biases of the organization (and those creating the system when done on behalf of clients)
- Insight for how patterns are named and what problems they solve
- Conventions for how class names and selectors are decided (with case, characters, separators, depth, specificity, etc.)
- Success criteria for a design system
- User research, usability research, and resulting data and themes that supports decisions in the design system
These all represent the decision making criteria in addition to the actual decisions.
A Meta Metaphor for Design Systems
So how do we capture this context?
In HTML, every document begins with a <head>.
The head element represents a collection of metadata for the document. Your design system needs a <head> to describe its context.
For example, while process, source control and governance typically fall under the role of Design Ops (operations), they should still be documented.
Here’s a structure for comprehensive metadata and a more complete design system:
<head>
Research & Insights
Principles & Ethics
Privacy & Security
Problem Statement(s)
Methodologies & Process
Definitions
Usage Guides
Other Criteria
Ecosystem
Localization
Performance Budget
Source Control
Governance
Copyright & Licensure
</head>
<body>
Design System
1. Principles
2. Accessibility
3. Platforms & Channel
4. Input
5. UI
5.1. Voice & Tone
5.2. Components and Patterns
5.3. Styles
5.4. Motion
6. Content
7. Localization & Variants
8. Performance Budget
9. Markup
9.1 Source Control
10. Hosting
11. Web View
</body>
Conclusion
All design systems have an origin story and iterate and evolve. Any changes made are the result of new learning. Capture that somewhere.
The “<head>” seems to be the perfect metaphor for that much needed layer of abstraction of all of the metadata about the design system.
UXPin is the design process tool that helps product teams around the world turn ideas into products faster.
With Merge, UXPin’s revolutionary technology, companies like PayPal can easily solve DesignOps challenges. UXPin Merge allows you to design with React components to achieve full consistency with the final product.
