Makepad 2.0 Vector

---
name: makepad-2.0-vector
description: |
  CRITICAL: Use for Makepad 2.0 Vector graphics widget. Triggers on:
  makepad vector, Vector widget, SVG path, makepad path, makepad circle,
  makepad gradient, makepad tween, vector animation, Gradient, RadGradient,
  Filter, DropShadow, Group transform, vector drawing, inline SVG,
  矢量图形, SVG, 路径, 渐变, 矢量动画
---

# Makepad 2.0 Vector Graphics Skill

> **Version:** makepad-widgets (dev branch) | **Last Updated:** 2026-03-03

## Overview

The `Vector` widget renders resolution-independent vector graphics using SVG-like syntax. It supports paths, shapes, gradients, filters, groups, transforms, and property animation via `Tween`.

**Two ways to use SVG in Splash:**
- **`Vector{}`** - Define shapes inline in Splash (paths, rects, circles, etc.)
- **`Svg{}`** - Load external `.svg` files via `crate_resource()` or `http_resource()`, with optional animation and custom GPU shaders

## Documentation

Refer to the local files for detailed documentation:
- `./references/vector-reference.md` - Complete Vector API, shapes, gradients, filters, animation

---

## Basic Usage

```
Vector{
    width: 48 height: 48
    viewbox: vec4(0 0 24 24)
    Path{
        d: "M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"
        fill: false
        stroke: #4488ff
        stroke_width: 2.0
        stroke_linecap: "round"
        stroke_linejoin: "round"
    }
}
```

### Key Properties

| Property | Description | Example |
|----------|-------------|---------|
| `width` / `height` | Widget size in pixels | `48` |
| `viewbox` | SVG viewBox as vec4 | `vec4(0 0 24 24)` |

### CRITICAL: Shape Properties vs Widget Properties

**Vector shapes use SVG-style properties, NOT `draw_bg.*` widget properties:**

```
// CORRECT — SVG properties
Path{d:"M 0 0 L 10 10" stroke:#x66aaff stroke_width:2.5}
Circle{cx:10 cy:10 r:5 fill:#x44ddaa}

// WRONG — these do nothing on Vector shapes!
Path{d:"..." draw_bg.stroke_color:#x66aaff draw_bg.stroke_width:2.}
Circle{cx:10 cy:10 r:5 draw_bg.fill_color:#x44ddaa}
```

---

## Shape Types

### Path (SVG path data)
```
Path{
    d: "M10 10 L20 20 L10 20 Z"
    fill: #f00
    stroke: #000
    stroke_width: 1.5
}
```

### Built-in Shapes
```
Rect{x: 0 y: 0 width: 100 height: 50 fill: #f00 rx: 5}
Circle{cx: 50 cy: 50 r: 25 fill: #00f}
Ellipse{cx: 50 cy: 30 rx: 40 ry: 20 fill: #0f0}
Line{x1: 0 y1: 0 x2: 100 y2: 100 stroke: #fff stroke_width: 2}
Polyline{points: "0,0 50,25 100,0" fill: false stroke: #fff}
Polygon{points: "50,0 100,100 0,100" fill: #f0f}
```

---

## Gradients

### Linear Gradient
```
Gradient{
    id: "myGrad"
    x1: 0 y1: 0 x2: 1 y2: 1
    Stop{offset: 0 color: #ff0000}
    Stop{offset: 1 color: #0000ff}
}
Path{d: "..." fill: "url(#myGrad)"}
```

### Radial Gradient
```
RadGradient{
    id: "radGrad"
    cx: 0.5 cy: 0.5 r: 0.5
    Stop{offset: 0 color: #ffffff}
    Stop{offset: 1 color: #000000}
}
```

---

## Groups & Transforms

```
Group{
    transform: "translate(10 20) rotate(45 50 50)"
    opacity: 0.8

    Circle{cx: 0 cy: 0 r: 10 fill: #f00}
    Rect{x: 20 y: 0 width: 20 height: 20 fill: #0f0}
}
```

---

## Filters

```
Filter{
    id: "shadow"
    DropShadow{dx: 2 dy: 2 blur: 4 color: #0008}
}
Path{d: "..." fill: #fff filter: "url(#shadow)"}
```

---

## Tween Animation (SVG Property Animation)

**CRITICAL:** Tween is a **property value**, NOT a container. It replaces a shape property (fill, stroke, opacity, cx, cy, r, etc.) with an animated value.

### Basic Syntax
```
// Animate opacity (pulse effect)
Circle{cx:8 cy:8 r:6 fill:#x44ddaa opacity:Tween{from:0.3 to:1.0 dur:1.5 loop_:true}}

// Animate position (moving dot)
Circle{cx:Tween{from:20 to:380 dur:3.0 loop_:true} cy:25 r:5 fill:#x66aaff}

// Animate color
Circle{fill:Tween{from:#x44ddaa to:#x6688dd dur:3.0 loop_:true} cx:10 cy:10 r:8}

// Animate stroke
Path{d:"M 0 0 L 100 0" stroke:Tween{from:#x333333 to:#x66aaff dur:2.0 loop_:true} stroke_width:2.}
```

