AR Icon SVG Spec

2026-11-05Loading rating…

Icons in AR projection are provided as SVG. After an SVG is uploaded to Pilot, Pilot parses and renders it according to the rules on this page; its parsing capability is a subset of standard SVG. This page summarizes the requirements and self-check methods for AR icon SVGs, to be used together with the AR Projection tutorial. The name text drawn next to the icon is rendered separately by the program—do not draw it into the SVG.

How to Use This Spec

The requirements in this spec fall into two categories; you do not need to read every item one by one:

  • Must-have items: always in effect, unconditionally. If not met, the icon cannot display properly. There are only a few of them—see the quick list below and make sure to satisfy them all.
  • Scenario items and boundary values: only take effect under a specific display mode or a specific switch, or are numeric upper limits you will almost never hit in normal design. Consult the relevant subsection based on your actual scenario.

To help you quickly judge whether a rule applies to you, every key constraint in the body is annotated with its trigger condition (such as "always in effect", "perspective mode only", "only when dynamic line width is enabled") and its consequence if not met (such as "icon does not display", "renders gray").

Must-have quick list (satisfy these unconditionally for the icon to display correctly and be recolorable):

Must-have itemOne-line requirement
File typeUse SVG; units may only be px or omitted
CanvasMust have viewBox; width / height equal to viewBox (a coordinate space of 24 / 48 is recommended)
Layer namingEvery graphic element's id carries a state suffix (_normal / _select × _color / _bg)
Color notationUse only #RGB / #RRGGBB / rgb() / named colors
Hollow (cutout)For a hollow shape, write fill-rule="evenodd" within the same <path>

Details and more scenario items are in the following sections. When something goes wrong, use Section 6 to diagnose by symptom.


1. Prerequisite: Two Display Modes

An icon has two display modes in the AR view. Some requirements depend on which one you use, so confirm this first:

Display modeBehaviorWhat to provide
Perspective (near-large / far-small)Icon size changes with target distance—larger when near, smaller when far—clamped between a max / min sizeTwo images: a large-size state image + a small-size state image
Fixed sizeIcon size is fixed; it only scales overall with screen resolution, not with distanceOne image

There is also a "text only, no icon" configuration, in which case no image is needed.


2. Basic Format and Canvas

2.1 Basic Format

ItemRequirement
File typeSVG
Other formatsPNG / JPG / WebP cannot be submitted directly; convert them to SVG (bitmaps can only be embedded, see Section 5)
UnitsOnly px or no unit
Forbidden unitspt, mm, cm, in, em, ex. These units get converted, shrinking the graphic until it is nearly invisible

2.2 Canvas and Size

  • A viewBox is required (or at least width / height; having neither makes the size uncontrollable).
  • A viewBox coordinate space of 24 or 48 is recommended; do not use 512 / 1024 (a large coordinate space breaks hollow detection, see Section 4).
  • Set width / height to the original design size, equal to the viewBox; do not pre-multiply by a scale factor.

Note: The root node's width / height becomes the lower bound of the icon's display size. If set too large, the max / min size configured on the program side will be overridden, showing up as "the icon is too big and config changes have no effect".

<!-- ✅ Correct: design size 24×24 -->
<!-- How many pixels it scales to is decided by the program-side config -->
<svg width="24" height="24" viewBox="0 0 24 24"> … </svg>

<!-- ❌ Wrong: 40 becomes a hard lower bound for display size; min-size config stops working -->
<svg width="40" height="40" viewBox="0 0 15 15"> … </svg>

Other constraints:

  • Do not use percentage width/height (width="100%"); it is computed as 0.
  • Do not nest <svg>; the inner one overrides the root node's size and viewBox, scrambling the whole image.
  • preserveAspectRatio is supported, but is generally not needed.

2.3 Aspect Ratio

The aspect-ratio requirement depends on the display mode:

Perspective mode must be a 1:1 square—width must equal height (or the viewBox must be square). A non-square image is not stretched; instead:

CaseActual consequence
Width > height (wide image)Content sticks to the top half of the square canvas, with empty space below; the icon sits high and looks smaller
Width < height (tall image)After proportional scaling it exceeds the canvas height and the bottom gets clipped

Fixed-size mode may be non-square, but with two accompanying conditions (filled in on the program side; must match the image):

  • The image aspect ratio filled in on the program side must equal the SVG's own aspect ratio; otherwise you get the same empty space or clipping.
  • The display aspect ratio filled in on the program side must match the image aspect ratio; otherwise the image is genuinely stretched.

Note: Some integration methods support "fill in only one dimension and auto-derive the other by ratio", but integration via config file (JSON) does not support auto-derivation—you must compute it accurately yourself.


3. Layers and Colors

