Page MenuHomePhabricator

Documentation: Designing icons
Closed, ResolvedPublic3 Estimated Story Points

Description

Background/Goal

We need to document the process to contribute in our system designing icons. Documentation will be added in the "Contributing" section of the Codex demo.

User stories

  • As a designer I need to know how to design new system icons.
  • As a designer I need to know how to redesign existing system icons.

Documentation

Acceptance criteria (or Done)

  • Document design process:
    • Design new icons (in this case we will add the new icon in the Figma library from scratch)
    • Redesign existing icons (in this case we will need to make sure that we don't delete the previous icon in order to not lose the instances where this main icon was being reused in many Figma projects)
  • Create a new "Designing icons" section in Codex and add this documentation there

Design Review

More details in this comment

The following sections in Codex need to be updated:

  • Add this start image in the documentation (under the first text)
    Icons - Designing Icons2.png (576×1 px, 15 KB)
  • 1. Report and validate
    • Update this section with the one in Notion
    • Delete the image in this section
  • 2. Research & Prepare section should be moved before the "Design the icon" one
  • 3. Design the icon
    • 3.1. Create a new exploration file in Figma
      • The first paragraph "Please note that the use of Figma..." should be a notice message
      • "Inventory (if needed) to collect..." needs a dot at the end of the sentence
    • 3.2. Design the icon following Wikimedia’s guidelines: Remove the Tip message
    • 3.4. Create an RTL version
      • Update the image with this new one
        MirroringIcons.png (280×1 px, 6 KB)
      • Do and Don’t text: delete emoticons and add texts in 2 columns
  • 4. Hand-off
    • 4.1. Document the design spec…: delete image from this section
    • 4.2.1. Prepare the icon for export. Check the links in this section:
      • "Icon strokes are outlined and converted to vector paths (learn how to do it)"
      • "All the shapes in the icon have been merged using union selection."
    • 4.2.2. Export the icon: add just this image in this section
      export-icons-svgo-2.01bdffbe.png (1×2 px, 81 KB)
    • 4.2.3. Attach the SVG icon to the Phabricator task: delete link from this paragraph
    • Add more separation between 3rd level sections (4.2.1, 4.2.2, 4.2.3...) This will be fixed in T325055
    • 4.3. Complete the design checklist...: delete image from this section
  • Update the name in the documentation links from "Icon System" to "Icon library" (to be discussed)

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

The process to contribute designing system icons has been documented in this Notion.

Both processes (designing new icons and redesign existing ones) have been documented in the same Notion page and explained separately in the “Add icon in the Figma library” section in that documentation, since the only difference between both processes is the way we add the icons in the Figma library.

@Sarai-WMDE to review this task and provide feedback since this documentation is focused on the design process.


To add this documentation in the Codex demo we should:

  • Create a "Contributing design" section in Codex with 2 subsections:
    • Designing components
    • Designing icons (the documentation from this task should be added here)


This should provide designers with the right Figma SVG export preset (“WikimediaUI”).

@Volker_E After some final touches, this documentation is ready to be published in the section "Contributing design > Designing Icons".

The write-up is available in the same Notion page: Designing Icons.

Here's a compressed folder with all the images used in the file.

Change 835633 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] docs: Add “Designing Icons” to “Contributing” section

https://gerrit.wikimedia.org/r/835633

Change 835633 merged by jenkins-bot:

[design/codex@main] docs: Add “Designing Icons” to “Contributing” section

https://gerrit.wikimedia.org/r/835633

@Sarai-WMDE Thanks for all the preparation work. For the future, let's please quickly describe what the image is showing in the file name. We don't know if we gonna adapt the list and suddenly our 3.2.1 image is under 3.2.2. Therefore I've renamed images with descriptions of section and content.

Two important pieces missing:

  1. The page should start with a more inviting image than Phab, probably a designing icons (the designing icons pic?
    image.png (472×2 px, 190 KB)
    )
  2. The two col lack in pieces of the page is clear. It was left out as the information architecture question needs to be captured first.

From a readers perspective the step should come first, Notion does a bad job here.

image.png (782×1 px, 370 KB)

Possibly also the text and the image in second column

Two important pieces missing:

  1. The page should start with a more inviting image than Phab, probably a designing icons (the designing icons pic?
    image.png (472×2 px, 190 KB)
    )

@Volker_E I agree, we could add a start image but I would add instead this other image since the other refers to the guidelines and it's being used in the "2.3. Designing icons" section. I would add this image under the text "The following document outlines..." as I've added in the Notion page.

