Reference Open Source Site

  • 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  guidelines are recommended?
    • Brand: What’s the appropriate balance of organizational, design system, and product brands?
    • CSS: What methodology does this design system follow? ? ? 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.