.svg){kind=logo}
Menu
Close
In a previous article, we looked at why it’s better to build a design system in Confluence than in design tools like Figma, or developer tools like Storybook. It’s because Figma and Storybook aren’t knowledge bases or documentation platforms, and Confluence is both. It’s also where all your teams are already working.
In this ultimate guide, we’ll look at how to structure, build, and maintain a Confluence design system in 8 steps. Then we’ll look at a design system documentation template for how you can structure your Confluence space. Finally we’ll look at a Confluence page template for documenting components.
If you’ve decided to build a design system, you probably already know your goals, or at least, you have a vague idea of them. But it’s important to get these crystallized and written down. And sometimes, you don’t know the exact purpose of your design system until you ask the right questions. So start with these:
Once you have answers to these questions, use them to articulate some overarching goals, which could be:
Design systems serve multiple teams with different needs. Now that you’ve listed some broad goals, create some more specific ones by identifying the core audience/s of your design system and what they need from it. This will help shape the contents, structure, and maintenance of your Confluence design system.
Here are some common audiences and their needs:
Although Confluence was designed for internal use, its anonymous access feature enables teams to make a space public. You may want to do this to show customers that you have a mature brand and you are proud of how your products are designed. It also increases accountability and can serve as a brilliant recruiting tool. And of course, it lets you work with external contractors and freelancers on product design.
If you decide not to make your Confluence design system public, you can still work with external partners because Confluence allows you to add guest users to a space (up to 5 guests per paid user).
You’ll need someone to take the lead on creating your design system. More often than not, the design system lead is a designer or team of designers. But in order to serve multiple audiences, the designer will need to work with other contributors to make sure everyone’s needs are covered.
For example, designers will need to work first and foremost with developers. Designers and developers will be the principal users of the design system, and it’s most important that it includes everything they need.
Designers should also work with product owners to make sure the design system documentation aligns with business goals and is structured in a way so as to encourage its adoption across teams.
A designer may also work with a copywriter to make sure tone of voice, grammar, and language requirements are all documented.
Determining how your Confluence design system will be structured is key to making sure it’s a useful and easily navigable resource. Here are some things to consider when deciding on your structure:
Now we come to the biggest step and the one that will take the longest. The most logical place to start is at the highest level, and work your way down to the detail. So, write the design principles and goals/purpose first. You could also create a “how to use this space” page, detailing the intended audience, how to request changes and improvements, who to reach out to for help, etc.
After that, move on to your foundations and brand guidelines, and then get into the nitty-gritty of your tokens, components, and patterns.
When you get to the stage of documenting design assets such as components and logos, this is when you’ll want to leverage some Atlassian Marketplace add-ons. Marketplace apps help make design systems more useful, maintainable, and scalable.
You can find dedicated developer integration apps for displaying live components and source code that users can interact with and inspect.
You can also embed Figma frames in Confluence pages using CollabSoft’s Figma for Confluence app. This saves you having to duplicate assets in the design system, and manually update them every time they change. The files live in Figma, but can be viewed in and downloaded from Confluence in whatever format you wish. Meanwhile, the app has a live sync with Figma that enables design updates to propagate automatically to Confluence.
In order to advocate your design system as a single source of truth, you can also use Figma for Confluence to pin a specific version to your Confluence page. This makes sure your design system is only showing fixed assets. Alternatively, you could institute a protocol within Figma itself to make sure designers don’t iterate on the frame linked to the design system. That they create a new version of the file, and only update the linked frame when the work is complete.
Either way, the ability to embed a locked-in Figma design is unique to CollabSoft’s Figma for Confluence app. Figma’s own Confluence feature doesn’t let you embed specific versions, so you’ll only ever see the live design. This makes instituting a policy in Figma your only option to make sure designs in the design system aren’t constantly changing while people are trying to use them.
The other thing that distinguishes CollabSoft’s app is that Confluence users don’t need a Figma license to see design assets on Confluence pages. With Figma’s native embed feature, Confluence users have to log in to Figma. You shouldn’t have to buy Figma licenses for non-designers just so they can use the design system.
When you’re creating your design system pages, you can use comments and @mentions in Confluence get input from team members on the content.
You can also create and share draft pages in Confluence, so that you can collaborate on the documentation before you finalize it. Alternatively, you can restrict access to a published page so that only those who need to contribute can see it. These options are especially important if you have made your design system space public using Confluence’s anonymous access feature.
Even when your pages are complete, it’s important to collect feedback from users, to make sure your design system documentation is meeting everyone’s needs. This will improve its quality and accuracy and encourage adoption across teams. It will also foster a culture of shared ownership, i.e. everyone plays a part in maintaining the design system, which helps it stay relevant and keep evolving.
A design system should be stable, but not static. Figma designs for logos shouldn’t be constantly changing while a marketing team is trying to use them in promotional materials. But equally, when design assets and patterns evolve, or accessibility standards change, the design system needs to be updated so that everyone’s singing from the same hymn sheet.
You should assign a design system maintenance lead to manage documentation updates, and designate team members within design and development as update owners. Update owners are responsible for informing the maintenance lead when there are code changes, new components or logos, and patterns that are outdated and need to be removed.
You could also create a request form in Jira for team members across the company to suggest improvements, so that you can continue to seek feedback on your design system long after it’s published.
What’s vitally important is that changes are communicated, which is why you need a changelog. You should also announce major updates likely to impact people’s work via team meetings and Slack/Google Chat. And you can set up Confluence notifications to alert users whenever there are changes to design system pages.
Now let’s look at some templates you can use to build your design system in Confluence.
Since Confluence only offers page templates, not space templates, we thought we’d make one ourselves.
So, here is a Confluence space template which you can use as a reference when building your design system page tree.
[Brief description of what the component does.]
[Give an overview of how the component should be used, e.g. use buttons when users need to either navigate through a product or perform a specific action.]
[Describe when each variation should be used, e.g. primary buttons for the most important actions, secondary buttons for actions that complement the primary action, or when multiple actions of equal importance are required]
[Describe when each variation should be used, e.g. medium-sized as default, small when space is limited]
The 8 steps described above will help you build a design system in Confluence that people want to use. A design system that serves the primary purpose of satisfying users and protecting your brand, by helping you keep the look and feel of your products and experiences consistent.
Defining goals and target audiences, working out a logical Confluence structure, and doing diligent design system maintenance are all essential for making sure the people who need to reference guidelines or access components can find them quickly and easily.
Meanwhile, organizing contributors and encouraging shared ownership of the documentation helps to speed adoption. This facilitates better developer-designer collaboration and improves speed and efficiency both at design handoff and during implementation.
If you’re looking at creating a Confluence design system, and you want to embed components and brand assets from Figma in your Confluence pages, try Figma for Confluence Pro free for 1 month.
A former lawyer, Berry loves theme parks, has published a sci-fi conspiracy thriller trilogy called Million Eyes to rave reviews, and is a specialist in writing content for tech companies.
