Architectural Knockout: Building Your Design System

9 min readJan 25, 2024

After the definition of the Architecture Design System (ADS) and its Concepts, it is time to present how to build an ADS using BAU tools. This is where theory meets practice, where your team’s collective knowledge transforms into a powerful, reusable toolset.

By mastering the system and its tools, you’re not just streamlining your design process; you’re setting a standard for efficiency and speed inside your team.

In order to implement the ADS, we need to select and use a set of tools that allow you to:

Create custom icons, such as services and general resources.
Create custom and well known diagrams defined within the ADS, such as, C4 model, BPMN 2.0, and UML.
Store and version the diagrams as code
Reuse all the ADS elements (styles and components) to build new foundations that will accelerate the diagraming, such as, patterns, layouts, and reference architectures.

Creating Custom Icons

Particularly in the case of custom diagrams, commonly used to explain the architecture elements to non-technical stakeholders. it is essential to establish and meticulously document a suite of custom icons. This ensures consistency and facilitates reuse across various presentations and materials.

The icons or element representations are the most effective method for communicating the essence of an architectural element and its primary function.

While it’s possible for these representations to be intricate, simplicity often enhances comprehension, maintenance, and the evolution of the system’s icons. Therefore, I recommend adopting a straightforward design approach that utilizes a clear container and an icon for each element.

Select your Icon

Your first challenge, it is to select the appropriate icon for the element as it involves distilling an entire concept into a single image.

To meet this challenge, I typically turn to resources like thenounproject.com to find icons using a single noun that embody the most significant attribute of the element that I am designing. However, nowadays, there are numerous tools available for crafting icons without the need for licensing fees. Below, I’ve listed some of these resources for your convenience:

Once the icon is selected or crafted, My recommendation is to store it in svg format so you can use it later on and adapt its color to the ADS style.

Implement an element representation

To seamlessly integrate the icon with the background, forming a new reusable element, I use Figma.

Figma facilitates the creation of a versatile component, which can be easily cloned and adapted as required, ensuring both efficiency and consistency in our design process. By defining a component in Figma, we can generate variants of it, wherein only the icon image needs to be replaced. This approach allows us to reuse all other attributes and features already established in the parent component, streamlining the design process.

Creating the service representation component

The steps outlined below detail the process for creating a “‘service representation”, which will serve as the foundational component.

Create a new page with the name Service representation
Create a square of 100 X 100
Add corner radius of 4
Add the background color #FFD759
Add the image and setup its size to 80x80
Align the image within the center of the square
Select both elements group them
Name the group as service
Add an auto layout and make sure that the align is in the center
The horizontal padding and vertical padding should be both 10

Once you create the layout transform the group into a frame
Right-click on the frame and select Create component.
Make sure the name of the component is Service.

The final result should look like this.

Create a new service representation icon

The icon selected is the documents representation taken from the noun project and identified with the code 746384.

Select the service component
Copy and paste
Select the instance object
Name the new element as you need, e.g. “general-purpose”
Select the icon image, by double clicking until you get there, or navigating through the elements in the left toolbar
Go to image property in the right toolbar
Select the image and click on choose image

Replace the existing image with the new one
Select the element
Add a svg export, by selecting the new element and got to the final section in the right tool bar
Export the file to svg

The final result should look like this.

Assignement: Create elements representations for all your icons.

Creating Custom Diagrams

In our quest to streamline the creation of diagrams within our design system, we conducted a comprehensive evaluation of various tools. After careful consideration of several factors, which I will detail in an upcoming article, we have chosen draw.io as our primary tool.

Draw.io stands out for its versatility in supporting a wide range of diagram types crucial for software architecture. It enables us to efficiently create diagrams based on the C4 model, BPMN 2.0, and UML. This selection aligns perfectly with the requirements outlined in our Architecture Design System (ADS).

One of the key strengths of draw.io is its extensive library of elements and templates, which facilitates rapid generation of custom diagrams. This library not only accelerates the design process but also ensures consistency across all our documentation. Whether we are mapping complex system architectures or detailing intricate processes, draw.io provides the flexibility to represent various elements accurately and effectively.

In conclusion, draw.io emerges as an indispensable tool in our design toolkit. Its comprehensive features and flexibility make it an excellent choice for crafting detailed and consistent software architecture diagrams, laying a strong foundation for our design system and enhancing our overall design workflow.

Round 1 — Creating icon libraries

We need to prepare a set of libraries that we can reuse every time a new custom diagram is created. In order to do so follow the next steps

