Overview

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

• Theme icon pack — choose which icon pack the theme uses. This can be 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.

Blocks never embed icon artwork directly — they store a reference to an icon, and the app resolves the artwork when rendering. This is what makes icons themable: switching packs reskins the app's icons without touching any block.

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 each pack's contents

• Upload a new pack

• Remove an existing pack

• Select which pack the theme uses — selecting saves the choice immediately and confirms with a notification

Uploading a Custom Pack

1. Open the theme in the Design System editor.

2. Navigate to the Icons tab.

3. Click Upload to upload your icon pack.

4. The pack must be a zip file of SVGs, organized into category folders.

5. After upload, browse the pack's contents and confirm the icons appear correctly.

6. Click Select on the pack row to make it the active pack for this theme.

Warning: One pack at a time: A theme selects 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

The app builder's theme panel has an icons view where you can:

• See every custom icon uploaded to the app

• Rename icons

• Delete icons

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. Navigate to the theme panel, then to the Icons view.

3. Use the upload control to add 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.

• Switching the active pack reskins all icon references simultaneously. Preview the result carefully if switching from a large custom pack back 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