Icons - Designing Icons2.png (576×1 px, 15 KB)

  1. The two col lack in pieces of the page is clear. It was left out as the information architecture question needs to be captured first.

From a readers perspective the step should come first, Notion does a bad job here.

image.png (782×1 px, 370 KB)

Possibly also the text and the image in second column

@Volker_E as we commented some days ago, since this section is a numbered list it makes sense to add the numbers and text on the left and the images on the right. I've updated the Notion page with this order.

Captura de Pantalla 2022-10-05 a las 12.03.24.png (1×1 px, 583 KB)

Anyway, I'm not sure if we should add these images in the Codex demo since the images here can't be open in fullscreen and they could be too small if we add them in 2 columns. I think in Notion it makes sense to have more images but I would clean the Codex demo documentation and I would leave just the images that are really necessary.

For this reason, I would explain the 3.2 section with a single image per section:

3.2.1. Prepare the icon for export

Make sure the icon meets the following requirements before exporting it:

export-icons-vector-paths.0ff6d2b9.png (658×1 px, 46 KB)

  1. Icon strokes are outlined and converted to vector paths (learn how to do it)
  2. All the shapes in the icon have been merged using union selection.
  3. The icon is pixel perfect. You can use the pixel preview (Ctrl + P/Command + Shift + P) to verify that the icon’s strokes fit within the pixel edges. This will help you verify that the icon is recognizable in low DPI resolutions.
  4. Once the icon’s strokes have been converted to vector paths, merged with union selection and checked using pixel preview, the icon can be flattened to group all shapes into a single vector.

In order to ensure that the exported icon displays the right filling and empty spaces, you’ll have to use the plugin Fill-Rule-Editor to define the fill rules of the icon’s vector objects.

3.2.2. Export the icon

Export the optimized version of the icon with help from Figma’s SVG Export plugin. This will make sure that the icon code is as small as possible without quality loss.

export-icons-svgo-2.01bdffbe.png (1×2 px, 81 KB)

  1. Find the SVG Export plugin using the ‘Plugins’ section in Figma’s main menu and run it. Before exporting the icon, please import the preset “WikimediaUI” [download link to JSON]. The import option is available from a menu in the ‘Presets’ panel.
  2. Apply the WikimediaUI SVGO presets to the icon to be exported, then proceed to export the icon using the ‘Export all’ button.

After doing the design sign-off I've found some things to fix in the Codex documentation. In general, I would delete some images from the Codex documentation. These images were added in the Notion page since we always create Notion with visual reinforcements. But I think we don't need them in the Codex documentation since in Codex we usually create more "clean" pages with only text. I would add images in Codex just when they are really necessary and they provide relevant info to the user. We need to update the following sections in Codex:

1. Report: Open a new design task in Phabricator
  • This section has been updated in the Notion page to explain that the task should be reviewed with the DST before starting to design the icon. We need to update Codex with this new info
  • I would delete the image in this section since it’s not providing relevant information about this section
2.4. Create an RTL version
  • The current image has too many icon examples so I’ve update it in Notion with this other instead. We should update it in the Codex demo too.
  • Do and Don’t text:
    • Delete ✅ and ❌ icons from Do and Don’t since we don’t usually use emoticons in our Codex documentation
    • Create 2 columns for the Do and Don’t
3.1. Document the design spec…
  • I would delete the first image from this section since it’s not providing additional info
3.2.1. Prepare the icon for export
3.2.2. Export the icon
3.3. Complete the design checklist and notify the developer
  • I would delete this image since it’s not providing relevant information about this section
bmartinezcalvo updated the task description. (Show Details)

@Volker_E I've updated the task description with all the corrections we need to fix in Codex.

Change 839451 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] [WIP] docs: Amending “Designing icons”

https://gerrit.wikimedia.org/r/839451

ldelench_wmf set the point value for this task to 3.Oct 24 2022, 3:37 PM

Change 849191 had a related patch set uploaded (by VolkerE; author: VolkerE):

[mediawiki/core@master] Update Codex from v0.2.1 to v0.2.2

https://gerrit.wikimedia.org/r/849191

Change 849191 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.2.1 to v0.2.2

https://gerrit.wikimedia.org/r/849191

@bmartinezcalvo Thanks for the long-form update.
Have incorporated as many changes as possible.

A few things to settle on together:

  • Agreed with not overdoing emojis, we have our icons and Unicode. It's counter-productive from a systems perspective to go too far down the emoji route here.

Have amended the Will/will not with the same treatment we've got on DSG. Let me know if you agree…

  • We should update the first image with the edit pencil as first icon. The edit pencil is the most important icon for our movement. Same goes for section 2.3 Design the icon image
  • I would leave the first image with the preset loading in under Export icons, specifically this is not obvious to find IMO.

