Getting Started & Customize the Kit

The UI Kit is a free product from Koala. We've made it free because we want it to be accessible to as many people as possible, so that everyone can enjoy a resource created and designed by professionals. Sometimes, starting out can be difficult, and finding good references can be quite complicated.

Styles vs Components

Understanding the distinction in the UI Kit is important. On one hand, there are the basic components, and on the other hand, there are the styles, which provide color and shape to these components.

Local Variables & Figma Libraries

Figma works with local variables, allowing us to have a single document synchronized with others. In other words, a single document gathers all the styles.

For example, at Koala, we have the UI Kit, and separately, we have the pages and blocks. You might wonder why we've separated them. Well, for this simple reason: this way, in Figma, we create a team called Koala. Then, this team will have within it:

• Templates
• Clients
• Pages & Blocks
• Store
• Etc.

Each of these pages logically uses Koala's styles, but obviously, we won't be importing styles individually into each document. That would be inefficient, and most importantly, we would lose synchronization with the library.

Thanks to Figma libraries, we can use just one document, which will be published in the project. This document will be called the "UI Kit," and then in each project, we simply need to go to libraries and import the styles.

The benefits of doing it this way are:

• Keeping a document as lightweight as possible: Some users might only want to use Koala's styles. If we had unified everything, every time you wanted to use Koala, you would have to open the entire document with over 3,000 components. This way, you can work much faster without any problem, with a document that contains enough: the most basic styles and components.
• Maintaining synchronization for better consistency: This way, when we need to make a change in the UI Kit, there's no need to go document by document; updating the library is enough, and this will be updated in all documents.

If you want to learn more about libraries and variables, we recommend reading Figma's official documentation.

• Variables
• Libraries

Variables vs Styles

The first thing we want to mention is why we chose variables instead of local styles. Well, the difference is very simple: simply because we wanted to be able to use "themes." What are themes? We recommend watching this Figma video where it's explained much better.

This allows us to have a collection for each property:

• Primitives
• Colors
• Radius
• Spacings

This will allow us to then apply each of these properties separately. That is, in a design, you can configure the color and the border radius separately. We provide an example just below. Not only does this give us more control, but also more customization capability, and additionally, in the case of color, we can play with themes (light, dark & cream modes).

All of this is not possible with styles; it can only be achieved with variables.

Variables Walkaround

The first thing we see when opening the variables are four collections. We explain what each thing is and what you should do with each thing:

Primitives

If you notice, in the previous section of "variables vs styles," we separated primitives from the rest. This was intentional. Variables should be separated into 2 parts: the values and the tokens. We won't explain now what tokens are and how they work; we recommend watching this video so that it's well understood. In a few words, using #346725 is not the same as using "fg-text-primary." Therefore, the primitives collection is the folder of definition; it's advisable not to touch it, as we mentioned, it gathers all the definitions of the styles, which will then be used in the other collections. That is, in the "colors" collection, you will find a color called "background-brand"; this "brand" corresponds to a color, in this case, to our orange.

To make it clear:

• In the "colors" collection, you can change that the background-brand equals the brand color or the black color.
• And in the "primitives" collection, you can change that the brand color goes from an orange to a blue. That is, if you want to change the brand color of the entire UI Kit and Koala's ecosystem, you will have to go to the primitives and redefine your "brand" color.The primitive collection not only gathers colors but also numbers. This applies to border radius and spacing.

Colors

In this collection, the styles of all properties where color applies are gathered, that is:

• Components
• Texts
• Icons
• Backgrounds

Each element or component in the ecosystem is linked to a color tag; these colors are gathered in this collection. As we mentioned before, this collection only gathers tokens; if you want to change the root colors, you must do it in the primitives folder.

Radius

In this collection, we find all the tokens and tags related to the border of the components. We have separated it into 2 types:

• Cards
• Buttons

And in 3 modes:

• Sharp
• Rounded
• Full

Why have we made this separation? Simply to have more control; it's not the same to apply 8px of border radius in cards as in buttons. Cards are usually much larger elements than buttons, and in smaller versions, the border radius will always be greater.

That is: In this way, for a button to look the same as the border radius of a card, in this way we can apply "8px" to the card and "6px" to the button, so that in reductions it looks consistent.

We have created the 3 modes so that you can have the most possible customization.

Spacings

In this collection, we find all the tokens and tags related to spacings. At Koala, we use spacings to determine:

• Fixed width of certain elements: Container size, input sizes, etc.
• Distances between components. Paddings, gaps, etc.

At the moment, there are no more modes, but it's possible that in the future we will add "tight" & "minimal" modes, one with narrower values and the other with values with more breathing room. We have placed it in a separate collection specifically for this reason, so that in the future we can do things with this.

How to edit Variables?

There are 2 things to keep in mind:

• The primitives
• The tags

It's important to mention that to edit the variables, you have to consider what you really want to change.

• Do you want the "fg-text-primary" to go from "gray 600" to "gray 500"? Well, you will have to do this in the "colors" collection.
• If you want the "gray 600" to have a hexadecimal from #347823 to #78758, you must do this from the "primitives" collection.

Once again, we recommend watching this Figma video; they explain it very well.

Typography

At Koala UI, we use DM Sans, a freely available typography from Google, so we know that using this font will save us a lot of problems. However, we understand that you may want to use a more personalized typography for the project, so on each occasion, you'll be interested in using a different typography.

To update the typography and use a new one, we recommend using the free Figma plugin called "batch styler"; this will open a menu and from there you can change the typography all at once.

Something to keep in mind when changing typography is that Koala UI is designed for DM Sans; each typography has a typographic box, and it's possible that the A of DM Sans (for example) is not the same A as "Perfectly Nineties." This means that when you apply "24px" of line height in one, it will be a different height than in the other, sometimes drastically changing the style and spacing of the typography.

To maintain a typographic scale as consistent as possible when you're going to change typography, we recommend that you use this tool called typescale that will give you the most optimal values for the typography you choose.

Remember that if you are using pages & blocks, this change will affect more than 3,000 components throughout the Koala ecosystem. Simply keep in mind that this change will affect almost everywhere there is text, that is, everywhere. It's possibly the change that can affect the most in a Design System.

If you need help from an expert to configure all this, you can contact us without any problem. We will help you.

Components

In this document, you will see that we have collected certain components; these components are the primitives, the most basic ones. This is why there are some components in this UI Kit and then other components in the templates or in pages and blocks.

The UI Kit gathers the components that allow you to create designs and products; they are the most basic elements of the atom scheme.

‍