Figma structure for library

The documentation in this issue is now deprecated. See the most up-to-date documentation: https://gitlab.com/gitlab-org/gitlab-design/-/blob/master/CONTRIBUTING-Figma.md#document-and-asset-library-structure

---

With Figma, we can organize components in the library by how they are structured or named in the document.

The default hierarchy is File/Page/Frame/Layer

It is also possible to use a slash convention in frame and layer names to structure the assets (similar to Sketch).

Figma docs →

Organizing components in a library →

Proposal

Because we’d like to incorporate Figma frames as specs within Pajamas, similar to how we output with Sketch Measure today, having common assets within one parent frame is the easiest way to share and incorporate designs into Pajamas, issues, and MRs, etc.

In a quick poll, all respondents (10) preferred one page with all variants as opposed to multiple pages.

Another benefit of a parent frame is that is can help clarify options in the Assets panel. For example, a frame named “Variants” for alerts let’s a designer know they are selection from a different variation of an alert.

We aim to keep the hierarchy DRY, and focus more on including structure specific to component context. If we didn’t put variants within a frame, we could easily keep the naming light, but it’d be at the cost of not having a specific frame to link to as specs.

Here’s a proposed hierarchy for structure and naming. Depending on the complexity of the component, the slash convention could also be used on the frame.

Page: [Component]
Frame: [Category], [Group] or “Variants”
Layer: [Breakpoint/Item/Size/State]

• Optional breakpoints (uppercase): XS, SM, MD, LG, XL, breakpoints can also use symbols to indicate range, such as ≥MD or ≤SM
• Optional sizes (lowercase): xs, sm, md, lg, xl, xxl

Examples

Page: Icons
Frame: Actions
Layer: Export
Result: Icons/Actions/Export

Page: Alerts
Frame: Variants
Layer: Danger
Result: Alerts/Variants/Danger

Page: Pagination
Frame: Variants
Layer: ≤MD/Truncated
Result: Pagination/Variants/≤MD/Truncated

Page: Toggles
Frame: Variants
Layer: On/Default
Result: Toggles/Variants/On/Default

Buttons are an example of something more complex, not because of the component, but because of the amount of variants. Given that it may be ideal to link to one design specs page, we could have something like this:

Page: Buttons
Frame: Variants
Layer: Primary/Info/Default
Result: Buttons/Variants/Primary/Info/Default

Icons	Toggles	Alerts	Pagination