@Volker_E design sign-off done for last patch. The design review list items captured in the task have been solved, but one change was missed in this last patch since we moved the "Research & prepare" section before the "Design the icon" in the last Notion update since research should be a step prior to design process.

Captura de Pantalla 2022-11-28 a las 19.24.54.png (1×2 px, 334 KB)

So the sections of this Designing icons documentation should be the following now:

  1. Report and validate
  2. Research & prepare
  3. Design the icon
  4. Hand-off
  5. Design sign-off
  6. Document: Add the new icon to the Figma library

Other things I found that we should update:

  • I've added some new items in the Design Review list in the task description related with text corrections and links
  • Could we add more separation between 3rd level sections? We need to separate them more so users visually distinguish each section
    Captura de Pantalla 2022-11-28 a las 20.00.28.png (686×1 px, 532 KB)
  • We updated the icons library name from "Icon System" to "Assets library". I wonder if we should update the name in the links in this documentation from "Icon System" to simply "Icon library"

@Volker_E for the columns in this section I think is ok if we use 50% for text and 50% for images (as we have in the last patch).

Captura de Pantalla 2022-11-28 a las 20.32.47.png (1×1 px, 1 MB)

Change 839451 merged by jenkins-bot:

[design/codex@main] docs: Amending “Designing icons”

https://gerrit.wikimedia.org/r/839451

@Volker_E I already reviewed the last patch and commented here with some things that we should update in the "Designing icons" documentation in the Codex demo. I added them as list items in the "Design Review" section in the task. So moving the task to Ready for development so you can fix them.

Change 865151 had a related patch set uploaded (by Eric Gardner; author: Eric Gardner):

[mediawiki/core@master] Update Codex from v0.3.0 to v0.4.0

https://gerrit.wikimedia.org/r/865151

Change 865151 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.3.0 to v0.4.0

https://gerrit.wikimedia.org/r/865151

@bmartinezcalvo If we make “Research and prepare” a top-level headline, we should move it to 1.
That would also align our structure with the general Product flywheel structure and also take off possible burden from designers (don't start just with blank Phab task that would get declined anyways).

Change 865822 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] docs: Amend “Designing Icons” page

https://gerrit.wikimedia.org/r/865822

Fyi, I've also updated the “Icon system library” to “Icon library” consistently.

@bmartinezcalvo On the "The standard icon size is 20px, but 16px and 12px variants are possible." – We quickly discussed in one design sync to leave the 12px variant in our code base but not talk about it as it's a usability flaw.

Volker_E renamed this task from [DESIGN] Documentation: Designing icons to Documentation: Designing icons.Dec 8 2022, 9:47 PM
Volker_E reassigned this task from Volker_E to bmartinezcalvo.

@bmartinezcalvo On the "The standard icon size is 20px, but 16px and 12px variants are possible." – We quickly discussed in one design sync to leave the 12px variant in our code base but not talk about it as it's a usability flaw.

@Volker_E then I would delete that message "The standard icon size is 20px, but 16px size is possible..." to avoid confusions. If our base icon size is 20px let's talk about it in our guidelines. Also, 16px size will be used at the moment for so specific use cases so I wouldn't comment about it in our guidelines since users could think that 16px is one of our usual icon sizes.

bmartinezcalvo updated the task description. (Show Details)

@Volker_E all looks good to me except 2 things:

  • Remove theTip message about the 16px icon size (commented above)
  • Add more separation between 3rd level sections (4.2.1, 4.2.2, 4.2.3...). Is this possible?

@Volker_E all looks good to me except 2 things:

  • Remove theTip message about the 16px icon size (commented above)

[] Add more separation between 3rd level sections (4.2.1, 4.2.2, 4.2.3...). Is this possible?

@Volker_E created this new task T325055 to increase the padding between sections in Codex, so the second corrections would not be needed in this task.

Change 865822 merged by jenkins-bot:

[design/codex@main] docs: Amend “Designing Icons” page with latest designer feedback

https://gerrit.wikimedia.org/r/865822

Change 867727 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[mediawiki/core@master] Update Codex from v0.4.0 to v0.4.1

https://gerrit.wikimedia.org/r/867727

Test wiki created on Patch demo by ATomasevich (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/cb9ffaffec/w

Change 867727 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.4.0 to v0.4.2

https://gerrit.wikimedia.org/r/867727

Test wiki on Patch demo by ATomasevich (WMF) using patch(es) linked to this task was deleted:

https://patchdemo.wmflabs.org/wikis/cb9ffaffec/w/