3.1 Layer Naming Rules

A single SVG is automatically split into 4 layers by the graphic elements' id. Every graphic element's id must contain a state suffix:

id contains bothBelongs to layerCan the color be replaced by the program
_normal + _colorUnselected · bodyYes (only RGB is replaced, opacity is preserved)
_normal + _bgUnselected · background / strokeNo, keeps the color you drew
_select + _colorSelected · bodyYes
_select + _bgSelected · background / strokeNo, keeps the color you drew

Naming examples:

ic_pin_normal_color         body when unselected
ic_pin_normal_bg            black stroke when unselected
ic_pin_select_color         body when selected
ic_pin_select_bg            black stroke when selected
ic_pin_normal_select_color  body shown in both states

Detailed rules (all always in effect):

  • One element can belong to multiple layers at once. To show an element in both unselected and selected states, name it xxx_normal_select_color.
  • If you provide only _normal and not _select, the icon disappears entirely when selected.
  • An id with no suffix falls into the "unselected · background" fallback layer, which means it can neither be recolored nor shown when selected.
  • The suffix may be written on the <g> only; child elements in the group without their own id inherit it automatically.

Note: The _color layer always sits on top of the _bg layer, regardless of layer order inside the SVG. Therefore your design must be splittable into "recolorable foreground on top / fixed-color background below"—you cannot have a stacking relationship where a fixed-color element needs to cover a recolorable element.

Note: Do not leave hidden layers. display="none" is forcibly turned on, and visibility="hidden" has no effect. Delete any layers you don't use.

Boundary limits: an id is at most 63 characters total (the excess is truncated; if the suffix is cut off, layering breaks); <g> group nesting depth is at most 127 levels.

3.2 Color Notation

Color notation is always in effect. Only 4 color notations are supported:

#RGB          e.g. #0E8
#RRGGBB       e.g. #00EE8B
rgb(r, g, b)  e.g. rgb(0, 238, 139)
named colors  e.g. black, white, red

The following notations are not supported and will make the icon render gray or lose opacity—do not use them:

NotationResult
#RRGGBBAA (8-digit color with alpha)Alpha is discarded; a semi-transparent color becomes fully opaque
rgba(...)Renders gray
currentColorRenders gray
hsl(...) / hsla(...)Renders gray
transparentRenders gray

Opacity can only be expressed with the opacity / fill-opacity / stroke-opacity attributes; it cannot be written into the color value.

Note: An icon showing an inexplicable gray is usually caused by one of the unsupported color notations in the table above.


4. Shape and Element Constraints

4.1 Hollow (Cutout Effect)

A hollow has three hard requirements:

  • Every hollow must explicitly write fill-rule="evenodd".
  • The hollow path must be written in the same <path> as the outer outline. Splitting into two <path>s or two elements cannot form a hollow.
  • Do not use the approach of "two nested outlines in the same direction + nonzero fill rule, expecting it to fill solid". The two rendering methods judge it oppositely, causing the fill to flicker between solid and hollow.

Hollow is inferred from "containment relationships", and this inference has a reliability boundary:

Hollow shapeReliable?
Circle, ellipse, convex shapesReliable
Rectangular hollow + thick borderEasily judged as solid; the hollow is lost
Mutually crossing pathsUnreliable judgment
viewBox coordinate space too large (512 / 1024)Very easily judged as solid

This is also why Section 2.2 requires a small viewBox coordinate space of 24 / 48.

4.2 Allowed and Forbidden Elements

Allowed elements:

svg  g  defs  path  rect  circle  ellipse  line  polyline  polygon
image  linearGradient  radialGradient  stop

Path commands M L H V C S Q T A Z (including lowercase) are all supported; arcs are available.

The following elements are discarded—do not use them:

ElementNote
textDo not draw text into the SVG; it is rendered separately by the program
use / symbolReference reuse is not supported; expand into concrete shapes
clipPathClipping is not supported; draw the final shape directly
maskMasking is not supported
filterFilters are not supported (shadows, blur, etc. all have no effect)
markerMarkers are not supported
patternPattern fills are not supported
Animation elementsNot supported

4.3 Attribute Whitelist

Only the following attributes take effect:

style              display            id                 transform
fill               fill-opacity       fill-rule
stroke             stroke-opacity     stroke-width
stroke-linecap     stroke-linejoin    stroke-miterlimit
stroke-dasharray   stroke-dashoffset
stop-color         stop-opacity       offset             font-size

Attributes outside the whitelist are ignored. Common ones are clip-path, mask, filter, paint-order, vector-effect, mix-blend-mode, class, visibility, marker-start / marker-mid / marker-end.

