DESIGN SYSTEMS

Guide #006: How to start a code-first Design System

Think reusability and shareability outside of your immediate projects. Try not to overextend yourself by building every use case.

Jason Stevens

Jan 12, 2023

Get buy-in with a clear definition of the problem(s) you’d like to solve

If you’re a developer looking to start a Design System, it’s likely because you’ve encountered some type of friction or inconsistency. Rather than dive right into building one, first seek to define the problem you're trying to solve or the ideal state you’d like to achieve. If you need to gain approval or buy-in for this work, align the benefits of a Design System with achieving a company goal. For example, if your company has prioritized an initiative to build more accessible products, frame the Design System as part of the solution for implementing more consistently accessible experiences.

Create a space for shared components and styles

Take a step back from your current projects, or even your current team, and think about how you might structure your component library so that other teams can use it. Think reusability and shareability outside of your immediate projects and team as your primary goal. Depending on your company’s code architecture, the simplest solution could be to create a new directory outside of your team’s main directory for your new sharable components and styles.

Start small and only build what you need

As you start to build components for a shared library, try not to overextend yourself by building every use case for a component. If you’re working with a design spec or refactoring code that already exists, accept that you may need to rewrite components multiple times as they get used. Don’t worry about getting it perfect or catching every edge case or attribute that a component might need. If you’re using React and TypeScript, architect your code to give yourself the flexibility to keep adding props/variants later.

Focus on components that are used across different teams and experiences

Adding edge case components will slow you down and distract you from focusing on components that everyone can benefit from. If a team needs a new component, it should not automatically be added to the Design System. Once you recognize the need for that component in two or three different applications, that’s when you should consider adding it to your shared library and supporting it.

Participate in code reviews with an eye for how your components are being used

As you build out a component library, maintain a close relationship with different product teams. When you review other people’s code, notice when your components are being adjusted or manipulated. If this happens repeatedly, especially by different teams, it’s a sign that you should extend or refactor the component. If your culture supports cross-team collaboration, be proactive and update your product team’s code base with your component fixes. This builds trust with your product teams, and you learn how your components are being used.

Document your decisions

As you create and add components to a shared library, document your decisions in a wiki or team documentation tool. Consider starting a working group with engineers from other teams. Encourage other engineers to review your code before adding it to the Design System. Maintaining documentation will increase the rate at which others adopt your system and join you in contributing to it.

Recruit partners on the design team and maintain visibility into what’s coming down the line

Participate in design standups or reviews where you can see how design is evolving. This will help you anticipate the needs of the Design System in the upcoming months. Share updates on your component library and be open to improvements and suggestions. Find an ally on the design team who will help you shepherd the work you’ve done within the code and translate it into the designer’s toolkit.

Featured expert

Katie Langerman

Senior Designer, GitHub

With a deep interest in how code connects design to engineering, Katie Langerman bridges the creative/tech divide. She also runs Ladies that UX Boston, empowering women in design and technology.

DESIGN SYSTEMS TOOLS STRATEGY

Suggestion Box