### CRITICAL: `loop_` Must Be Boolean
```
// CORRECT — indefinite loop
opacity:Tween{from:0.3 to:1.0 dur:1.5 loop_:true}

// CORRECT — play 3 times
opacity:Tween{from:0.3 to:1.0 dur:1.5 loop_:3.0}

// WRONG — string doesn't trigger Indefinite, plays only once!
opacity:Tween{from:0.3 to:1.0 dur:1.5 loop_:"indefinite"}
```

### Tween Properties

| Property | Type | Description | Default |
|----------|------|-------------|---------|
| `from` | value | Start value (color, float, string) | - |
| `to` | value | End value | - |
| `values` | Vec | Keyframe values (alternative to from/to) | - |
| `dur` | f32 | Duration in seconds | 1.0 |
| `begin` | f32 | Delay offset in seconds | 0.0 |
| `loop_` | bool/f32 | `true` = indefinite, float = repeat count | 1.0 |
| `calc` | string | "discrete", "paced", "spline" | "linear" |
| `fill_mode` | string | "freeze" or "remove" | "remove" |

### Animatable Properties
Any shape property can be animated with Tween:
- `fill`, `stroke` — color animation
- `stroke_width`, `opacity`, `stroke_opacity` — float animation
- `cx`, `cy`, `r` (Circle) — position/size animation
- `d` (Path) — path morphing animation

### Common Patterns

**Pulsing indicator:**
```
Vector{width:16 height:16
  Circle{cx:8 cy:8 r:6 fill:#x44ddaa opacity:Tween{from:0.3 to:1.0 dur:1.5 loop_:true}}
}
```

**Moving dot along a line:**
```
Vector{width:Fill height:40
  Path{d:"M 20 20 L 380 20" stroke:#x333355 stroke_width:1.}
  Circle{cx:Tween{from:20 to:380 dur:3.0 loop_:true} cy:20 r:4 fill:Tween{from:#x44ddaa to:#xffaa44 dur:3.0 loop_:true}}
}
```

**Delayed sequential animation:**
```
Circle{cx:8 cy:8 r:6 fill:#x44ddaa opacity:Tween{from:0.3 to:1.0 dur:1.5 begin:0.0 loop_:true}}
Circle{cx:8 cy:8 r:6 fill:#xffaa44 opacity:Tween{from:0.3 to:1.0 dur:1.5 begin:0.5 loop_:true}}
Circle{cx:8 cy:8 r:6 fill:#x6688dd opacity:Tween{from:0.3 to:1.0 dur:1.5 begin:1.0 loop_:true}}
```

### Tween vs Animator

| Feature | `Tween` (Vector) | `Animator` (Widget) |
|---------|------------------|---------------------|
| Scope | SVG shape properties | Widget shader `instance` vars |
| Syntax | Property value replacement | `animator: Animator{...}` block |
| Triggers | Automatic on render | State transitions (hover, etc.) |
| Loop | `loop_:true` | `Loop {duration: 1.0}` |
| Use for | SVG animations | UI hover/focus/active effects |

---

## Icon Pattern (Common)

Most Vector widgets in Makepad 2.0 are used as icons with SVG paths:

```
let IconCheck = Vector{width: 18 height: 18 viewbox: vec4(0 0 24 24)
    Path{d: "M20 6L9 17L4 12" fill: false stroke: theme.color_highlight stroke_width: 2.5
        stroke_linecap: "round" stroke_linejoin: "round"}
}

let IconTrash = Vector{width: 14 height: 14 viewbox: vec4(0 0 24 24)
    Path{d: "M3 6h18M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" fill: false stroke: theme.color_label_inner_inactive stroke_width: 1.8 stroke_linecap: "round" stroke_linejoin: "round"}
}
```

**Use with theme colors** for consistent styling across light/dark modes.

---

## Vector vs Svg vs SDF2D

| Feature | `Vector{}` | `Svg{}` | SDF2D Shader |
|---------|-----------|---------|-------------|
| Input | Inline shapes in Splash | External `.svg` file | Shader code |
| SVG path data | Yes (`d: "..."`) | Yes (parsed from file) | No |
| Gradients | `let` bindings | SVG `<defs>` | Manual |
| Filters | `Filter{DropShadow{}}` | SVG `<filter>` | Manual |
| Animation | `Tween{}` | SVG `<animate>` + `animating: true` | Shader uniforms |
| Custom GPU shader | `shader_id` | `draw_svg +: {get_color: fn(){...}}` | Full control |
| URL loading | No | Yes (`http_resource()`) | No |
| Resolution-independent | Yes | Yes | Yes |
| Performance | Good for static | Good for complex SVGs | Best for animated |

**Use `Vector{}` for:** Inline icons, illustrations, programmatic vector graphics
**Use `Svg{}` for:** Loading pre-made SVG files, complex SVG assets, SVG from URLs
**Use SDF2D for:** Animated shapes, hover effects, custom widget backgrounds

---

## Hex Color Escape

When using hex colors containing the letter 'e', prefix with `#x`:

```
// WRONG - parser misreads 'e' as exponent
stroke: #2ecc71

// CORRECT
stroke: #x2ecc71
```

---

## Best Practices

1. **Use `viewbox`** to define coordinate space independent of widget size
2. **Use theme colors** for icon strokes/fills for dark/light mode support
3. **Use `let` bindings** for reusable icon definitions
4. **Keep paths simple** - Complex SVG paths can impact performance
5. **Use `fill: false`** for outline-only icons (most common pattern)
6. **Set `stroke_linecap: "round"`** for cleaner line endings on icons