Open diagrams.net (draw.io): Start by going to the diagrams.net website or opening the desktop application if you have it installed.
Create or Open a Diagram: You can start with a new diagram or open an existing one where you want to create the library.
Import Icons:To import, go to File > Import From and choose the source. You can import SVGs, images, and other supported formats to use as icons.
Add Icons to a New Library:

Select the icon you want to add to your library.
Click on + sign in the bottom panel of the Library pane on the left side.
Choose New Library and give it a name.

5. Add Icons to the Library:

With the library open, drag and drop your icons or custom shapes into the library pane.
Alternatively, select the shape or icon on the canvas, then click the Edit menu and choose Add to Library.

6. Edit Icon Properties:

Right-click on the icon in the library and select Edit.
Here, you can change the icon’s title, add a search tag, and modify other properties.

7. Save Your Library: Once you have added all your icons, click on the Save button in the library pane to keep your library for future use.

8. Use Your Icons: To use an icon from your library, simply drag it from the library pane onto the canvas.

9. Export/Share Your Library:

Right-click on the library’s title in the library pane.
Choose Export Library to save it as a .xml file, which you can share or import into diagrams.net later.

10. Save your library in a folder (design-system/components/services) with the name ads-services.xml

Round 2 — Creating group libraries

Do the same steps for the icons associated with groups, and save your library in the folder design-system/components/groups with the name ads-groups-icons.xml

The groups elements in the ADS are not only icons, they are composed by a frame that enclosed the elements that belongs to that particular group. In order to do that, we are going to create a shape in draw.io and add it to a new library.

Import the icon that represent the group.
Resize the icon to 50 x 50 dimensions
Add a text box aligned to the left
Align the text and the icon in the middle
Group the icon and the text box

6. Select the group and add a line

7. then select the icon and text again and move it one space to the right and one space to bottom.

8. Go to style/property and uncheck the Resize Children attribute

9. Select the group and resize to 480 x 320

10. Select the icon and change the property editable to false

11. Select the text box and uncheck the properties

a. Movable

b. Rotatable

c. Cloneable

d. Deletable

12. Select the shape and add it to a new library

13. Repeat these steps for every group in the ADS to complete the groups library

14. Export your library and save it in the folder design-system/components/groups with the name ads-groups.xml

Round 3 — Setting up your design environment

With our custom diagram libraries now in place, enhancing the architect’s experience becomes paramount. Our focus shifts to simplifying the creation, documentation, and storage of these diagrams. To achieve this, we are leveraging the power of existing Integrated Development Environments (IDEs). These IDEs offer advanced capabilities for crafting markdown documents and seamless integration with Git repositories, thus streamlining our diagram generation process and enriching the overall architectural design workflow.

My recommendation is to use MS Visual Studio Code with Daw.io extension.

Download Visual Code and install it from here
Go to extensions and look for draw.io and install the one shown below

3. Once that you have installed the plugin you are able to open it by pressing command+shift+p writing Draw.io and selecting the option named New Draw.io Diagram

4. Go to file/import and select the ads-service.xml file

5. Go to file/import and select the ads-arrows.xml file

6. Go to file/import and select the ads-groups-icons.xml file

7. Go to file/import and select the ads-groups.xml file

Storage the diagrams as code

Setup the repository structure

The repository should contains all the design system elements, to achieve that I am proposing create a structure of folders that is depicted as follows:

design-system/
┣ components/
┃ ┣ arrows/
┃ ┣ groups/
┃ ┣ resources/
┃ ┣ services/
┣ foundations/
┃ ┣ layouts/
┃ ┣ patterns/
┃ ┣ reference-architectures/
┃ ┃ ┗ domain/
┃ ┃   ┗ product/
┃ ┃ ┃   ┣ application/
┃ ┃ ┃   ┣ business/
┃ ┃ ┃   ┣ data/
┃ ┃ ┃   ┗ infrastructure/
┣ styles/
┃ ┣ icons/
┃ ┃ ┣ groups/
┃ ┃ ┣ services/
┃ ┃ ┗ sources/
┗ README.md

Now it is your turn create your first diagram!

Use the IDE and create a new file with the extension .drawio
Generate your diagram using the libraries
Save the diagram into foundations folder accordingly

You will find that, now you can easily version your diagram and manage it in the repository.

Please let me know if you would like me to create a repository for sharing an example. You can do this by clicking ‘Clap’ and leaving a comment.