There’s a high probability, that your first encounter with any particular design system happens through its public reference site. For example, if you wanted to learn more about Google’s Material Design system, you’d be browsing the content at https://material.io/. Or if you wanted to learn more about Shopify’s Polaris Design System, you’d be browsing the content at https://polaris.shopify.com/.
Also called a “documentation site” or “styleguide site,” we define a reference site to be “a visible manifestation of a design system, typically a URL that displays both the full component library and a set of guidelines.” The first homework assignment in our Design Systems 101 class is to build a few pages with an existing design system, and part of the point of the assignment is to emphasize how important a reference site for design system users. It’s a non-starter for your design system if you can’t even figure out how to download or import the dang thing.
Across our work with many teams creating design systems, we’ve collected a few best practices and recommendations for what sections and content users expect to find in a reference site, and where. While your terminology, syntax, and order may vary, these types of sections represent many of the things design system users need and want from a reference site. If you’re creating a reference site, consider this a starting point for your site’s information architecture.
Home: What’s the high-level value proposition for using this design system above others? Where can people find the most useful information? What’s the latest that’s been happening around this design system?
Get Started: How does one get rolling? Make download links and installation instructions extra apparent.
Guidelines: What should users know about how to make the best use of this design system?
- Accessibility: How does this design system ensure the widest range of usage for created products? What level of adherence to WCAG guidelines are recommended?
- Brand: What’s the appropriate balance of organizational, design system, and product brands?
- CSS: What methodology does this design system follow? BEM? OOCSS? Is there a global namespace or prefixes that should be used?
- Color: What’s the philosophy around using color in this design system?
- Data Display: What’s the best way to show data in any given context? Where to use a table vs. a list? Where are charts and graphs applicable? Static images vs. interactive data that can be manipulated?
- Date, Time, and Unit Formats: How does this design system suggest writing dates and times? What should be abbreviated? Metric system?
- Error Handling: What are this design system’s best practices around working with clean and complete data? What are the recommendations around reducing errors in data entry? What’s the appropriate balance of client-side and server-side validation? Is error handling real-time or only after attempted submissions?
- Forms or Data Entry: What are this design system’s best practices for creating forms? Should labels be left-aligned or top-aligned? Should tooltips or helper text be used?
- Grid System or Layout: How does one lay out a page with this design system? Is there a 12-column grid? Is there an 8-point grid?
- HTML: What are this design system’s best practices for writing HTML? How should text be indented? Wha’s the etiquette for comments?
- Icons: Where do icons live? How can they be used and referenced? Should they all be a certain size?
- Illustration: What’s the role of illustration in this design system? Should it be used sparingly? Liberally? Where? And where not?
- JavaScript: Does this design system use ES6? Does this design system’s JavaScript writing prefer an object-oriented, functional, or procedural approach?
- Localization & Internationalization: How can this design system’s elements adapt to different locales to signal the most appropriate culture fit? How flexible are the guidelines and elements to work with different languages and cultural norms?
- Mission or Principles or Values: What are the underlying philosophies of this design system? Why does it exist? What makes it distinct?
- Navigation: Should most products use vertical navigation or horizontal navigation? Why or why not? Is there a recommended minimum or maximum number of items in any given navigation? What’s the recommendation for local navigation?
- Performance: How important is performance in this design system? What elements exist to help users experience the lowest-friction interfaces?
- Process & Workflow: How do designers, developers, and product owners best use this design system? Separately? Together?
- Sound or Audio: What is this design system’s approach to working with sound? How should sound communicate appropriate personality and feedback?
- Spacing: Creating space in an interface can be done in so many different ways; how does this design system recommend doing that?
- Typography: What typefaces are allowed? How should they be used?
- Writing or Tone or Voice: Sentence case? Humor? Brevity vs. verbosity?
Components: The bread and butter of all design systems. What are all the components that can be used, and how?
- Accordion
- Breadcrumb
- Card
- etc.
Examples or Case Studies: An incredibly important section than often gets overlooked, showing examples of completed pages or products using the design system is one of the most helpful guides for design system users. It should also be one of the most exciting and inspiring sections of the reference site!
Support or Help: What resources are available to design system users when they’re stuck? Is there a helpdesk? A Slack channel? An email address?
Blog or News: What are the latest happenings with this design system? What’s being explored?
About: Who was responsible for creating this great system and reference site? Flex a little!
Release History or Changelog: Make it easy for current and potential contributors to see what has changed between each release. Frequent activity here also signals to users that the system is current, and they won’t likely be left high and dry.
Search: As a last resort.
Join 57,400+ subscribers to the weekly Dan Mall Teaches newsletter. I promise to keep my communication light and valuable!