AR Icon SVG Spec
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 item | One-line requirement |
|---|---|
| File type | Use SVG; units may only be px or omitted |
| Canvas | Must have viewBox; width / height equal to viewBox (a coordinate space of 24 / 48 is recommended) |
| Layer naming | Every graphic element's id carries a state suffix (_normal / _select × _color / _bg) |
| Color notation | Use 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 mode | Behavior | What to provide |
|---|---|---|
| Perspective (near-large / far-small) | Icon size changes with target distance—larger when near, smaller when far—clamped between a max / min size | Two images: a large-size state image + a small-size state image |
| Fixed size | Icon size is fixed; it only scales overall with screen resolution, not with distance | One 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
| Item | Requirement |
|---|---|
| File type | SVG |
| Other formats | PNG / JPG / WebP cannot be submitted directly; convert them to SVG (bitmaps can only be embedded, see Section 5) |
| Units | Only px or no unit |
| Forbidden units | pt, mm, cm, in, em, ex. These units get converted, shrinking the graphic until it is nearly invisible |
2.2 Canvas and Size
- A
viewBoxis required (or at leastwidth/height; having neither makes the size uncontrollable). - A
viewBoxcoordinate space of 24 or 48 is recommended; do not use 512 / 1024 (a large coordinate space breaks hollow detection, see Section 4). - Set
width/heightto the original design size, equal to theviewBox; do not pre-multiply by a scale factor.
Note: The root node's
width/heightbecomes 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 andviewBox, scrambling the whole image. preserveAspectRatiois 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:
| Case | Actual 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 both | Belongs to layer | Can the color be replaced by the program |
|---|---|---|
_normal + _color | Unselected · body | Yes (only RGB is replaced, opacity is preserved) |
_normal + _bg | Unselected · background / stroke | No, keeps the color you drew |
_select + _color | Selected · body | Yes |
_select + _bg | Selected · background / stroke | No, 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
_normaland not_select, the icon disappears entirely when selected. - An
idwith 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 ownidinherit it automatically.
Note: The
_colorlayer always sits on top of the_bglayer, 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, andvisibility="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:
| Notation | Result |
|---|---|
#RRGGBBAA (8-digit color with alpha) | Alpha is discarded; a semi-transparent color becomes fully opaque |
rgba(...) | Renders gray |
currentColor | Renders gray |
hsl(...) / hsla(...) | Renders gray |
transparent | Renders 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 +
nonzerofill 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 shape | Reliable? |
|---|---|
| Circle, ellipse, convex shapes | Reliable |
| Rectangular hollow + thick border | Easily judged as solid; the hollow is lost |
| Mutually crossing paths | Unreliable 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:
| Element | Note |
|---|---|
text | Do not draw text into the SVG; it is rendered separately by the program |
use / symbol | Reference reuse is not supported; expand into concrete shapes |
clipPath | Clipping is not supported; draw the final shape directly |
mask | Masking is not supported |
filter | Filters are not supported (shadows, blur, etc. all have no effect) |
marker | Markers are not supported |
pattern | Pattern fills are not supported |
| Animation elements | Not 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 +classselectors are not supported; styles must be written as element attributes.- Inline
style="fill:#fff;stroke:none"attributes are fine. - Do not write both
fill="..."andstyle="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 intodefsand 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.
transformis not supported. You must write absolutex/y/width/heightdirectly 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
hrefandxlink:hrefnotations 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 feature | Method A (bitmap) | Method B (vector) | Usable when dynamic line width is on |
|---|---|---|---|
| Pure path + pure solid color | Supported | Supported | Usable |
fill-rule="evenodd" hollow | Supported | Supported | Usable |
| Multi-stop gradient | Full | Only the first and last two stops kept | Not recommended |
| Stroke gradient | Supported | Not drawn | Forbidden |
| Dashes | Supported | Become solid lines | Forbidden |
| Embedded bitmap | Supported | Disappears | Forbidden |
| Line width varies with scaling | Fixed | Supported | Decided 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
| Symptom | Cause localization |
|---|---|
| Icon does not display at all | Format / unit error; an unsupported element was used; or icon display is not enabled on the program side |
| Icon disappears after being selected | Missing _select layer, or the id has no suffix and fell into the fallback layer (Section 3.1) |
| Program recoloring has no effect | id lacks the _color suffix; or the id exceeds 63 characters and is truncated (Section 3.1) |
| Inexplicable gray appears | Used rgba() / currentColor / hsl() (Section 3.2) |
| Semi-transparent becomes opaque | Used an #RRGGBBAA 8-digit color (Section 3.2) |
| Icon too big, config changes have no effect | The root node width / height pre-multiplied a scale factor (Section 2.2) |
| Icon sits high / bottom clipped | A non-1:1 image was used in perspective mode (Section 2.3) |
| Icon stretched and distorted | In fixed-size mode, the display ratio does not match the image ratio (Section 2.3) |
| An area that should be hollow turns solid | Missing fill-rule="evenodd"; or rectangular hollow + thick border; or viewBox coordinate space too large (Section 4.1) |
| Uneven stroke thickness | Used non-uniform scaling or a skew transform (Section 4.4) |
| Shadow / blur / clip effect lost | Used filter / mask / clipPath, none of which are supported (Section 4.2) |
| Shows a gray checkerboard | The embedded bitmap is not a Base64 Data URI (Section 5.1) |
| Hidden layer unexpectedly shows up | Hidden layers are forcibly displayed; delete them directly (Section 3.1) |
| Appearance suddenly changes near center or when selected | Dynamic line width is on, but a feature outside the capability intersection was used (Section 5.2) |