Skip to content

Designing icons

This page outlines the steps that collaborators should follow to contribute a new design or design improvement to Codex’s icon library.

Codex icon collection excerpt

1. Report and validate

1.1. Create a new task in Phabricator

In order to validate the need to design or redesign an icon for the Codex design system, a new Phabricator task needs to be created. Use this icon creation task template to file the task, and provide as much information as possible.

1.2. Review the task with the Design System Team (DST)

The task must be reviewed with the DST before starting to design the icon to clarify that this new icon is really necessary or if it can be covered with another system solution (e.g. with another icon from our set). Apart from adding the Design-System-Team project tag in the task, you can also post a comment once the task has been created and ping the DST there so you can start discussing the need of this new icon with them.

Once the task is validated with the DST and the need of the new icon is clear you can start designing the icon.

2. Research and prepare

Start by observing and comparing the new and current use cases of the icon to guide your design process and ensure that the new element is as conveniently reusable as possible. You can check the following relevant links in order to collect relevant information that can support the icon design process:

  • List of all icons: to access all the existing icons in our system.
  • Icon Library Figma file: check the design of our system's current icons.
  • Style guide: understand the visual style that the new icon should follow.
  • Wikimedia web products: find current (and future) use cases where we use this icon.

Collect and compare use cases to detect requirements. Detect similar icons and consider their properties: they should influence design decisions to make the new icon consistent with the rest of icons in our iconography.

3. Design the icon

3.1. Create a new exploration file in Figma


Please note that the use of Figma is not mandatory. Contributors are free to use their design tool of choice to design icons. Nevertheless, the icon will need to be imported to Figma in order to make it available to designers through the Codex Figma icon library.

Create a new design exploration file in Figma so that different proposals and versions of the new icon are located in a central place. You can duplicate this icon exploration template and use it to create your own exploration file. The different iterations will be shared in the Phabricator task.

Figma icon exploration template

Include the following information in the design exploration file:

  • Cover: contains a title, description, Phabricator task link and the task owner.
  • Inventory (if needed) to collect and analyze the real use cases of the icon collected during the research phase.
  • Versioning: Create a new Figma page for every new version of the icon. Indicate the version (e.g. “v1”) and date (e.g. “2022-07-17”) and an icon to indicate if the version is final (✅), archived (📁) or work-in-progress (WIP 🛠).

3.2. Design the icon following Wikimedia’s guidelines

While designing the icon, follow the principles and visual styles described in our style guide. Wikimedia icons should be simple, neutral, monochromatic and front-facing.

Icons will be designed on a 20px canvas, and be either solid or use a 2px stroke if they’re outlined.

Designing icons in Figma

3.3. Create an RTL version (if needed)

Design an RTL (or mirrored) version of the icon in case it represents horizontal directionality, lists or text.

An arrow icon pointing left for left to right directionality and an arrow icon pointing right for right to left directionality

  • Mirror icons that represent horizontal directionality.
  • Mirror icons that represent lists or text.

A calendar icon unnecessarily flipped horizontally

  • Mirror icons that represent time.
  • Mirror check icons.
  • Mirror icons that represent objects usually held with the right hand (like a pencil or magnifying glass icon).
  • Mirror icons with question marks; icons will not be mirrored in Hebrew but will be mirrored in Arabic.

3.4. Evaluate & iterate

Once the new icon proposal has been defined in the design exploration file, it should be shared in the relevant Phabricator task in order to collect feedback from the Design System team, other designers and community members. The icon proposal (or proposals) will be discussed in Phabricator in order to make a consensus decision. Iterations will be carried on if needed.


Icons shouldn’t be added to the system unless they’re validated by the Design System team. The new design proposal will need to be reviewed with help from a system designer. Post a comment in the Phabricator task and ping system designers there, so they can review the icon and track the task.

4. Hand-off to development

4.1. Document the design specifications in the Phabricator task description

Once there’s agreement on the icon design proposal, the new icon will be documented in the Phabricator task description, so contributors can easily find it when reviewing the task:

  • Describe the design proposal in the “Proposal” section, so anyone can easily find and understand the specifications of the new icon.
  • Add a link to the Figma exploration file in the “Design spec” section in the task description, so the file can be easily accessed.

4.2 Export the new icon as SVG

4.2.1. Prepare the icon for export

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

  1. Icon strokes are outlined and converted to vector paths (learn how to do it)

Export icons vector paths

  1. All the shapes in the icon have been merged using union selection.

Shapes union selection Figma screenshot

  1. 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.

Pixel perfect preview Figma screenshot

  1. 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.

Flatten the icon Figma screenshot

  1. 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.

Fill rule plugin Figma screenshot

4.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.

  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 for JSON file). 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

Export icons Figma plugin SVG Export screenshot 2

4.2.3. Attach the SVG icon to the Phabricator task

The exported SVG icon will be included within the “SVG icon” section in the task description, so developers can easily find it once they need to add it to the Codex icon repository.

4.3. Complete the design checklist and notify the developer

Make sure to complete and check all the items in the Design checklist included under the Acceptance criteria section of the icon design task.

Once the design checklist is complete, add a comment in the Phabricator task and ping the Design System Team to assign a developer in charge of adding the new icon or icon version to the Codex repository, so they can take over the task.

5. Design sign-off

Once the developer completes the task of adding the new icon to the Codex repository, they will move the task to the “Design Sign-Off” column in the Design System Team Phabricator board.

At that point, the task should be assigned back to the designer of the icon, so they can verify that it was created successfully.

Once the design sign-off is completed, the designer will provide feedback in a comment and move the task to the “Product sign-off” column so that the change can be approved before the final release of the icon.

6. Document: Add the new icon to the Figma library

Once the icon has been released as part of the Codex library, it will be included in the main Icon Library in Figma by the Design System Team. This will make the icon available for reuse in the design projects consuming the icon library.

Icons library figma


The icon will be added and published in the Figma library by a Design System member in order to avoid problems with current components and instances. Ping system designers in the relevant Phabricator task and share with them your design exploration file, so they can add the icon in the Icon Library.