# Vector Container Detection & Asset Management
## Purpose
Authoritative reference for detecting which Figma nodes should be exported as image assets (SVG, PNG, JPG) versus rendered as CSS, and for managing the full asset pipeline: vector container detection, CSS-renderable shape identification, image fill handling, asset deduplication, and export format selection. Encodes production-proven heuristics that prevent attempting to render complex vector geometry as CSS divs while avoiding unnecessary asset exports for simple shapes that CSS handles natively.
## When to Use
Reference this module when you need to:
- Determine if a Figma frame/group should be exported as a single SVG (vector container detection)
- Decide whether a shape node (ELLIPSE, RECTANGLE, VECTOR, etc.) should be CSS or SVG
- Handle nodes with IMAGE fills (photos, textures, backgrounds)
- Map Figma `scaleMode` (FILL, FIT, CROP, TILE) to CSS `object-fit` / `background-size`
- Build an asset map for deduplication based on `imageHash`
- Select the correct export format (SVG, PNG@2x, JPG) for different asset types
- Understand the interaction between Auto Layout containers and vector container detection
- Handle edge cases like BOOLEAN_OPERATION nodes, mixed content containers, and icon detection
- Generate `` tags with correct `src` and `alt` attributes from asset data
---
## Content
### 1. Vector Container Detection (Critical Heuristic)
The most important decision in asset management is determining which containers should be exported as a single SVG unit versus traversed as HTML/CSS. A **vector container** is a frame or group whose visible children are all vector-compatible types and that contains at least one "true" vector child (not just simple CSS shapes).
#### Why This Matters
Without vector container detection:
- An icon made of 5 VECTOR paths would produce 5 individual `
` elements (broken)
- A logo with BOOLEAN_OPERATION children would attempt CSS rendering of complex geometry (impossible)
- An illustration frame would generate dozens of meaningless positioned divs
With vector container detection:
- The entire icon frame is exported as a single SVG file
- The logo renders as one `` element
- The illustration becomes a clean image reference
#### Vector-Compatible Types
These node types can exist inside a vector container:
```typescript
const VECTOR_COMPATIBLE_TYPES = new Set([
'VECTOR', // Path-based vector shape
'BOOLEAN_OPERATION', // Union, Intersect, Subtract, Exclude of vectors
'STAR', // Star polygon
'POLYGON', // Regular polygon
'LINE', // Line segment
'ELLIPSE', // Circle or ellipse
'RECTANGLE', // Rectangle (may have rounded corners)
])
```
#### Container Types
These node types can hold vector children:
```typescript
const CONTAINER_TYPES = new Set([
'GROUP', // Figma group (no Auto Layout)
'FRAME', // Figma frame (may have Auto Layout)
'COMPONENT', // Component definition
'INSTANCE', // Component instance
])
```
#### Detection Algorithm
The detection is a multi-step process with several guard rails:
```
isVectorContainer(node):
1. Must be a container type (GROUP, FRAME, COMPONENT, INSTANCE)
2. Must have children
3. Must have at least one visible child
4. Must have at least one "true" vector child:
- VECTOR, BOOLEAN_OPERATION, STAR, POLYGON, or LINE
- (ELLIPSE and RECTANGLE alone do NOT qualify -- they're CSS-renderable)
5. ALL visible children must be vector-compatible
6. If ANY child is not vector-compatible → NOT a vector container
```
**Key insight:** A frame containing only RECTANGLE and ELLIPSE children is NOT a vector container. Those shapes are CSS-renderable. The container must have at least one type that requires SVG (VECTOR, BOOLEAN_OPERATION, STAR, POLYGON, LINE).
#### Implementation
```typescript
function isVectorContainer(node: SceneNode): boolean {
// Must be a container type with children
if (!CONTAINER_TYPES.has(node.type) || !('children' in node)) return false
const visibleChildren = (node as ChildrenMixin & SceneNode)
.children.filter(child => child.visible)
// Must have at least one visible child
if (visibleChildren.length === 0) return false
// Must have at least one TRUE vector child (not just CSS shapes)
const hasVectorChildren = visibleChildren.some(child =>
child.type === 'VECTOR' ||
child.type === 'BOOLEAN_OPERATION' ||
child.type === 'STAR' ||
child.type === 'POLYGON' ||
child.type === 'LINE'
)
if (!hasVectorChildren) return false
// ALL children must be vector-compatible
return visibleChildren.every(child => isVectorCompatible(child))
}
```
#### Recursive Vector Compatibility
A container child (GROUP, FRAME) is vector-compatible if ALL of its own children are recursively vector-compatible:
```typescript
function isVectorCompatible(node: SceneNode): boolean {
// Direct vector types are always compatible
if (VECTOR_COMPATIBLE_TYPES.has(node.type)) return true
// Container types: check all children recursively
if (CONTAINER_TYPES.has(node.type) && 'children' in node) {
const container = node as ChildrenMixin & SceneNode
if (container.children.length === 0) return false // Empty = not vector
return container.children
.filter(child => child.visible)
.every(child => isVectorCompatible(child))
}
return false
}
```
---
### 2. CSS-Renderable Shapes vs SVG Export
Not every shape node needs to be exported as an image. Simple geometric shapes can be rendered more efficiently as CSS.
#### Decision Matrix
| Node Type | CSS-Renderable? | SVG Export? | CSS Technique |
|-----------|----------------|-------------|---------------|
| `RECTANGLE` | Yes | Only if complex fills | `
` with `border-radius`, `background-color` |
| `ELLIPSE` | Yes (if circle) | If non-circular | `border-radius: 50%` on equal width/height |
| `VECTOR` | No | Always | Complex path geometry |
| `BOOLEAN_OPERATION` | No | Always | Union/Intersect/Subtract/Exclude results |
| `STAR` | No | Always | Multi-point star polygon |
| `POLYGON` | No | Always | Regular polygon (triangle, hexagon, etc.) |
| `LINE` | Partial | Usually | `border-top` or `` for simple lines |
#### Decision Tree (Pseudocode)
```
decideRendering(node):
IF node is TEXT:
→ Render as HTML text (NEVER export as image)
→ Exception: text with IMAGE fill = text with background image
IF node is a vector container (Section 1):
→ Export entire container as single SVG
IF node.type is VECTOR, BOOLEAN_OPERATION, STAR, POLYGON:
→ Export as SVG (single node)
IF node.type is LINE:
→ IF simple horizontal/vertical line with solid stroke:
→ CSS border or ``
→ ELSE: Export as SVG
IF node.type is ELLIPSE:
→ IF width === height (circle) AND solid fill only:
→ CSS `border-radius: 50%`
→ ELSE: Export as SVG (ellipse or complex fills)
IF node.type is RECTANGLE:
→ IF solid/gradient fill only:
→ CSS `
` with background and border-radius
→ IF has IMAGE fill:
→ Render as `` or `background-image`
IF node is FRAME/GROUP with children:
→ Traverse children recursively (layout container, not asset)
```
#### Circle Detection
```typescript
if (node.type === 'ELLIPSE') {
if (Math.abs(node.bounds.width - node.bounds.height) < 1) {
styles.borderRadius = '50%' // Circle
}
// Non-circular ellipses need SVG
}
```
---
### 3. SVG Export via Figma API
When a node is identified for SVG export, the actual export happens via the Figma REST API image export endpoint or the Plugin API's `exportAsync`.
#### REST API Export
```
GET /v1/files/:file_key/images?ids=NODE_ID&format=svg
```
**Parameters:**
- `ids` -- Comma-separated node IDs (URL-encoded, colons as `%3A`)
- `format` -- `svg`, `png`, `jpg`, or `pdf`
- `svg_include_id` -- Include Figma node IDs in SVG (default: false)
- `svg_include_node_id` -- Include `data-node-id` attributes (default: false)
- `svg_simplify_stroke` -- Simplify stroke geometry (default: true)
**Response:**
```json
{
"err": null,
"images": {
"1:23": "https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/..."
}
}
```
The response contains temporary URLs to the generated SVG files. Download these immediately as URLs expire.
#### Plugin API Export
Within a Figma plugin, use `exportAsync`:
```typescript
const svgBuffer = await node.exportAsync({
format: 'SVG',
svgIdAttribute: false,
})
const svgString = String.fromCharCode(...new Uint8Array(svgBuffer))
```
#### SVG Cleanup
Exported SVGs from Figma often contain unnecessary metadata. Consider cleaning:
- Remove `xmlns:xlink` if no xlink references
- Remove empty `` blocks
- Remove Figma-specific metadata comments
- Optimize with SVGO (external tool) for production
- Preserve `viewBox` attribute (critical for correct scaling)
- Keep `fill` and `stroke` attributes that define the visual appearance
#### Inline SVG vs External File
| Approach | Use When | Advantages |
|----------|----------|------------|
| Inline `
` element
- The illustration becomes a clean image reference
#### Vector-Compatible Types
These node types can exist inside a vector container:
```typescript
const VECTOR_COMPATIBLE_TYPES = new Set([
'VECTOR', // Path-based vector shape
'BOOLEAN_OPERATION', // Union, Intersect, Subtract, Exclude of vectors
'STAR', // Star polygon
'POLYGON', // Regular polygon
'LINE', // Line segment
'ELLIPSE', // Circle or ellipse
'RECTANGLE', // Rectangle (may have rounded corners)
])
```
#### Container Types
These node types can hold vector children:
```typescript
const CONTAINER_TYPES = new Set([
'GROUP', // Figma group (no Auto Layout)
'FRAME', // Figma frame (may have Auto Layout)
'COMPONENT', // Component definition
'INSTANCE', // Component instance
])
```
#### Detection Algorithm
The detection is a multi-step process with several guard rails:
```
isVectorContainer(node):
1. Must be a container type (GROUP, FRAME, COMPONENT, INSTANCE)
2. Must have children
3. Must have at least one visible child
4. Must have at least one "true" vector child:
- VECTOR, BOOLEAN_OPERATION, STAR, POLYGON, or LINE
- (ELLIPSE and RECTANGLE alone do NOT qualify -- they're CSS-renderable)
5. ALL visible children must be vector-compatible
6. If ANY child is not vector-compatible → NOT a vector container
```
**Key insight:** A frame containing only RECTANGLE and ELLIPSE children is NOT a vector container. Those shapes are CSS-renderable. The container must have at least one type that requires SVG (VECTOR, BOOLEAN_OPERATION, STAR, POLYGON, LINE).
#### Implementation
```typescript
function isVectorContainer(node: SceneNode): boolean {
// Must be a container type with children
if (!CONTAINER_TYPES.has(node.type) || !('children' in node)) return false
const visibleChildren = (node as ChildrenMixin & SceneNode)
.children.filter(child => child.visible)
// Must have at least one visible child
if (visibleChildren.length === 0) return false
// Must have at least one TRUE vector child (not just CSS shapes)
const hasVectorChildren = visibleChildren.some(child =>
child.type === 'VECTOR' ||
child.type === 'BOOLEAN_OPERATION' ||
child.type === 'STAR' ||
child.type === 'POLYGON' ||
child.type === 'LINE'
)
if (!hasVectorChildren) return false
// ALL children must be vector-compatible
return visibleChildren.every(child => isVectorCompatible(child))
}
```
#### Recursive Vector Compatibility
A container child (GROUP, FRAME) is vector-compatible if ALL of its own children are recursively vector-compatible:
```typescript
function isVectorCompatible(node: SceneNode): boolean {
// Direct vector types are always compatible
if (VECTOR_COMPATIBLE_TYPES.has(node.type)) return true
// Container types: check all children recursively
if (CONTAINER_TYPES.has(node.type) && 'children' in node) {
const container = node as ChildrenMixin & SceneNode
if (container.children.length === 0) return false // Empty = not vector
return container.children
.filter(child => child.visible)
.every(child => isVectorCompatible(child))
}
return false
}
```
---
### 2. CSS-Renderable Shapes vs SVG Export
Not every shape node needs to be exported as an image. Simple geometric shapes can be rendered more efficiently as CSS.
#### Decision Matrix
| Node Type | CSS-Renderable? | SVG Export? | CSS Technique |
|-----------|----------------|-------------|---------------|
| `RECTANGLE` | Yes | Only if complex fills | `