Skip to main content

Contributing to the Figma Library

To ensure consistent quality and a seamless workflow, the Design System Designers follow conventions and best practices when working with Figma.

note

This document talks to both experienced and novice Figma users to also help while onboarding new team members.

Overview​

We use Figma for:

  • all visual UI & UX design
  • design feedback via comments, live collaboration, and figjam
  • prototyping of designs, components and high-level animations
  • (branches) version control of all design files

There is a dedicated project in Figma for the Design System libraries. These libraries contain all components which are linked as dependencies to other Figma files, even across projects

Setup — Before You Start Working​

  • Set up your Figma account and request invite to the adjust Team. It's highly recommended to use the Figma Desktop app instead of the browser version.
  • In the Figma Desktop app (does not work in the browser version), enable Figma → Color Space and make sure sRGB is selected.
  • If you have no custom display color calibration, go to your OSX System Preferences and select Displays, change to the tab Color and select sRGB IEC61966-2.1 from the profile list on the left.
  • Install the font San Francisco: Download Apple San Francisco Pro
  • Install the following Figma plugin:

Conventions​

General​

  • Components in Figma which map to components in production must have the same name.
  • Text styles, color presets, effects and margins map directly to the design tokens in production.
  • Stick to the naming scheme.
  • For any text, use text styles.
  • For any color, use a Color Variable from the Core library.
  • For any effect, use a Effect from the Core library if it represents an elevation type.

Do Not Over-Complicate​

Figma offers plenty powerful features for components. It is tempting to try and hone the perfect shared library but this is not a realistic goal.

Try to keep components as simple or complex as reasonable, don’t go too crazy with auto layout, variants, and interactive components.

Do Not Add Component Categories​

Organize components in your library files in only the follwing categories:

  • Actions
  • Data
  • Feedback
  • Input
  • Layout
  • Navigation
  • Typography
  • Helpers

Don’t add more categories. If you feel a new component does not fit any category or if you have an idea to improve categorization, please reach out to the design system team.

Use these Figma Features for Consistency​

Figma offers a set of great features to basically define once and re-use:

By creating a Figma library and linking it to other documents, you have a powerful centralized resource from which changes get distributed to all instances.

Please makes sure you first learn everything about these features from the Figma manual.

Stick to the Naming Scheme for Components​

Figma lets you organize components by page and frame structure. For example, a component that lives in the feedback page and within a frame named tooltip will show up in the Assets sidebar within the expandable sections: feedback → tooltip → component name.

For different states of components, use Variants. Try to avoid creating stand alone components just to cover eg. hover or active states. To bulk rename multiple components, use the Rename It plugin.

Make sure to name your layers and groups. All layer names, component names and variant names must be written in lowercase. In addition to a name, you should add a description for each component (note: don’t add a description for variants, the two are often confused). The description should look like this: Component Name (variant1; variant2; variant3) , for example: Drag Card (size; type; state).

Naming Principles

For finding good component names, please check out our Naming Principles Page.

Analogous Terms for Naming​

These word pairs may help you with naming and structuring your symbols:

  • Size: [small | medium | large ]
  • Horizontal Position: [left | middle | right]
  • Vertical Position: [top | middle | bottom], [above | below]
  • Composition: [single | combined]
  • Direction: [up | right | down | left]
  • State: [default | active | disabled | focus | hover | invalid | highlighted], [collapsed | expanded], [open | closed], [on | off]

Be Obsessively Tidy (in Libraries)​

Since libraries are distributed to all other documents and used by all other designers on your team, it is important to keep them very very tidy. Libraries should always have neatly named frames, groups, and layers. The component pages should always be organized in order and aligned correctly.

For your designs, make sure you always stick to defined margins and paddings. Be pixel-perfect.

Also: Test your component! Make sure all auto layout settings, resizing, and variants work as expected.

Name all your layers — and name them well! Avoid bad field labels like layer 1, aim for more meaningful labels like title. On components that do require some kind of information or documentation for other team members, use the component Description field.

Be Slightly Sloppy (in Layouts and Drafts)​

When working on Figma documents other than libraries, it is okay to be a little loose with naming layers or organizing frames. It simply speeds up your work and you can always clean up stuff later (if you even need to), once everything got signed off.

But once you create a new component (which you then add to a library), you must switch back to OCD mode!

Avoid Decoration​

Please don’t add random emojis, ascii symbols or any other decoration to file or layer names in the library files. Remember that you are collaborating with other people and what might seem fun in the moment could turn into a distraction later on.

All documentation should go on the Design System website to make it accessible to the whole team and company. Avoid putting comments or onboarding instructions into Figma files because managing similar information in multiple places will produce mistakes and confusion.

Version Management with Branches​

Branches are controlled environments—like sandboxes—where you can explore changes to styles, components, and other aspects of a file or library without affecting the main file.

Before starting work on a new component, or any updates to an existing component, color, text, or effect styles, you should create a new branch.

Branch naming conventions​

Name your branch with the following convention: [Jira Ticket]/[short-description-lowercase]. For example, if you are working on a ticket (FIG-324 in Jira) that has the feature request to create a new component called Status Indicator, you should create a branch called FIG-324/status-indicator.

Before merging​

When you're satisfied with your changes, you can start the review process and in the end merge your branch with the main file. You'll have the option to resolve any conflicts before applying changes from your branch to the main file.

Before merging a branch into the main file, make sure that:

  • You've pulled all updates from the main file, so that you have the latest version of the file.
  • Resolved all possible merge conflicts.
  • Your additions or changes have been reviewed and approved by at least one team member of the Atlas design team. This needs to be done via the Figma Review feature.

Figma Component QA Checklist​

Whenever you add a new component to a shared library, go through this checklist to make sure there are no mistakes and your teammates can use it without problems.

Did you …

  • pick a meaningful component name and correct structure?
  • put the component in the category that fits best?
  • pick meaningful layer names (as labels for overrides)?
  • use only color variables (instead of plain colors)?
  • set all outlines to inside?
  • check all alignment, margins, paddings, sizes — is everything on grid?

Figma Component Handover Checklist​

Before the grooming session with the developers, make sure you completed the following steps.

Did you …

  • apply updates from linked libraries (blue dot on library icon in the Assets tab)?
  • prepare a card on the index page in Core?
  • added a link to the relevant index card on Jira ticket?
  • delete all proposals, sketches etc. that do not belong into the library?

Tips​