Skip to content

New icon – Work items

Description

We are in the process of working towards consolidating all planning items into a shared list which is being termed Work items (based on the outcome of https://gitlab.com/gitlab-org/ux-research/-/issues/3001). Although this wouldn't require the need of an icon for the list page itself (as navigation items under groupings in the main nav don't utilize icons), there are some other locations that do currently utilize icons and would need considered for this change. A couple examples include:

Assigned issues page (in Your work) Global Search
Screenshot_2024-12-13_at_3.26.41_PM

Screenshot_2024-12-13_at_3.47.12_PM 		Screenshot_2024-12-13_at_3.22.50_PM

Options

There are a couple options to consider for this change.

  1. We could utilize the current Issues icon to represent Work items, and create a new icon to represent the Issue type.
    •  Pro : the Issues icon has already somewhat been used as a container for multiple types in the product. For example, Tasks, Incidents, and Test cases all show up under Issues lists today (where in some cases the icon is used, such as Your work and Global Search).
    •  Pro : the current Issues icon appears non-singular in nature, compared to other type icons that exist. We could change this to be similar to the other types in representing just a concept and appearing singular (which works better when used on a specific item – such as the detail page). This could just be a simplified version of the current Issues icon.
    •  Con : since this icon has been in use for quite awhile in the product, users have drawn a connection between this icon and the term "Issue".
  2. We could create a new icon to represent Work items, while maintaining the Issues icon for the Issue type.
    •  Pro : doesn't create any confusion around the Issue type icon changing.
    •  Con : introduces a new icon users have to learn, while also not addressing the current non-singular aspect of the Issues type icon today.

Figma file

❖ Figma branch showing holistic changes →

Proposal

There are various changes involved with the introduction of the new work items icon, and this work is being broken up into multiple steps (and branches in Figma), to minimize potential impact as well as to ease maintenance.

Step 1 – Add work items icon (✅ Done)

This adds the new work-items icon that has been finalized for this effort (shown below).

work-items.svg

Step 2 – Update design of issue-type-issue and issue-new icons (✅ Done)

With the new icon for work items, we have revised the design for the singular issue-type-issue icon (for indicating the issue work item type) in order to connect it more to work-items. Additionally, we are updating the issue-new icon as it uses the same base/object of the issue-type-issue icon, and thus needs updated along with this. Updates shown below:

icon before after
issue-type-issue issue-type-issue-before.svg issue-type-issue-after.svg
issue-new issue-new-before.svg issue-new-after.svg

Step 3 – Deprecate unused and duplicate icons (In progress)

We will deprecate the following unused icons:

  • issue-closed
  • epic-closed
  • issue-update

We will also deprecate icons that are duplicates of the work item type versions.

  • issues
  • requirements

During this step, we will also complete the following work:

  • Ensure there are no instances of the icons within the product
  • If there are instances, migrate them to the appropriate alternative (gitlab#526952)

Step 4 – Rename and organize the Issue types icons (In progress)

This will include renaming the Issue types grouping to be called Work item types. With that we will be updating icon names and descriptions.

  • Issue types -> Work item types
  • Work item icon naming convention: work-item-[type]

Additionally, we will move the current Epics icon into the newly named Work item types grouping, and updating its name accordingly.

  • epic -> work-item-epic

During this step, we will also complete the following work:

  • Adding new (duplicate) icons with the new names to the SVGs project.
  • Migrating icons in the product to the icons with the new name.
  • Update Documentation site with any icon updates.
  • Deprecating icons with the old name in the SVGs project.

Step 5 – Remove deprecated icons

After a minimum of 1 milestone from when the icons are deprecated (validating with analytics), we can remove the deprecated icons.

Checklists

After all of the following tasks are complete you can close this issue:

Assignee tasks:

See tasks:
  1. Create or update an icon
    • If you’re a community contributor, please fork the GitLab Product Icons file when updating or creating an icon.
    • If you’re a GitLab team member, please create a branch of the GitLab Product Icons file. Prefix the branch name with the issue, MR, or epic number, and add your GitLab username as the suffix. For example, #860-new-icon-lvanc. Then update or create an icon.
  2. Update the link to the working file under the Figma link section above.
  3. If work was not done in a branch (a merged branch will automatically be archived), move your working file to the shared Figma project:
    1. For all other changes, move your file to the Misc archive project.
    2. If you’re a community contributor, please consider transferring ownership of your draft file to the maintainer so they can move it to our archive, along with its version history and comments.
  4. When applicable, follow our iconography guidelines. For third-party trademarks, please review the third-party trademark usage guidelines.
  5. Ask a Foundations designer to review your design.
    • If you’re a community contributor, ensure the designer that will be reviewing your file has edit permissions in Figma.
    • If you’re a GitLab team member, request a review in Figma.

Reviewer tasks:

See tasks:
  1. Review the icon in the author’s branch. Add design-specific comments in Figma to maintain context. Add general comments to this issue, including your approval status.
  2. Once review is approved, assign to a Figma maintainer for final review.

Maintainer tasks:

See tasks:
  1. Merge the branch to the GitLab Product Icons file, convert the icon to a component, add keywords and usage notes (optional) in the description, and view it in the Assets panel to ensure it aligns with what’s outlined in the document and asset library structure documentation.
  2. Publish the library changes along with a clear message about the update.

Library addition tasks:

Once the Reviewer or Maintainer has approved your icon design, consider the following tasks to add the icon the gitlab-svgs library.

See tasks:
  1. Create a new merge request (MR) from this issue.
  2. Assign a label to the MR, such as foundationiconography, and any other relevant labels as needed.
  3. Open the branch in the Web IDE.
  4. In Figma, export the icon component from the GitLab Product Icons file. The parent frame of the icon should not have "Clip content" checked in the Design panel. Consider using the Advanced SVG Export plugin to export an optimized SVG file (the plugin settings can also control what attributes are included or removed).
  5. In the Web IDE, upload the file to the /sprite_icons folder. The file name should be lowercase, and use hyphens as a separator between terms.
  6. Open the icon file and:
    • Ensure that the viewBox attribute is present and matches the icon frame dimensions (either viewBox="0 0 12 12" or viewBox="0 0 16 16").
    • Remove any desc or clipPath attributes.
    • Remove the fill="none" attribute from the <svg> element.
  7. After you’ve committed the changes and the pipeline passes, double-check your icon in the review app by changing settings in the Icon configuration panel of the site. The icon should change color and size with no issues.
  8. Assign the MR to be reviewed and merged by a maintainer, and proceed with any changes.
  9. Add a reference to the change in the Pajamas UI Kit release notes by adding a commit to the current draft MR.

If you run into any problems, ensure that all other steps in the project README have been followed.

Links / references

Edited by Nick Brandt