The design system is the shared language that lets developers, designers, and AI tools easily map mockups to what we build with. It’s a set of components, tokens, values and rules. It’s context that ensures UI is coherent across.
Basics
The Automattic Design System is a collection of various packages, used together to build products. Each package typically has a corresponding Figma library to utilize, and a Storybook instance where documentation can be found.
The Figma libraries are auto-attached to new Figma files. They are in lockstep with the shipping codebase. This ensures developers can map mockups to what they build with.
That means if you use a Button component, that Button has a code counterpart, likewise a Card, an ToggleControl, a CheckboxControl, etc. If something’s missing, it’s either intentional, or an error. For example the ToggleControl includes both a toggle and the text label to the right of it. This is because the code as it exists doesn’t allow you to use one without the other, to ensure its legibility for screen readers.
If you’re a designer:
- Check you have the right libraries attached. See the FAQ.
- Use the Figma asset search.
- Look at the source of truth, the code as documented in Storybook.
All relevant storybooks for each package are linked on the homepage.
If you’re an engineer:
- Point your AI tooling to this website, and the linked Storybook instances.
- Connect with your engineering friends in Slack.
If you want to contribute:
- The code, the source of truth for WordPress components, is the Gutenberg repository.
- It’s not static, it’s meant to evolve.
- It’s worth talking about.
Simplicity is not a simple thing, and there’s almost always a history of decisions that led to a particular design. That means the best evolution of such a design understands this history deeply, in order to evolve it. Look at open issues for each component in the repository, or ask the contributors to ensure you’ve captured the context.
Principles
Design principles are grounded in a core truth: humans love patterns. Consistency reduces cognitive load, speeds up task completion, and helps users feel confident across products.
Think in patterns
“Consistency is one of the most powerful usability principles: when things always behave the same, users don’t have to worry about what will happen”
Jakob Nielsen
Patterns reduce complexity, making it quicker and easier for users to perform tasks. The design system aims to level up the thinking from the specific use case or job to be done to the pattern. By identifying the make-up of a user journey, the design system seeks to identify the commonality that this behavior shares with other platform behaviors.
Think in reuse
For everything that you are designing and building, consider how to make it design system-ready. If it has potential for re-use or iteration into a different use case, consider building it for the system. If you are designing user experiences that are completely unique, consider whether that experience could be confusing to the user and consider a pattern driven approach instead.
It’s not all or nothing
Using, or contributing to the design system should not create blockers to progress.
Meet accessibility standards
The baseline for the design system is to meet a minimum of WCAG 2.1 AA standards across the board.
Learn the language
Adopt the design language of the system. This means being observant of the building blocks that exist, and building upon them. Always consider: what is the knock on effect, and whether changes can be made across the board.
Build sustainably
Consider the internal feedback carefully in your design decisions and aim to align to it. Balance whether to build new, vs. adopting what exists based on user needs and timelines.
Progress over perfection
Inclusion in the design system will be like a catchment area. We don’t need to reach 100% agreement on all aspects. Feedback is guidance, and we are striving for progress over perfection. It’s better to submit a provisional proposal for the design system which can then be tested and evolved than to build it locally in isolation.