Icon naming and aliases
What
As the icon library continues to grow and individual icons get added or updated (&1557) it could be beneficial to document icon naming guidelines, consider new features (like aliases), and update the workflow.
The result of updated naming conventions would be present in:
- Design file artboard names and organization
- Pajamas documentation (added to this page)
- The GitLab SVG project icon file names and aliases
Why
Icons are not fully categorized, named consistently, grouped, easily searched, or mapped to their use or alternate meanings.
Considerations
It would be a lot of work to update all icons at once. The scope of this issue is simply to get a consensus on naming and ideas around workflow so we can complete documentation and begin to open other issues to handle the associated work as time allows.
The current icon workflow per @leipert is:
- UX: designs new icon
- Frontend maintainer: merges new icon
- Frontend maintainer: releases new version of icon library
- Frontend: In case of icon renaming, has to search for every use in CE/EE, and replace the name. This is very tedious and error prone. (See this issue https://gitlab.com/gitlab-org/gitlab-ce/issues/49236)
- Frontend: Creates CE merge request with library update, maybe a EE MR as well.
- UX: Does review of MRs
- Frontend maintainer: Does review of MRs and merges them
Proposal
- Use a BEM-like format for icon naming; for example,
[category]__[object]--[modifier]
.symbol__plus.svg
symbol__plus--sm.svg
git__merge.svg
git__merge--closed.svg
action__close.svg
action__close--solid.svg
object__weight.svg
object__folder--open.svg
- Use literal names for the icon object as the default, with the ability to name icons per the concept as a fallback.
- A
+
icon namedsymbol__plus.svg
- A
○
icon used for status namedstatus__default.svg
instead ofobject__circle.svg
.
- A
- Find a way to associate aliases (like labels or tags) to each icon.
- A
+
icon namedsymbol__plus.svg
has aliases ofadd
,new
, orexpand
. (If we used Figma, this type of meta can be added/queried for each component (symbol) within the design tool too.)
- A
- Organize icons in the design tool by the same categories.
- Find/replace icons in the product with new naming conventions on an as-needed basis, as time allows, or as they are updated.
- Brainstorm on opportunities to streamline the workflow.
Questions
-
@timzallmann Would it be possible to create semantic aliases of icon names? e.g.,
object__weight -> scales
. If we need to change the icon (see, https://gitlab.com/gitlab-org/gitlab-ee/issues/5340), we could just change the pointer forobject__weight -> weight
- Would it be possible to add the ability to search by aliases in the SVG Previewer?