Overview

Icons are part of a theme's identity, and the theming system gives you two levers:

• Theme icon pack — the icons the theme uses. This is the built-in Unify Icons set, or a custom pack you upload. Every app using this theme shares the same pack.

• Per-app custom icons — upload individual icons to a specific app. These icons show in that app's icon pickers, independent of the theme.

Theme Icon Pack

Every theme points at exactly one icon pack:

Managing Icon Packs in the Theme

From the theme's Icons settings you can:

• Browse the icons by category

• Upload a custom pack with Add Icon Pack

• Delete the custom pack (trash icon on its category card) to return the theme to Unify Icons

Uploading a Custom Pack

1. Open the theme in the full Design System editor. The Icons tab is only there — the compact Theme Builder inside an app (Settings → Design System → Theme Builder) shows only the Colors, Typography and Border tabs.

2. Navigate to the Icons tab.

3. Click Add Icon Pack and upload a .zip of SVGs or individual SVG files. In a zip, folder names become category names.

4. The uploaded pack becomes the theme's icon set automatically, and its categories replace the Unify Icons grid.

5. Browse the pack's contents and confirm the icons appear correctly.

Warning: One pack at a time: A theme uses a single pack — there is no way to mix two custom packs. If you need icons from both, combine them into one pack before uploading.

Per-App Custom Icons

Separately from packs, an app can carry its own uploaded icons. These are independent of the theme and stay with the app even if you switch its theme.

Managing Per-App Icons

In the app builder, go to Settings → Design System → Custom Icons. There you can:

• See every custom icon uploaded to the app (switch between the large and compact grid with the view toggles)

• Rename an icon: click the icon, choose Rename and type the new name

• Delete an icon: click the icon and choose Delete

Per-app icons appear in the app's icon pickers alongside the theme's pack. Any block property that takes an icon (a button's leading icon, a navigation item, a tab icon) can use them.

Uploading Per-App Icons

1. Open the app in the builder.

2. Go to Settings → Design System → Custom Icons.

3. Click the + button at the top right (or Add Icon Pack if the app has no custom icons yet) and upload individual SVG icons.

4. Give each icon a descriptive name — this is how builders find and select it in pickers.

How Icon Selection Affects Blocks

Blocks never embed icon artwork directly. Instead, they store a reference to an icon name, and the app resolves that reference to actual artwork at render time based on the active icon pack.

Note: Why this matters: Switching the theme's icon pack reskins every icon in the app simultaneously — from a navigation icon to a button's leading icon — without touching any individual block. The blocks keep their icon references; only the artwork the references resolve to changes.

Theme Pack vs. Per-App Icons

Trade-offs & Gotchas

• Pack icons belong to the theme; custom icons belong to the app. Choose the level that matches how widely you want the icons shared.

• One pack at a time. Combine icons from multiple packs into one zip file before uploading if you need icons from different sources.

• Uploading or deleting a custom pack reskins all icon references simultaneously. Preview the result carefully if you delete a large custom pack to return to Unify Icons — some icon names may not exist in both packs and will resolve to a fallback or empty state.

Related Pages

• Theme Builder — how icons fit into the whole theme

• Appearance & Styling Guide — theming the icon component family (size, color treatments)

• Tokens & Custom CSS — advanced overrides