Getting Developers Started with a Design System

Onboard Step-by-Step So They Build with Confidence

Nathan Curtis
May 25, 2018 · 6 min read

A smooth onboarding is an essential moment in a product experience. That’s why an Getting Started as an Engineer is arguably the most important documentation your system publishes.

Engineers want to traverse simple, dependable steps that are quick, effortless, and painless. Getting stuck can be catastrophic. They should plow through, even in minutes. By the end, they yearn to feel empowered and successful, ready to weave the system throughout their codebase. This first impression is critical to make or break their belief, leaving them confident (yes!) or confounded (oh no!).

Getting Started for Engineers is not just positioned prominently on system’s homepage and in navigation. It should also be composed early as you iterate towards launch. The authoring process leads a team to affirm system architecture, test onboarding with key partners during a beta period, and polish it up by the time adoption is widespread.

Getting Started Content, Step-by-Step

#1. Installation

  • Choose how to consume assets that are hosted, downloaded (as pre-built or built by the adopter), or integrated via tools such as yarn, bower, npm, and/or gulp. (example: Material Design Lite).
  • Access such repositories, if authentication is required.
  • Apply the system to a specific platform like web versus React Native, Android, or Apple (example: Hudl Uniform).
  • Choose between a JavaScript-based framework like React or Vue or vanilla HTML & CSS, if both are available. (example: Shopify Polaris)
  • Integrate with or relate to other environments used by the community. (example: Salesforce Lightning Design System)

Takeaway: Don’t skimp on installation. If poorly described, you risk alienating adopters before they get through the front door and/or relying upon costly and disruptive calls for assistance.

#2. Inspect What’s Included

├── components/
│ ├── component.js
│ ├── component.sass
│ └── component markup/import
├── styles/
│ ├── system.css
│ └── system.min.css
├── tokens/
│ ├── system.tokens.json
│ └── system.tokens.scss
├── scripts/
│ ├── system.js
│ └── system.min.js
├── icons/
│ ├── system.svg
│ ├── download.svg
│ ├── check.svg
│ └── ...
├── fonts/
│ └── display/
└── ...

Takeaway: Help an engineer see and find what they want while sensitizing them to what’s to come. This familiarity improves confidence and momentum towards the tasks that remain.

#3. Apply Visual Style

  • Refer to “the main CSS” such via a <link> in the view (example: Morningstar Design System), if relevant.
  • Refer to icon assets, whether a single or set of SVGs or other file type(s).
  • Refer to fonts used for typography and/or icon symbols.
  • Load and compile pre-compiled style assets and functions like Sass mixins, when relevant.
  • Integrate and apply design tokens, whether as a file integrated into the library or consumed as a separate dependency.
  • Link with other libraries like animation (example: Angular Material) or photographs (as content repos?).

Takeaway: Don’t skip visual style as you barrel towards components. Empower engineers to ground and extend their implementation using the system with style tools and assets that are well-organized and dependable.

#4. Use a Component

  • Include a component, sometimes via import statement & folder paths.
  • Integrate a component by adding the element markup to a layout or invoking it via a script.
  • Configure a component in context, such as adding BEM modifier classes or adjusting props.
  • Properly encode components for maintainability, such as using functions or macros rather than copying and pasting markup.
  • Architect their own app (to the extent you can), often by viewing a sample reference application you publish based on your system.

This is almost always done by a single, sensitizing example akin to the “Hello World” of a component in an implementation.

Takeaway: Here more than anywhere, the focus should be on instructions and outcomes. Code examples are essential, but improving the instructions with rendered outputs can reinforce the “what you get” and provide opportunities to elaborate on the most important suggestions to optimize their adoption.

#5. Override / Extend a Component

Engineers need to know how to:

  • Compose in context to extend markup, style, and script to extend an existing component.
  • Apply lower-order system features — particularly, design tokens and primitive components like Icon and Button—to build a custom displays like a Card action bar.
  • Model composition in a manner consistent with system architecture, particularly if the work hints at a future system contribution.

Takeaway: As much as you may want to believe otherwise, a system doesn’t solve every problem for every adopter. Therefore, tune onboarding to the reality that a system serves as baseline tools that equip adopters to compose components themselves, too.

#6. Configure & Optimize What’s Used

  • Theme components to an alternative visual style.
  • Configure what assets are consumed to optimize outputs (like <link>ed CSS) and other downloads (like an icon SVG).

For more powerful configurations, these topics may warrant their own pages to describe more in-depth step-by-step processes. When this occurs, expose the scenarios here to familiarize first timers and link elsewhere to the details.

Takeaway: Since adaption can take many forms, limit onboarding materials to the most common case(s) for which your system invests in tuning its tooling.

#7. Learn the Rest: Principles, Methodology, Dependencies, and Resources

  • Principles on how code was architected, packaged, and distributed.
  • Standards serving as criteria of how code was made, such as accessibility and browsers supported. (Example: Discovery Education’s Comet)
  • General rules and recommendations, such as how to compose markup and classes. (Example: Material Lite)
  • Methodologies on how code was constructed, such as the BEM CSS methodology.
  • Dependencies like jQuery, Select2, polyfills and more that make their way into adopter’s front-end code (Example: Morningstar, IBM Carbon).
  • Resources to learn more about employed frameworks such as React or Vue. (Example: Shopify Polaris)

#8. Connect with the Community

  • Get help when things go wrong.
  • Identify defects of how things currently work.
  • Request features they lack the confidence or time to build themselves.
  • Contribute their own feature.

Takeaway: Conclude an onboarding process with calls-to-action that leave the a new adopter not stranded on an island but connected to a community. Encourage them to engage!

About to embark on a design system, or need to dive deeper to discuss products and players? EightShapes conducts systems planning workshops and coaches clients on design systems. Let’s talk!


A collection of stories, studies, and deep thinking from…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store