Proposing an Icon

What is an icon?

An icon is a visual metaphor: a compact symbol that represents a discreet object, action, or idea. Icons are meant to be quickly and universally understood, bridging language and cultures.

They don’t include additional styling such as colourful backgrounds or multi-colour fills, containers with specific shapes, or text.

How do icons relate to other components?

Icons are commonly used independently or nested within other, larger components. It’s possible to create a new UI component that heavily relies on the presence of an icon (for example: an Avatar with predefined icons that a user can choose) but is not itself an icon.

Additionally, several existing UI components might look similar to an icon but are not one. Below, you can check the difference between icons and other types of media that might or might not include an icon:

	Description	Colour	File Format
Icon	A compact symbol that represents a discreet object, action or idea.	Single-colour	SVG
Logo	A symbol that identifies a brand.	Single-colour or multi-colour	SVG
Avatar	A complex illustration of a narrative, used to accompany content.	Multi-colour	WEBP, AVIF, SVG
Image	A representation of a user or entity (such as Projects, Tenants or Spaces).	Multi-colour	WEBP, AVIF, SVG

Naming conventions

Names should be object-based (unless an icon is Octopus-specific)

We use descriptive naming instead of prescriptive. This allows icons to be easily discovered, even without previewing them. The only use cases in which we follow prescriptive naming are Octopus-specific icons corresponding to unique features or concepts consistently reused across the product.
For example:

object-based: magnifying-glass, cog.

Octopus-specific: tenant, runbook.

Names should be hyphenated

If an icon name requires several words, we separate them with a hyphen. We don’t use camel case. For example: user-group, check-circle.

Names should have modifiers as suffixes

Icons can include a base icon and additional, reusable shapes to signify meaning. Some icons might be wrapped in a larger shape or consist of two icon shapes. In that case, the additional shape should be added as a suffix. For example: plus-circle, eye-off, user-add.

Names shouldn’t include -alt

Unless it’s absolutely necessary, we avoid using -alt as a suffix. Instead, we focus on describing the unique features of each icon. For example: hourglass-xmark, user-cog.

Names for arrows and chevrons should imply direction

Directional icons, such as arrows and chevrons, should always include the direction they are pointing towards. For example: arrow-up, chevron-left.

Contributing an icon

We are phasing out CSS class icon usage
If you need to add a new icon, follow the process outlined below. Avoid adding icons by attaching Font Awesome class (fa-*) to HTML elements.

We consider adding an icon as a Light contribution to the design system, as it’s easy to review and it doesn’t affect the stability of the existing components. When proposing a new icon, follow the guidelines for a Light contribution, including specific guidelines for designers and engineers.

We have an automated process in place that synchronises icons between the Figma Component Library and design-system-icons package in the Octopus Deploy GitHub repository. It uses a Figma plugin, Figma REST API and GitHub Actions to dynamically generate and update icons.

Design

The FileKey field has to be updated each time you run the workflow (unlike the other plugin settings). There’s a known limitation of the current solution as it reverts back to frontend-foundations without manual intervention.

Set up Run GitHub Actions Workflow plugin: before you can publish icons, you need to set up the connection between Figma and GitHub. You will only need to do this once:

Install Run GitHub Actions Workflow plugin for Figma

Fill the FileKey field with your team name (e.g.: fire-and-motion, modern-deployments)

Click the plus icon next to Workflows heading to create two new workflows: one for adding icons and another for updating an icon if a change is requested by an engineer after they review the generated Pull Request. Provide the following information:

	Add Icons	Update Pull Request
Name	add-icons	update-pull-request
Access Token	figma-github-action-token available in Design Vault in 1Password	figma-github-action-token available in Design Vault in 1Password
Owner	OctopusDeploy	OctopusDeploy
Repo	OctopusDeploy	OctopusDeploy
Ref	main	${value_in_filekey_field}/update-icons (e.g.: ${modern-deployments}/update-icons)
Workflow ID	sync-and-build-icons.yml	sync-and-build-icons.yml

Add (or edit) the icon to System Icons: create a new branch in Figma, and use the Icon template to guide you in creating an icon that’s consistent with the existing set.

Request review for your branch: use Figma’s request a branch review and communicate the request in #team-frontend-foundations-requests channel.

Once the branch is merged, run the icon workflow to publish the change:

Adding a new icon: press the play icon next to the add-icons workflow. Your changes will be automatically pushed to GitHub in a new pull request

Updating an existing icon Pull Request: press the play icon next to the update-pull-request workflow. Your changes will be automatically pushed to the existing GitHub pull request.

Notify the collaborating engineer: let the engineer you’re working with know that you’ve pushed the icon to GitHub. The generated React component for the icon will match the name of the icon in Figma, so it’s easy to find.

Engineering

Each Pull Request opened by the icon automation process will be reviewed by the Frontend Foundations team. Once merged, the icon will immediately be available through the design-system-icons package.