Skip to main content
When you create your catalog entry, you can upload a custom icon to represent your agent. A well-designed icon helps customers recognise your product and builds trust. Follow these guidelines to avoid validation failures and ensure your icon looks correct across all themes and screen sizes.

​
File requirements

Upload an SVG file only. SVG files scale cleanly without losing clarity at any resolution, support transparency, and load quickly. PNG or other raster formats are not accepted. Keep the file size under 200 KB. Optimise your SVG by removing unused metadata, comments, and hidden elements before uploading.
Icons that do not meet these requirements will fail validation during onboarding. Ensure your file is an SVG with a transparent background and is under 200 KB before you upload it.

​
Design guidelines

​
Use a transparent background

Do not include a coloured, white, or black background in your icon. The catalog renders icons on different backgrounds depending on the user’s theme (light or dark). A transparent background ensures your icon blends in correctly in both themes.

​
Represent your brand clearly

Your icon should be your company logo or a recognisable brand mark — not a generic illustration or clipart. The icon appears as a small tile in the catalog and must be identifiable at a glance.

​
Keep it simple and high contrast

Icons display at small sizes in the catalog grid. Avoid fine details, thin strokes, or complex patterns that become illegible when scaled down. Use bold shapes and sufficient contrast between foreground elements and any backgrounds they will appear on.

​
Use vector shapes only

Build your icon entirely from vector paths. Do not embed raster images (PNG, JPEG, GIF) inside your SVG — they cannot scale cleanly and increase file size.

​
Avoid embedded fonts

Do not use text inside your icon, or if you must, convert all text to outlines (paths) before exporting. Embedded fonts can cause rendering inconsistencies across environments and increase file size.

​
Dos and don’ts

  • Upload a clean SVG with a transparent background.
  • Use your company’s official logo or brand mark.
  • Ensure the icon reads clearly at 48 × 48 px.
  • Optimise the SVG to remove unused elements and reduce file size.
  • Test your icon on both light and dark backgrounds before uploading.
  • Don’t use a white, black, or coloured background rectangle.
  • Don’t upload a PNG, JPEG, or any raster format.
  • Don’t embed raster images or fonts inside the SVG.
  • Don’t use fine details or decorative elements that are illegible at small sizes.
  • Don’t exceed 200 KB.

​
How to export an SVG correctly

The steps vary by tool, but the key principles are the same across Figma, Adobe Illustrator, and Inkscape:
  1. Select your icon frame or component.
  2. In the right panel, scroll to Export and click +.
  3. Select SVG from the format drop-down.
  4. Enable Include “id” attribute if needed; otherwise leave defaults.
  5. Click Export.
  6. Check that the exported SVG does not include a background rectangle.
  1. Go to File → Export → Export As.
  2. Choose SVG as the format.
  3. In the SVG Options dialog, set Styling to Presentation Attributes and Images to Embed.
  4. Ensure no background rectangle is included on the artboard.
  5. Click Export.
  1. Go to File → Save As and select Plain SVG or Optimised SVG.
  2. Remove any background <rect> elements from the SVG source before saving.
  3. Use File → Clean Up Document to strip unused elements.

​
Optimising your SVG

After exporting, run your SVG through an optimiser to reduce file size before uploading:
  • SVGO — command-line optimiser (recommended)
  • SVGOMG — browser-based interface for SVGO
A typical logo SVG should come in well under 200 KB after optimisation.

​
Where to upload your icon

Upload your icon in the IBM Concierge app when completing your catalog entry:
  1. Navigate to My AI products → Catalog entry.
  2. On the listing details page, click Upload custom icon.
  3. Select your optimised SVG file.
  4. Preview the icon and confirm it looks correct on both light and dark backgrounds.
The custom icon field is optional. If you do not upload an icon, the catalog displays a default placeholder icon for your product.

​
Reference

For the equivalent guidelines in the main watsonx Orchestrate product documentation, see Design guidelines for agent icons in the IBM Documentation.