Forma 36

Adding icons

Give feedback

How to build icons for Forma 36

Visit Icons for usage guidelines.

Before adding a new icon

Adding an existing Phosphor icon

  1. Find the icon (prefer the Simple variant).

  2. Create a branch of the Assets library (e.g. Adding Camera Icon).

  3. Open Plugins → From Contentful → Forma 36 Icon Importer.

  4. Search using the exact Phosphor name, then click Import icon.

    • A component with size and state variants is created automatically.

  5. Apply colors manually:

    • Default → Grey/900

    • Active → Blue/600

  6. Request review (reviewer: @daniel.amann). After approval, merge the branch. Learn how

Adding a custom icon

  1. Confirm with UI Foundation before starting.

  2. Create a branch of the Assets library (e.g. Adding Camera Icon).

  3. Use the Phosphor plugin to import a Raw base (32×32, 2px stroke).

  4. Adjust design following Design principles and guidelines (see below).

  5. Keep an editable backup of the raw vector.

  6. Convert strokes to outlines (Shift + Cmd + O) and flatten vectors (Alt + Shift + F).

  7. Use Plugins → From Contentful → Custom Icon Creator to generate the component.

  8. Apply colors:

    • Default → Grey/900

    • Active → Blue/600

  9. Add a usage note + alternative semantic tags in the description.

  10. Request review (reviewer: @daniel.amann). After approval, your branch will be merged with the main branch of the library.

Design principles

  • Clarity: recognizable, readable, no ambiguity.

  • Brevity: minimal details, reductive style.

  • Character: subtle quirks for warmth, used sparingly.

Design guidelines

  • Use continuous strokes unless a break aids clarity.

  • Line spacing ≥ stroke weight.

  • Use straight lines, perfect arcs, and 15° increments.

  • Refine curves for clarity and style.

  • Leave a 2px margin around edges (except long narrow shapes).

  • Include a 20% opacity base layer for duotone style.

Naming conventions

  • PascalCase, semantic base + optional suffix for state/shape/direction.

    • Base: Camera, ChatCircle, MagnifyingGlass

    • State/Shape: LockOpen, CheckCircle

    • Direction: ArrowUpRight, CaretDown

    • Always end with the suffix Icon: ArrowUpRightIcon

  • Style weights (Bold, Fill, Duotone) are handled as separate sets, not in names.

  • Add alternative semantic names as tags in the description for better searchability.

Engineers - Adding icons to the f36-icons package

Adding an existing Phosphor icon

  • Create a new file within the /packages/components/icons/src/vendor/Phosphor directory.

  • Use the Phosphor icon name and prepend the Icon word to it using the Pascal case naming convention (e.g., for arrow-down, the file name would be ArrowDownIcon.tsx).

  • Use the template below and replace the icon with the one you need import { generateForma36Icon } from '@contentful/f36-icon'; import { ArrowDownIcon as ArrowDown } from '@phosphor-icons/react'; export const ArrowDownIcon = generateForma36Icon(ArrowDown);

  • Use the same name as the filename to export the component. ⚠️

  • Once you are done, open a PR, add the changeset (a bot will give you instructions), and wait for our team's review.

  • Once the PR is merged, the f36-icons package will be updated, and a new version will be published for you to import the icon.

Adding a custom icon

  • Create a new file within the /packages/components/icons/src/custom directory.

  • Use the same name as the one the designer chose in the Forma 36 Assets library. ⚠️

  • Follow the example of the EntryIcon.tsx implementation and update the SVG paths with your own.

  • SVG paths must be added without the <svg /> tag and its sizing & viewbox properties, as sizing is controlled by the Icon component rendering the SVG path. ⚠️

  • Replace any hardcoded color values with the currentColor value (e.g., fill="currentColor"), as the color will be automatically applied based on the icon's variant.

  • Once you are done, open a PR, add the changeset (a bot will give you instructions), and wait for our team's review.

  • Once the PR is merged, the f36-icons package will be updated, and a new version will be published for you to import the icon.

Check the icon rendering

After adding the icon, run the build command from the f36-icons package root directory (npm run build), which will automatically add the icon to the main barrel file and update the ./dist folder.

QA in Storybook

  • Once the build is complete and successful, run the Storybook command from Forma 36's root directory - npm run storybook.

  • Once Storybook is up and running, visit the Icons story and verify that the icon is rendering correctly, usually running at http:localhost:9001.

QA on the documentation website

  • Once the build is complete and successful, run the website start command from the website's package root directory - npm run storybook.

  • Once the website is up and running, visit the Icons component documentation page and verify that the icon is rendering correctly, usually at https://localhost:3000/components/icons.

Need help?

@daniel.amann for design questions

#prd-ui-foundation for engineering questions

Help improve this page

Read the contribution guide