Structural constraints:

  • <style> style sheets + class selectors are not supported; styles must be written as element attributes.
  • Inline style="fill:#fff;stroke:none" attributes are fine.
  • Do not write both fill="..." and style="fill:..." on the same element. Which one wins depends on attribute writing order and does not follow standard CSS priority.
  • Inside <defs>, only gradients are preserved; placing a shape into defs and referencing it does not work.

Boundary limits: a single element has at most 253 attributes; an empty graphic with no actual path is ignored.

4.4 Stroke and Transform

transform is fully supported: matrix, translate, scale, rotate, skewX, skewY.

Note: Do not apply non-uniform scaling (such as scale(2,1)) or skew (skew) to stroked elements. The stroke width is converted using the average of the horizontal and vertical scaling, which distorts noticeably. When you need such transforms, expand the stroke into a path in your design tool first.

Boundary limit: stroke-dasharray dashes support at most 8 segments; the excess is discarded.


5. Embedded Bitmaps and Dynamic Line Width

Both items in this section are scenario items: you only need to care about them when you need an embedded bitmap, or when the program side has enabled dynamic line width. Otherwise you can skip this section.

5.1 Embedded Bitmaps

If you truly need a bitmap (photo, complex texture), it can only be embedded in the SVG, and should be avoided as much as possible:

  • Must use a Base64 Data URI: <image xlink:href="data:image/png;base64,..." />.
  • A file path or network URL does not work and shows up as a gray checkerboard placeholder.
  • transform is not supported. You must write absolute x / y / width / height directly on the <image>; you cannot position it via an outer <g transform>.
  • Scaling uses nearest-neighbor sampling with no smooth interpolation. The bitmap's pixel size must be no smaller than the actual display pixels, otherwise aliasing is obvious.
  • Within the same element, the bitmap is drawn first, and fill and stroke are drawn afterward (covering the bitmap).
  • Both href and xlink:href notations are recognized.

5.2 Extra Constraints When "Line Width Varies with Distance" Is Enabled

The program side has a switch for "line width varies dynamically with icon scaling" (the built-in annotation point / Pin point enables it by default). Once enabled, the same SVG switches between two rendering methods:

  • Method A: pre-converted to a bitmap and then drawn (default).
  • Method B: real-time vector drawing (only used when the icon is selected or located in the central region of the view).

The two methods have different capabilities, so the SVG can only use the intersection of their capabilities:

SVG featureMethod A (bitmap)Method B (vector)Usable when dynamic line width is on
Pure path + pure solid colorSupportedSupportedUsable
fill-rule="evenodd" hollowSupportedSupportedUsable
Multi-stop gradientFullOnly the first and last two stops keptNot recommended
Stroke gradientSupportedNot drawnForbidden
DashesSupportedBecome solid linesForbidden
Embedded bitmapSupportedDisappearsForbidden
Line width varies with scalingFixedSupportedDecided by this switch

When the capability intersection is not met, the icon's appearance changes as it approaches the center of the view or gets selected.

Note: Fixed-size mode never uses Method B and is not subject to this section. When you don't need dynamic line width, you can have the program side turn off this switch for the most predictable appearance.


6. Self-Check and Troubleshooting

6.1 Common Issue Self-Check

SymptomCause localization
Icon does not display at allFormat / unit error; an unsupported element was used; or icon display is not enabled on the program side
Icon disappears after being selectedMissing _select layer, or the id has no suffix and fell into the fallback layer (Section 3.1)
Program recoloring has no effectid lacks the _color suffix; or the id exceeds 63 characters and is truncated (Section 3.1)
Inexplicable gray appearsUsed rgba() / currentColor / hsl() (Section 3.2)
Semi-transparent becomes opaqueUsed an #RRGGBBAA 8-digit color (Section 3.2)
Icon too big, config changes have no effectThe root node width / height pre-multiplied a scale factor (Section 2.2)
Icon sits high / bottom clippedA non-1:1 image was used in perspective mode (Section 2.3)
Icon stretched and distortedIn fixed-size mode, the display ratio does not match the image ratio (Section 2.3)
An area that should be hollow turns solidMissing fill-rule="evenodd"; or rectangular hollow + thick border; or viewBox coordinate space too large (Section 4.1)
Uneven stroke thicknessUsed non-uniform scaling or a skew transform (Section 4.4)
Shadow / blur / clip effect lostUsed filter / mask / clipPath, none of which are supported (Section 4.2)
Shows a gray checkerboardThe embedded bitmap is not a Base64 Data URI (Section 5.1)
Hidden layer unexpectedly shows upHidden layers are forcibly displayed; delete them directly (Section 3.1)
Appearance suddenly changes near center or when selectedDynamic line width is on, but a feature outside the capability intersection was used (Section 5.2)
Last Updated: