We kicked off a new design system project this week. It provided a valuable opportunity to distil our thoughts and experiences around best practices for establishing a new project. We made ourselves a checklist of design system questions and tooling considerations which you may find helpful.
General questions
Below are some common questions to ask your project owner during kickoff. While some may seem obvious, it’s important to include them since the initial scramble can be chaotic and it’s easy to overlook things.
What are the stakeholder expectations?
As we’ve been making design systems a long time, it’s easy to presume what is expected of a design system, however the desired outcomes are likely nuanced. To avoid costly assumptions it’s good to scrutinise delivery expectations to distil the project’s scope. Discuss and document, at regular intervals, so that all relevant parties are aligned from the outset.
Who will use the design system?
While this might seem like a silly question, it’s vital that we understand who we’re building for. Consider the various disciplines that will use the design system e.g. designers, developers, content editors, product owners etc. and acknowledge that their expectations and competency will differ. Assuming too much about consumers risks alienating those who aren’t as familiar with design systems.
Where should we predominantly focus our time?
It’s often the case that more than one product will benefit from the design system. However, there’s typically one project that will be the “test-flight”. Make sure that the initial effort focuses almost exclusively on the requirements of that project. There’s no point spending time on e.g. a DatePicker when it won’t be necessary for 6 months.
Is there a requirement for language support i.e i18n?
Introducing support for localisation into a design system that’s in-flight is far more difficult than preparing for it from the start.
Is there a requirement for theme support? e.g. light/dark mode, multi-brand, etc.
If there’s even a hint that theme support will be required in the future, build support for it from the start. Trying to introduce theming later in the project is difficult.
What level of accessibility conformance is acceptable?
While we should strive for an inclusive web, the project’s needs and budget must be considered. Make sure stakeholders understand what is expected depending on their user requirements, and what is involved to meet those requirements.
Is there an existing system that must be extended?
Starting fresh will almost always be quicker and easier than updating existing systems. Somewhat counterintuitive, and difficult to sell to the project owner; modifying components etc., that are already in production adds a great deal of overhead to the build.
Is there an expectation that the design system will include a dedicated documentation website?
Building a documentation website is deceptively non-trivial. Where possible, avoid this investment until it’s warranted, Storybook is typically enough to begin building and sharing progress.
How much time should be invested building the thing VS defining a roadmap for next steps?
Ideally, depending on the length of the engagement, the implementation does most of the heavy lifting, laying foundational tooling and outlining best practices. Leaving breadcrumbs for other designers and developers to follow is more efficient than writing documents, but there’s definitely a balance to be struck.
Who, at Client Company, will be responsible for the design system?
This person should be a champion for the design system and promote adoption. Ideally they are competent in design and development, and capable of connecting the system with the teams and products that consume it. More people ≠ better outcomes: One person is capable of steering a ship, more than one increases the likelihood of indirection. We still want ambassadors to advocate for the design system, but a single person should be responsible for its direction.
Design system assets
What will be used for the assets below and where are the resources stored?
Iconography
Typically this will be a free and open-source library of SVG files. Though it could be a custom, in-house solution. Finding this out early will inform how you move forward with build steps etc., to keep design and development in sync.
Typography
Projects often require the use of one or more brand fonts. Make sure you see the license agreement: project owners sometimes assume that they have bought the font outright but in a lot of cases they only have a “desktop” license, not a web license. It’s our job to limit potential exposure for them.
Illustrations
These are often in-house designs, that compose SVG elements from open licensed libraries. Finding this out early will inform how you move forward with build steps etc., to keep design and development in sync.
Imagery
Ideally this can be avoided, better to inline SVGs where possible. When necessary, it’s important to make a plan for how images will be stored and served to the user.
Glossary
This one might seem out of place but it’s important to find or define as soon as possible. Every company uses their own jargon for miscellaneous terminology; when all parties are on the same page things move smoothly.
Design system tooling
Baseline*
Project requirements and constraints will vary wildly but there’s a handful of tools that can hopefully* be assumed as a certainty.
Confirm the following with the project owner, and decide on versions where applicable:
Project dependent
While we all have preferences, many tools will be influenced by existing projects and the project owner’s familiarity + confidence.
The following list includes a handful of examples but is far from exhaustive. Choices here should be discussed with the owner to ensure that they fully understand the pros and cons of each decision with regard to their current and future requirements:
- Styling
- Compiled, developed by Atlassian, is a styling solution designed to streamline the creation of consistent and maintainable UI components. It offers a declarative syntax for defining styles, enabling developers to encapsulate design decisions and enhance code reusability. Compiled prioritises performance and scalability, making it suitable for building large-scale applications with complex styling requirements.
- Emotion is popular in the React ecosystem, offering powerful features for styling components. It is a CSS-in-JS styling solution, allowing developers to write styles directly within their JavaScript code. Emotion emphasises flexibility, offering various utilities for managing styles, including theming, global styles, and dynamic styles based on component props.
- StyleX is a modern styling solution developed by Meta (formerly Facebook), optimised for building scalable and maintainable user interfaces. It introduces a new approach to styling components using JavaScript and CSS variables. With StyleX, developers can define styles programmatically and leverage composition to create reusable style components.
- Tailwind CSS is a utility-first CSS framework that provides a comprehensive set of pre-defined utility classes for building user interfaces. It emphasises simplicity and rapid development by enabling developers to apply styles directly to HTML elements. Tailwind's utility-first approach facilitates quick prototyping and responsive design, offering a robust foundation for creating custom designs without the need for extensive CSS expertise.
- Vanilla Extract is a zero-runtime "stylesheets in TypeScript" solution that generates static CSS files at build time. It offers a type-safe approach to styling, enabling developers to write styles using familiar CSS syntax while leveraging the benefits of type checking. Vanilla Extract emphasizes performance and maintainability, producing optimized CSS output and enabling efficient caching and serving of stylesheets.
- Framework
- Package management
- npm or Node Package Manager, is a widely used JavaScript package manager integrated with Node.js. It offers a vast repository of open-source packages for developers and simplifies dependency management and project updates through its command-line interface.
- pnpm stands out with its symlink-based approach to dependency management, reducing disk space usage and speeding up installation times. It shares dependencies across projects, promoting resource efficiency without sacrificing project isolation.
- Yarn, developed by Facebook, Google, and others, prioritises performance, security, and consistency. It features fast dependency management, deterministic builds, and offline package installation, optimising development workflows and enabling developers to focus on coding.
- Design tokens — assuming tokens will be stored and managed in Figma, you may want a tool to translate token data from one format to another.
- Diez (FOSS) is a design token framework focused on generating cross-platform design code using a single source of truth. It enables designers and developers to collaborate effectively by automatically synchronising design changes across multiple platforms, including iOS, Android, and web.
- Style Dictionary (FOSS), from Amazon, provides a flexible and customisable platform for managing design tokens and generating platform-specific output. It offers extensive configuration options and supports multiple platforms, making it suitable for large-scale design systems.
- Theo (FOSS), from SalesForce, facilitates the conversion of design tokens into various formats, such as JSON, SCSS, and CSS. It streamlines the process of maintaining design consistency across different platforms and environments.
- Specify (paid) is a design token engine designed to streamline the process of creating and managing design systems. It offers a user-friendly interface for defining and organising design tokens, allowing teams to efficiently generate platform-specific output for their projects.
- Supernova (paid) is a design system tool focused on bridging the gap between design and development workflows. It offers features such as automated code generation, version control, and integration with popular design tools, enabling teams to efficiently translate design decisions into production-ready code.
- ZeroHeight (paid) is a design system platform that centralises the documentation and distribution of design systems. It provides a collaborative space for designers and developers to create, organise, and share design tokens and components, ensuring consistency across projects.
- Module bundler
- Parcel is a zero-config module bundler that simplifies the development process by automatically resolving dependencies and supporting various file formats out of the box. It offers fast and efficient builds with minimal configuration.
- Rollup is a module bundler known for its tree-shaking capabilities, which eliminate unused code to produce smaller bundles. It focuses on producing optimised output for libraries and packages, leveraging ES module syntax for efficient code splitting.
- Vite is a modern build tool that leverages native ES module imports to deliver lightning-fast development experiences. It offers instant server start times and supports hot module replacement, making it ideal for building Vue.js and React applications.
- Webpack is a powerful and highly configurable module bundler widely used in the JavaScript ecosystem. It offers extensive customisation options and supports a wide range of loaders and plugins for handling diverse project requirements, including code splitting, asset optimisation, and module bundling.
- Component library
- React Aria Components is a robust and mature headless UI library from Adobe. Over 40 components with built-in behaviour, adaptive interactions, top-tier accessibility, and internationalisation out of the box.
- Radix UI is an open source component library optimised for fast development, easy maintenance, and accessibility.
- Ariakit is an unstyled open source library with a focus on accessibility and composability.
- Testing
- Jest is the obvious candidate for a test runner, due to its wide usage, support for a variety of testing strategies, and ease of setup.
- Vitest is modern Jest-compatible test runner built on top of Vite with out-of-the-box support for ESM, TypeScript, and JSX.
- React Testing Library should be more than adequate for unit and integration tests. It encourages writing tests that focus on the behaviour of components from the user's perspective, resulting in more robust and maintainable tests.
- Playwright tests are powerful but can be resource-intensive. They provide end-to-end testing capabilities, making them ideal for ensuring the functionality and usability of user journeys. However, due to their cost in terms of execution time and resources, we suggest limiting their usage to the most critical user journeys.
- Axe tests can be included with end-to-end tests to ensure user journeys contain no violations. Unit tests should cover discrete a11y support; they lack important context to be valuable candidates for Axe testing.
