Naming and organization of symbols in the GitLab Design Library
As we’ve decided to adopt Sketch libraries to implement the GitLab design library, the first step would be to come to a consensus on the naming scheme and organization of the symbols.
Goals
- The design library should be the source of truth for designers with the most current design patterns (design.gitlab.com will be the source of truth for developers).
- It should be a 1:1 match with the coded components, both visually and structurally.
- It should be easy to maintain – Updates or additions should be simple so that designers get the latest without much wait.
The naming scheme and hierarchy is crucial to both the documentation of our design library as well as for the day-to-day productivity of designers using the library.
Productivity equals what works, not what’s newest. The design system is the interface for the designer to expand on the product. The goal here is to organize the various design patterns in GitLab into a simple package for designers.
Below are some thoughts and suggestions on how we can achieve the above goals with a simpler organization scheme.
Using Pages for Organization
The current elements file has the bulk of the symbols in the “Symbols” page (except for the icons). We can group these in their own pages. For example: Create separate pages for Colors, Icons, Buttons, etc. These pages act as the top-level namespace for all the buttons. Also, this organization scheme matches that of design.gitlab.com.
- Getting Started
- Colors
- Icons
- Avatars
- Badges
- Breadcrumbs
- Buttons
- ...
- ...
- Library Preview
The Library Preview is to give our Library a custom preview image when you go to add the Library in Sketch’s preferences (this is now supported by default in Sketch as of v48). It includes a 200x160 artboard with the name Library Preview
.
Naming Symbols
Atomic design framework helps us with a mental model of how large components are broken into smaller pieces. However, we need not reflect this in our naming scheme. The naming scheme is basically the interface with which we, as designers, interact with the design library. Hence we can follow a scheme that closely resembles that of design.gitlab.com.
Note: This has nothing to do with organizing symbols in pages (described above).
colors/
blue
green
grey
...
icons/
abuse
account
appearance
...
components/
avatar
badge
breadcrumbs
...
views/
navigation
issuables
pipeline-table
search
_overrides/
colors/
blue/
blue-050
blue-100
...
...
components/
avatars/
group-avatar
project-avatar
user-avatar
...
Modifiers and molecules that make up a component can be moved to the _overrides
namespace. This is very similar to how the built-in iOS Sketch library is organized. By doing this we have a clean components
namespaces with one of all the unique components.
We can retain the lower-case naming convention. However we must avoid using abbreviated spellings for a cleaner naming style. Eg. Change icn/close
to icons/close
for the close icon.
Variable Symbols
An in-depth tutorial on this technique can be found here.
The goal here is to keep the symbol tree simple and easily navigable for better designer productivity. By doing this, we’ll have a top-level namespace called components
, within which we’ll have just one of all the unique components of our design library.
components/
avatar
badge
breadcrumb
button
...
...
When using the design library, in order to use a button, we can just add components/button
. This button symbol can now be overridden to its various states or types.
Limiting Symbol Overrides with Locked Layers
Symbols may be overridable but within their logically acceptable limits. For example, in the toast component, it makes sense to lock the close button symbols as we’ll never have to remove or customize it. The logic here is that, if we were to override the close button to something else, then the resulting component will not logically be a toast component. This breaks our design pattern usage.
Ordering Symbol Layers
The order of your layers in your symbols matter. How they’re ordered in the symbol is how they’ll be ordered in the Overrides panel.
Symbol Layers in an artboard can be arranged in the order that closely resembles the component’s visual appearance. We can prioritize top to bottom and left to right when ordering symbol layers. This need not be a hard rule but a guideline for consistency.
Ordering Artboards
Artboards can be ordered in a reverse-alphabetical order (Z on top and A at the bottom). The reasoning behind this is that Sketch indexes artboards from bottom to top. We can use the “Make Grid” tool to cleanly distribute the artboards in a page.
Plugin Recommendations
- Sketch Runner – General workflow management
- Sort Me – To sort layers and artboards in asc./desc. order
- Rename It – For bulk renaming of layers and artboards using regexp.
- Stark – Color-blindness simulation
Next Action
Rather than tackling the problems all at once, we can organize the GitLab design library methodically.
- First, we can move colors and icons to their own pages.
- Next, we can start the process of moving and reorganizing individual components as they are listed on design.gitlab.com.
- Finally, we can assemble and verify the page components and add them as symbols to the library.
This exercise can ultimately help us comb through the current design library and fix inconsistencies in naming, spacing, and over normalization.
cc. @cperessini @dimitrieh @hazelyang @pedroms @sarrahvesselov @tauriedavis