diff --git a/.agent/rules.md b/.agent/rules.md
index 2800b922e..c66d9bf57 100644
--- a/.agent/rules.md
+++ b/.agent/rules.md
@@ -45,6 +45,7 @@ ImageSource            →  ImageSelector
 FileSource<M>          →  FileSelector<M>
 RemoteSource<M>        →  GenericSelector
 RichTextSource<O>      →  RichTextSelector<O>
+SvgSource<O>           →  SvgSelector<O>
 SourceObject           →  ObjectSelector<T>
 SourceArray            →  ArraySelector<T>
 string/number/boolean  →  StringSelector/NumberSelector/BooleanSelector
@@ -62,7 +63,8 @@ export type Source =
   | RemoteSource
   | FileSource
   | ImageSource
-  | RichTextSource<RichTextOptions>;
+  | RichTextSource<RichTextOptions>
+  | SvgSource<AllSvgOptions>;
 ```
 
 **SelectorSource** (`packages/core/src/selector/index.ts`):
@@ -77,6 +79,7 @@ export type SelectorSource =
   | FileSource
   | RemoteSource
   | RichTextSource<AllRichTextOptions>
+  | SvgSource<AllSvgOptions>
   | GenericSelector<Source>;
 ```
 
@@ -127,6 +130,7 @@ Each Schema class validates and types its corresponding Source type:
 | `ImageSchema<T>`    | `ImageSource`       | `s.image()`           |
 | `FileSchema<T>`     | `FileSource`        | `s.file()`            |
 | `RichTextSchema<O>` | `RichTextSource<O>` | `s.richtext(options)` |
+| `SvgSchema<O>`      | `SvgSource<O>`      | `s.svg(options)`      |
 | `ObjectSchema<T>`   | `SourceObject`      | `s.object({...})`     |
 | `ArraySchema<T>`    | `SourceArray`       | `s.array(schema)`     |
 
@@ -498,6 +502,53 @@ This handles both local and remote refs, with or without pending patches. The `M
 
 The `/api/val/files` endpoint (`ValServer.ts`) serves draft files by loading them from the patch directory (via `getBase64EncodedBinaryFileFromPatch`) and published files directly from the filesystem (`getBinaryFile`). No auth is required on this endpoint (patch IDs serve as unguessable tokens).
 
+## Working with Svg
+
+`s.svg()` stores an svg as a **json node tree**, not a file. Colors are
+**variables**, not baked hexes, so an icon can be rethemed at render time.
+
+### Shape
+
+```typescript
+// packages/core/src/source/svg.ts
+type SvgSource<O> = {
+  viewBox: string;
+  width: number | null; // null, never undefined: undefined is not Json
+  height: number | null;
+  children: SvgNode<O>[];
+  readonly [SVG_VAL_PATH]?: string; // injected by stega, never stored
+};
+type SvgNode<O> = { tag: SvgTag; attrs: SvgAttrs<O>; children: SvgNode<O>[] };
+```
+
+`SvgAttrs<O>` is a **per-attribute mapped type**, not `Record<string, unknown>`:
+`fill` / `stroke` take `SvgColorValue<O>`, geometry attributes take `number`,
+`stroke-linecap` and friends take their enum, and `d` / `points` / `transform` /
+`stroke-dasharray` are the only free strings. This makes the palette constraint
+a _compile_ error, not only a validation error: with the default
+`literals: "forbid"`, `fill: "#f00"` does not typecheck.
+
+### Rules when touching svg code
+
+1. **Never stega encode an svg.** Every string in one (`d`, `viewBox`,
+   `points`, `transform`) is machine parsed; invisible characters corrupt the
+   icon. `stegaEncode` returns the source untouched and attaches the path as
+   `SVG_VAL_PATH`, which `ValSvg` turns into `data-val-path`.
+2. **The allowlist in `packages/core/src/schema/svg/allowlist.ts` is the entire
+   security boundary.** `ValSvg` builds React elements, and React renders
+   unknown attributes on host elements verbatim - `onload` does fire on svg
+   elements. It must stay a strict per-tag allowlist of exact attribute names,
+   never an `on*` denylist. Do not add a tag or attribute to it without
+   thinking about what it can load, execute or leak.
+3. **The parser is not a security boundary.** `packages/shared/src/internal/svg`
+   parses, then everything goes through the allowlist, then through validation.
+   Keep that order.
+4. **`ValSvg`'s `vars` is exhaustive when given**, exactly like
+   `ValRichText`'s `theme`. That is deliberate: a new variable should break the
+   call sites so someone revisits them.
+5. **The palette lives only in the schema.** Do not mirror it into the source -
+   that is what creates drift and repair fixes.
+
 ## Common Fixes
 
 ### "Type 'X' does not satisfy constraint 'Source'"
diff --git a/.changeset/svg-schema.md b/.changeset/svg-schema.md
new file mode 100644
index 000000000..a6ce3d118
--- /dev/null
+++ b/.changeset/svg-schema.md
@@ -0,0 +1,41 @@
+---
+"@valbuild/core": patch
+"@valbuild/shared": patch
+"@valbuild/react": patch
+"@valbuild/next": patch
+"@valbuild/server": patch
+"@valbuild/ui": patch
+---
+
+Add `s.svg()` — a schema that stores an SVG as a JSON node tree instead of a binary file, so custom icons become real, diffable, type-checked content.
+
+Colors are **variables**, not baked hexes. A schema declares the variables an icon may use, along with an example value that doubles as the CSS fallback and as the key used to auto-match literal colors on import:
+
+```ts
+s.svg({
+  width: 24,
+  height: 24,
+  variables: {
+    brand: "#0055ff",
+    line: { value: "currentColor" },
+    surface: { value: "#ffffff", match: ["#fff", "#fefefe"] },
+  },
+});
+```
+
+Drop an SVG onto the field in the editor and its literal colors are matched onto those variables automatically; anything that does not match is surfaced as a mapping step where the editor picks a variable per unmatched color. With the default `literals: "forbid"`, a raw color is both a validation error and a _compile_ error — attributes are a per-attribute mapped type, so `fill: "#f00"` does not typecheck. `literals: "allow"` or an explicit allowlist relaxes that. Geometry can be constrained too, via `width` / `height` / `aspectRatio`, validated against the viewBox.
+
+`<ValSvg>` renders the tree as React elements — never `dangerouslySetInnerHTML` — and is exhaustively typed the same way `ValRichText`'s `theme` is: adding a variable to the schema breaks every call site until the mapping is supplied.
+
+```tsx
+<ValSvg
+  src={icons.bell}
+  size={32}
+  vars={{ brand: "var(--brand-500)", line: "currentColor", surface: "#fff" }}
+/>
+```
+
+Notes:
+
+- **The allowlist in `@valbuild/core` is the security boundary.** `ValSvg` builds React elements, and React renders unknown attributes on host elements verbatim, so tags and attributes are checked against a strict per-tag allowlist of exact names. `script`, `foreignObject`, `style`, `image`, `a`, animation and filter elements, all `on*` handlers, and any non-local `href` are rejected. `id` is not an allowed attribute at all, so `url(#…)` references have nothing to point at and gradients, masks and clip paths are out of scope for this first version - which also means two icons on a page have no ids to collide over.
+- **SVG sources are never stega encoded.** Every string in one (`d`, `viewBox`, `points`, `transform`) is machine parsed, and invisible characters would corrupt the icon, so `stegaEncode` returns the source untouched and attaches the path out of band for the visual editing overlay.
diff --git a/.github/pr-assets/svg-schema/README.md b/.github/pr-assets/svg-schema/README.md
new file mode 100644
index 000000000..6458560b9
--- /dev/null
+++ b/.github/pr-assets/svg-schema/README.md
@@ -0,0 +1,9 @@
+# PR review assets: `s.svg()`
+
+Screenshots referenced from the pull request body, captured from the storybook
+stories in `packages/ui/spa/components/fields/SvgField.stories.tsx` and from
+`examples/next`.
+
+They live here only so GitHub can render them in the PR. This whole directory
+is a separate commit and can be dropped before merge without touching the
+feature.
diff --git a/.github/pr-assets/svg-schema/svg-example-app.png b/.github/pr-assets/svg-schema/svg-example-app.png
new file mode 100644
index 000000000..d10d6f2a9
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-example-app.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-color-mapper-dark.png b/.github/pr-assets/svg-schema/svg-field-color-mapper-dark.png
new file mode 100644
index 000000000..bd138eb13
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-color-mapper-dark.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-color-mapper-light.png b/.github/pr-assets/svg-schema/svg-field-color-mapper-light.png
new file mode 100644
index 000000000..b9979174f
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-color-mapper-light.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-empty-dark.png b/.github/pr-assets/svg-schema/svg-field-empty-dark.png
new file mode 100644
index 000000000..459cc2f95
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-empty-dark.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-empty-light.png b/.github/pr-assets/svg-schema/svg-field-empty-light.png
new file mode 100644
index 000000000..34d0b95ff
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-empty-light.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-import-dark.png b/.github/pr-assets/svg-schema/svg-field-import-dark.png
new file mode 100644
index 000000000..95c44bd5d
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-import-dark.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-import-light.png b/.github/pr-assets/svg-schema/svg-field-import-light.png
new file mode 100644
index 000000000..fe9dfd57f
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-import-light.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-rendering-dark.png b/.github/pr-assets/svg-schema/svg-field-rendering-dark.png
new file mode 100644
index 000000000..37a068ee6
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-rendering-dark.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-rendering-light.png b/.github/pr-assets/svg-schema/svg-field-rendering-light.png
new file mode 100644
index 000000000..0f4ee573f
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-rendering-light.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-with-icon-dark.png b/.github/pr-assets/svg-schema/svg-field-with-icon-dark.png
new file mode 100644
index 000000000..24acbe20d
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-with-icon-dark.png differ
diff --git a/.github/pr-assets/svg-schema/svg-field-with-icon-light.png b/.github/pr-assets/svg-schema/svg-field-with-icon-light.png
new file mode 100644
index 000000000..589be5b3f
Binary files /dev/null and b/.github/pr-assets/svg-schema/svg-field-with-icon-light.png differ
diff --git a/examples/next/app/page.tsx b/examples/next/app/page.tsx
index 37a206033..bd92befd4 100644
--- a/examples/next/app/page.tsx
+++ b/examples/next/app/page.tsx
@@ -1,8 +1,9 @@
 import { notFound } from "next/navigation";
 import { fetchVal, fetchValRoute } from "../val/rsc";
 import pageVal from "./page.val";
-import { ValImage, ValRichText } from "@valbuild/next";
+import { ValImage, ValRichText, ValSvg } from "@valbuild/next";
 import authorsVal from "../content/authors.val";
+import iconsVal from "../content/icons.val";
 import themeVal from "../content/theme.val";
 import Link from "next/link";
 import { val } from "../val.config";
@@ -13,6 +14,7 @@ export default async function Home({ params }: { params: unknown }) {
     notFound();
   }
   const authors = await fetchVal(authorsVal);
+  const icons = await fetchVal(iconsVal);
   const theme = await fetchVal(themeVal);
   const author = authors[page.author];
   return (
@@ -54,6 +56,46 @@ export default async function Home({ params }: { params: unknown }) {
         <span>{page.video.text}</span>
         <video src={page.video.file.url} controls />
       </section>
+      <section>
+        <div style={{ display: "flex", gap: "1.5rem", alignItems: "center" }}>
+          {/* Every declared variable must be mapped. Adding one to the schema
+              is a compile error here until it is given a color, the same way
+              ValRichText's theme works. */}
+          <ValSvg
+            src={icons.bookmark}
+            size={32}
+            vars={{ brand: "#0055ff", line: "currentColor", surface: "#fff" }}
+          />
+          {/* `line` is mapped to currentColor, so the bell's clapper follows
+              the surrounding text color. */}
+          <span
+            style={{ color: "#b91c1c", display: "inline-flex", gap: ".5rem" }}
+          >
+            <ValSvg
+              src={icons.bell}
+              size={32}
+              vars={{
+                brand: "currentColor",
+                line: "currentColor",
+                surface: "#fff",
+              }}
+            />
+            Inherits currentColor
+          </span>
+          {/* Mapped to css custom properties this app owns, so a dark mode
+              stylesheet can retheme the icon without re-rendering. */}
+          <ValSvg
+            src={icons.check}
+            size={32}
+            title="Done"
+            vars={{
+              brand: "var(--icon-brand, #15803d)",
+              line: null,
+              surface: "var(--icon-surface, #f0fdf4)",
+            }}
+          />
+        </div>
+      </section>
       <section
         style={{
           background: theme.overlay,
diff --git a/examples/next/content/icons.val.ts b/examples/next/content/icons.val.ts
new file mode 100644
index 000000000..533ff92b2
--- /dev/null
+++ b/examples/next/content/icons.val.ts
@@ -0,0 +1,122 @@
+import { s, c, type t } from "../val.config";
+
+/**
+ * A set of custom icons.
+ *
+ * Colors are declared as variables rather than baked into the markup, so the
+ * same icon can inherit the surrounding text color, follow a dark mode
+ * stylesheet, or be recolored per usage. The color on each variable is an
+ * example: it is what the editor previews, what `svgVarsCss` writes into the
+ * stylesheet, and what a pasted color is matched against on import.
+ */
+export const iconSchema = s
+  .svg({
+    width: 24,
+    height: 24,
+    aspectRatio: "1:1",
+    variables: {
+      brand: {
+        value: "#0055ff",
+        match: ["#0055FF", "#0050f0"],
+        description: "The primary shape of the icon",
+      },
+      line: {
+        value: "currentColor",
+        description: "Strokes: inherits the surrounding text color",
+      },
+      surface: {
+        value: "#ffffff",
+        match: ["#fff", "#fefefe"],
+        description: "Cut-outs and badges",
+      },
+    },
+  })
+  .describe("A 24x24 icon. Paste svg markup to replace it.");
+
+export const schema = s.record(iconSchema);
+
+export type Icons = t.inferSchema<typeof schema>;
+
+export default c.define("/content/icons.val.ts", schema, {
+  bell: {
+    viewBox: "0 0 24 24",
+    width: 24,
+    height: 24,
+    children: [
+      {
+        tag: "path",
+        attrs: {
+          d: "M12 2.5A5.5 5.5 0 0 0 6.5 8v4.2L4.8 15.2a.6.6 0 0 0 .52.9h13.36a.6.6 0 0 0 .52-.9L17.5 12.2V8A5.5 5.5 0 0 0 12 2.5Z",
+          fill: { var: "brand" },
+        },
+        children: [],
+      },
+      {
+        tag: "path",
+        attrs: {
+          d: "M9.6 18.5a2.4 2.4 0 0 0 4.8 0",
+          stroke: { var: "line" },
+          "stroke-width": 1.6,
+          "stroke-linecap": "round",
+          fill: "none",
+        },
+        children: [],
+      },
+      {
+        tag: "circle",
+        attrs: { cx: 17.5, cy: 6, r: 2.6, fill: { var: "surface" } },
+        children: [],
+      },
+    ],
+  },
+  bookmark: {
+    viewBox: "0 0 24 24",
+    width: 24,
+    height: 24,
+    children: [
+      {
+        tag: "path",
+        attrs: {
+          d: "M6.5 3.5h11a1 1 0 0 1 1 1v16l-6.5-4.2-6.5 4.2v-16a1 1 0 0 1 1-1Z",
+          fill: { var: "brand" },
+        },
+        children: [],
+      },
+      {
+        tag: "path",
+        attrs: {
+          d: "M9.5 8.5h5",
+          stroke: { var: "surface" },
+          "stroke-width": 1.6,
+          "stroke-linecap": "round",
+          fill: "none",
+        },
+        children: [],
+      },
+    ],
+  },
+  check: {
+    viewBox: "0 0 24 24",
+    width: 24,
+    height: 24,
+    children: [
+      {
+        tag: "circle",
+        attrs: { cx: 12, cy: 12, r: 9.5, fill: { var: "brand" } },
+        children: [],
+      },
+      {
+        tag: "path",
+        attrs: {
+          d: "M7.5 12.3 10.6 15.4 16.5 9.5",
+          stroke: { var: "surface" },
+          "stroke-width": 2,
+          "stroke-linecap": "round",
+          "stroke-linejoin": "round",
+          fill: "none",
+        },
+        children: [],
+      },
+    ],
+  },
+});
diff --git a/examples/next/val.modules.ts b/examples/next/val.modules.ts
index ef30e9d7e..cf95368b0 100644
--- a/examples/next/val.modules.ts
+++ b/examples/next/val.modules.ts
@@ -7,6 +7,7 @@ export default modules(config, [
   { def: () => import("./app/support/[slug]/page.val") },
   { def: () => import("./app/generic/[[...path]]/page.val") },
   { def: () => import("./content/media.val") },
+  { def: () => import("./content/icons.val") },
   { def: () => import("./content/theme.val") },
   { def: () => import("./app/page.val") },
   { def: () => import("./app/external.val") },
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 8d14bc4e9..e51924a42 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -43,6 +43,23 @@ export type {
   SpanNode,
   UnorderedListNode,
 } from "./source/richtext";
+export type {
+  AllSvgOptions,
+  GenericSvgNode,
+  GenericSvgSource,
+  SvgAttrs,
+  SvgColorValue,
+  SvgKeywordColor,
+  SvgLiterals,
+  SvgNode,
+  SvgOptions,
+  SvgSource,
+  SvgTag,
+  SvgVarRef,
+  SvgVariable,
+  SvgVariableName,
+} from "./source/svg";
+export { SVG_VAL_PATH, isSvgVarRef, svgVariableValue } from "./source/svg";
 export {
   type Val,
   type SerializedVal,
@@ -145,6 +162,22 @@ export {
   type SerializedRichTextSchema,
   RichTextSchema,
 } from "./schema/richtext";
+export { type SerializedSvgSchema, SvgSchema, svgVarsCss } from "./schema/svg";
+export {
+  SVG_TAGS,
+  SVG_COMMON_ATTRS,
+  SVG_TAG_ATTRS,
+  SVG_COLOR_ATTRS,
+  SVG_NUMBER_ATTRS,
+  SVG_ENUM_ATTRS,
+  SVG_STRING_ATTRS,
+  SVG_KEYWORD_COLORS,
+  SVG_DEFAULT_MAX_NODES,
+  SVG_DEFAULT_MAX_DEPTH,
+  isSvgTag,
+  isAllowedSvgAttr,
+  parseSvgViewBox,
+} from "./schema/svg/allowlist";
 export {
   type SerializedUnionSchema,
   UnionSchema,
diff --git a/packages/core/src/initSchema.ts b/packages/core/src/initSchema.ts
index 3ef41590d..defbaa76b 100644
--- a/packages/core/src/initSchema.ts
+++ b/packages/core/src/initSchema.ts
@@ -6,6 +6,7 @@ import { string } from "./schema/string";
 import { boolean } from "./schema/boolean";
 import { union } from "./schema/union";
 import { richtext } from "./schema/richtext";
+import { svg } from "./schema/svg";
 import { image } from "./schema/image";
 import { literal } from "./schema/literal";
 import { keyOf } from "./schema/keyOf";
@@ -100,6 +101,38 @@ export type InitSchema = {
    * ]);
    */
   readonly richtext: typeof richtext;
+  /**
+   * Define an svg icon.
+   *
+   * The svg is stored as a json tree, so colors can be constrained to a set of
+   * named variables. Each variable declares an example color, which is what the
+   * editor previews, what `svgVarsCss` emits, and what literal fills are matched
+   * against when an svg is pasted in. The color that actually renders is
+   * resolved from `--val-svg-<name>`, so an icon supports `currentColor`, dark
+   * mode and per-usage overrides.
+   *
+   * Render it with `ValSvg`.
+   *
+   * @example
+   * const schema = s.svg({
+   *   width: 24,
+   *   height: 24,
+   *   variables: { brand: "#0055ff", line: "currentColor" },
+   * });
+   * export default c.define("/example.val.ts", schema, {
+   *   viewBox: "0 0 24 24",
+   *   width: 24,
+   *   height: 24,
+   *   children: [
+   *     {
+   *       tag: "path",
+   *       attrs: { d: "M4 12h16", stroke: { var: "line" }, fill: "none" },
+   *       children: [],
+   *     },
+   *   ],
+   * });
+   */
+  readonly svg: typeof svg;
   /**
    * Define an image.
    *
@@ -287,6 +320,7 @@ export function initSchema() {
     union,
     // oneOf,
     richtext,
+    svg,
     image,
     literal,
     keyOf,
diff --git a/packages/core/src/module.ts b/packages/core/src/module.ts
index 9806a0b2f..845533a26 100644
--- a/packages/core/src/module.ts
+++ b/packages/core/src/module.ts
@@ -14,6 +14,7 @@ import { ArraySchema, SerializedArraySchema } from "./schema/array";
 import { UnionSchema, SerializedUnionSchema } from "./schema/union";
 import { Json } from "./Json";
 import { RichTextSchema, SerializedRichTextSchema } from "./schema/richtext";
+import { SerializedSvgSchema, SvgSchema } from "./schema/svg";
 import {
   ImageMetadata,
   ImageSchema,
@@ -22,6 +23,7 @@ import {
 import { FILE_REF_PROP, FileSource } from "./source/file";
 import { isJson } from "./source/json";
 import { AllRichTextOptions, RichTextSource } from "./source/richtext";
+import { AllSvgOptions, SvgSource } from "./source/svg";
 import { RecordSchema, SerializedRecordSchema } from "./schema/record";
 import { RawString } from "./schema/string";
 import { ImageSelector } from "./selector/image";
@@ -256,6 +258,17 @@ function isRichTextSchema(
   );
 }
 
+function isSvgSchema(
+  schema: Schema<SelectorSource> | SerializedSchema,
+): schema is
+  | SvgSchema<AllSvgOptions, SvgSource<AllSvgOptions>>
+  | SerializedSvgSchema {
+  return (
+    schema instanceof SvgSchema ||
+    (typeof schema === "object" && "type" in schema && schema.type === "svg")
+  );
+}
+
 function isImageSchema(
   schema: Schema<SelectorSource> | SerializedSchema,
 ): schema is
@@ -461,6 +474,10 @@ export function resolvePath<
             : resolvedSchema;
       }
       resolvedSource = resolvedSource[part];
+    } else if (isSvgSchema(resolvedSchema)) {
+      // Svg sources are edited as a whole: the schema stays pinned while the
+      // path walks down into the node tree (same as richtext).
+      resolvedSource = resolvedSource[part];
     } else {
       throw Error(
         `Invalid path: ${part} resolved to an unexpected schema ${JSON.stringify(
@@ -734,6 +751,9 @@ export function safeResolvePath<
             : resolvedSchema;
       }
       resolvedSource = resolvedSource[part];
+    } else if (isSvgSchema(resolvedSchema)) {
+      // See the note in resolvePath.
+      resolvedSource = resolvedSource[part];
     } else {
       return {
         status: "error",
diff --git a/packages/core/src/schema/describe.test.ts b/packages/core/src/schema/describe.test.ts
index 1a5886b71..79915cec5 100644
--- a/packages/core/src/schema/describe.test.ts
+++ b/packages/core/src/schema/describe.test.ts
@@ -4,6 +4,7 @@ import { array } from "./array";
 import { boolean } from "./boolean";
 import { color } from "./color";
 import { date } from "./date";
+import { svg } from "./svg";
 import { deserializeSchema } from "./deserialize";
 import { image } from "./image";
 import { literal } from "./literal";
@@ -40,6 +41,16 @@ describe("Schema.describe()", () => {
     });
   });
 
+  test("svg: describe is serialized", () => {
+    const schema = svg({ variables: { brand: "#0055ff" } }).describe(
+      "Brand icon",
+    );
+    expect(schema["executeSerialize"]()).toMatchObject({
+      type: "svg",
+      description: "Brand icon",
+    });
+  });
+
   test("color: describe is serialized", () => {
     const schema = color().describe("Brand color");
     expect(schema["executeSerialize"]()).toMatchObject({
@@ -279,6 +290,18 @@ describe("Schema.describe() survives serialize → deserialize round-trip", () =
     });
   });
 
+  test("svg", () => {
+    expect(
+      roundTrip(
+        svg({ variables: { brand: "#0055ff" } }).describe("Brand icon"),
+      ),
+    ).toMatchObject({
+      type: "svg",
+      description: "Brand icon",
+      options: { variables: { brand: "#0055ff" } },
+    });
+  });
+
   test("color", () => {
     expect(
       roundTrip(color({ format: "hex" }).describe("Brand color")),
diff --git a/packages/core/src/schema/deserialize.ts b/packages/core/src/schema/deserialize.ts
index aa6c5e4a9..5d8af9177 100644
--- a/packages/core/src/schema/deserialize.ts
+++ b/packages/core/src/schema/deserialize.ts
@@ -18,6 +18,7 @@ import { RecordSchema } from "./record";
 import { RichTextSchema } from "./richtext";
 import { RouteSchema } from "./route";
 import { StringSchema } from "./string";
+import { SvgSchema } from "./svg";
 import { UnionSchema } from "./union";
 
 export function deserializeSchema(
@@ -157,6 +158,15 @@ function deserializeSchemaImpl(
         serialized.description,
       );
     }
+    case "svg":
+      return new SvgSchema(
+        serialized.options ?? {},
+        serialized.opt,
+        [],
+        false,
+        false,
+        serialized.description,
+      );
     case "record":
       return new RecordSchema(
         deserializeSchema(serialized.item),
diff --git a/packages/core/src/schema/hidden.test.ts b/packages/core/src/schema/hidden.test.ts
index 85fa0e160..4c24610fd 100644
--- a/packages/core/src/schema/hidden.test.ts
+++ b/packages/core/src/schema/hidden.test.ts
@@ -47,6 +47,7 @@ describe("Schema.hidden()", () => {
     expect(s.number().hidden()["executeSerialize"]().hidden).toBe(true);
     expect(s.boolean().hidden()["executeSerialize"]().hidden).toBe(true);
     expect(s.date().hidden()["executeSerialize"]().hidden).toBe(true);
+    expect(s.svg().hidden()["executeSerialize"]().hidden).toBe(true);
     expect(s.array(s.string()).hidden()["executeSerialize"]().hidden).toBe(
       true,
     );
diff --git a/packages/core/src/schema/index.ts b/packages/core/src/schema/index.ts
index 2098888b8..ec6975d06 100644
--- a/packages/core/src/schema/index.ts
+++ b/packages/core/src/schema/index.ts
@@ -11,6 +11,7 @@ import { SerializedNumberSchema } from "./number";
 import { SerializedObjectSchema } from "./object";
 import { SerializedRecordSchema } from "./record";
 import { SerializedRichTextSchema } from "./richtext";
+import { SerializedSvgSchema } from "./svg";
 import { RawString, SerializedStringSchema } from "./string";
 import { SerializedUnionSchema } from "./union";
 import { SerializedColorSchema } from "./color";
@@ -23,6 +24,7 @@ import {
 } from "./validation/ValidationError";
 import { FileSource } from "../source/file";
 import { GenericRichTextSourceNode, RichTextSource } from "../source/richtext";
+import { GenericSvgSource, SvgOptions, SvgSource } from "../source/svg";
 import { ReifiedRender } from "../render";
 // import { SerializedI18nSchema } from "./future/i18n";
 // import { SerializedOneOfSchema } from "./future/oneOf";
@@ -38,6 +40,7 @@ export type SerializedSchema =
   | SerializedArraySchema
   | SerializedUnionSchema
   | SerializedRichTextSchema
+  | SerializedSvgSchema
   | SerializedRecordSchema
   | SerializedKeyOfSchema
   | SerializedFileSchema
@@ -69,13 +72,15 @@ export type SchemaAssertResult<Src extends SelectorSource> =
         : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
           Src extends RichTextSource<{}>
           ? GenericRichTextSourceNode[]
-          : Src extends Primitives
-            ? Src
-            : Src extends Array<SelectorSource>
-              ? SelectorSource[]
-              : Src extends { [key: string]: SelectorSource }
-                ? { [key in keyof Src]: SelectorSource }
-                : never;
+          : Src extends SvgSource<SvgOptions>
+            ? GenericSvgSource
+            : Src extends Primitives
+              ? Src
+              : Src extends Array<SelectorSource>
+                ? SelectorSource[]
+                : Src extends { [key: string]: SelectorSource }
+                  ? { [key in keyof Src]: SelectorSource }
+                  : never;
       success: true;
     }
   | { success: false; errors: Record<SourcePath, AssertError[]> };
diff --git a/packages/core/src/schema/readonly.test.ts b/packages/core/src/schema/readonly.test.ts
index a52465395..a6430c960 100644
--- a/packages/core/src/schema/readonly.test.ts
+++ b/packages/core/src/schema/readonly.test.ts
@@ -40,6 +40,7 @@ describe("Schema.readonly()", () => {
     expect(s.number().readonly()["executeSerialize"]().readonly).toBe(true);
     expect(s.boolean().readonly()["executeSerialize"]().readonly).toBe(true);
     expect(s.date().readonly()["executeSerialize"]().readonly).toBe(true);
+    expect(s.svg().readonly()["executeSerialize"]().readonly).toBe(true);
     expect(s.array(s.string()).readonly()["executeSerialize"]().readonly).toBe(
       true,
     );
diff --git a/packages/core/src/schema/svg.test.ts b/packages/core/src/schema/svg.test.ts
new file mode 100644
index 000000000..d19d3e63b
--- /dev/null
+++ b/packages/core/src/schema/svg.test.ts
@@ -0,0 +1,162 @@
+import { initVal } from "../initVal";
+import { deserializeSchema } from "./deserialize";
+import { svgVarsCss, SvgSchema } from "./svg";
+import { SourcePath } from "../val";
+
+const { s } = initVal();
+
+const path = "/test" as SourcePath;
+
+const iconSchema = s.svg({
+  width: 24,
+  height: 24,
+  variables: { brand: "#0055ff", line: "currentColor" },
+});
+
+const icon = {
+  viewBox: "0 0 24 24",
+  width: 24,
+  height: 24,
+  children: [
+    {
+      tag: "path" as const,
+      attrs: {
+        d: "M4 12h16",
+        stroke: { var: "line" as const },
+        fill: "none" as const,
+      },
+      children: [],
+    },
+  ],
+};
+
+describe("SvgSchema.assert", () => {
+  test("accepts a well formed svg", () => {
+    expect(iconSchema["executeAssert"](path, icon)).toStrictEqual({
+      success: true,
+      data: icon,
+    });
+  });
+
+  test("only checks the root type, not the nodes", () => {
+    // A node with an unsupported tag still asserts: assert is a runtime type
+    // check, validate is what checks values.
+    const result = iconSchema["executeAssert"](path, {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [{ tag: "script", attrs: {}, children: [] }],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects a non object", () => {
+    expect(iconSchema["executeAssert"](path, "nope").success).toBe(false);
+    expect(iconSchema["executeAssert"](path, []).success).toBe(false);
+    expect(iconSchema["executeAssert"](path, null).success).toBe(false);
+  });
+
+  test("rejects an object without viewBox or children", () => {
+    expect(iconSchema["executeAssert"](path, { children: [] }).success).toBe(
+      false,
+    );
+    expect(
+      iconSchema["executeAssert"](path, { viewBox: "0 0 1 1" }).success,
+    ).toBe(false);
+  });
+
+  test("accepts null when nullable", () => {
+    expect(iconSchema.nullable()["executeAssert"](path, null)).toStrictEqual({
+      success: true,
+      data: null,
+    });
+  });
+});
+
+describe("SvgSchema serialization", () => {
+  test("serializes its options", () => {
+    expect(iconSchema["executeSerialize"]()).toStrictEqual({
+      type: "svg",
+      opt: false,
+      options: {
+        width: 24,
+        height: 24,
+        variables: { brand: "#0055ff", line: "currentColor" },
+      },
+      customValidate: false,
+      readonly: false,
+      hidden: false,
+      description: undefined,
+    });
+  });
+
+  test("round trips through deserializeSchema", () => {
+    const serialized = iconSchema["executeSerialize"]();
+    const deserialized = deserializeSchema(serialized);
+    expect(deserialized).toBeInstanceOf(SvgSchema);
+    expect(deserialized["executeSerialize"]()).toStrictEqual(serialized);
+    // and it still validates the same way
+    expect(deserialized["executeValidate"](path, icon)).toBe(false);
+  });
+
+  test("renders nothing special", () => {
+    expect(iconSchema["executeRender"]()).toStrictEqual({});
+  });
+});
+
+describe("SvgSchema builders", () => {
+  test("width / height / aspectRatio return new instances", () => {
+    const base = s.svg({ variables: {} });
+    const constrained = base.width(16).height(16).aspectRatio("1:1");
+    expect(constrained["executeSerialize"]()).toMatchObject({
+      options: { width: 16, height: 16, aspectRatio: "1:1" },
+    });
+    expect(base["executeSerialize"]()).toMatchObject({ options: {} });
+  });
+
+  test("describe / readonly / hidden are serialized", () => {
+    expect(
+      iconSchema.describe("An icon").readonly().hidden()["executeSerialize"](),
+    ).toMatchObject({
+      description: "An icon",
+      readonly: true,
+      hidden: true,
+    });
+  });
+
+  test("custom validate functions run", () => {
+    const schema = s
+      .svg({ variables: {} })
+      .validate((src) => (src.children.length === 0 ? "Icon is empty" : false));
+    const errors = schema["executeValidate"](path, {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [],
+    });
+    expect(errors).toStrictEqual({
+      [path]: [{ message: "Icon is empty", value: expect.anything() }],
+    });
+  });
+});
+
+describe("svgVarsCss", () => {
+  test("emits the declared example colors", () => {
+    expect(svgVarsCss(iconSchema)).toBe(
+      ":root{--val-svg-brand:#0055ff;--val-svg-line:currentColor}",
+    );
+  });
+
+  test("accepts a custom selector, for dark mode blocks", () => {
+    expect(
+      svgVarsCss(
+        s.svg({ variables: { brand: "#6699ff" } }),
+        '[data-theme="dark"]',
+      ),
+    ).toBe('[data-theme="dark"]{--val-svg-brand:#6699ff}');
+  });
+
+  test("is empty when there are no variables", () => {
+    expect(svgVarsCss(s.svg())).toBe("");
+  });
+});
diff --git a/packages/core/src/schema/svg.ts b/packages/core/src/schema/svg.ts
new file mode 100644
index 000000000..d061a7881
--- /dev/null
+++ b/packages/core/src/schema/svg.ts
@@ -0,0 +1,738 @@
+import {
+  CustomValidateFunction,
+  Schema,
+  SchemaAssertResult,
+  SerializedSchema,
+} from ".";
+import { ReifiedRender } from "../render";
+import {
+  SvgOptions,
+  SvgSource,
+  SvgTag,
+  SvgVariable,
+  SVG_VAL_PATH,
+  isSvgVarRef,
+  svgVariableValue,
+} from "../source/svg";
+import { SourcePath } from "../val";
+import {
+  ValidationError,
+  ValidationErrors,
+} from "./validation/ValidationError";
+import {
+  SVG_ASPECT_RATIO_EPSILON,
+  SVG_DEFAULT_MAX_DEPTH,
+  SVG_DEFAULT_MAX_NODES,
+  SVG_ATTR_NAME_PATTERN,
+  SVG_COLOR_ATTRS,
+  SVG_ENUM_ATTRS,
+  SVG_KEYWORD_COLORS,
+  SVG_NUMBER_ATTRS,
+  SVG_STRING_ATTRS,
+  isAllowedSvgAttr,
+  isSvgTag,
+  parseSvgViewBox,
+} from "./svg/allowlist";
+import { unsafeCreateSourcePath } from "../selector/SelectorProxy";
+
+export type SerializedSvgSchema = {
+  type: "svg";
+  options?: SvgOptions;
+  opt: boolean;
+  customValidate?: boolean;
+  readonly?: boolean;
+  hidden?: boolean;
+  description?: string;
+};
+
+type SizeConstraint = number | { min?: number; max?: number };
+
+function checkSize(
+  actual: number,
+  constraint: SizeConstraint | undefined,
+): string | null {
+  if (constraint === undefined) {
+    return null;
+  }
+  if (typeof constraint === "number") {
+    return actual === constraint
+      ? null
+      : `Expected ${constraint}, got ${actual}`;
+  }
+  if (constraint.min !== undefined && actual < constraint.min) {
+    return `Expected at least ${constraint.min}, got ${actual}`;
+  }
+  if (constraint.max !== undefined && actual > constraint.max) {
+    return `Expected at most ${constraint.max}, got ${actual}`;
+  }
+  return null;
+}
+
+function parseAspectRatio(
+  aspectRatio: number | `${number}:${number}`,
+): number | null {
+  if (typeof aspectRatio === "number") {
+    return Number.isFinite(aspectRatio) && aspectRatio > 0 ? aspectRatio : null;
+  }
+  const parts = aspectRatio.split(":");
+  if (parts.length !== 2) {
+    return null;
+  }
+  const w = Number(parts[0]);
+  const h = Number(parts[1]);
+  if (!Number.isFinite(w) || !Number.isFinite(h) || h === 0 || w <= 0) {
+    return null;
+  }
+  return w / h;
+}
+
+/**
+ * Builds the CSS custom properties that back an svg schema's color variables.
+ *
+ * `ValSvg` renders `fill="var(--val-svg-<name>, currentColor)"`, so an app emits
+ * this once - typically a `<style>` in the root layout - to make the schema's
+ * example colors the ones that actually render. Overriding a variable in a
+ * media query or a `[data-theme]` block is then all dark mode requires.
+ *
+ * @example
+ * svgVarsCss(iconSchema)
+ * // ":root{--val-svg-brand:#0055ff;--val-svg-line:currentColor}"
+ */
+export function svgVarsCss(
+  schema:
+    | SerializedSvgSchema
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    | SvgSchema<any, any>
+    | SvgOptions,
+  selector: string = ":root",
+): string {
+  const variables =
+    schema instanceof SvgSchema
+      ? // Bracket access: options is private, and this helper is the supported
+        // way to read it. Same pattern as richtext / record use internally.
+        schema["options"]?.variables
+      : "type" in schema && schema.type === "svg"
+        ? schema.options?.variables
+        : (schema as SvgOptions).variables;
+  if (!variables) {
+    return "";
+  }
+  const declarations = Object.entries(variables)
+    .map(
+      ([name, variable]) =>
+        `--val-svg-${name}:${svgVariableValue(variable as SvgVariable)}`,
+    )
+    .join(";");
+  if (!declarations) {
+    return "";
+  }
+  return `${selector}{${declarations}}`;
+}
+
+export class SvgSchema<
+  O extends SvgOptions,
+  Src extends SvgSource<O> | null,
+> extends Schema<Src> {
+  constructor(
+    private readonly options: O,
+    private readonly opt: boolean = false,
+    private readonly customValidateFunctions: CustomValidateFunction<Src>[] = [],
+    private readonly isReadonly: boolean = false,
+    private readonly isHidden: boolean = false,
+    private readonly description?: string,
+  ) {
+    super();
+  }
+
+  private copy(
+    overrides: Partial<{
+      options: O;
+      opt: boolean;
+      customValidateFunctions: CustomValidateFunction<Src>[];
+      isReadonly: boolean;
+      isHidden: boolean;
+      description: string | undefined;
+    }> = {},
+  ): SvgSchema<O, Src> {
+    return new SvgSchema<O, Src>(
+      overrides.options ?? this.options,
+      overrides.opt ?? this.opt,
+      overrides.customValidateFunctions ?? this.customValidateFunctions,
+      overrides.isReadonly ?? this.isReadonly,
+      overrides.isHidden ?? this.isHidden,
+      "description" in overrides ? overrides.description : this.description,
+    );
+  }
+
+  describe(description: string | null): SvgSchema<O, Src> {
+    return this.copy({ description: description ?? undefined });
+  }
+
+  validate(
+    validationFunction: (src: Src) => false | string,
+  ): SvgSchema<O, Src> {
+    return this.copy({
+      customValidateFunctions: [
+        ...this.customValidateFunctions,
+        validationFunction,
+      ],
+    });
+  }
+
+  /** Require an exact intrinsic width, or a range. Constrains the viewBox. */
+  width(width: SizeConstraint): SvgSchema<O, Src> {
+    return this.copy({ options: { ...this.options, width } });
+  }
+
+  /** Require an exact intrinsic height, or a range. Constrains the viewBox. */
+  height(height: SizeConstraint): SvgSchema<O, Src> {
+    return this.copy({ options: { ...this.options, height } });
+  }
+
+  /** Require a viewBox aspect ratio, as a number or `"w:h"`. */
+  aspectRatio(aspectRatio: number | `${number}:${number}`): SvgSchema<O, Src> {
+    return this.copy({ options: { ...this.options, aspectRatio } });
+  }
+
+  protected override executeCustomValidateAt(
+    path: SourcePath,
+    src: Src,
+  ): ValidationError[] {
+    return this.executeCustomValidateFunctions(
+      src,
+      this.customValidateFunctions,
+      { path },
+    );
+  }
+
+  protected executeValidate(path: SourcePath, src: Src): ValidationErrors {
+    const customValidationErrors: ValidationError[] =
+      this.executeCustomValidateFunctions(src, this.customValidateFunctions, {
+        path,
+      });
+    if (this.opt && (src === null || src === undefined)) {
+      return customValidationErrors.length > 0
+        ? ({ [path]: customValidationErrors } as ValidationErrors)
+        : false;
+    }
+    let errors: ValidationErrors = false;
+    if (customValidationErrors.length > 0) {
+      errors = { [path]: customValidationErrors } as ValidationErrors;
+    }
+    if (src === null || src === undefined) {
+      return this.appendValidationError(
+        errors,
+        path,
+        "Expected 'object', got 'null'",
+        src,
+      );
+    }
+    if (typeof src !== "object" || Array.isArray(src)) {
+      return this.appendValidationError(
+        errors,
+        path,
+        `Expected 'object', got '${Array.isArray(src) ? "array" : typeof src}'`,
+        src,
+      );
+    }
+    errors = this.validateGeometry(path, src, errors);
+    if (!Array.isArray(src.children)) {
+      return this.appendValidationError(
+        errors,
+        unsafeCreateSourcePath(path, "children"),
+        `Expected 'array' of svg nodes, got '${typeof src.children}'`,
+        src.children,
+      );
+    }
+    const counters = {
+      nodes: 0,
+      maxNodes: this.options.maxNodes ?? SVG_DEFAULT_MAX_NODES,
+      maxDepth: this.options.maxDepth ?? SVG_DEFAULT_MAX_DEPTH,
+      exceeded: false,
+    };
+    errors = this.validateNodes(
+      unsafeCreateSourcePath(path, "children"),
+      src.children,
+      1,
+      counters,
+      errors,
+    );
+    if (counters.exceeded) {
+      errors = this.appendValidationError(
+        errors,
+        path,
+        `Svg has too many nodes: max is ${counters.maxNodes}`,
+        undefined,
+      );
+    }
+    return errors;
+  }
+
+  private validateGeometry(
+    path: SourcePath,
+    src: SvgSource<O>,
+    errors: ValidationErrors,
+  ): ValidationErrors {
+    if (typeof src.viewBox !== "string") {
+      return this.appendValidationError(
+        errors,
+        unsafeCreateSourcePath(path, "viewBox"),
+        `Expected 'string', got '${typeof src.viewBox}'`,
+        src.viewBox,
+      );
+    }
+    const viewBox = parseSvgViewBox(src.viewBox);
+    if (!viewBox) {
+      return this.appendValidationError(
+        errors,
+        unsafeCreateSourcePath(path, "viewBox"),
+        `Invalid viewBox: expected 4 numbers ('min-x min-y width height') with a non-negative width and height, got '${src.viewBox}'`,
+        src.viewBox,
+      );
+    }
+    const widthError = checkSize(viewBox.width, this.options.width);
+    if (widthError) {
+      errors = this.appendValidationError(
+        errors,
+        unsafeCreateSourcePath(path, "viewBox"),
+        `Invalid viewBox width. ${widthError}`,
+        src.viewBox,
+      );
+    }
+    const heightError = checkSize(viewBox.height, this.options.height);
+    if (heightError) {
+      errors = this.appendValidationError(
+        errors,
+        unsafeCreateSourcePath(path, "viewBox"),
+        `Invalid viewBox height. ${heightError}`,
+        src.viewBox,
+      );
+    }
+    if (this.options.aspectRatio !== undefined) {
+      const expected = parseAspectRatio(this.options.aspectRatio);
+      if (expected === null) {
+        errors = this.appendValidationError(
+          errors,
+          path,
+          `Invalid aspectRatio in schema: '${this.options.aspectRatio}'`,
+          src.viewBox,
+          true,
+        );
+      } else if (viewBox.height === 0) {
+        errors = this.appendValidationError(
+          errors,
+          unsafeCreateSourcePath(path, "viewBox"),
+          "Cannot check aspect ratio: viewBox height is 0",
+          src.viewBox,
+        );
+      } else {
+        const actual = viewBox.width / viewBox.height;
+        if (Math.abs(actual - expected) > SVG_ASPECT_RATIO_EPSILON) {
+          errors = this.appendValidationError(
+            errors,
+            unsafeCreateSourcePath(path, "viewBox"),
+            `Invalid aspect ratio: expected ${this.options.aspectRatio}, got ${viewBox.width}:${viewBox.height}`,
+            src.viewBox,
+          );
+        }
+      }
+    }
+    for (const key of ["width", "height"] as const) {
+      const value = src[key];
+      if (value === null || value === undefined) {
+        continue;
+      }
+      if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        errors = this.appendValidationError(
+          errors,
+          unsafeCreateSourcePath(path, key),
+          `Expected a non-negative number or null, got '${JSON.stringify(value)}'`,
+          value,
+        );
+        continue;
+      }
+      const error = checkSize(value, this.options[key]);
+      if (error) {
+        errors = this.appendValidationError(
+          errors,
+          unsafeCreateSourcePath(path, key),
+          `Invalid ${key}. ${error}`,
+          value,
+        );
+      }
+    }
+    return errors;
+  }
+
+  private validateNodes(
+    path: SourcePath,
+    nodes: unknown[],
+    depth: number,
+    counters: {
+      nodes: number;
+      maxNodes: number;
+      maxDepth: number;
+      exceeded: boolean;
+    },
+    errors: ValidationErrors,
+  ): ValidationErrors {
+    for (let i = 0; i < nodes.length; i++) {
+      const nodePath = unsafeCreateSourcePath(path, i);
+      counters.nodes++;
+      if (counters.nodes > counters.maxNodes) {
+        counters.exceeded = true;
+        return errors;
+      }
+      errors = this.validateNode(nodePath, nodes[i], depth, counters, errors);
+    }
+    return errors;
+  }
+
+  private validateNode(
+    path: SourcePath,
+    node: unknown,
+    depth: number,
+    counters: {
+      nodes: number;
+      maxNodes: number;
+      maxDepth: number;
+      exceeded: boolean;
+    },
+    errors: ValidationErrors,
+  ): ValidationErrors {
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+      return this.appendValidationError(
+        errors,
+        path,
+        `Expected an svg node object, got '${node === null ? "null" : Array.isArray(node) ? "array" : typeof node}'`,
+        node,
+      );
+    }
+    if (depth > counters.maxDepth) {
+      return this.appendValidationError(
+        errors,
+        path,
+        `Svg is nested too deeply: max depth is ${counters.maxDepth}`,
+        undefined,
+      );
+    }
+    const candidate = node as {
+      tag?: unknown;
+      attrs?: unknown;
+      children?: unknown;
+    };
+    if (typeof candidate.tag !== "string") {
+      return this.appendValidationError(
+        errors,
+        unsafeCreateSourcePath(path, "tag"),
+        `Expected 'string', got '${typeof candidate.tag}'`,
+        candidate.tag,
+      );
+    }
+    if (!isSvgTag(candidate.tag)) {
+      return this.appendValidationError(
+        errors,
+        unsafeCreateSourcePath(path, "tag"),
+        `Tag '${candidate.tag}' is not supported`,
+        candidate.tag,
+      );
+    }
+    const tag: SvgTag = candidate.tag;
+    errors = this.validateAttrs(
+      unsafeCreateSourcePath(path, "attrs"),
+      tag,
+      candidate.attrs,
+      errors,
+    );
+    if (candidate.children === undefined) {
+      return errors;
+    }
+    if (!Array.isArray(candidate.children)) {
+      return this.appendValidationError(
+        errors,
+        unsafeCreateSourcePath(path, "children"),
+        `Expected 'array' of svg nodes, got '${typeof candidate.children}'`,
+        candidate.children,
+      );
+    }
+    return this.validateNodes(
+      unsafeCreateSourcePath(path, "children"),
+      candidate.children,
+      depth + 1,
+      counters,
+      errors,
+    );
+  }
+
+  private validateAttrs(
+    path: SourcePath,
+    tag: SvgTag,
+    attrs: unknown,
+    errors: ValidationErrors,
+  ): ValidationErrors {
+    if (attrs === undefined) {
+      return errors;
+    }
+    if (typeof attrs !== "object" || attrs === null || Array.isArray(attrs)) {
+      return this.appendValidationError(
+        errors,
+        path,
+        `Expected 'object' of attributes, got '${Array.isArray(attrs) ? "array" : typeof attrs}'`,
+        attrs,
+      );
+    }
+    for (const [name, value] of Object.entries(attrs)) {
+      const attrPath = unsafeCreateSourcePath(path, name);
+      if (!SVG_ATTR_NAME_PATTERN.test(name)) {
+        errors = this.appendValidationError(
+          errors,
+          attrPath,
+          `Invalid attribute name: '${name}'`,
+          value,
+        );
+        continue;
+      }
+      if (!isAllowedSvgAttr(tag, name)) {
+        errors = this.appendValidationError(
+          errors,
+          attrPath,
+          `Attribute '${name}' is not supported on '${tag}'`,
+          value,
+        );
+        continue;
+      }
+      errors = this.validateAttrValue(attrPath, name, value, errors);
+    }
+    return errors;
+  }
+
+  private validateAttrValue(
+    path: SourcePath,
+    name: string,
+    value: unknown,
+    errors: ValidationErrors,
+  ): ValidationErrors {
+    if ((SVG_COLOR_ATTRS as readonly string[]).includes(name)) {
+      return this.validateColor(path, name, value, errors);
+    }
+    if ((SVG_NUMBER_ATTRS as readonly string[]).includes(name)) {
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        return this.appendValidationError(
+          errors,
+          path,
+          `Expected a finite 'number' for '${name}', got '${typeof value}'`,
+          value,
+        );
+      }
+      return errors;
+    }
+    if (name in SVG_ENUM_ATTRS) {
+      const allowed = SVG_ENUM_ATTRS[name as keyof typeof SVG_ENUM_ATTRS];
+      if (
+        typeof value !== "string" ||
+        !(allowed as readonly string[]).includes(value)
+      ) {
+        return this.appendValidationError(
+          errors,
+          path,
+          `Invalid '${name}': expected one of ${(allowed as readonly string[]).map((v) => `'${v}'`).join(", ")}, got '${JSON.stringify(value)}'`,
+          value,
+        );
+      }
+      return errors;
+    }
+    if (name in SVG_STRING_ATTRS) {
+      const { pattern, maxLength } =
+        SVG_STRING_ATTRS[name as keyof typeof SVG_STRING_ATTRS];
+      if (typeof value !== "string") {
+        return this.appendValidationError(
+          errors,
+          path,
+          `Expected 'string' for '${name}', got '${typeof value}'`,
+          value,
+        );
+      }
+      if (value.length > maxLength) {
+        return this.appendValidationError(
+          errors,
+          path,
+          `'${name}' is too long: max is ${maxLength} characters, got ${value.length}`,
+          value,
+        );
+      }
+      if (!pattern.test(value)) {
+        return this.appendValidationError(
+          errors,
+          path,
+          `Invalid '${name}': contains unsupported characters`,
+          value,
+        );
+      }
+      return errors;
+    }
+    return this.appendValidationError(
+      errors,
+      path,
+      `Attribute '${name}' is not supported`,
+      value,
+    );
+  }
+
+  private validateColor(
+    path: SourcePath,
+    name: string,
+    value: unknown,
+    errors: ValidationErrors,
+  ): ValidationErrors {
+    if (isSvgVarRef(value)) {
+      const variables = this.options.variables ?? {};
+      if (!(value.var in variables)) {
+        const declared = Object.keys(variables);
+        return this.appendValidationError(
+          errors,
+          path,
+          declared.length > 0
+            ? `Unknown color variable '${value.var}'. Declared variables: ${declared.join(", ")}`
+            : `Unknown color variable '${value.var}'. This schema declares no variables`,
+          value,
+        );
+      }
+      return errors;
+    }
+    if (typeof value !== "string") {
+      return this.appendValidationError(
+        errors,
+        path,
+        `Expected a color variable ({ var: ... }) or a color string for '${name}', got '${typeof value}'`,
+        value,
+      );
+    }
+    if (SVG_KEYWORD_COLORS.includes(value)) {
+      return errors;
+    }
+    const literals = this.options.literals ?? "forbid";
+    if (literals === "allow") {
+      return errors;
+    }
+    const declared = Object.keys(this.options.variables ?? {});
+    if (literals === "forbid") {
+      return this.appendValidationError(
+        errors,
+        path,
+        declared.length > 0
+          ? `Raw color '${value}' is not allowed. Use one of the declared variables: ${declared.join(", ")}`
+          : `Raw color '${value}' is not allowed. Declare a color variable, or set literals to allow raw colors`,
+        value,
+      );
+    }
+    if (!literals.includes(value)) {
+      return this.appendValidationError(
+        errors,
+        path,
+        `Raw color '${value}' is not allowed. Allowed raw colors: ${literals.join(", ")}`,
+        value,
+      );
+    }
+    return errors;
+  }
+
+  protected executeAssert(
+    path: SourcePath,
+    src: unknown,
+  ): SchemaAssertResult<Src> {
+    if (this.opt && src === null) {
+      return { success: true, data: src } as SchemaAssertResult<Src>;
+    }
+    if (src === null) {
+      return {
+        success: false,
+        errors: {
+          [path]: [
+            { message: "Expected 'object', got 'null'", typeError: true },
+          ],
+        },
+      };
+    }
+    if (typeof src !== "object" || Array.isArray(src)) {
+      return {
+        success: false,
+        errors: {
+          [path]: [
+            {
+              message: `Expected 'object', got '${Array.isArray(src) ? "array" : typeof src}'`,
+              typeError: true,
+            },
+          ],
+        },
+      };
+    }
+    if (!("viewBox" in src) || typeof src.viewBox !== "string") {
+      return {
+        success: false,
+        errors: {
+          [path]: [
+            { message: "Expected an svg with a 'viewBox'", typeError: true },
+          ],
+        },
+      };
+    }
+    if (!("children" in src) || !Array.isArray(src.children)) {
+      return {
+        success: false,
+        errors: {
+          [path]: [
+            {
+              message: "Expected an svg with an array of 'children'",
+              typeError: true,
+            },
+          ],
+        },
+      };
+    }
+    return { success: true, data: src } as SchemaAssertResult<Src>;
+  }
+
+  nullable(): SvgSchema<O, Src | null> {
+    return new SvgSchema<O, Src | null>(
+      this.options,
+      true,
+      [],
+      this.isReadonly,
+      this.isHidden,
+      this.description,
+    );
+  }
+
+  readonly(): SvgSchema<O, Src> {
+    return this.copy({ isReadonly: true });
+  }
+
+  hidden(): SvgSchema<O, Src> {
+    return this.copy({ isHidden: true });
+  }
+
+  protected executeSerialize(): SerializedSchema {
+    return {
+      type: "svg",
+      options: this.options,
+      opt: this.opt,
+      customValidate:
+        this.customValidateFunctions && this.customValidateFunctions.length > 0,
+      readonly: this.isReadonly,
+      hidden: this.isHidden,
+      description: this.description,
+    };
+  }
+
+  protected executeRender(): ReifiedRender {
+    return {};
+  }
+}
+
+export const svg = <O extends SvgOptions>(
+  options?: O,
+): SvgSchema<O, SvgSource<O>> => {
+  return new SvgSchema<O, SvgSource<O>>((options ?? {}) as O);
+};
+
+export { SVG_VAL_PATH };
diff --git a/packages/core/src/schema/svg/allowlist.ts b/packages/core/src/schema/svg/allowlist.ts
new file mode 100644
index 000000000..5320f0127
--- /dev/null
+++ b/packages/core/src/schema/svg/allowlist.ts
@@ -0,0 +1,160 @@
+import {
+  SvgColorAttr,
+  SvgEnumAttr,
+  SvgEnumAttrs,
+  SvgNumberAttr,
+  SvgStringAttr,
+  SvgTag,
+} from "../../source/svg";
+
+/**
+ * The svg subset Val stores and renders.
+ *
+ * `ValSvg` builds React elements from this tree instead of using
+ * `dangerouslySetInnerHTML`, so this allowlist is the *entire* security
+ * boundary. React renders unknown attributes on host elements verbatim -
+ * `createElement("circle", { onload: "alert(1)" })` really does emit
+ * `onload="alert(1)"`, and `onload` fires on svg elements - so this must be a
+ * strict allowlist of exact attribute names per tag, never an `on*` denylist.
+ */
+
+export const SVG_TAGS: readonly SvgTag[] = [
+  "g",
+  "path",
+  "circle",
+  "ellipse",
+  "rect",
+  "line",
+  "polyline",
+  "polygon",
+];
+
+export const SVG_COLOR_ATTRS: readonly SvgColorAttr[] = ["fill", "stroke"];
+
+/** Attributes allowed on every tag. */
+export const SVG_COMMON_ATTRS: readonly string[] = [
+  "fill",
+  "stroke",
+  "fill-opacity",
+  "stroke-opacity",
+  "opacity",
+  "stroke-width",
+  "stroke-dashoffset",
+  "stroke-miterlimit",
+  "stroke-dasharray",
+  "stroke-linecap",
+  "stroke-linejoin",
+  "fill-rule",
+  "clip-rule",
+  "vector-effect",
+  "transform",
+];
+
+/** Geometry attributes, allowed only on the tag that owns them. */
+export const SVG_TAG_ATTRS: Readonly<Record<SvgTag, readonly string[]>> = {
+  g: [],
+  path: ["d"],
+  circle: ["cx", "cy", "r"],
+  ellipse: ["cx", "cy", "rx", "ry"],
+  rect: ["x", "y", "width", "height", "rx", "ry"],
+  line: ["x1", "y1", "x2", "y2"],
+  polyline: ["points"],
+  polygon: ["points"],
+};
+
+export const SVG_NUMBER_ATTRS: readonly SvgNumberAttr[] = [
+  "cx",
+  "cy",
+  "r",
+  "rx",
+  "ry",
+  "x",
+  "y",
+  "width",
+  "height",
+  "x1",
+  "y1",
+  "x2",
+  "y2",
+  "opacity",
+  "fill-opacity",
+  "stroke-opacity",
+  "stroke-width",
+  "stroke-dashoffset",
+  "stroke-miterlimit",
+];
+
+export const SVG_ENUM_ATTRS: Readonly<{
+  [K in SvgEnumAttr]: readonly SvgEnumAttrs[K][];
+}> = {
+  "stroke-linecap": ["butt", "round", "square"],
+  "stroke-linejoin": ["miter", "round", "bevel"],
+  "fill-rule": ["nonzero", "evenodd"],
+  "clip-rule": ["nonzero", "evenodd"],
+  "vector-effect": ["non-scaling-stroke"],
+};
+
+/**
+ * The only free-form strings in the format. Each is both regex constrained and
+ * length capped, so there is no unbounded attacker controlled string anywhere.
+ */
+export const SVG_STRING_ATTRS: Readonly<
+  Record<SvgStringAttr, { pattern: RegExp; maxLength: number }>
+> = {
+  d: {
+    pattern: /^[MmLlHhVvCcSsQqTtAaZz0-9\s,.\-+eE]*$/,
+    maxLength: 100_000,
+  },
+  points: { pattern: /^[\d.\s,\-+eE]*$/, maxLength: 50_000 },
+  transform: { pattern: /^[a-z0-9\s(),.\-+eE]*$/i, maxLength: 512 },
+  "stroke-dasharray": { pattern: /^[\d.\s,]*$/, maxLength: 512 },
+};
+
+/** Colors that are allowed whatever the schema's `literals` option is. */
+export const SVG_KEYWORD_COLORS: readonly string[] = [
+  "currentColor",
+  "none",
+  "transparent",
+];
+
+/**
+ * Attribute names must look like plain svg attributes before they are handed to
+ * `createElement`. This also blocks `__proto__` / `constructor` keys smuggled in
+ * through `JSON.parse`.
+ */
+export const SVG_ATTR_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+export const SVG_VIEW_BOX_PATTERN = /^-?\d+(\.\d+)?( -?\d+(\.\d+)?){3}$/;
+
+export const SVG_DEFAULT_MAX_NODES = 2000;
+export const SVG_DEFAULT_MAX_DEPTH = 32;
+
+/**
+ * Tolerance used when comparing aspect ratios, so that a viewBox with rounded
+ * float dimensions is not rejected.
+ */
+export const SVG_ASPECT_RATIO_EPSILON = 1e-4;
+
+export function isSvgTag(tag: string): tag is SvgTag {
+  return (SVG_TAGS as readonly string[]).includes(tag);
+}
+
+export function isAllowedSvgAttr(tag: SvgTag, attr: string): boolean {
+  return SVG_COMMON_ATTRS.includes(attr) || SVG_TAG_ATTRS[tag].includes(attr);
+}
+
+export function parseSvgViewBox(
+  viewBox: string,
+): { minX: number; minY: number; width: number; height: number } | null {
+  if (!SVG_VIEW_BOX_PATTERN.test(viewBox)) {
+    return null;
+  }
+  const [minX, minY, width, height] = viewBox.split(" ").map(Number);
+  if (![minX, minY, width, height].every((n) => Number.isFinite(n))) {
+    return null;
+  }
+  if (width < 0 || height < 0) {
+    return null;
+  }
+  return { minX, minY, width, height };
+}
diff --git a/packages/core/src/schema/validation.test.ts b/packages/core/src/schema/validation.test.ts
index e8bd43dab..19d3f9644 100644
--- a/packages/core/src/schema/validation.test.ts
+++ b/packages/core/src/schema/validation.test.ts
@@ -20,6 +20,7 @@ import { define } from "../module";
 import { union } from "./union";
 import { createValPathOfItem } from "../selector/SelectorProxy";
 import { date } from "./date";
+import { svg } from "./svg";
 import { initFile } from "../source/file";
 
 const fileVal = initFile();
@@ -27,6 +28,10 @@ const testPath = "/test" as SourcePath;
 const pathOf = (p: string | symbol | number) => {
   return createValPathOfItem(testPath, p);
 };
+/** testPath with a sub-path appended, keeping the SourcePath brand. */
+const subPathOf = (p: string | symbol | number, rest: string) => {
+  return (createValPathOfItem(testPath, p) + rest) as SourcePath;
+};
 const ValidationTestCases: {
   description: string;
   input: any;
@@ -467,6 +472,250 @@ const ValidationTestCases: {
     expected: [testPath],
   },
 
+  // svg
+  {
+    description: "basic svg",
+    input: {
+      viewBox: "0 0 24 24",
+      width: 24,
+      height: 24,
+      children: [
+        {
+          tag: "path",
+          attrs: { d: "M4 12h16", stroke: { var: "line" }, fill: "none" },
+          children: [],
+        },
+      ],
+    },
+    schema: svg({ variables: { brand: "#0055ff", line: "currentColor" } }),
+    expected: false,
+  },
+  {
+    description: "svg with an unsupported tag",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [{ tag: "script", attrs: {}, children: [] }],
+    },
+    schema: svg(),
+    expected: [subPathOf("children", ".0." + '"tag"')],
+  },
+  {
+    description: "svg with an event handler attribute",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [
+        { tag: "circle", attrs: { onload: "alert(1)" }, children: [] },
+      ],
+    },
+    schema: svg(),
+    expected: [subPathOf("children", ".0." + '"attrs"."onload"')],
+  },
+  {
+    description: "svg with an attribute that is not valid on that tag",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [{ tag: "circle", attrs: { d: "M0 0" }, children: [] }],
+    },
+    schema: svg(),
+    expected: [subPathOf("children", ".0." + '"attrs"."d"')],
+  },
+  {
+    description: "svg with a raw color, literals forbidden (default)",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [{ tag: "circle", attrs: { fill: "#ff0000" }, children: [] }],
+    },
+    schema: svg({ variables: { brand: "#0055ff" } }),
+    expected: [subPathOf("children", ".0." + '"attrs"."fill"')],
+  },
+  {
+    description: "svg with a raw color that is in the literals allowlist",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [{ tag: "circle", attrs: { fill: "#000000" }, children: [] }],
+    },
+    schema: svg({ variables: {}, literals: ["#000000"] }),
+    expected: false,
+  },
+  {
+    description: "svg with a raw color that is not in the literals allowlist",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [{ tag: "circle", attrs: { fill: "#ff0000" }, children: [] }],
+    },
+    schema: svg({ variables: {}, literals: ["#000000"] }),
+    expected: [subPathOf("children", ".0." + '"attrs"."fill"')],
+  },
+  {
+    description: "svg with any raw color, literals allowed",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [{ tag: "circle", attrs: { fill: "#ff0000" }, children: [] }],
+    },
+    schema: svg({ variables: {}, literals: "allow" }),
+    expected: false,
+  },
+  {
+    description: "svg referencing a variable that is not declared",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [
+        { tag: "circle", attrs: { fill: { var: "nope" } }, children: [] },
+      ],
+    },
+    schema: svg({ variables: { brand: "#0055ff" } }),
+    expected: [subPathOf("children", ".0." + '"attrs"."fill"')],
+  },
+  {
+    description: "svg with the always allowed color keywords",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [
+        {
+          tag: "circle",
+          attrs: { fill: "none", stroke: "currentColor" },
+          children: [],
+        },
+      ],
+    },
+    schema: svg(),
+    expected: false,
+  },
+  {
+    description: "svg with a malformed viewBox",
+    input: {
+      viewBox: "0 0 24",
+      width: null,
+      height: null,
+      children: [],
+    },
+    schema: svg(),
+    expected: [pathOf("viewBox")],
+  },
+  {
+    description: "svg with a viewBox that violates an exact width",
+    input: {
+      viewBox: "0 0 32 24",
+      width: null,
+      height: null,
+      children: [],
+    },
+    schema: svg({ width: 24 }),
+    expected: [pathOf("viewBox")],
+  },
+  {
+    description: "svg with a viewBox outside a min / max range",
+    input: {
+      viewBox: "0 0 128 128",
+      width: null,
+      height: null,
+      children: [],
+    },
+    schema: svg({ width: { min: 16, max: 64 } }),
+    expected: [pathOf("viewBox")],
+  },
+  {
+    description: "svg with the wrong aspect ratio",
+    input: {
+      viewBox: "0 0 32 24",
+      width: null,
+      height: null,
+      children: [],
+    },
+    schema: svg({ aspectRatio: "1:1" }),
+    expected: [pathOf("viewBox")],
+  },
+  {
+    description: "svg with a float viewBox that is within the ratio epsilon",
+    input: {
+      viewBox: "0 0 23.99999 24",
+      width: null,
+      height: null,
+      children: [],
+    },
+    schema: svg({ aspectRatio: 1 }),
+    expected: false,
+  },
+  {
+    description: "svg where width contradicts a satisfied viewBox",
+    input: {
+      viewBox: "0 0 24 24",
+      width: 100,
+      height: 24,
+      children: [],
+    },
+    schema: svg({ width: 24 }),
+    expected: [pathOf("width")],
+  },
+  {
+    description: "svg with too many nodes",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [
+        { tag: "circle", attrs: {}, children: [] },
+        { tag: "circle", attrs: {}, children: [] },
+        { tag: "circle", attrs: {}, children: [] },
+      ],
+    },
+    schema: svg({ maxNodes: 2 }),
+    expected: [testPath],
+  },
+  {
+    description: "svg nested too deeply",
+    input: {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [
+        {
+          tag: "g",
+          attrs: {},
+          children: [
+            {
+              tag: "g",
+              attrs: {},
+              children: [{ tag: "g", attrs: {}, children: [] }],
+            },
+          ],
+        },
+      ],
+    },
+    schema: svg({ maxDepth: 2 }),
+    expected: [subPathOf("children", ".0." + '"children".0."children".0')],
+  },
+  {
+    description: "svg is null",
+    input: null,
+    schema: svg(),
+    expected: [testPath],
+  },
+  {
+    description: "nullable svg is null",
+    input: null,
+    schema: svg().nullable(),
+    expected: false,
+  },
+
   // TODO: oneOf
   // TODO: i18n
 ];
diff --git a/packages/core/src/selector/index.ts b/packages/core/src/selector/index.ts
index 8519603ac..8e8ebc270 100644
--- a/packages/core/src/selector/index.ts
+++ b/packages/core/src/selector/index.ts
@@ -11,8 +11,10 @@ import { Schema } from "../schema";
 import type { A } from "ts-toolbelt";
 import { FileSource } from "../source/file";
 import { AllRichTextOptions, RichTextSource } from "../source/richtext";
+import { AllSvgOptions, SvgSource } from "../source/svg";
 import { ImageSelector } from "./image";
 import { RichTextSelector } from "./richtext";
+import { SvgSelector } from "./svg";
 import { ImageSource } from "../source/image";
 import { RemoteSource } from "../source/remote";
 import { JsonSource } from "../source/json";
@@ -27,19 +29,21 @@ export type Selector<T extends Source> = Source extends T
         ? GenericSelector<JsonSource>
         : T extends RichTextSource<infer O>
           ? RichTextSelector<O>
-          : T extends SourceObject
-            ? ObjectSelector<T>
-            : T extends SourceArray
-              ? ArraySelector<T>
-              : T extends string
-                ? StringSelector<T>
-                : T extends number
-                  ? NumberSelector<T>
-                  : T extends boolean
-                    ? BooleanSelector<T>
-                    : T extends null
-                      ? PrimitiveSelector<null>
-                      : never;
+          : T extends SvgSource<infer SO>
+            ? SvgSelector<SO>
+            : T extends SourceObject
+              ? ObjectSelector<T>
+              : T extends SourceArray
+                ? ArraySelector<T>
+                : T extends string
+                  ? StringSelector<T>
+                  : T extends number
+                    ? NumberSelector<T>
+                    : T extends boolean
+                      ? BooleanSelector<T>
+                      : T extends null
+                        ? PrimitiveSelector<null>
+                        : never;
 
 export type SelectorSource =
   | SourcePrimitive
@@ -53,6 +57,7 @@ export type SelectorSource =
   | RemoteSource
   | JsonSource
   | RichTextSource<AllRichTextOptions>
+  | SvgSource<AllSvgOptions>
   | GenericSelector<Source>;
 
 // Identity symbols are registered in the global Symbol registry so that
diff --git a/packages/core/src/selector/svg.ts b/packages/core/src/selector/svg.ts
new file mode 100644
index 000000000..320e0c8b9
--- /dev/null
+++ b/packages/core/src/selector/svg.ts
@@ -0,0 +1,6 @@
+import { SvgOptions, SvgSource } from "../source/svg";
+import { GenericSelector } from ".";
+
+// NOTE: as with RichText, we do not (yet) support selecting sub-nodes of an svg.
+// This exists so that every Source type has a corresponding Selector type.
+export type SvgSelector<O extends SvgOptions> = GenericSelector<SvgSource<O>>;
diff --git a/packages/core/src/source/index.ts b/packages/core/src/source/index.ts
index f8a4d0eb8..2a237343c 100644
--- a/packages/core/src/source/index.ts
+++ b/packages/core/src/source/index.ts
@@ -3,6 +3,7 @@ import { ImageSource } from "./image";
 import { JsonSource } from "./json";
 import { RemoteSource } from "./remote";
 import { RichTextOptions, RichTextSource } from "./richtext";
+import { AllSvgOptions, SvgSource } from "./svg";
 
 export type Source =
   | SourcePrimitive
@@ -12,7 +13,8 @@ export type Source =
   | FileSource
   | ImageSource
   | JsonSource
-  | RichTextSource<RichTextOptions>;
+  | RichTextSource<RichTextOptions>
+  | SvgSource<AllSvgOptions>;
 
 export type SourceObject = { [key in string]: Source } & {
   // TODO: update these restricted parameters:
diff --git a/packages/core/src/source/svg.ts b/packages/core/src/source/svg.ts
new file mode 100644
index 000000000..022da8fa2
--- /dev/null
+++ b/packages/core/src/source/svg.ts
@@ -0,0 +1,232 @@
+/**
+ * Key that carries the {@link SourcePath} of an svg module on a resolved
+ * {@link SvgSource}.
+ *
+ * Svg sources are deliberately excluded from stega encoding: every string in an
+ * svg (`d`, `viewBox`, `points`, ...) is machine parsed, so injecting invisible
+ * characters into them corrupts the icon. The path is therefore attached as an
+ * ordinary, serializable field instead, which `ValSvg` reads to emit
+ * `data-val-path`.
+ *
+ * It is injected by stega encoding only: it is never authored and never stored.
+ */
+export const SVG_VAL_PATH = "_valPath";
+
+/**
+ * A named color variable.
+ *
+ * The `value` is an *example*: it is what the editor previews, what
+ * `svgVarsCss` emits as the CSS custom property, and the color that literal
+ * fills / strokes are matched against when an svg is imported. The value that
+ * actually renders is resolved at runtime from `--val-svg-<name>`.
+ */
+export type SvgVariable =
+  | string
+  | {
+      /**
+       * Example color. May be any CSS color, or `currentColor`.
+       */
+      value: string;
+      /**
+       * Additional literal colors that also map onto this variable on import.
+       * Useful because exports from design tools drift (`#fff` vs `#ffffff` vs
+       * a rounded `#fefefe`).
+       */
+      match?: readonly string[];
+      /**
+       * Also match colors within this normalized RGB distance (0..1).
+       * `0` (the default) means exact matches only.
+       */
+      tolerance?: number;
+      description?: string;
+    };
+
+/**
+ * How permissive to be about a color that is not a variable.
+ *
+ * - `"forbid"` (default): a raw color is a validation error
+ * - `"allow"`: any raw color passes
+ * - `string[]`: only these exact raw colors pass
+ *
+ * `currentColor`, `none` and `transparent` are always allowed.
+ */
+export type SvgLiterals = "forbid" | "allow" | readonly string[];
+
+export type SvgSizeConstraint = number | { min?: number; max?: number };
+
+export type SvgOptions = {
+  variables?: Record<string, SvgVariable>;
+  literals?: SvgLiterals;
+  /** Exact intrinsic width, or a range. Constrains the viewBox width. */
+  width?: SvgSizeConstraint;
+  /** Exact intrinsic height, or a range. Constrains the viewBox height. */
+  height?: SvgSizeConstraint;
+  /**
+   * Constrain viewBox width / height. A number, or `"w:h"` (e.g. `"1:1"`).
+   * Compared with an epsilon so float viewBoxes are not rejected.
+   */
+  aspectRatio?: number | `${number}:${number}`;
+  /** Maximum number of nodes in the tree. Defaults to 2000. */
+  maxNodes?: number;
+  /** Maximum nesting depth. Defaults to 32. */
+  maxDepth?: number;
+};
+
+/**
+ * The widest instantiation of {@link SvgOptions}, used where the concrete
+ * options are not known (unions, `SelectorSource`).
+ */
+export type AllSvgOptions = {
+  variables: Record<string, SvgVariable>;
+  literals: "allow";
+  width?: SvgSizeConstraint;
+  height?: SvgSizeConstraint;
+  aspectRatio?: number | `${number}:${number}`;
+  maxNodes?: number;
+  maxDepth?: number;
+};
+
+export type SvgVariableName<O extends SvgOptions> = Extract<
+  keyof NonNullable<O["variables"]>,
+  string
+>;
+
+/** A reference to one of the schema's declared color variables. */
+export type SvgVarRef<O extends SvgOptions> = {
+  var: SvgVariableName<O>;
+};
+
+/** Colors that are always allowed, whatever `literals` is set to. */
+export type SvgKeywordColor = "currentColor" | "none" | "transparent";
+
+type LiteralColorOf<O extends SvgOptions> =
+  O["literals"] extends readonly string[]
+    ? O["literals"][number]
+    : O["literals"] extends "allow"
+      ? string
+      : never;
+
+/**
+ * The value of a color attribute (`fill` / `stroke`).
+ *
+ * With the default `literals: "forbid"` this is a variable reference or a
+ * keyword only, so a raw hex is a *type* error and not merely a validation
+ * error.
+ */
+export type SvgColorValue<O extends SvgOptions> =
+  | SvgVarRef<O>
+  | SvgKeywordColor
+  | LiteralColorOf<O>;
+
+export type SvgColorAttr = "fill" | "stroke";
+export type SvgNumberAttr =
+  | "cx"
+  | "cy"
+  | "r"
+  | "rx"
+  | "ry"
+  | "x"
+  | "y"
+  | "width"
+  | "height"
+  | "x1"
+  | "y1"
+  | "x2"
+  | "y2"
+  | "opacity"
+  | "fill-opacity"
+  | "stroke-opacity"
+  | "stroke-width"
+  | "stroke-dashoffset"
+  | "stroke-miterlimit";
+export type SvgStringAttr = "d" | "points" | "transform" | "stroke-dasharray";
+export type SvgEnumAttrs = {
+  "stroke-linecap": "butt" | "round" | "square";
+  "stroke-linejoin": "miter" | "round" | "bevel";
+  "fill-rule": "nonzero" | "evenodd";
+  "clip-rule": "nonzero" | "evenodd";
+  "vector-effect": "non-scaling-stroke";
+};
+export type SvgEnumAttr = keyof SvgEnumAttrs;
+
+/**
+ * The attributes an svg node may carry.
+ *
+ * This mapped type *is* the attribute allowlist at the type level; the runtime
+ * table in `schema/svg/allowlist` mirrors it per tag.
+ */
+export type SvgAttrs<O extends SvgOptions> = {
+  [K in SvgColorAttr]?: SvgColorValue<O>;
+} & {
+  [K in SvgNumberAttr]?: number;
+} & {
+  [K in SvgStringAttr]?: string;
+} & {
+  [K in SvgEnumAttr]?: SvgEnumAttrs[K];
+};
+
+export type SvgTag =
+  | "g"
+  | "path"
+  | "circle"
+  | "ellipse"
+  | "rect"
+  | "line"
+  | "polyline"
+  | "polygon";
+
+export type SvgNode<O extends SvgOptions> = {
+  tag: SvgTag;
+  attrs: SvgAttrs<O>;
+  children: SvgNode<O>[];
+};
+
+/**
+ * An svg as defined in a ValModule.
+ *
+ * The root `<svg>` element is implicit: it *is* this object, which is why a
+ * nested `<svg>` is unrepresentable. `viewBox` is the single authority for the
+ * intrinsic box; `width` / `height` are the default rendered size.
+ */
+export type SvgSource<O extends SvgOptions> = {
+  viewBox: string;
+  width: number | null;
+  height: number | null;
+  children: SvgNode<O>[];
+  /**
+   * Injected by stega encoding, never authored and never stored.
+   * See {@link SVG_VAL_PATH}.
+   */
+  readonly [SVG_VAL_PATH]?: string;
+};
+
+/** An svg node with the options erased, for generic traversal. */
+export type GenericSvgNode = {
+  tag: string;
+  attrs: Record<string, string | number | { var: string }>;
+  children: GenericSvgNode[];
+};
+
+/** An svg source with the options erased, for generic traversal. */
+export type GenericSvgSource = {
+  viewBox: string;
+  width: number | null;
+  height: number | null;
+  children: GenericSvgNode[];
+  readonly [SVG_VAL_PATH]?: string;
+};
+
+export function isSvgVarRef(value: unknown): value is { var: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "var" in value &&
+    typeof (value as { var: unknown }).var === "string"
+  );
+}
+
+/** Resolves the shorthand form of {@link SvgVariable} to its object form. */
+export function svgVariableValue(variable: SvgVariable): string {
+  return typeof variable === "string" ? variable : variable.value;
+}
diff --git a/packages/next/README.md b/packages/next/README.md
index 981664a6f..0fd082672 100644
--- a/packages/next/README.md
+++ b/packages/next/README.md
@@ -52,6 +52,7 @@
   - [Router](#router)
   - [Object](#object)
   - [Rich text](#richtext)
+  - [Svg](#svg)
   - [Image](#image)
   - [keyOf](#keyof)
   - [Route](#route)
@@ -713,6 +714,258 @@ export function ValRichText({
 type MyRichTextOptions = AnyRichTextOptions; // you can reduce the surface of what you need to render, by restricting the `options` in `s.richtext(options)`
 ```
 
+## Svg
+
+<details>
+<summary>Svg in Val is stored as <strong>json</strong>, not as a file, and its colors are <strong>variables</strong> rather than baked in.</summary>
+
+An svg stored with `s.image()` or `s.file()` is an opaque blob: it cannot be recolored, it cannot be checked against your design system, and it cannot be diffed. `s.svg()` stores the same icon as a json node tree instead, so Val can validate what is in it and your app can retheme it.
+
+The flip-side, as with RichText, is that Val supports a subset: the shapes an icon is made of. Animation, filters, gradients, embedded raster images and scripting are not part of it.
+
+</details>
+
+### Svg Schema
+
+```ts
+s.svg({
+  // options
+});
+```
+
+### Initializing svg content
+
+```ts
+import { s, c } from "./val.config";
+
+export const iconSchema = s.svg({
+  // geometry, checked against the viewBox
+  width: 24,
+  height: 24,
+  aspectRatio: "1:1",
+
+  // the color palette. Every fill and stroke must resolve to one of these.
+  variables: {
+    // shorthand: the example color
+    brand: "#0055ff",
+    // long form
+    line: {
+      value: "currentColor",
+      description: "Strokes. Follows the surrounding text color.",
+    },
+    surface: {
+      value: "#ffffff",
+      // colors that should also map onto this variable on import, because
+      // exports from design tools drift
+      match: ["#fff", "#fefefe"],
+      // optionally, also match anything within this distance (0..1)
+      // tolerance: 0.05,
+    },
+  },
+
+  // what to do with a color that is not a variable:
+  //   "forbid" (default) - a raw color is an error, and the editor makes you
+  //                        map it onto the palette on import
+  //   "allow"            - any raw color passes
+  //   string[]           - only these raw colors pass
+  literals: "forbid",
+});
+
+export const schema = s.record(iconSchema);
+
+export default c.define("/content/icons.val.ts", schema, {
+  bell: {
+    viewBox: "0 0 24 24",
+    width: 24,
+    height: 24,
+    children: [
+      {
+        tag: "path",
+        attrs: { d: "M12 2.5A5.5 5.5 0 0 0 …", fill: { var: "brand" } },
+        children: [],
+      },
+      {
+        tag: "path",
+        attrs: {
+          d: "M9.6 18.5a2.4 2.4 0 0 0 4.8 0",
+          stroke: { var: "line" },
+          "stroke-width": 1.6,
+          "stroke-linecap": "round",
+          fill: "none",
+        },
+        children: [],
+      },
+    ],
+  },
+});
+```
+
+The `value` on a variable is an **example**. It is what the editor previews and what a pasted literal color is matched against. What actually renders is decided by the app - see below.
+
+Colors are type-checked, not only validated: with the default `literals: "forbid"`, writing `fill: "#ff0000"` is a TypeScript error, because the only things assignable are `{ var: … }`, `currentColor`, `none` and `transparent`.
+
+### Rendering svg
+
+Use the `ValSvg` component.
+
+```tsx
+"use client";
+import { ValSvg } from "@valbuild/next";
+import iconsVal from "./icons.val";
+import { useVal } from "./val/val.client";
+
+export default function Page() {
+  const icons = useVal(iconsVal);
+  return (
+    <ValSvg
+      src={icons.bell}
+      size={24}
+      vars={{
+        brand: "var(--brand-500)",
+        line: "currentColor",
+        surface: "#fff",
+      }}
+    />
+  );
+}
+```
+
+#### ValSvg: vars property
+
+`vars` maps each of the schema's color variables to the color that should actually render. A value can be any css color, including `currentColor` and a reference to one of your own design tokens.
+
+**NOTE**: if `vars` is defined, you must define a color for **every** variable the schema declares. What variables you have is decided by the `variables` on the `s.svg()` schema.
+
+```tsx
+<ValSvg
+  src={icons.bell}
+  vars={{
+    brand: "var(--brand-500)",
+    line: "currentColor",
+    surface: null, // either a string or null is required
+  }}
+/>
+```
+
+**NOTE**: the reason you must define a color for every variable is the same as for `ValRichText`'s `theme`: it forces you to revisit the places an icon is rendered when the schema changes, instead of a new variable silently rendering as something you did not choose.
+
+`null` means "leave it to css": that attribute is emitted as `var(--val-svg-<name>, currentColor)`, so a stylesheet can set it. Omitting `vars` entirely does the same for every variable, and `svgVarsCss` writes the schema's example colors into those custom properties:
+
+```tsx
+import { svgVarsCss } from "@valbuild/next";
+import { iconSchema } from "./icons.val";
+
+// once, in your layout
+<style>{svgVarsCss(iconSchema)}</style>;
+// :root{--val-svg-brand:#0055ff;--val-svg-line:currentColor;--val-svg-surface:#ffffff}
+```
+
+```css
+/* dark mode, with no React involved */
+[data-theme="dark"] {
+  --val-svg-brand: #6699ff;
+  --val-svg-surface: #111;
+}
+```
+
+#### ValSvg: size, and accessibility
+
+`viewBox` is the single authority for the aspect ratio. `size` sets both width and height; an explicit `width` or `height` wins over it; and if none are given the intrinsic size on the source is used.
+
+```tsx
+<ValSvg src={icons.bell} size={24} />
+<ValSvg src={icons.bell} width={32} height={16} />
+```
+
+Pass `title` when the icon carries meaning on its own - it renders a `<title>` and marks the svg `role="img"`. Leave it out for a decorative icon sitting next to a label, and the svg is marked `aria-hidden` instead.
+
+### Editing svg
+
+In the editor an svg field is a tile showing the icon. Drop an `.svg` file on it, paste svg markup into it, or click it to pick a file.
+
+On import Val reads every color in the markup and maps it onto the palette: an exact match on a variable's `value` or one of its `match` aliases, `currentColor` / `none` / `transparent` kept as they are, and anything within `tolerance` of a variable that opted in. Nothing is snapped to a nearby variable otherwise - a brand color that is quietly rewritten is worse than one you are asked about.
+
+Colors with nowhere to go are listed with a dropdown of the allowed colors, and the icon is not saved until every one of them has been mapped. If the schema's `literals` allows raw colors, keeping the original is offered as one of the choices.
+
+Anything outside the supported subset - `<script>`, `<style>`, `<foreignObject>`, `<a>`, `<use>`, `<image>`, animation and filter elements, and attributes such as `style`, `id`, `class`, `href` and `on*` - is removed on import, and the editor says what it removed.
+
+### The Svg type
+
+The svg source is a tree of the shapes an icon is made of:
+
+```ts
+type SvgSource = {
+  viewBox: string;
+  width: number | null;
+  height: number | null;
+  children: SvgNode[];
+};
+
+type SvgNode = {
+  tag:
+    | "g"
+    | "path"
+    | "circle"
+    | "ellipse"
+    | "rect"
+    | "line"
+    | "polyline"
+    | "polygon";
+  attrs: {
+    // colors: a variable, or one of the always allowed keywords
+    fill?: { var: string } | "currentColor" | "none" | "transparent";
+    stroke?: { var: string } | "currentColor" | "none" | "transparent";
+    // geometry and presentation: d, points, cx, cy, r, x, y, width, height,
+    // stroke-width, stroke-linecap, fill-rule, transform, ...
+    [attr: string]: unknown;
+  };
+  children: SvgNode[];
+};
+```
+
+The root `<svg>` element is the source itself, which is why a nested `<svg>` cannot be represented.
+
+Because the tree is rendered by building React elements one tag at a time - never with `dangerouslySetInnerHTML` - and only allowlisted tags and attributes exist in it, an icon an editor pasted cannot introduce script into your app.
+
+### Svg: full custom
+
+`SvgSource` maps 1-to-1 to svg elements, so writing your own renderer is straightforward. This is a simplified version of `ValSvg`:
+
+```tsx
+export function MyIcon({
+  src,
+  size,
+}: {
+  src: Svg<typeof iconSchema>;
+  size: number;
+}) {
+  const colors: Record<string, string> = {
+    brand: "var(--brand-500)",
+    line: "currentColor",
+    surface: "#fff",
+  };
+  function build(node: SvgNode, key: number): JSX.Element {
+    const attrs: Record<string, unknown> = {};
+    for (const [name, value] of Object.entries(node.attrs)) {
+      attrs[name] =
+        typeof value === "object" && value && "var" in value
+          ? colors[(value as { var: string }).var]
+          : value;
+    }
+    return React.createElement(
+      node.tag,
+      { key, ...attrs },
+      node.children.map(build),
+    );
+  }
+  return (
+    <svg viewBox={src.viewBox} width={size} height={size}>
+      {src.children.map(build)}
+    </svg>
+  );
+}
+```
+
 ## Image
 
 ### Image Schema
diff --git a/packages/next/src/external_exempt_from_val_quickjs.ts b/packages/next/src/external_exempt_from_val_quickjs.ts
index ef5ce2331..9e2f2812c 100644
--- a/packages/next/src/external_exempt_from_val_quickjs.ts
+++ b/packages/next/src/external_exempt_from_val_quickjs.ts
@@ -4,6 +4,13 @@ export type { SourceObject, SourcePrimitive, Source } from "@valbuild/core";
 export type { ValModule, SerializedModule } from "@valbuild/core";
 export type { FileSource } from "@valbuild/core";
 export type { RichTextSource } from "@valbuild/core";
+export type {
+  SvgSource,
+  SvgOptions,
+  SvgVariable,
+  SvgNode,
+} from "@valbuild/core";
+export { svgVarsCss, SVG_VAL_PATH } from "@valbuild/core";
 export {
   type Val,
   type SerializedVal,
@@ -27,7 +34,12 @@ export {
 } from "@valbuild/core";
 
 // React
-export { ValRichText } from "@valbuild/react/internal";
+export {
+  ValRichText,
+  ValSvg,
+  type ValSvgProps,
+  type SvgVars,
+} from "@valbuild/react/internal";
 
 // Stega
 export {
@@ -35,6 +47,7 @@ export {
   type File,
   type Image,
   type RichText,
+  type Svg,
 } from "@valbuild/react/stega";
 
 // Next specific
diff --git a/packages/react/package.json b/packages/react/package.json
index e3a735f33..7cede4b3f 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -22,6 +22,7 @@
   "devDependencies": {
     "@testing-library/react": "^14.0.0",
     "@types/react": "^18.2.38",
+    "@types/react-dom": "^18.2.0",
     "jest-environment-jsdom": "^29.5.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
diff --git a/packages/react/src/internal/ValSvg.test.tsx b/packages/react/src/internal/ValSvg.test.tsx
new file mode 100644
index 000000000..b178dbc6a
--- /dev/null
+++ b/packages/react/src/internal/ValSvg.test.tsx
@@ -0,0 +1,157 @@
+import { initVal, SvgSource, SVG_VAL_PATH } from "@valbuild/core";
+import { renderToStaticMarkup } from "react-dom/server";
+import { SvgVars, ValSvg } from "./ValSvg";
+
+const { s } = initVal();
+
+const iconSchema = s.svg({
+  variables: { brand: "#0055ff", line: "currentColor" },
+});
+type IconOptions = { variables: { brand: string; line: string } };
+
+const icon: SvgSource<IconOptions> = {
+  viewBox: "0 0 24 24",
+  width: 24,
+  height: 24,
+  children: [
+    {
+      tag: "path",
+      attrs: { d: "M4 12h16", fill: { var: "brand" } },
+      children: [],
+    },
+    {
+      tag: "circle",
+      attrs: {
+        cx: 12,
+        cy: 12,
+        r: 4,
+        stroke: { var: "line" },
+        fill: "none",
+      },
+      children: [],
+    },
+  ],
+};
+
+// Type level: `vars` must cover every variable the schema declares, so adding
+// one to the schema is a compile error at the call site. Same contract as
+// ValRichText's `theme`.
+type Assert<T extends true> = T;
+type IsRequired<T, K extends keyof T> =
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  {} extends Pick<T, K> ? false : true;
+type _BrandIsRequired = Assert<IsRequired<SvgVars<IconOptions>, "brand">>;
+type _LineIsRequired = Assert<IsRequired<SvgVars<IconOptions>, "line">>;
+
+describe("ValSvg", () => {
+  test("resolves variables from vars", () => {
+    const html = renderToStaticMarkup(
+      <ValSvg<IconOptions>
+        src={icon}
+        vars={{ brand: "var(--brand-500)", line: "currentColor" }}
+      />,
+    );
+    expect(html).toContain('fill="var(--brand-500)"');
+    expect(html).toContain('stroke="currentColor"');
+    // a non variable color is emitted as written
+    expect(html).toContain('fill="none"');
+  });
+
+  test("falls back to a css custom property when a var is null", () => {
+    const html = renderToStaticMarkup(
+      <ValSvg<IconOptions> src={icon} vars={{ brand: null, line: "red" }} />,
+    );
+    expect(html).toContain('fill="var(--val-svg-brand, currentColor)"');
+    expect(html).toContain('stroke="red"');
+  });
+
+  test("resolves every variable from css when vars is omitted", () => {
+    const html = renderToStaticMarkup(<ValSvg src={icon} />);
+    expect(html).toContain('fill="var(--val-svg-brand, currentColor)"');
+    expect(html).toContain('stroke="var(--val-svg-line, currentColor)"');
+  });
+
+  describe("sizing", () => {
+    test("size sets both", () => {
+      const html = renderToStaticMarkup(<ValSvg src={icon} size={32} />);
+      expect(html).toContain('width="32"');
+      expect(html).toContain('height="32"');
+    });
+
+    test("an explicit width or height wins over size", () => {
+      const html = renderToStaticMarkup(
+        <ValSvg src={icon} size={32} height={16} />,
+      );
+      expect(html).toContain('width="32"');
+      expect(html).toContain('height="16"');
+    });
+
+    test("falls back to the intrinsic size on the source", () => {
+      const html = renderToStaticMarkup(<ValSvg src={icon} />);
+      expect(html).toContain('width="24"');
+      expect(html).toContain('height="24"');
+    });
+
+    test("always emits the viewBox", () => {
+      expect(renderToStaticMarkup(<ValSvg src={icon} size={8} />)).toContain(
+        'viewBox="0 0 24 24"',
+      );
+    });
+  });
+
+  describe("accessibility", () => {
+    test("a title makes it an image with an accessible name", () => {
+      const html = renderToStaticMarkup(
+        <ValSvg src={icon} title="Notifications" />,
+      );
+      expect(html).toContain('role="img"');
+      expect(html).toContain('aria-label="Notifications"');
+      expect(html).toContain("<title>Notifications</title>");
+      expect(html).not.toContain("aria-hidden");
+    });
+
+    test("without a title it is decorative", () => {
+      const html = renderToStaticMarkup(<ValSvg src={icon} />);
+      expect(html).toContain('aria-hidden="true"');
+      expect(html).toContain('role="presentation"');
+      expect(html).not.toContain("<title>");
+    });
+  });
+
+  test("emits data-val-path from the field stega attaches", () => {
+    const html = renderToStaticMarkup(
+      <ValSvg src={{ ...icon, [SVG_VAL_PATH]: '/icons.val.ts?p="bell"' }} />,
+    );
+    expect(html).toContain('data-val-path="/icons.val.ts?p=&quot;bell&quot;"');
+  });
+
+  test("omits data-val-path when stega did not run", () => {
+    expect(renderToStaticMarkup(<ValSvg src={icon} />)).not.toContain(
+      "data-val-path",
+    );
+  });
+
+  test("renders nothing for a missing source", () => {
+    expect(
+      renderToStaticMarkup(
+        <ValSvg src={null as unknown as SvgSource<IconOptions>} />,
+      ),
+    ).toBe("");
+  });
+
+  test("the schema and the component agree on the variable names", () => {
+    const serialized = iconSchema["executeSerialize"]();
+    const names =
+      serialized.type === "svg"
+        ? Object.keys(serialized.options?.variables ?? {})
+        : [];
+    const vars: SvgVars<IconOptions> = {
+      brand: "#0055ff",
+      line: "currentColor",
+    };
+    expect(names.sort()).toStrictEqual(Object.keys(vars).sort());
+  });
+});
+
+// Keep the unused type aliases referenced so lint does not drop them.
+export type _TypeChecks = [_BrandIsRequired, _LineIsRequired];
diff --git a/packages/react/src/internal/ValSvg.tsx b/packages/react/src/internal/ValSvg.tsx
new file mode 100644
index 000000000..9ee07bd25
--- /dev/null
+++ b/packages/react/src/internal/ValSvg.tsx
@@ -0,0 +1,175 @@
+import {
+  isSvgVarRef,
+  GenericSvgNode,
+  SvgOptions,
+  SvgSource,
+  SvgVariableName,
+  SVG_COLOR_ATTRS,
+  SVG_VAL_PATH,
+} from "@valbuild/core";
+import React, { CSSProperties, ReactElement } from "react";
+
+/**
+ * A color for every variable the schema declares.
+ *
+ * `Record` makes each key required, so adding a variable to the schema is a
+ * compile error at every call site until it is given a color. This mirrors
+ * `ValRichText`'s `theme`, and for the same reason: a schema change should
+ * force you to revisit the places that render it, rather than silently
+ * changing how they look.
+ *
+ * A value may be any css color - `#0055ff`, `currentColor`, or a reference to
+ * one of your own design tokens such as `var(--brand-500)`. `null` means "leave
+ * it to css": the attribute is emitted as `var(--val-svg-<name>, currentColor)`
+ * so a stylesheet can set it.
+ */
+export type SvgVars<O extends SvgOptions> = Record<
+  SvgVariableName<O>,
+  string | null
+>;
+
+export type ValSvgProps<O extends SvgOptions> = {
+  src: SvgSource<O>;
+  /** Sets both width and height. Overridden by an explicit width or height. */
+  size?: number | string;
+  width?: number | string;
+  height?: number | string;
+  /**
+   * A color per declared variable. Exhaustive if given at all - see
+   * {@link SvgVars}. Omit it to let every variable resolve from css.
+   */
+  vars?: SvgVars<O>;
+  className?: string;
+  style?: CSSProperties;
+  /**
+   * Accessible name. Leave it out for decorative icons: the svg is then marked
+   * `aria-hidden`, which is what a screen reader wants for an icon sitting next
+   * to a label that already says the same thing.
+   */
+  title?: string;
+};
+
+function cssVar(name: string): string {
+  return `var(--val-svg-${name}, currentColor)`;
+}
+
+function colorAttrValue(
+  value: unknown,
+  vars: Record<string, string | null> | undefined,
+): string | null {
+  if (isSvgVarRef(value)) {
+    if (vars && value.var in vars) {
+      return vars[value.var] ?? cssVar(value.var);
+    }
+    return cssVar(value.var);
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return null;
+}
+
+function buildNode(
+  node: GenericSvgNode,
+  key: number,
+  vars: Record<string, string | null> | undefined,
+): ReactElement | null {
+  if (!node || typeof node !== "object" || typeof node.tag !== "string") {
+    return null;
+  }
+  const props: Record<string, unknown> = { key };
+  for (const [name, value] of Object.entries(node.attrs ?? {})) {
+    if ((SVG_COLOR_ATTRS as readonly string[]).includes(name)) {
+      const color = colorAttrValue(value, vars);
+      if (color !== null) {
+        props[name] = color;
+      }
+      continue;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+      props[name] = value;
+    }
+  }
+  const children = (node.children ?? [])
+    .map((child, i) => buildNode(child, i, vars))
+    .filter((child): child is ReactElement => child !== null);
+  return React.createElement(
+    node.tag,
+    props,
+    children.length > 0 ? children : undefined,
+  );
+}
+
+/**
+ * Render an svg using JSX.
+ *
+ * The node tree is turned into React elements one tag at a time - there is no
+ * `dangerouslySetInnerHTML` - and each color resolves through the schema's
+ * variables, so the same icon can inherit the surrounding text color, follow a
+ * dark mode stylesheet, or be recolored for one usage.
+ *
+ * @example
+ * const icons = useVal(iconsVal);
+ * return <ValSvg src={icons.bell} size={24} />;
+ *
+ * @example
+ * // Wire the schema's variables to your own design tokens. Every declared
+ * // variable must be listed, so adding one to the schema brings you back here.
+ * const icons = useVal(iconsVal);
+ * return (
+ *   <ValSvg
+ *     src={icons.bell}
+ *     size={24}
+ *     title="Notifications"
+ *     vars={{
+ *       brand: "var(--brand-500)",
+ *       line: "currentColor",
+ *       surface: null, // resolves from --val-svg-surface in css
+ *     }}
+ *   />
+ * );
+ */
+export function ValSvg<O extends SvgOptions>({
+  src,
+  size,
+  width,
+  height,
+  vars,
+  className,
+  style,
+  title,
+}: ValSvgProps<O>): ReactElement | null {
+  if (!src || typeof src !== "object") {
+    return null;
+  }
+  const resolvedVars = vars as Record<string, string | null> | undefined;
+  const resolvedWidth = width ?? size ?? src.width ?? undefined;
+  const resolvedHeight = height ?? size ?? src.height ?? undefined;
+  const valPath = (src as { [SVG_VAL_PATH]?: string })[SVG_VAL_PATH];
+  const children = (src.children ?? [])
+    .map((child, i) =>
+      buildNode(child as unknown as GenericSvgNode, i, resolvedVars),
+    )
+    .filter((child): child is ReactElement => child !== null);
+
+  return React.createElement(
+    "svg",
+    {
+      xmlns: "http://www.w3.org/2000/svg",
+      viewBox: src.viewBox,
+      width: resolvedWidth,
+      height: resolvedHeight,
+      className,
+      style,
+      role: title ? "img" : "presentation",
+      "aria-hidden": title ? undefined : true,
+      "aria-label": title,
+      // Svg sources are never stega encoded, so the overlay reads the path from
+      // this field rather than from encoded strings. See stegaEncode.
+      "data-val-path": valPath,
+    },
+    title
+      ? [React.createElement("title", { key: "title" }, title), ...children]
+      : children,
+  );
+}
diff --git a/packages/react/src/internal/index.ts b/packages/react/src/internal/index.ts
index c7d7ba5c8..7e813c660 100644
--- a/packages/react/src/internal/index.ts
+++ b/packages/react/src/internal/index.ts
@@ -1,2 +1,3 @@
 // NOTE: the exports of this file needs to be kept in sync with the stubs in loadValModules
 export { ValRichText } from "./ValRichText";
+export { ValSvg, type ValSvgProps, type SvgVars } from "./ValSvg";
diff --git a/packages/react/src/stega/index.ts b/packages/react/src/stega/index.ts
index 4eed78de6..cfd565042 100644
--- a/packages/react/src/stega/index.ts
+++ b/packages/react/src/stega/index.ts
@@ -10,6 +10,7 @@ export {
   type File,
   type Image,
   type RichText,
+  type Svg,
 } from "./stegaEncode";
 export { stegaDecodeStrings } from "./stegaDecodeStrings";
 export { attrs } from "./attrs";
diff --git a/packages/react/src/stega/stegaEncode.test.ts b/packages/react/src/stega/stegaEncode.test.ts
index 528fca585..713968b4e 100644
--- a/packages/react/src/stega/stegaEncode.test.ts
+++ b/packages/react/src/stega/stegaEncode.test.ts
@@ -5,6 +5,7 @@ import {
   Schema,
   SelectorSource,
   initVal,
+  SVG_VAL_PATH,
 } from "@valbuild/core";
 import { vercelStegaDecode, vercelStegaSplit } from "@vercel/stega";
 
@@ -427,3 +428,83 @@ describe("stegaEncode root seed (jsonValues entries)", () => {
 
 type SchemaOf<T extends Schema<SelectorSource>> =
   T extends Schema<infer S> ? S : never;
+
+describe("stega transform: svg", () => {
+  const iconSchema = s.svg({
+    variables: { brand: "#0055ff", line: "currentColor" },
+  });
+  const icon = {
+    viewBox: "0 0 24 24",
+    width: 24,
+    height: 24,
+    children: [
+      {
+        tag: "path" as const,
+        attrs: {
+          d: "M12 2C8.7 2 6 4.7 6 8v5l-2 3h16l-2-3V8c0-3.3-2.7-6-6-6z",
+          transform: "translate(1 1)",
+          fill: { var: "brand" as const },
+        },
+        children: [],
+      },
+      {
+        tag: "polyline" as const,
+        attrs: { points: "1,2 3,4 5,6", stroke: { var: "line" as const } },
+        children: [],
+      },
+    ],
+  };
+
+  test("leaves every string byte identical", () => {
+    const valModule = c.define("/icon.val.ts", iconSchema, icon);
+    const transformed = stegaEncode(valModule, {});
+
+    // No invisible characters anywhere: an svg is machine parsed, so encoding
+    // d / viewBox / points / transform would corrupt the icon.
+    expect(transformed.viewBox).toBe(icon.viewBox);
+    expect(transformed.children[0].attrs.d).toBe(icon.children[0].attrs.d);
+    expect(transformed.children[0].attrs.transform).toBe(
+      icon.children[0].attrs.transform,
+    );
+    expect(transformed.children[1].attrs.points).toBe(
+      icon.children[1].attrs.points,
+    );
+    expect(vercelStegaDecode(transformed.children[0].attrs.d)).toBe(undefined);
+    expect(vercelStegaDecode(transformed.viewBox)).toBe(undefined);
+    expect(vercelStegaSplit(transformed.children[0].attrs.d).encoded).toBe("");
+  });
+
+  test("attaches the source path as a plain field, for ValSvg", () => {
+    const valModule = c.define("/icon.val.ts", iconSchema, icon);
+    const transformed = stegaEncode(valModule, {});
+    expect(transformed[SVG_VAL_PATH]).toBe("/icon.val.ts");
+  });
+
+  test("carries the path of a nested svg", () => {
+    const schema = s.record(iconSchema);
+    const valModule = c.define("/icons.val.ts", schema, { bell: icon });
+    const transformed = stegaEncode(valModule, {});
+    expect(transformed.bell[SVG_VAL_PATH]).toBe('/icons.val.ts?p="bell"');
+  });
+
+  test("attaches nothing when stega is disabled", () => {
+    const valModule = c.define("/icon.val.ts", iconSchema, icon);
+    const transformed = stegaEncode(valModule, { disabled: true });
+    expect(transformed[SVG_VAL_PATH]).toBe(undefined);
+    expect(transformed.viewBox).toBe(icon.viewBox);
+  });
+
+  test("does not disturb stega encoding of sibling fields", () => {
+    const schema = s.object({ title: s.string(), icon: iconSchema });
+    const valModule = c.define("/page.val.ts", schema, {
+      title: "Notifications",
+      icon,
+    });
+    const transformed = stegaEncode(valModule, {});
+    expect(vercelStegaDecode(transformed.title)).toStrictEqual({
+      data: { valPath: '/page.val.ts?p="title"' },
+      origin: "val.build",
+    });
+    expect(transformed.icon.children[0].attrs.d).toBe(icon.children[0].attrs.d);
+  });
+});
diff --git a/packages/react/src/stega/stegaEncode.ts b/packages/react/src/stega/stegaEncode.ts
index b203b8e26..228163405 100644
--- a/packages/react/src/stega/stegaEncode.ts
+++ b/packages/react/src/stega/stegaEncode.ts
@@ -19,6 +19,10 @@ import {
   SerializedDateSchema,
   SerializedDateTimeSchema,
   SerializedColorSchema,
+  SerializedSvgSchema,
+  SvgOptions,
+  SvgSource,
+  SVG_VAL_PATH,
 } from "@valbuild/core";
 import { vercelStegaCombine, vercelStegaSplit } from "@vercel/stega";
 import { FileSource, Source, SourceObject } from "@valbuild/core";
@@ -211,29 +215,41 @@ export type RichText<O extends RichTextOptions> = StegaOfRichTextSource<
   readonly __brand?: "RichText";
 };
 
+/**
+ * Svg sources are never stega encoded: every string in an svg (`d`, `viewBox`,
+ * `points`, ...) is machine parsed, so injecting invisible characters into them
+ * corrupts the icon. The source therefore passes through unchanged, with the
+ * source path attached as an ordinary field for `ValSvg` to read.
+ */
+export type Svg<O extends SvgOptions> = SvgSource<O> & {
+  readonly [SVG_VAL_PATH]?: string;
+};
+
 export type StegaOfSource<T extends Source> = Json extends T
   ? Json
   : T extends RichTextSource<infer O>
     ? RichText<O>
-    : T extends ImageSource
-      ? Image
-      : T extends FileSource<infer M>
-        ? M extends FileMetadata
-          ? File<M>
-          : never
-        : T extends SourceObject
-          ? {
-              [key in keyof T]: StegaOfSource<T[key]>;
-            }
-          : T extends SourceArray
-            ? StegaOfSource<T[number]>[]
-            : T extends RawString
-              ? string
-              : string extends T
-                ? ValEncodedString
-                : T extends JsonPrimitive
-                  ? T
-                  : never;
+    : T extends SvgSource<infer SO>
+      ? Svg<SO>
+      : T extends ImageSource
+        ? Image
+        : T extends FileSource<infer M>
+          ? M extends FileMetadata
+            ? File<M>
+            : never
+          : T extends SourceObject
+            ? {
+                [key in keyof T]: StegaOfSource<T[key]>;
+              }
+            : T extends SourceArray
+              ? StegaOfSource<T[number]>[]
+              : T extends RawString
+                ? string
+                : string extends T
+                  ? ValEncodedString
+                  : T extends JsonPrimitive
+                    ? T
+                    : never;
 
 /**
  * Resolves the matching sub-schema for a tagged union based on the discriminator key.
@@ -417,6 +433,20 @@ export function stegaEncode(
     if (recOpts?.schema && isRichTextSchema(recOpts.schema)) {
       return handleRichTextSchema(sourceOrSelector, recOpts, rec);
     }
+    if (recOpts?.schema && isSvgSchema(recOpts.schema)) {
+      // Deliberately not encoded: see the note on `Svg` above. The path is
+      // attached as a plain field instead, which ValSvg turns into
+      // data-val-path. A symbol would not survive RSC serialization.
+      if (
+        opts.disabled ||
+        !recOpts.path ||
+        typeof sourceOrSelector !== "object" ||
+        sourceOrSelector === null
+      ) {
+        return sourceOrSelector;
+      }
+      return { ...sourceOrSelector, [SVG_VAL_PATH]: recOpts.path };
+    }
 
     if (typeof sourceOrSelector === "object") {
       if (!sourceOrSelector) {
@@ -601,6 +631,12 @@ function isRichTextSchema(
   return schema?.type === "richtext";
 }
 
+function isSvgSchema(
+  schema: SerializedSchema | undefined,
+): schema is SerializedSvgSchema {
+  return schema?.type === "svg";
+}
+
 function isObjectSchema(
   schema: SerializedSchema | undefined,
 ): schema is SerializedObjectSchema {
diff --git a/packages/server/src/hasRemoteFileSchema.ts b/packages/server/src/hasRemoteFileSchema.ts
index b0930714f..ea37c6290 100644
--- a/packages/server/src/hasRemoteFileSchema.ts
+++ b/packages/server/src/hasRemoteFileSchema.ts
@@ -55,7 +55,8 @@ export function hasRemoteFileSchema(schema: SerializedSchema): boolean {
     schema.type === "dateTime" ||
     schema.type === "color" ||
     schema.type === "keyOf" ||
-    schema.type === "route"
+    schema.type === "route" ||
+    schema.type === "svg"
   ) {
     return false;
   } else {
diff --git a/packages/shared/src/internal/index.ts b/packages/shared/src/internal/index.ts
index 247381e26..bbda70a7e 100644
--- a/packages/shared/src/internal/index.ts
+++ b/packages/shared/src/internal/index.ts
@@ -15,3 +15,4 @@ export * from "./routeValidation";
 export * from "./resolveSchemaSourceFixes";
 export * from "./getErrorMessageFromUnknownJson";
 export * from "./zod/SerializedSchema";
+export * from "./svg";
diff --git a/packages/shared/src/internal/svg/colors.ts b/packages/shared/src/internal/svg/colors.ts
new file mode 100644
index 000000000..7e996b896
--- /dev/null
+++ b/packages/shared/src/internal/svg/colors.ts
@@ -0,0 +1,175 @@
+/**
+ * Color normalization for svg import.
+ *
+ * Design tools emit the same color in many spellings (`#FFF`, `#ffffff`,
+ * `rgb(255,255,255)`, `white`). To match a pasted color against a schema's
+ * declared variables we reduce every spelling to a single canonical form.
+ */
+
+export type Rgb = { r: number; g: number; b: number; a: number };
+
+/**
+ * The subset of the CSS named colors that actually turns up in exported svg.
+ * Deliberately not the full 148: anything missing simply fails to normalize and
+ * is reported as unmatched, which is a safe outcome.
+ */
+const NAMED_COLORS: Readonly<Record<string, string>> = {
+  aqua: "#00ffff",
+  black: "#000000",
+  blue: "#0000ff",
+  cyan: "#00ffff",
+  fuchsia: "#ff00ff",
+  gray: "#808080",
+  green: "#008000",
+  grey: "#808080",
+  lime: "#00ff00",
+  magenta: "#ff00ff",
+  maroon: "#800000",
+  navy: "#000080",
+  olive: "#808000",
+  orange: "#ffa500",
+  purple: "#800080",
+  red: "#ff0000",
+  silver: "#c0c0c0",
+  teal: "#008080",
+  white: "#ffffff",
+  yellow: "#ffff00",
+};
+
+function clamp255(n: number): number {
+  return Math.max(0, Math.min(255, Math.round(n)));
+}
+
+function hex2(n: number): string {
+  return clamp255(n).toString(16).padStart(2, "0");
+}
+
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  const hue = ((h % 360) + 360) % 360;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((hue / 60) % 2) - 1));
+  const m = l - c / 2;
+  let rgb: [number, number, number];
+  if (hue < 60) rgb = [c, x, 0];
+  else if (hue < 120) rgb = [x, c, 0];
+  else if (hue < 180) rgb = [0, c, x];
+  else if (hue < 240) rgb = [0, x, c];
+  else if (hue < 300) rgb = [x, 0, c];
+  else rgb = [c, 0, x];
+  return [(rgb[0] + m) * 255, (rgb[1] + m) * 255, (rgb[2] + m) * 255];
+}
+
+/**
+ * Parses a CSS color into rgba components, or returns null if the spelling is
+ * not one we understand.
+ */
+export function parseColor(input: string): Rgb | null {
+  const value = input.trim();
+  if (!value) {
+    return null;
+  }
+  const lower = value.toLowerCase();
+  if (lower in NAMED_COLORS) {
+    return parseColor(NAMED_COLORS[lower]);
+  }
+  if (value.startsWith("#")) {
+    const hex = value.slice(1);
+    if (!/^[0-9a-fA-F]+$/.test(hex)) {
+      return null;
+    }
+    if (hex.length === 3 || hex.length === 4) {
+      const [r, g, b, a] = hex.split("");
+      return {
+        r: parseInt(r + r, 16),
+        g: parseInt(g + g, 16),
+        b: parseInt(b + b, 16),
+        a: a === undefined ? 1 : parseInt(a + a, 16) / 255,
+      };
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      return {
+        r: parseInt(hex.slice(0, 2), 16),
+        g: parseInt(hex.slice(2, 4), 16),
+        b: parseInt(hex.slice(4, 6), 16),
+        a: hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1,
+      };
+    }
+    return null;
+  }
+  const fn = /^(rgba?|hsla?)\(([^)]*)\)$/i.exec(value);
+  if (!fn) {
+    return null;
+  }
+  const name = fn[1].toLowerCase();
+  const parts = fn[2]
+    .split(/[\s,/]+/)
+    .map((part) => part.trim())
+    .filter((part) => part !== "");
+  if (parts.length < 3) {
+    return null;
+  }
+  const num = (raw: string, scale: number): number | null => {
+    if (raw.endsWith("%")) {
+      const n = Number(raw.slice(0, -1));
+      return Number.isFinite(n) ? (n / 100) * scale : null;
+    }
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+  };
+  const alpha = parts.length > 3 ? num(parts[3], 1) : 1;
+  if (alpha === null) {
+    return null;
+  }
+  if (name === "rgb" || name === "rgba") {
+    const r = num(parts[0], 255);
+    const g = num(parts[1], 255);
+    const b = num(parts[2], 255);
+    if (r === null || g === null || b === null) {
+      return null;
+    }
+    return { r, g, b, a: alpha };
+  }
+  const h = num(parts[0], 360);
+  const s = num(parts[1], 1);
+  const l = num(parts[2], 1);
+  if (h === null || s === null || l === null) {
+    return null;
+  }
+  const [r, g, b] = hslToRgb(
+    h,
+    Math.max(0, Math.min(1, s)),
+    Math.max(0, Math.min(1, l)),
+  );
+  return { r, g, b, a: alpha };
+}
+
+/**
+ * Reduces a color to a canonical `#rrggbb` (or `#rrggbbaa`) string.
+ * Returns null for spellings we do not understand, and for the keywords, which
+ * callers handle separately.
+ */
+export function normalizeColor(input: string): string | null {
+  const rgb = parseColor(input);
+  if (!rgb) {
+    return null;
+  }
+  const base = `#${hex2(rgb.r)}${hex2(rgb.g)}${hex2(rgb.b)}`;
+  return rgb.a >= 1 ? base : `${base}${hex2(rgb.a * 255)}`;
+}
+
+/**
+ * Normalized RGB distance in 0..1, used for `tolerance` matching.
+ * Plain euclidean distance in sRGB: crude, but predictable, and only ever
+ * applied when a variable explicitly opts in.
+ */
+export function colorDistance(a: string, b: string): number | null {
+  const left = parseColor(a);
+  const right = parseColor(b);
+  if (!left || !right) {
+    return null;
+  }
+  const dr = (left.r - right.r) / 255;
+  const dg = (left.g - right.g) / 255;
+  const db = (left.b - right.b) / 255;
+  return Math.sqrt((dr * dr + dg * dg + db * db) / 3);
+}
diff --git a/packages/shared/src/internal/svg/index.ts b/packages/shared/src/internal/svg/index.ts
new file mode 100644
index 000000000..96cced0d8
--- /dev/null
+++ b/packages/shared/src/internal/svg/index.ts
@@ -0,0 +1,23 @@
+export {
+  parseSvg,
+  type ParseSvgOptions,
+  type ParseSvgResult,
+  type SvgColorOverride,
+  type SvgDroppedAttr,
+  type SvgUnmatchedColor,
+} from "./parseSvg";
+export {
+  svgToString,
+  svgSourceToJson,
+  stripSvgValPath,
+  svgVariablesOf,
+  type SvgToStringOptions,
+} from "./svgToString";
+export { colorDistance, normalizeColor, parseColor, type Rgb } from "./colors";
+export {
+  parseXml,
+  decodeXmlEntities,
+  encodeXmlText,
+  type XmlElement,
+  type XmlParseResult,
+} from "./xml";
diff --git a/packages/shared/src/internal/svg/parseSvg.test.ts b/packages/shared/src/internal/svg/parseSvg.test.ts
new file mode 100644
index 000000000..01e555197
--- /dev/null
+++ b/packages/shared/src/internal/svg/parseSvg.test.ts
@@ -0,0 +1,362 @@
+import { SvgOptions } from "@valbuild/core";
+import { parseSvg } from "./parseSvg";
+import { decodeXmlEntities } from "./xml";
+import { svgToString } from "./svgToString";
+import { normalizeColor } from "./colors";
+
+const options: SvgOptions = {
+  variables: {
+    brand: "#0055ff",
+    line: "currentColor",
+    surface: { value: "#ffffff", match: ["#fefefe"] },
+    warn: { value: "#ff8800", tolerance: 0.05 },
+  },
+};
+
+function parse(markup: string, overrides = {}) {
+  return parseSvg(markup, options, { overrides });
+}
+
+describe("normalizeColor", () => {
+  test.each([
+    ["#FFF", "#ffffff"],
+    ["#ffffff", "#ffffff"],
+    ["white", "#ffffff"],
+    ["rgb(255, 255, 255)", "#ffffff"],
+    ["rgb(100%, 100%, 100%)", "#ffffff"],
+    ["hsl(0, 0%, 100%)", "#ffffff"],
+    ["#0AF", "#00aaff"],
+    ["rgba(0, 0, 0, 0.5)", "#00000080"],
+  ])("normalizes %s to %s", (input, expected) => {
+    expect(normalizeColor(input)).toBe(expected);
+  });
+
+  test("returns null for spellings it does not understand", () => {
+    expect(normalizeColor("currentColor")).toBe(null);
+    expect(normalizeColor("url(#grad)")).toBe(null);
+    expect(normalizeColor("")).toBe(null);
+  });
+});
+
+describe("parseSvg", () => {
+  test("parses a typical export and maps colors onto variables", () => {
+    const result = parse(`<?xml version="1.0" encoding="UTF-8"?>
+      <!-- Exported from a design tool -->
+      <svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+        <path d="M4 12h16" stroke="#0055FF" stroke-width="2" fill="none"/>
+      </svg>`);
+    expect(result).toMatchObject({
+      status: "success",
+      unmatched: [],
+      source: {
+        viewBox: "0 0 24 24",
+        width: 24,
+        height: 24,
+        children: [
+          {
+            tag: "path",
+            attrs: {
+              d: "M4 12h16",
+              stroke: { var: "brand" },
+              "stroke-width": 2,
+              fill: "none",
+            },
+            children: [],
+          },
+        ],
+      },
+    });
+  });
+
+  test("matches a color listed in a variable's match aliases", () => {
+    const result = parse(
+      `<svg viewBox="0 0 8 8"><circle cx="4" cy="4" r="4" fill="#FEFEFE"/></svg>`,
+    );
+    expect(result).toMatchObject({
+      status: "success",
+      source: { children: [{ attrs: { fill: { var: "surface" } } }] },
+    });
+  });
+
+  test("matches a near color only when the variable opted in with tolerance", () => {
+    const near = parse(
+      `<svg viewBox="0 0 8 8"><circle cx="4" cy="4" r="4" fill="#ff8a02"/></svg>`,
+    );
+    expect(near).toMatchObject({
+      status: "success",
+      source: { children: [{ attrs: { fill: { var: "warn" } } }] },
+    });
+    // brand has no tolerance, so a color near it is reported instead of snapped
+    const nearBrand = parse(
+      `<svg viewBox="0 0 8 8"><circle cx="4" cy="4" r="4" fill="#0056ff"/></svg>`,
+    );
+    expect(nearBrand).toMatchObject({
+      status: "success",
+      unmatched: [{ raw: "#0056ff", normalized: "#0056ff", count: 1 }],
+    });
+  });
+
+  test("keeps the color keywords verbatim", () => {
+    const result = parse(
+      `<svg viewBox="0 0 8 8"><circle cx="4" cy="4" r="4" fill="none" stroke="currentColor"/></svg>`,
+    );
+    expect(result).toMatchObject({
+      status: "success",
+      source: {
+        children: [{ attrs: { fill: "none", stroke: "currentColor" } }],
+      },
+    });
+  });
+
+  test("reports unmatched colors once, with a use count", () => {
+    const result = parse(`<svg viewBox="0 0 8 8">
+      <circle cx="2" cy="2" r="1" fill="#ff0000"/>
+      <circle cx="6" cy="6" r="1" fill="#FF0000"/>
+    </svg>`);
+    expect(result).toMatchObject({
+      status: "success",
+      unmatched: [{ raw: "#ff0000", normalized: "#ff0000", count: 2 }],
+    });
+    if (result.status !== "success") throw new Error("unreachable");
+    // the attribute is left off entirely until the caller decides
+    expect(result.source.children[0].attrs).not.toHaveProperty("fill");
+  });
+
+  test("applies caller supplied overrides for unmatched colors", () => {
+    const markup = `<svg viewBox="0 0 8 8"><circle cx="4" cy="4" r="4" fill="#ff0000"/></svg>`;
+    expect(
+      parse(markup, { "#ff0000": { type: "var", var: "brand" } }),
+    ).toMatchObject({
+      status: "success",
+      unmatched: [],
+      source: { children: [{ attrs: { fill: { var: "brand" } } }] },
+    });
+    expect(
+      parse(markup, {
+        "#ff0000": { type: "keyword", keyword: "currentColor" },
+      }),
+    ).toMatchObject({
+      status: "success",
+      source: { children: [{ attrs: { fill: "currentColor" } }] },
+    });
+  });
+
+  test("derives a viewBox from width and height when there is none", () => {
+    expect(parse(`<svg width="16" height="16"><g/></svg>`)).toMatchObject({
+      status: "success",
+      source: { viewBox: "0 0 16 16" },
+    });
+  });
+
+  test("normalizes whitespace and commas in the viewBox", () => {
+    expect(parse(`<svg viewBox="0,0,  24, 24"><g/></svg>`)).toMatchObject({
+      status: "success",
+      source: { viewBox: "0 0 24 24" },
+    });
+  });
+
+  test("handles self closing tags, entities and comments", () => {
+    const result = parse(
+      `<svg viewBox="0 0 8 8"><!-- c --><g transform="translate(1 1)"><circle cx="4" cy="4" r="2"/></g></svg>`,
+    );
+    expect(result).toMatchObject({
+      status: "success",
+      source: {
+        children: [
+          {
+            tag: "g",
+            attrs: { transform: "translate(1 1)" },
+            children: [{ tag: "circle" }],
+          },
+        ],
+      },
+    });
+  });
+
+  describe("the allowlist", () => {
+    test("drops unsupported elements", () => {
+      const result = parse(`<svg viewBox="0 0 8 8">
+        <script>alert(1)</script>
+        <style>svg{color:red}</style>
+        <foreignObject><div/></foreignObject>
+        <image href="https://example.com/x.png"/>
+        <a href="javascript:alert(1)"><circle cx="1" cy="1" r="1"/></a>
+        <circle cx="4" cy="4" r="4"/>
+      </svg>`);
+      if (result.status !== "success") throw new Error(result.message);
+      expect(result.source.children).toHaveLength(1);
+      expect(result.droppedTags).toStrictEqual([
+        "script",
+        "style",
+        "foreignObject",
+        "image",
+        "a",
+      ]);
+    });
+
+    test("drops event handlers and other unsupported attributes", () => {
+      const result = parse(
+        `<svg viewBox="0 0 8 8"><circle cx="4" cy="4" r="4" onload="alert(1)" onclick="x()" style="fill:red" id="a" class="b" xlink:href="#c" data-x="1"/></svg>`,
+      );
+      if (result.status !== "success") throw new Error(result.message);
+      expect(result.source.children[0].attrs).toStrictEqual({
+        cx: 4,
+        cy: 4,
+        r: 4,
+      });
+      expect(result.droppedAttrs.map((a) => a.attr).sort()).toStrictEqual([
+        "class",
+        "data-x",
+        "id",
+        "onclick",
+        "onload",
+        "style",
+        "xlink:href",
+      ]);
+    });
+
+    test("drops a d attribute containing characters a path cannot have", () => {
+      const result = parse(
+        `<svg viewBox="0 0 8 8"><path d="M0 0 url(javascript:alert(1))"/></svg>`,
+      );
+      if (result.status !== "success") throw new Error(result.message);
+      expect(result.source.children[0].attrs).not.toHaveProperty("d");
+    });
+
+    test("drops an out of range enum value", () => {
+      const result = parse(
+        `<svg viewBox="0 0 8 8"><path d="M0 0" stroke-linecap="nope"/></svg>`,
+      );
+      if (result.status !== "success") throw new Error(result.message);
+      expect(result.source.children[0].attrs).not.toHaveProperty(
+        "stroke-linecap",
+      );
+    });
+  });
+
+  describe("rejections", () => {
+    test.each([
+      [
+        "entity declarations",
+        `<!DOCTYPE svg [<!ENTITY x "y">]><svg viewBox="0 0 1 1"/>`,
+      ],
+      [
+        "a doctype with an internal subset",
+        `<!DOCTYPE svg [ <!-- x --> ]><svg viewBox="0 0 1 1"/>`,
+      ],
+      ["an unclosed tag", `<svg viewBox="0 0 1 1"><g>`],
+      ["a mismatched closing tag", `<svg viewBox="0 0 1 1"><g></path></svg>`],
+      ["a non svg root", `<div><svg viewBox="0 0 1 1"/></div>`],
+      ["no viewBox and no size", `<svg><g/></svg>`],
+      ["a malformed viewBox", `<svg viewBox="nope"><g/></svg>`],
+      ["empty input", ``],
+    ])("rejects %s", (_name, markup) => {
+      expect(parse(markup).status).toBe("error");
+    });
+
+    test("rejects an svg that exceeds the node budget", () => {
+      const many = Array.from(
+        { length: 30 },
+        () => `<circle cx="1" cy="1" r="1"/>`,
+      ).join("");
+      const result = parseSvg(`<svg viewBox="0 0 8 8">${many}</svg>`, {
+        maxNodes: 10,
+      });
+      expect(result).toMatchObject({ status: "error" });
+    });
+
+    test("rejects an svg nested deeper than the budget", () => {
+      const deep = "<g>".repeat(10) + "</g>".repeat(10);
+      const result = parseSvg(`<svg viewBox="0 0 8 8">${deep}</svg>`, {
+        maxDepth: 3,
+      });
+      expect(result).toMatchObject({ status: "error" });
+    });
+
+    test("rejects a d attribute larger than the cap", () => {
+      const huge = "M0 0 " + "L1 1 ".repeat(30_000);
+      const result = parse(`<svg viewBox="0 0 8 8"><path d="${huge}"/></svg>`);
+      if (result.status !== "success") throw new Error(result.message);
+      expect(result.source.children[0].attrs).not.toHaveProperty("d");
+    });
+  });
+});
+
+describe("decodeXmlEntities", () => {
+  test("decodes the named and numeric entities it knows", () => {
+    expect(
+      decodeXmlEntities("a &amp; b &lt;c&gt; &quot;d&quot; &apos;e&apos;"),
+    ).toBe(`a & b <c> "d" 'e'`);
+    expect(decodeXmlEntities("&#65;&#x42;")).toBe("AB");
+    expect(decodeXmlEntities("&#x1F600;")).toBe("\u{1F600}");
+  });
+
+  test("leaves an out-of-range numeric entity alone instead of throwing", () => {
+    // `String.fromCodePoint` throws a RangeError above 0x10FFFF, and these all
+    // parse to finite numbers - so an unguarded call crashes the parse of any
+    // svg that contains one.
+    for (const value of [
+      "&#1114112;",
+      "&#x110000;",
+      "&#x7FFFFFFF;",
+      "&#99999999999;",
+    ]) {
+      expect(decodeXmlEntities(value)).toBe(value);
+    }
+  });
+
+  test("leaves an unknown named entity alone", () => {
+    expect(decodeXmlEntities("&nbsp;&foo;")).toBe("&nbsp;&foo;");
+  });
+
+  test("leaves an uppercase-X hex entity alone", () => {
+    // Not a legal XML character reference (the production is lowercase `x`), so
+    // it stays as written rather than being decoded.
+    expect(decodeXmlEntities("&#X43;")).toBe("&#X43;");
+  });
+
+  test("an out-of-range entity in markup parses rather than crashing", () => {
+    expect(() =>
+      parse(`<svg viewBox="0 0 8 8"><title>&#x110000;</title></svg>`),
+    ).not.toThrow();
+  });
+});
+
+describe("svgToString", () => {
+  const markup = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
+  <g transform="translate(1 1)">
+    <path d="M4 12h16" stroke="var(--val-svg-brand, currentColor)" stroke-width="2" fill="none"/>
+  </g>
+</svg>`;
+
+  test("round trips parse -> string -> parse", () => {
+    const first = parse(markup);
+    if (first.status !== "success") throw new Error(first.message);
+    const printed = svgToString(first.source, { pretty: true });
+    expect(printed).toBe(markup);
+    const second = parse(printed);
+    if (second.status !== "success") throw new Error(second.message);
+    expect(second.source).toStrictEqual(first.source);
+  });
+
+  test("resolves variables to concrete colors when asked", () => {
+    const result = parse(
+      `<svg viewBox="0 0 24 24"><path d="M4 12h16" stroke="#0055ff"/></svg>`,
+    );
+    if (result.status !== "success") throw new Error(result.message);
+    expect(
+      svgToString(result.source, { variables: options.variables }),
+    ).toContain('stroke="#0055ff"');
+  });
+
+  test("escapes attribute values", () => {
+    expect(
+      svgToString({
+        viewBox: '0 0 1 1" onload="alert(1)',
+        width: null,
+        height: null,
+        children: [],
+      }),
+    ).not.toContain('onload="alert(1)"');
+  });
+});
diff --git a/packages/shared/src/internal/svg/parseSvg.ts b/packages/shared/src/internal/svg/parseSvg.ts
new file mode 100644
index 000000000..834606e84
--- /dev/null
+++ b/packages/shared/src/internal/svg/parseSvg.ts
@@ -0,0 +1,333 @@
+import {
+  isAllowedSvgAttr,
+  isSvgTag,
+  parseSvgViewBox,
+  svgVariableValue,
+  SvgNode,
+  SvgOptions,
+  SvgSource,
+  SvgTag,
+  SvgVariable,
+  SVG_COLOR_ATTRS,
+  SVG_DEFAULT_MAX_DEPTH,
+  SVG_DEFAULT_MAX_NODES,
+  SVG_ENUM_ATTRS,
+  SVG_KEYWORD_COLORS,
+  SVG_NUMBER_ATTRS,
+  SVG_STRING_ATTRS,
+} from "@valbuild/core";
+import { colorDistance, normalizeColor } from "./colors";
+import { parseXml, XmlElement } from "./xml";
+
+/** A literal color that could not be mapped onto a declared variable. */
+export type SvgUnmatchedColor = {
+  /** The color exactly as it appeared in the markup. */
+  raw: string;
+  /** Canonical `#rrggbb` form, when we could parse it. */
+  normalized: string | null;
+  /** How many attributes used it. */
+  count: number;
+};
+
+/** An attribute that was dropped because the allowlist does not include it. */
+export type SvgDroppedAttr = {
+  tag: string;
+  attr: string;
+};
+
+export type ParseSvgResult<O extends SvgOptions> =
+  | {
+      status: "success";
+      source: SvgSource<O>;
+      /** Literal colors with no home. The editor prompts for these. */
+      unmatched: SvgUnmatchedColor[];
+      /** Tags removed by the allowlist. */
+      droppedTags: string[];
+      /** Attributes removed by the allowlist. */
+      droppedAttrs: SvgDroppedAttr[];
+    }
+  | { status: "error"; message: string };
+
+/**
+ * How a literal color should be resolved, when the caller has already made a
+ * decision for it (the editor's unmatched-color prompt).
+ */
+export type SvgColorOverride =
+  | { type: "var"; var: string }
+  | { type: "keyword"; keyword: "currentColor" | "none" | "transparent" }
+  | { type: "literal" };
+
+export type ParseSvgOptions = {
+  /** Keyed by the *normalized* color, or by the raw string if unparseable. */
+  overrides?: Record<string, SvgColorOverride>;
+};
+
+type VariableEntry = {
+  name: string;
+  normalized: string | null;
+  keyword: string | null;
+  matches: (string | null)[];
+  tolerance: number;
+};
+
+function variableEntries(options: SvgOptions): VariableEntry[] {
+  return Object.entries(options.variables ?? {}).map(([name, variable]) => {
+    const spec: SvgVariable = variable;
+    const value = svgVariableValue(spec);
+    const extra = typeof spec === "string" ? [] : (spec.match ?? []);
+    return {
+      name,
+      normalized: normalizeColor(value),
+      keyword: SVG_KEYWORD_COLORS.includes(value) ? value : null,
+      matches: extra.map((m) => normalizeColor(m)),
+      tolerance: typeof spec === "string" ? 0 : (spec.tolerance ?? 0),
+    };
+  });
+}
+
+function numberOf(raw: string): number | null {
+  // Strip a unit: exports commonly write width="24px".
+  const value = raw.trim().replace(/px$/i, "");
+  if (value === "") {
+    return null;
+  }
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Parses svg markup into an {@link SvgSource}, mapping literal colors onto the
+ * schema's declared variables.
+ *
+ * Everything outside the allowlist is dropped rather than rejected, so pasting
+ * a real-world export mostly works; what was dropped is reported so the editor
+ * can say so. Colors that cannot be mapped are reported too - we never guess a
+ * nearest variable unless that variable opted in with `tolerance`.
+ */
+export function parseSvg<O extends SvgOptions>(
+  markup: string,
+  options: O,
+  parseOptions: ParseSvgOptions = {},
+): ParseSvgResult<O> {
+  const parsed = parseXml(markup);
+  if (parsed.status === "error") {
+    return parsed;
+  }
+  const root = parsed.root;
+  if (root.tag.toLowerCase() !== "svg") {
+    return {
+      status: "error",
+      message: `Expected a root <svg> element, got <${root.tag}>`,
+    };
+  }
+
+  const viewBoxAttr = root.attrs.viewBox ?? root.attrs.viewbox;
+  const widthAttr = root.attrs.width ? numberOf(root.attrs.width) : null;
+  const heightAttr = root.attrs.height ? numberOf(root.attrs.height) : null;
+  let viewBox = viewBoxAttr?.trim().replace(/[\s,]+/g, " ");
+  if (!viewBox && widthAttr !== null && heightAttr !== null) {
+    viewBox = `0 0 ${widthAttr} ${heightAttr}`;
+  }
+  if (!viewBox) {
+    return {
+      status: "error",
+      message: "The svg has no viewBox, and no width/height to derive one from",
+    };
+  }
+  if (!parseSvgViewBox(viewBox)) {
+    return { status: "error", message: `Invalid viewBox: '${viewBox}'` };
+  }
+
+  const variables = variableEntries(options);
+  const literals = options.literals ?? "forbid";
+  const overrides = parseOptions.overrides ?? {};
+  const unmatched = new Map<string, SvgUnmatchedColor>();
+  const droppedTags: string[] = [];
+  const droppedAttrs: SvgDroppedAttr[] = [];
+  const maxNodes = options.maxNodes ?? SVG_DEFAULT_MAX_NODES;
+  const maxDepth = options.maxDepth ?? SVG_DEFAULT_MAX_DEPTH;
+  let nodeCount = 0;
+  let exceeded = false;
+
+  const resolveColor = (raw: string): unknown | undefined => {
+    const trimmed = raw.trim();
+    // Read back the form svgToString emits, so "copy as svg" and re-paste is
+    // lossless rather than silently dropping every variable.
+    const varRef = /^var\(\s*--val-svg-([a-zA-Z0-9_-]+)\s*(?:,[^)]*)?\)$/.exec(
+      trimmed,
+    );
+    if (varRef) {
+      const name = varRef[1];
+      if (variables.some((v) => v.name === name)) {
+        return { var: name };
+      }
+    }
+    const keyword = SVG_KEYWORD_COLORS.find(
+      (k) => k.toLowerCase() === trimmed.toLowerCase(),
+    );
+    if (keyword) {
+      return keyword;
+    }
+    const normalized = normalizeColor(trimmed);
+    const key = normalized ?? trimmed;
+    const override = overrides[key];
+    if (override) {
+      if (override.type === "var") {
+        return { var: override.var };
+      }
+      if (override.type === "keyword") {
+        return override.keyword;
+      }
+      return normalized ?? trimmed;
+    }
+    if (normalized) {
+      const exact = variables.find(
+        (v) =>
+          v.normalized === normalized ||
+          v.matches.includes(normalized) ||
+          (v.keyword !== null &&
+            v.keyword.toLowerCase() === trimmed.toLowerCase()),
+      );
+      if (exact) {
+        return { var: exact.name };
+      }
+      let best: { name: string; distance: number } | null = null;
+      for (const variable of variables) {
+        if (variable.tolerance <= 0 || !variable.normalized) {
+          continue;
+        }
+        const distance = colorDistance(normalized, variable.normalized);
+        if (distance === null || distance > variable.tolerance) {
+          continue;
+        }
+        if (!best || distance < best.distance) {
+          best = { name: variable.name, distance };
+        }
+      }
+      if (best) {
+        return { var: best.name };
+      }
+    }
+    const canKeepLiteral =
+      literals === "allow" ||
+      (Array.isArray(literals) &&
+        (literals as readonly string[]).includes(normalized ?? trimmed));
+    if (canKeepLiteral) {
+      return normalized ?? trimmed;
+    }
+    const existing = unmatched.get(key);
+    if (existing) {
+      existing.count++;
+    } else {
+      unmatched.set(key, { raw: trimmed, normalized, count: 1 });
+    }
+    return undefined;
+  };
+
+  const convertAttrs = (
+    tag: SvgTag,
+    element: XmlElement,
+  ): Record<string, unknown> => {
+    const attrs: Record<string, unknown> = {};
+    for (const [rawName, rawValue] of Object.entries(element.attrs)) {
+      const name = rawName.toLowerCase();
+      if (!isAllowedSvgAttr(tag, name)) {
+        droppedAttrs.push({ tag, attr: rawName });
+        continue;
+      }
+      if ((SVG_COLOR_ATTRS as readonly string[]).includes(name)) {
+        const color = resolveColor(rawValue);
+        if (color !== undefined) {
+          attrs[name] = color;
+        }
+        continue;
+      }
+      if ((SVG_NUMBER_ATTRS as readonly string[]).includes(name)) {
+        const n = numberOf(rawValue);
+        if (n !== null) {
+          attrs[name] = n;
+        } else {
+          droppedAttrs.push({ tag, attr: rawName });
+        }
+        continue;
+      }
+      if (name in SVG_ENUM_ATTRS) {
+        const allowed = SVG_ENUM_ATTRS[
+          name as keyof typeof SVG_ENUM_ATTRS
+        ] as readonly string[];
+        const value = rawValue.trim();
+        if (allowed.includes(value)) {
+          attrs[name] = value;
+        } else {
+          droppedAttrs.push({ tag, attr: rawName });
+        }
+        continue;
+      }
+      if (name in SVG_STRING_ATTRS) {
+        const { pattern, maxLength } =
+          SVG_STRING_ATTRS[name as keyof typeof SVG_STRING_ATTRS];
+        const value = rawValue.trim();
+        if (value.length <= maxLength && pattern.test(value)) {
+          attrs[name] = value;
+        } else {
+          droppedAttrs.push({ tag, attr: rawName });
+        }
+        continue;
+      }
+      droppedAttrs.push({ tag, attr: rawName });
+    }
+    return attrs;
+  };
+
+  const convert = (elements: XmlElement[], depth: number): unknown[] => {
+    const nodes: unknown[] = [];
+    for (const element of elements) {
+      const tag = element.tag.toLowerCase();
+      if (!isSvgTag(tag)) {
+        if (!droppedTags.includes(element.tag)) {
+          droppedTags.push(element.tag);
+        }
+        continue;
+      }
+      if (depth > maxDepth) {
+        exceeded = true;
+        return nodes;
+      }
+      nodeCount++;
+      if (nodeCount > maxNodes) {
+        exceeded = true;
+        return nodes;
+      }
+      nodes.push({
+        tag,
+        attrs: convertAttrs(tag, element),
+        children: convert(element.children, depth + 1),
+      });
+    }
+    return nodes;
+  };
+
+  const children = convert(root.children, 1);
+  if (exceeded) {
+    return {
+      status: "error",
+      message: `The svg is too large: max is ${maxNodes} nodes and ${maxDepth} levels of nesting`,
+    };
+  }
+
+  const box = parseSvgViewBox(viewBox);
+  const source = {
+    viewBox,
+    width: widthAttr ?? box?.width ?? null,
+    height: heightAttr ?? box?.height ?? null,
+    children: children as SvgNode<O>[],
+  } as SvgSource<O>;
+
+  return {
+    status: "success",
+    source,
+    unmatched: Array.from(unmatched.values()),
+    droppedTags,
+    droppedAttrs,
+  };
+}
diff --git a/packages/shared/src/internal/svg/svgToString.ts b/packages/shared/src/internal/svg/svgToString.ts
new file mode 100644
index 000000000..f87c24088
--- /dev/null
+++ b/packages/shared/src/internal/svg/svgToString.ts
@@ -0,0 +1,150 @@
+import {
+  isSvgVarRef,
+  svgVariableValue,
+  GenericSvgNode,
+  GenericSvgSource,
+  SvgOptions,
+  SvgVariable,
+  SVG_COLOR_ATTRS,
+  SVG_VAL_PATH,
+} from "@valbuild/core";
+import { type JSONValue } from "@valbuild/core/patch";
+import { encodeXmlText } from "./xml";
+
+export type SvgToStringOptions = {
+  /**
+   * Resolve variables to concrete colors instead of `var(--val-svg-*)`.
+   * Pass the schema's variables to get markup that stands on its own - which is
+   * what "copy as svg" in the editor wants.
+   */
+  variables?: Record<string, SvgVariable>;
+  /** Indent the output. Off by default. */
+  pretty?: boolean;
+};
+
+function colorToAttrValue(
+  value: unknown,
+  variables: Record<string, SvgVariable> | undefined,
+): string | null {
+  if (isSvgVarRef(value)) {
+    const declared = variables?.[value.var];
+    if (declared !== undefined) {
+      return svgVariableValue(declared);
+    }
+    return `var(--val-svg-${value.var}, currentColor)`;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return null;
+}
+
+/**
+ * Serializes an svg source back to markup.
+ *
+ * The inverse of `parseSvg` for everything the allowlist keeps, so the two can
+ * be round-trip tested against each other.
+ */
+export function svgToString(
+  source: GenericSvgSource,
+  options: SvgToStringOptions = {},
+): string {
+  const { variables, pretty } = options;
+  const nl = pretty ? "\n" : "";
+  const pad = (depth: number) => (pretty ? "  ".repeat(depth) : "");
+
+  const renderNode = (node: GenericSvgNode, depth: number): string => {
+    const attrs: string[] = [];
+    for (const [name, value] of Object.entries(node.attrs ?? {})) {
+      const rendered = (SVG_COLOR_ATTRS as readonly string[]).includes(name)
+        ? colorToAttrValue(value, variables)
+        : typeof value === "number"
+          ? String(value)
+          : typeof value === "string"
+            ? value
+            : null;
+      if (rendered === null) {
+        continue;
+      }
+      attrs.push(`${name}="${encodeXmlText(rendered)}"`);
+    }
+    const open = [node.tag, ...attrs].join(" ");
+    const children = node.children ?? [];
+    if (children.length === 0) {
+      return `${pad(depth)}<${open}/>`;
+    }
+    const inner = children
+      .map((child) => renderNode(child, depth + 1))
+      .join(nl);
+    return `${pad(depth)}<${open}>${nl}${inner}${nl}${pad(depth)}</${node.tag}>`;
+  };
+
+  const rootAttrs = [
+    'xmlns="http://www.w3.org/2000/svg"',
+    `viewBox="${encodeXmlText(source.viewBox)}"`,
+  ];
+  if (source.width !== null && source.width !== undefined) {
+    rootAttrs.push(`width="${source.width}"`);
+  }
+  if (source.height !== null && source.height !== undefined) {
+    rootAttrs.push(`height="${source.height}"`);
+  }
+  const children = (source.children ?? [])
+    .map((child) => renderNode(child, 1))
+    .join(nl);
+  if (!children) {
+    return `<svg ${rootAttrs.join(" ")}/>`;
+  }
+  return `<svg ${rootAttrs.join(" ")}>${nl}${children}${nl}</svg>`;
+}
+
+/**
+ * Rebuilds an svg source as plain, mutable json.
+ *
+ * Patches are typed as `JSONValue`, while a source is `Json` (deeply readonly)
+ * and may carry the stega-injected path field. Rebuilding is how we bridge the
+ * two without a type assertion, and it drops `_valPath` on the way.
+ */
+export function svgSourceToJson(source: GenericSvgSource): JSONValue {
+  const node = (n: GenericSvgNode): JSONValue => {
+    const attrs: { [key: string]: JSONValue } = {};
+    for (const [name, value] of Object.entries(n.attrs ?? {})) {
+      if (typeof value === "string" || typeof value === "number") {
+        attrs[name] = value;
+      } else if (isSvgVarRef(value)) {
+        attrs[name] = { var: value.var };
+      }
+    }
+    return {
+      tag: n.tag,
+      attrs,
+      children: (n.children ?? []).map(node),
+    };
+  };
+  return {
+    viewBox: source.viewBox,
+    width: source.width ?? null,
+    height: source.height ?? null,
+    children: (source.children ?? []).map(node),
+  };
+}
+
+/**
+ * Strips the stega-injected path field, so a source can be compared or written
+ * back to a module.
+ */
+export function stripSvgValPath<T extends GenericSvgSource>(source: T): T {
+  if (!(SVG_VAL_PATH in source)) {
+    return source;
+  }
+  const copy = { ...source } as Record<string, unknown>;
+  delete copy[SVG_VAL_PATH];
+  return copy as T;
+}
+
+/** Convenience: the variables of a schema, in the shape `svgToString` wants. */
+export function svgVariablesOf(
+  options: SvgOptions | undefined,
+): Record<string, SvgVariable> | undefined {
+  return options?.variables;
+}
diff --git a/packages/shared/src/internal/svg/xml.ts b/packages/shared/src/internal/svg/xml.ts
new file mode 100644
index 000000000..e5fe74935
--- /dev/null
+++ b/packages/shared/src/internal/svg/xml.ts
@@ -0,0 +1,223 @@
+/**
+ * A minimal, dependency free XML reader, scoped to what an exported svg
+ * contains.
+ *
+ * We hand roll rather than take a dependency because `@valbuild/shared` ships
+ * into every Val user's server bundle and svg-as-xml is a small grammar: no
+ * optional end tags, no implicit closing, no raw text elements. `DOMParser` is
+ * deliberately not used - it does not exist in node or QuickJS, and two
+ * implementations would be two divergence surfaces.
+ *
+ * This reader is *not* a security boundary. Its output is filtered against the
+ * allowlist in `@valbuild/core` before anything else looks at it.
+ */
+
+export type XmlElement = {
+  tag: string;
+  attrs: Record<string, string>;
+  children: XmlElement[];
+};
+
+export type XmlParseResult =
+  | { status: "success"; root: XmlElement }
+  | { status: "error"; message: string };
+
+const ENTITIES: Readonly<Record<string, string>> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+};
+
+/**
+ * `String.fromCodePoint` THROWS a RangeError on anything outside 0..0x10FFFF,
+ * and `&#1114112;` / `&#x7FFFFFFF;` parse to finite numbers that are outside it.
+ * Since this runs on imported svg markup, an unguarded call turns a malformed
+ * entity into a crash in the middle of parsing. Leave an out-of-range entity as
+ * written instead: the surrounding validation reports the markup, the parser
+ * does not die on it.
+ */
+function codePointToString(code: number, match: string): string {
+  if (!Number.isInteger(code) || code < 0 || code > 0x10ffff) {
+    return match;
+  }
+  return String.fromCodePoint(code);
+}
+
+export function decodeXmlEntities(input: string): string {
+  return input.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (match, body) => {
+    // Lowercase `x` only, per the XML CharRef production - which is also all the
+    // regex above can match, so `&#X43;` is left as written.
+    if (body.startsWith("#x")) {
+      return codePointToString(parseInt(body.slice(2), 16), match);
+    }
+    if (body.startsWith("#")) {
+      return codePointToString(parseInt(body.slice(1), 10), match);
+    }
+    const named = ENTITIES[body as keyof typeof ENTITIES];
+    return named === undefined ? match : named;
+  });
+}
+
+export function encodeXmlText(input: string): string {
+  return input
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Parses xml and returns the single root element.
+ *
+ * Rejects entity declarations and doctypes with an internal subset outright:
+ * those are the XXE / billion-laughs vectors, and a parser that silently
+ * ignores them is worse than no parser at all.
+ */
+export function parseXml(input: string): XmlParseResult {
+  if (/<!ENTITY/i.test(input)) {
+    return {
+      status: "error",
+      message: "Entity declarations are not allowed",
+    };
+  }
+  let i = 0;
+  const src = input;
+  const stack: XmlElement[] = [];
+  let root: XmlElement | null = null;
+
+  const error = (message: string): XmlParseResult => ({
+    status: "error",
+    message,
+  });
+
+  while (i < src.length) {
+    const lt = src.indexOf("<", i);
+    if (lt === -1) {
+      break;
+    }
+    i = lt;
+    if (src.startsWith("<!--", i)) {
+      const end = src.indexOf("-->", i + 4);
+      if (end === -1) {
+        return error("Unterminated comment");
+      }
+      i = end + 3;
+      continue;
+    }
+    if (src.startsWith("<![CDATA[", i)) {
+      const end = src.indexOf("]]>", i + 9);
+      if (end === -1) {
+        return error("Unterminated CDATA section");
+      }
+      i = end + 3;
+      continue;
+    }
+    if (src.startsWith("<?", i)) {
+      const end = src.indexOf("?>", i + 2);
+      if (end === -1) {
+        return error("Unterminated processing instruction");
+      }
+      i = end + 2;
+      continue;
+    }
+    if (src.startsWith("<!", i)) {
+      // <!DOCTYPE ...>. An internal subset ('[' before '>') is rejected.
+      const gt = src.indexOf(">", i + 2);
+      const bracket = src.indexOf("[", i + 2);
+      if (gt === -1) {
+        return error("Unterminated declaration");
+      }
+      if (bracket !== -1 && bracket < gt) {
+        return error("Doctype with an internal subset is not allowed");
+      }
+      i = gt + 1;
+      continue;
+    }
+    if (src.startsWith("</", i)) {
+      const gt = src.indexOf(">", i + 2);
+      if (gt === -1) {
+        return error("Unterminated closing tag");
+      }
+      const tag = src.slice(i + 2, gt).trim();
+      const open = stack.pop();
+      if (!open) {
+        return error(`Unexpected closing tag '${tag}'`);
+      }
+      if (open.tag !== tag) {
+        return error(
+          `Mismatched closing tag: expected '${open.tag}', got '${tag}'`,
+        );
+      }
+      i = gt + 1;
+      continue;
+    }
+
+    // Opening tag. Scan to '>' while respecting quoted attribute values.
+    let j = i + 1;
+    let quote: string | null = null;
+    while (j < src.length) {
+      const ch = src[j];
+      if (quote) {
+        if (ch === quote) {
+          quote = null;
+        }
+      } else if (ch === '"' || ch === "'") {
+        quote = ch;
+      } else if (ch === ">") {
+        break;
+      }
+      j++;
+    }
+    if (j >= src.length) {
+      return error("Unterminated tag");
+    }
+    let body = src.slice(i + 1, j);
+    const selfClosing = body.trimEnd().endsWith("/");
+    if (selfClosing) {
+      body = body.trimEnd().slice(0, -1);
+    }
+    const nameMatch = /^([^\s/>]+)/.exec(body);
+    if (!nameMatch) {
+      return error("Malformed tag");
+    }
+    const tag = nameMatch[1];
+    const attrs: Record<string, string> = {};
+    const attrSrc = body.slice(nameMatch[1].length);
+    const attrRe = /([^\s=/]+)\s*(?:=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+    let attrMatch: RegExpExecArray | null;
+    while ((attrMatch = attrRe.exec(attrSrc)) !== null) {
+      const name = attrMatch[1];
+      if (!name) {
+        continue;
+      }
+      const raw = attrMatch[3] ?? attrMatch[4] ?? attrMatch[5] ?? "";
+      // Later duplicates lose, matching how browsers read xml attributes.
+      if (!(name in attrs)) {
+        attrs[name] = decodeXmlEntities(raw);
+      }
+    }
+    const element: XmlElement = { tag, attrs, children: [] };
+    const parent = stack[stack.length - 1];
+    if (parent) {
+      parent.children.push(element);
+    } else if (root) {
+      return error("Expected a single root element");
+    } else {
+      root = element;
+    }
+    if (!selfClosing) {
+      stack.push(element);
+    }
+    i = j + 1;
+  }
+
+  if (stack.length > 0) {
+    return error(`Unclosed tag '${stack[stack.length - 1].tag}'`);
+  }
+  if (!root) {
+    return error("No element found");
+  }
+  return { status: "success", root };
+}
diff --git a/packages/shared/src/internal/zod/SerializedSchema.ts b/packages/shared/src/internal/zod/SerializedSchema.ts
index 959178a68..761527ccf 100644
--- a/packages/shared/src/internal/zod/SerializedSchema.ts
+++ b/packages/shared/src/internal/zod/SerializedSchema.ts
@@ -18,6 +18,8 @@ import {
   type SerializedDateTimeSchema as SerializedDateTimeSchemaT,
   type SerializedColorSchema as SerializedColorSchemaT,
   type SerializedImageSchema as SerializedImageSchemaT,
+  type SerializedSvgSchema as SerializedSvgSchemaT,
+  type SvgOptions as SvgOptionsT,
 } from "@valbuild/core";
 import { SourcePath } from "./SourcePath";
 
@@ -177,6 +179,65 @@ export const SerializedRichTextSchema: z.ZodType<SerializedRichTextSchemaT> =
     hidden: z.boolean().optional(),
   });
 
+export const SvgVariable = z.union([
+  z.string(),
+  z.object({
+    value: z.string(),
+    match: z.array(z.string()).optional(),
+    tolerance: z.number().optional(),
+    description: z.string().optional(),
+  }),
+]);
+const SvgSizeConstraint = z.union([
+  z.number(),
+  z.object({ min: z.number().optional(), max: z.number().optional() }),
+]);
+/**
+ * `aspectRatio` is `number | \`${number}:${number}\`` in core. A plain
+ * `z.string()` parses to `string`, which is not assignable to the template
+ * literal - that mismatch is what used to force an `as any` on the whole
+ * options object, silencing every other field with it. Narrow just this one
+ * field instead.
+ */
+const SvgAspectRatio: z.ZodType<number | `${number}:${number}`> = z.union([
+  z.number(),
+  z.custom<`${number}:${number}`>(
+    (val) => {
+      if (typeof val !== "string") {
+        return false;
+      }
+      const parts = val.split(":");
+      // Mirrors `${number}:${number}`: two number-ish parts, so exotic but
+      // legal spellings ("1e3:2") parse rather than being rejected here.
+      return (
+        parts.length === 2 &&
+        parts.every((part) => part !== "" && Number.isFinite(Number(part)))
+      );
+    },
+    { message: 'Expected a number or a "w:h" ratio' },
+  ),
+]);
+export const SvgOptions: z.ZodType<SvgOptionsT> = z.object({
+  variables: z.record(z.string(), SvgVariable).optional(),
+  literals: z
+    .union([z.literal("forbid"), z.literal("allow"), z.array(z.string())])
+    .optional(),
+  width: SvgSizeConstraint.optional(),
+  height: SvgSizeConstraint.optional(),
+  aspectRatio: SvgAspectRatio.optional(),
+  maxNodes: z.number().optional(),
+  maxDepth: z.number().optional(),
+});
+export const SerializedSvgSchema: z.ZodType<SerializedSvgSchemaT> = z.object({
+  type: z.literal("svg"),
+  options: SvgOptions.optional(),
+  opt: z.boolean(),
+  customValidate: z.boolean().optional(),
+  readonly: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  description: z.string().optional(),
+});
+
 export const SerializedRecordSchema: z.ZodType<SerializedRecordSchemaT> =
   z.lazy(() => {
     return z
@@ -313,6 +374,7 @@ export const SerializedSchema: z.ZodType<SerializedSchemaT> = z.union([
   SerializedArraySchema,
   SerializedUnionSchema,
   SerializedRichTextSchema,
+  SerializedSvgSchema,
   SerializedRecordSchema,
   SerializedKeyOfSchema,
   SerializedRouteSchema,
diff --git a/packages/ui/spa/ValSyncEngine.ts b/packages/ui/spa/ValSyncEngine.ts
index 6d3a765cc..13f335cbb 100644
--- a/packages/ui/spa/ValSyncEngine.ts
+++ b/packages/ui/spa/ValSyncEngine.ts
@@ -5077,6 +5077,7 @@ const nonInterDependentTypes = [
   "dateTime",
   "color",
   "richtext",
+  "svg",
   "file",
   "image",
 ];
diff --git a/packages/ui/spa/components/AnyField.tsx b/packages/ui/spa/components/AnyField.tsx
index 925113b88..3ffabd963 100644
--- a/packages/ui/spa/components/AnyField.tsx
+++ b/packages/ui/spa/components/AnyField.tsx
@@ -7,6 +7,7 @@ import { NumberField } from "./fields/NumberField";
 import { ObjectFields } from "./fields/ObjectFields";
 import { RecordFields } from "./fields/RecordFields";
 import { RichTextField } from "./fields/RichTextField";
+import { SvgField } from "./fields/SvgField";
 import { RouteField } from "./fields/RouteField";
 import { StringField } from "./fields/StringField";
 import { UnionField } from "./fields/UnionField";
@@ -123,6 +124,8 @@ export function AnyField({
         {...leafProps}
       />
     );
+  } else if (schema.type === "svg") {
+    leaf = <SvgField key={path} path={path} {...leafProps} />;
   } else if (schema.type === "date") {
     leaf = <DateField key={path} path={path} {...leafProps} />;
   } else if (schema.type === "dateTime") {
diff --git a/packages/ui/spa/components/NodeIcon.tsx b/packages/ui/spa/components/NodeIcon.tsx
index b09007594..fb5af50e0 100644
--- a/packages/ui/spa/components/NodeIcon.tsx
+++ b/packages/ui/spa/components/NodeIcon.tsx
@@ -17,6 +17,7 @@ import {
   ToggleRight,
   HelpCircle,
   Layers,
+  Shapes,
 } from "lucide-react";
 
 export function NodeIcon({
@@ -47,6 +48,8 @@ export function NodeIcon({
       return <List size={size} className={className} />;
     case "union":
       return <Split size={size} className={className} />;
+    case "svg":
+      return <Shapes size={size} className={className} />;
     case "richtext":
       return <FileText size={size} className={className} />;
     case "record":
diff --git a/packages/ui/spa/components/Preview.tsx b/packages/ui/spa/components/Preview.tsx
index 762890a9d..4e14cee18 100644
--- a/packages/ui/spa/components/Preview.tsx
+++ b/packages/ui/spa/components/Preview.tsx
@@ -15,6 +15,7 @@ import { ColorPreview } from "./fields/ColorField";
 import { LiteralPreview } from "./fields/LiteralPreview";
 import { RecordPreview } from "./fields/RecordFields";
 import { RichTextPreview } from "./fields/RichTextField";
+import { SvgPreview } from "./fields/SvgField";
 import { FilePreview } from "./fields/FileField";
 import { Loader2 } from "lucide-react";
 
@@ -71,6 +72,8 @@ export function Preview({
     return <RecordPreview path={path} size={size} />;
   } else if (type === "richtext") {
     return <RichTextPreview path={path} />;
+  } else if (type === "svg") {
+    return <SvgPreview path={path} />;
   } else if (type === "file") {
     return <FilePreview path={path} />;
   } else {
diff --git a/packages/ui/spa/components/ValFieldProvider.tsx b/packages/ui/spa/components/ValFieldProvider.tsx
index 33e22b812..e11c6791f 100644
--- a/packages/ui/spa/components/ValFieldProvider.tsx
+++ b/packages/ui/spa/components/ValFieldProvider.tsx
@@ -24,6 +24,7 @@ import {
 import { Operation, Patch, FileOperation } from "@valbuild/core/patch";
 import { ParentRef } from "@valbuild/shared/internal";
 import { isJsonArray } from "../utils/isJsonArray";
+import { runtimeKind } from "../utils/runtimeKind";
 import { JsonEntriesProgress, ValSyncEngine } from "../ValSyncEngine";
 import { getNavPathFromAll } from "./getNavPath";
 import { z } from "zod";
@@ -983,6 +984,7 @@ type ShallowSource = {
   };
   literal: string;
   richtext: unknown[];
+  svg: { readonly [key: string]: Json };
 };
 
 function getShallowSourceAtSourcePath<
@@ -1101,6 +1103,17 @@ function mapSource<SchemaType extends SerializedSchema["type"]>(
       status: "success",
       data: source as ShallowSource[SchemaType],
     };
+  } else if (type === "svg") {
+    if (typeof source !== "object" || source === null || isJsonArray(source)) {
+      return {
+        status: "error",
+        error: `Expected svg (i.e. object), got ${runtimeKind(source)}`,
+      };
+    }
+    return {
+      status: "success",
+      data: source as ShallowSource[SchemaType],
+    };
   } else if (
     type === "date" ||
     type === "dateTime" ||
diff --git a/packages/ui/spa/components/ValProvider.tsx b/packages/ui/spa/components/ValProvider.tsx
index f3357f560..9f14cff8d 100644
--- a/packages/ui/spa/components/ValProvider.tsx
+++ b/packages/ui/spa/components/ValProvider.tsx
@@ -31,6 +31,7 @@ import {
   getNextAppRouterSourceFolder,
 } from "@valbuild/shared/internal";
 import { isJsonArray } from "../utils/isJsonArray";
+import { runtimeKind } from "../utils/runtimeKind";
 import { AuthenticationState, useStatus } from "../hooks/useStatus";
 import { findRequiredRemoteFiles } from "../utils/findRequiredRemoteFiles";
 import { defaultOverlayEmitter, ValSyncEngine } from "../ValSyncEngine";
@@ -1419,6 +1420,7 @@ export type ShallowSource = EnsureAllTypes<{
   };
   literal: string;
   richtext: unknown[];
+  svg: { readonly [key: string]: Json };
 }>;
 
 export function useCurrentProfile() {
@@ -1833,6 +1835,17 @@ function mapSource<SchemaType extends SerializedSchema["type"]>(
       status: "success",
       data: source as ShallowSource[SchemaType],
     };
+  } else if (type === "svg") {
+    if (typeof source !== "object" || source === null || isJsonArray(source)) {
+      return {
+        status: "error",
+        error: `Expected svg (i.e. object), got ${runtimeKind(source)}`,
+      };
+    }
+    return {
+      status: "success",
+      data: source as ShallowSource[SchemaType],
+    };
   } else if (
     type === "date" ||
     type === "dateTime" ||
diff --git a/packages/ui/spa/components/fields/SvgField.stories.tsx b/packages/ui/spa/components/fields/SvgField.stories.tsx
new file mode 100644
index 000000000..a3f6d48a1
--- /dev/null
+++ b/packages/ui/spa/components/fields/SvgField.stories.tsx
@@ -0,0 +1,204 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { SerializedSvgSchema } from "@valbuild/core";
+import { useState } from "react";
+import { SvgColorMapper, SvgEditor, SvgRender } from "./SvgField";
+import type { GenericSvgSource } from "@valbuild/core";
+
+const iconSchema: SerializedSvgSchema = {
+  type: "svg",
+  opt: false,
+  options: {
+    width: 24,
+    height: 24,
+    aspectRatio: "1:1",
+    variables: {
+      brand: "#0055ff",
+      line: "#1f2933",
+      surface: { value: "#ffffff", match: ["#fefefe"] },
+    },
+  },
+};
+
+const bell: GenericSvgSource = {
+  viewBox: "0 0 24 24",
+  width: 24,
+  height: 24,
+  children: [
+    {
+      tag: "path",
+      attrs: {
+        d: "M12 2.5A5.5 5.5 0 0 0 6.5 8v4.2L4.8 15.2a.6.6 0 0 0 .52.9h13.36a.6.6 0 0 0 .52-.9L17.5 12.2V8A5.5 5.5 0 0 0 12 2.5Z",
+        fill: { var: "brand" },
+      },
+      children: [],
+    },
+    {
+      tag: "path",
+      attrs: {
+        d: "M9.6 18.5a2.4 2.4 0 0 0 4.8 0",
+        stroke: { var: "line" },
+        "stroke-width": 1.6,
+        "stroke-linecap": "round",
+        fill: "none",
+      },
+      children: [],
+    },
+    {
+      tag: "circle",
+      attrs: { cx: 17.5, cy: 6, r: 2.6, fill: { var: "surface" } },
+      children: [],
+    },
+  ],
+};
+
+const meta: Meta<typeof SvgEditor> = {
+  title: "Fields/SvgField",
+  component: SvgEditor,
+  parameters: { layout: "padded" },
+};
+export default meta;
+
+/**
+ * The default, and what an editor sees almost every time: just the icon, the
+ * palette it uses, and a dark mode toggle. Icons are read far more often than
+ * they are replaced, so nothing else is on screen until you drop an svg on the
+ * tile, paste markup into it, or click it to pick a file.
+ */
+export const WithIcon: StoryObj<typeof SvgEditor> = {
+  render: () => {
+    const [source, setSource] = useState<GenericSvgSource | null>(bell);
+    return (
+      <div className="max-w-2xl">
+        <SvgEditor schema={iconSchema} source={source} onChange={setSource} />
+      </div>
+    );
+  },
+};
+
+/** An empty field. The tile is the drop target and the file picker. */
+export const Empty: StoryObj<typeof SvgEditor> = {
+  render: () => {
+    const [source, setSource] = useState<GenericSvgSource | null>(null);
+    return (
+      <div className="max-w-2xl">
+        <SvgEditor schema={iconSchema} source={source} onChange={setSource} />
+      </div>
+    );
+  },
+};
+
+/** Read only: the tile is inert, and the icon is all there is. */
+export const Readonly: StoryObj<typeof SvgEditor> = {
+  render: () => (
+    <div className="max-w-2xl">
+      <SvgEditor
+        schema={iconSchema}
+        source={bell}
+        onChange={() => {}}
+        readonly
+      />
+    </div>
+  ),
+};
+
+/**
+ * Dropping an export whose colors are not in the palette. The mapping controls
+ * appear only now, and the icon is not committed until every color has
+ * somewhere to go - a half mapped icon would silently lose fills.
+ *
+ * Copy the markup below and paste it onto the tile to drive it yourself.
+ */
+export const UnmatchedColors: StoryObj<typeof SvgEditor> = {
+  render: () => {
+    const [source, setSource] = useState<GenericSvgSource | null>(null);
+    return (
+      <div className="max-w-2xl">
+        <SvgEditor schema={iconSchema} source={source} onChange={setSource} />
+        <p className="mt-4 text-xs text-text-secondary">
+          Paste this onto the tile:
+        </p>
+        <pre className="mt-1 p-2 text-xs bg-bg-secondary rounded overflow-x-auto">
+          {`<svg width="24" height="24" viewBox="0 0 24 24">
+  <circle cx="12" cy="12" r="10" fill="#ff5c00"/>
+  <path d="M8 12h8" stroke="#123456" stroke-width="2"/>
+</svg>`}
+        </pre>
+      </div>
+    );
+  },
+};
+
+/** The color mapper on its own, with two colors still to place. */
+export const ColorMapper: StoryObj<typeof SvgColorMapper> = {
+  render: () => {
+    const [value, setValue] = useState({});
+    return (
+      <div className="max-w-2xl">
+        <SvgColorMapper
+          unmatched={[
+            { raw: "#ff5c00", normalized: "#ff5c00", count: 3 },
+            { raw: "#123456", normalized: "#123456", count: 1 },
+          ]}
+          variables={iconSchema.options?.variables ?? {}}
+          value={value}
+          onChange={setValue}
+          allowLiterals
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * The same source at several sizes, and with the variables overridden - which
+ * is what `<ValSvg vars={...} />` and a dark mode stylesheet each do.
+ */
+export const Rendering: StoryObj<typeof SvgRender> = {
+  render: () => {
+    const variables = iconSchema.options?.variables ?? {};
+    return (
+      <div className="flex flex-col gap-6">
+        <div className="flex items-end gap-4">
+          {[16, 24, 32, 48, 64].map((size) => (
+            <div key={size} className="flex flex-col items-center gap-1">
+              <SvgRender source={bell} variables={variables} size={size} />
+              <span className="text-xs text-text-secondary">{size}px</span>
+            </div>
+          ))}
+        </div>
+        <div className="flex items-center gap-4">
+          <div className="flex flex-col items-center gap-1 p-3 rounded bg-white">
+            <SvgRender source={bell} variables={variables} size={48} />
+            <span className="text-xs text-black">example colors</span>
+          </div>
+          <div className="flex flex-col items-center gap-1 p-3 rounded bg-black">
+            <SvgRender
+              source={bell}
+              variables={variables}
+              overrides={{
+                brand: "#6699ff",
+                line: "#e5e7eb",
+                surface: "#111111",
+              }}
+              size={48}
+            />
+            <span className="text-xs text-white">dark mode</span>
+          </div>
+          <div className="flex flex-col items-center gap-1 p-3 rounded bg-white">
+            <SvgRender
+              source={bell}
+              variables={variables}
+              overrides={{
+                brand: "#dc2626",
+                line: "#7f1d1d",
+                surface: "#fee2e2",
+              }}
+              size={48}
+            />
+            <span className="text-xs text-black">vars override</span>
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/packages/ui/spa/components/fields/SvgField.tsx b/packages/ui/spa/components/fields/SvgField.tsx
new file mode 100644
index 000000000..bed821b99
--- /dev/null
+++ b/packages/ui/spa/components/fields/SvgField.tsx
@@ -0,0 +1,719 @@
+import {
+  isSvgVarRef,
+  svgVariableValue,
+  GenericSvgNode,
+  GenericSvgSource,
+  SerializedSvgSchema,
+  SourcePath,
+  SvgVariable,
+  SVG_COLOR_ATTRS,
+} from "@valbuild/core";
+import {
+  parseSvg,
+  svgSourceToJson,
+  svgToString,
+  type SvgColorOverride,
+  type SvgUnmatchedColor,
+} from "@valbuild/shared/internal";
+import React, { useMemo, useRef, useState } from "react";
+import { Button } from "../designSystem/button";
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "../designSystem/accordion";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../designSystem/select";
+import { cn } from "../designSystem/cn";
+import { FieldLoading } from "../FieldLoading";
+import { FieldNotFound } from "../FieldNotFound";
+import { FieldSchemaError } from "../FieldSchemaError";
+import { FieldSchemaMismatchError } from "../FieldSchemaMismatchError";
+import { FieldSourceError } from "../FieldSourceError";
+import { PreviewLoading, PreviewNull } from "../Preview";
+import { ValidationErrors } from "../ValidationError";
+import {
+  useAddPatch,
+  useSchemaAtPath,
+  useShallowSourceAtPath,
+} from "../ValFieldProvider";
+
+const KEYWORD_OPTIONS = ["currentColor", "none", "transparent"] as const;
+
+type Variables = Record<string, SvgVariable>;
+
+function isSvgSource(source: unknown): source is GenericSvgSource {
+  return (
+    typeof source === "object" &&
+    source !== null &&
+    !Array.isArray(source) &&
+    typeof (source as { viewBox?: unknown }).viewBox === "string"
+  );
+}
+
+function colorAttrValue(
+  value: unknown,
+  resolved: Record<string, string>,
+): string | null {
+  if (isSvgVarRef(value)) {
+    // The editor resolves variables eagerly so the preview shows real colors
+    // rather than unresolved custom properties.
+    return resolved[value.var] ?? `var(--val-svg-${value.var}, currentColor)`;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return null;
+}
+
+function buildNode(
+  node: GenericSvgNode,
+  key: number,
+  resolved: Record<string, string>,
+): React.ReactElement | null {
+  if (!node || typeof node !== "object" || typeof node.tag !== "string") {
+    return null;
+  }
+  const props: Record<string, unknown> = { key };
+  for (const [name, value] of Object.entries(node.attrs ?? {})) {
+    if ((SVG_COLOR_ATTRS as readonly string[]).includes(name)) {
+      const color = colorAttrValue(value, resolved);
+      if (color !== null) {
+        props[name] = color;
+      }
+      continue;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+      props[name] = value;
+    }
+  }
+  const children = (node.children ?? [])
+    .map((child, i) => buildNode(child, i, resolved))
+    .filter((child): child is React.ReactElement => child !== null);
+  return React.createElement(
+    node.tag,
+    props,
+    children.length > 0 ? children : undefined,
+  );
+}
+
+/**
+ * Renders an svg source.
+ *
+ * A separate implementation from `ValSvg` in `@valbuild/react`, which the
+ * editor cannot depend on - and which resolves variables through css rather
+ * than eagerly, as the preview needs to.
+ */
+export function SvgRender({
+  source,
+  variables,
+  overrides,
+  size,
+  className,
+}: {
+  source: GenericSvgSource;
+  variables?: Variables;
+  /** Per-variable color overrides, e.g. a dark mode preview. */
+  overrides?: Record<string, string>;
+  size?: number;
+  className?: string;
+}) {
+  const resolved = useMemo(() => {
+    const map: Record<string, string> = {};
+    for (const [name, variable] of Object.entries(variables ?? {})) {
+      map[name] = svgVariableValue(variable);
+    }
+    return { ...map, ...overrides };
+  }, [variables, overrides]);
+  if (!isSvgSource(source)) {
+    return null;
+  }
+  const children = (source.children ?? [])
+    .map((child, i) => buildNode(child, i, resolved))
+    .filter((child): child is React.ReactElement => child !== null);
+  return React.createElement(
+    "svg",
+    {
+      xmlns: "http://www.w3.org/2000/svg",
+      viewBox: source.viewBox,
+      width: size ?? source.width ?? undefined,
+      height: size ?? source.height ?? undefined,
+      role: "presentation",
+      "aria-hidden": true,
+      className,
+    },
+    children,
+  );
+}
+
+/**
+ * One row per color the import could not place, with the colors it is allowed
+ * to become.
+ *
+ * We never snap a color to the nearest variable on our own: a brand color that
+ * is quietly rewritten is worse than one the editor is asked about. A variable
+ * can opt in to fuzzy matching with `tolerance`, and then it never reaches
+ * here.
+ */
+export function SvgColorMapper({
+  unmatched,
+  variables,
+  value,
+  onChange,
+  allowLiterals,
+}: {
+  unmatched: SvgUnmatchedColor[];
+  variables: Variables;
+  value: Record<string, SvgColorOverride>;
+  onChange: (next: Record<string, SvgColorOverride>) => void;
+  allowLiterals: boolean;
+}) {
+  if (unmatched.length === 0) {
+    return null;
+  }
+  const variableNames = Object.keys(variables);
+  const remaining = unmatched.filter(
+    (color) => value[color.normalized ?? color.raw] === undefined,
+  ).length;
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="text-sm text-text-secondary">
+        {remaining === 0
+          ? "All colors mapped."
+          : remaining === 1
+            ? "1 color is not in the palette. Pick what it should become:"
+            : `${remaining} colors are not in the palette. Pick what they should become:`}
+      </div>
+      {unmatched.map((color) => {
+        const key = color.normalized ?? color.raw;
+        const current = value[key];
+        const selected =
+          current === undefined
+            ? ""
+            : current.type === "var"
+              ? `var:${current.var}`
+              : current.type === "keyword"
+                ? `keyword:${current.keyword}`
+                : "literal";
+        return (
+          <div key={key} className="flex items-center gap-2">
+            <span
+              className="w-6 h-6 rounded border border-border-primary shrink-0"
+              // `color.raw` is arbitrary text out of imported markup, and
+              // `background` is a shorthand that also takes `url(...)` and
+              // gradients - so a hostile (or merely odd) fill would render as an
+              // external request from inside the editor. Paint `backgroundColor`
+              // instead, and only from `normalized`, which is always a plain
+              // `#rrggbb[aa]` produced by our own parser. An unparseable color
+              // gets an empty swatch; its text is right beside it.
+              style={
+                color.normalized
+                  ? { backgroundColor: color.normalized }
+                  : undefined
+              }
+              title={color.raw}
+            />
+            <code className="text-xs w-24 shrink-0">{color.raw}</code>
+            <span className="text-xs text-text-secondary w-16 shrink-0">
+              {color.count === 1 ? "1 use" : `${color.count} uses`}
+            </span>
+            <Select
+              value={selected}
+              onValueChange={(next) => {
+                let override: SvgColorOverride;
+                if (next.startsWith("var:")) {
+                  override = { type: "var", var: next.slice("var:".length) };
+                } else if (next.startsWith("keyword:")) {
+                  override = {
+                    type: "keyword",
+                    keyword: next.slice(
+                      "keyword:".length,
+                    ) as (typeof KEYWORD_OPTIONS)[number],
+                  };
+                } else {
+                  override = { type: "literal" };
+                }
+                onChange({ ...value, [key]: override });
+              }}
+            >
+              <SelectTrigger className="w-56">
+                <SelectValue placeholder="Choose a color" />
+              </SelectTrigger>
+              <SelectContent>
+                {variableNames.map((name) => (
+                  <SelectItem key={name} value={`var:${name}`}>
+                    <span className="inline-flex items-center gap-2">
+                      <span
+                        className="w-3 h-3 rounded-sm border border-border-primary"
+                        // `backgroundColor`, not the `background` shorthand, for
+                        // the same reason as the swatch above - though this value
+                        // comes from the schema author's own `variables`, not
+                        // from imported markup.
+                        style={{
+                          backgroundColor: svgVariableValue(variables[name]),
+                        }}
+                      />
+                      {name}
+                    </span>
+                  </SelectItem>
+                ))}
+                {KEYWORD_OPTIONS.map((keyword) => (
+                  <SelectItem key={keyword} value={`keyword:${keyword}`}>
+                    {keyword}
+                  </SelectItem>
+                ))}
+                {allowLiterals && (
+                  <SelectItem value="literal">Keep {color.raw}</SelectItem>
+                )}
+              </SelectContent>
+            </Select>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * The tile an icon lives in, and the only thing on screen most of the time.
+ *
+ * Icons are read far more often than they are replaced, so the tile *is* the
+ * control: drop an svg on it, paste markup into it, or click it to pick a file.
+ * Nothing else is rendered until one of those happens.
+ */
+export function SvgDropTile({
+  source,
+  pending,
+  variables,
+  overrides,
+  readonly,
+  onMarkup,
+  onFile,
+}: {
+  source: GenericSvgSource | null;
+  /** The icon shown is an import in progress, not what is stored. */
+  pending?: boolean;
+  variables: Variables;
+  overrides?: Record<string, string>;
+  readonly?: boolean;
+  onMarkup: (markup: string) => void;
+  onFile: (file: File) => void;
+}) {
+  const [dragging, setDragging] = useState(false);
+  const fileInput = useRef<HTMLInputElement>(null);
+  const interactive = !readonly;
+  return (
+    <div
+      role={interactive ? "button" : undefined}
+      tabIndex={interactive ? 0 : undefined}
+      aria-label={
+        interactive
+          ? "Icon. Drop an svg file, paste svg markup, or press enter to choose a file."
+          : undefined
+      }
+      className={cn(
+        "relative flex items-center justify-center w-24 h-24 rounded-md border shrink-0 transition-colors",
+        overrides ? "bg-black text-white" : "bg-bg-primary",
+        dragging
+          ? "border-border-brand-primary border-dashed bg-bg-secondary"
+          : pending
+            ? "border-border-brand-primary border-dashed"
+            : "border-border-primary",
+        interactive &&
+          "cursor-pointer hover:border-border-brand-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      )}
+      onClick={() => interactive && fileInput.current?.click()}
+      onKeyDown={(ev) => {
+        if (interactive && (ev.key === "Enter" || ev.key === " ")) {
+          ev.preventDefault();
+          fileInput.current?.click();
+        }
+      }}
+      onPaste={(ev) => {
+        if (!interactive) return;
+        const text = ev.clipboardData.getData("text");
+        const file = Array.from(ev.clipboardData.files)[0];
+        if (file) {
+          ev.preventDefault();
+          onFile(file);
+        } else if (text.trim()) {
+          ev.preventDefault();
+          onMarkup(text);
+        }
+      }}
+      onDragOver={(ev) => {
+        if (!interactive) return;
+        ev.preventDefault();
+        setDragging(true);
+      }}
+      onDragLeave={() => setDragging(false)}
+      onDrop={(ev) => {
+        if (!interactive) return;
+        ev.preventDefault();
+        setDragging(false);
+        const file = Array.from(ev.dataTransfer.files)[0];
+        if (file) {
+          onFile(file);
+          return;
+        }
+        const text = ev.dataTransfer.getData("text");
+        if (text.trim()) {
+          onMarkup(text);
+        }
+      }}
+    >
+      {source ? (
+        <SvgRender
+          source={source}
+          variables={variables}
+          overrides={overrides}
+          size={48}
+        />
+      ) : (
+        <span className="px-2 text-xs text-center text-text-secondary">
+          Drop or paste an svg
+        </span>
+      )}
+      {dragging && (
+        <span className="absolute inset-0 flex items-center justify-center px-2 text-xs text-center rounded-md bg-bg-primary/80 text-text-primary">
+          Drop to replace
+        </span>
+      )}
+      <input
+        ref={fileInput}
+        type="file"
+        accept="image/svg+xml,.svg"
+        className="hidden"
+        onChange={(ev) => {
+          const file = ev.target.files?.[0];
+          if (file) {
+            onFile(file);
+          }
+          ev.target.value = "";
+        }}
+      />
+    </div>
+  );
+}
+
+/**
+ * The presentational half of the svg field: an icon you can drop onto, and the
+ * mapping controls that appear only when an import needs a decision.
+ *
+ * Kept free of Val providers so it can be driven from storybook and tests.
+ */
+export function SvgEditor({
+  schema,
+  source,
+  onChange,
+  readonly,
+}: {
+  schema: SerializedSvgSchema;
+  source: GenericSvgSource | null;
+  onChange: (source: GenericSvgSource) => void;
+  readonly?: boolean;
+}) {
+  const variables = (schema.options?.variables ?? {}) as Variables;
+  const literals = schema.options?.literals ?? "forbid";
+  const [markup, setMarkup] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [notes, setNotes] = useState<string[]>([]);
+  const [unmatched, setUnmatched] = useState<SvgUnmatchedColor[]>([]);
+  const [overrides, setOverrides] = useState<Record<string, SvgColorOverride>>(
+    {},
+  );
+  const [dark, setDark] = useState(false);
+
+  /**
+   * The icon being imported, shown in the tile while its colors are mapped.
+   *
+   * Unmapped colors are previewed as they came in - an explicit `literal`
+   * override keeps a color whatever the schema's `literals` says - so you can
+   * see the icon you dropped, and watch it move onto the palette as you pick.
+   */
+  const pending = useMemo(() => {
+    if (markup === null || unmatched.length === 0) {
+      return null;
+    }
+    const asLiterals: Record<string, SvgColorOverride> = {};
+    for (const color of unmatched) {
+      asLiterals[color.normalized ?? color.raw] = { type: "literal" };
+    }
+    const result = parseSvg(markup, schema.options ?? {}, {
+      overrides: { ...asLiterals, ...overrides },
+    });
+    return result.status === "success"
+      ? (result.source as unknown as GenericSvgSource)
+      : null;
+  }, [markup, unmatched, overrides, schema.options]);
+
+  const darkOverrides = useMemo(() => {
+    if (!dark) {
+      return undefined;
+    }
+    // Stands in for the app's dark mode stylesheet, so it is obvious which
+    // parts of the icon are actually themeable.
+    const map: Record<string, string> = {};
+    for (const name of Object.keys(variables)) {
+      map[name] = "#f5f5f5";
+    }
+    return map;
+  }, [dark, variables]);
+
+  const runImport = (
+    input: string,
+    colorOverrides: Record<string, SvgColorOverride>,
+  ) => {
+    const result = parseSvg(input, schema.options ?? {}, {
+      overrides: colorOverrides,
+    });
+    if (result.status === "error") {
+      setError(result.message);
+      setUnmatched([]);
+      setNotes([]);
+      return;
+    }
+    setError(null);
+    setUnmatched(result.unmatched);
+    const nextNotes: string[] = [];
+    if (result.droppedTags.length > 0) {
+      nextNotes.push(`Removed unsupported: ${result.droppedTags.join(", ")}`);
+    }
+    if (result.droppedAttrs.length > 0) {
+      const attrs = Array.from(new Set(result.droppedAttrs.map((a) => a.attr)));
+      nextNotes.push(`Removed attributes: ${attrs.join(", ")}`);
+    }
+    setNotes(nextNotes);
+    // Only commit once every color has somewhere to go: a half mapped icon
+    // would silently lose fills.
+    if (result.unmatched.length === 0) {
+      setMarkup(null);
+      onChange(result.source as unknown as GenericSvgSource);
+    }
+  };
+
+  const onNewMarkup = (input: string) => {
+    if (!input.trim()) {
+      setError("That does not look like svg markup");
+      return;
+    }
+    setMarkup(input);
+    setOverrides({});
+    runImport(input, {});
+  };
+
+  const onNewFile = (file: File) => {
+    // Read as text: an svg field stores the tree in the module, so there is no
+    // binary to upload and no file op to create.
+    const reader = new FileReader();
+    reader.onerror = () => setError(`Could not read ${file.name}`);
+    reader.onload = () => onNewMarkup(String(reader.result ?? ""));
+    reader.readAsText(file);
+  };
+
+  const onOverridesChange = (next: Record<string, SvgColorOverride>) => {
+    setOverrides(next);
+    const allChosen = unmatched.every(
+      (color) => next[color.normalized ?? color.raw] !== undefined,
+    );
+    if (allChosen && markup !== null) {
+      runImport(markup, next);
+    }
+  };
+
+  const hasFeedback =
+    error !== null || notes.length > 0 || unmatched.length > 0;
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-start gap-4">
+        <SvgDropTile
+          source={pending ?? source}
+          pending={pending !== null}
+          variables={variables}
+          overrides={darkOverrides}
+          readonly={readonly}
+          onMarkup={onNewMarkup}
+          onFile={onNewFile}
+        />
+        {source && (
+          <div className="flex flex-col gap-2 pt-1 text-xs text-text-secondary">
+            <span>
+              <code>{source.viewBox}</code>
+            </span>
+            <div className="flex flex-wrap gap-2">
+              {Object.entries(variables).map(([name, variable]) => (
+                <span
+                  key={name}
+                  className="inline-flex items-center gap-1"
+                  title={svgVariableValue(variable)}
+                >
+                  <span
+                    className="w-3 h-3 rounded-sm border border-border-primary"
+                    style={{
+                      background:
+                        darkOverrides?.[name] ?? svgVariableValue(variable),
+                    }}
+                  />
+                  {name}
+                </span>
+              ))}
+            </div>
+            <button
+              type="button"
+              className="self-start underline underline-offset-2"
+              onClick={() => setDark((d) => !d)}
+            >
+              {dark ? "Preview light" : "Preview dark"}
+            </button>
+          </div>
+        )}
+      </div>
+      {error && <div className="text-sm text-text-error">{error}</div>}
+      {notes.map((note) => (
+        <div key={note} className="text-xs text-text-secondary">
+          {note}
+        </div>
+      ))}
+      <SvgColorMapper
+        unmatched={unmatched}
+        variables={variables}
+        value={overrides}
+        onChange={onOverridesChange}
+        allowLiterals={literals === "allow" || Array.isArray(literals)}
+      />
+      {unmatched.length > 0 && (
+        <div>
+          <Button
+            type="button"
+            size="sm"
+            variant="secondary"
+            onClick={() => {
+              setMarkup(null);
+              setUnmatched([]);
+              setOverrides({});
+              setNotes([]);
+              setError(null);
+            }}
+          >
+            Cancel import
+          </Button>
+        </div>
+      )}
+      {source && !hasFeedback && (
+        <Accordion type="single" collapsible>
+          <AccordionItem value="markup" className="border-b-0">
+            <AccordionTrigger className="py-1 text-xs text-text-secondary">
+              Markup
+            </AccordionTrigger>
+            <AccordionContent>
+              <pre className="p-2 overflow-x-auto text-xs rounded bg-bg-secondary">
+                {svgToString(source, { variables, pretty: true })}
+              </pre>
+            </AccordionContent>
+          </AccordionItem>
+        </Accordion>
+      )}
+    </div>
+  );
+}
+
+export function SvgField({
+  path,
+  readonly,
+}: {
+  path: SourcePath;
+  readonly?: boolean;
+  compact?: boolean;
+  autoFocus?: boolean;
+}) {
+  const type = "svg";
+  const schemaAtPath = useSchemaAtPath(path);
+  const sourceAtPath = useShallowSourceAtPath(path, type);
+  const { patchPath, addPatch } = useAddPatch(path);
+  if (schemaAtPath.status === "error") {
+    return (
+      <FieldSchemaError path={path} error={schemaAtPath.error} type={type} />
+    );
+  }
+  if (sourceAtPath.status === "error") {
+    return (
+      <FieldSourceError
+        path={path}
+        error={sourceAtPath.error}
+        schema={schemaAtPath}
+      />
+    );
+  }
+  if (
+    sourceAtPath.status == "not-found" ||
+    schemaAtPath.status === "not-found"
+  ) {
+    return <FieldNotFound path={path} type={type} />;
+  }
+  if (schemaAtPath.status === "loading") {
+    return <FieldLoading path={path} type={type} />;
+  }
+  if (!("data" in sourceAtPath) || sourceAtPath.data === undefined) {
+    return <FieldLoading path={path} type={type} />;
+  }
+  if (schemaAtPath.data.type !== type) {
+    return (
+      <FieldSchemaMismatchError
+        path={path}
+        expectedType={type}
+        actualType={schemaAtPath.data.type}
+      />
+    );
+  }
+  const source = sourceAtPath.data;
+  return (
+    <div id={path} className={cn(readonly && "opacity-70")}>
+      <ValidationErrors path={path} />
+      <SvgEditor
+        schema={schemaAtPath.data}
+        source={isSvgSource(source) ? source : null}
+        readonly={readonly}
+        onChange={(next) => {
+          if (readonly) return;
+          // The tree is replaced whole on import: a partial patch of a freshly
+          // pasted icon would be meaningless.
+          addPatch(
+            [{ op: "replace", path: patchPath, value: svgSourceToJson(next) }],
+            type,
+          );
+        }}
+      />
+    </div>
+  );
+}
+
+export function SvgPreview({ path }: { path: SourcePath }) {
+  const schemaAtPath = useSchemaAtPath(path);
+  const sourceAtPath = useShallowSourceAtPath(path, "svg");
+  if (!("data" in sourceAtPath) || sourceAtPath.data === undefined) {
+    return <PreviewLoading path={path} />;
+  }
+  const source = sourceAtPath.data;
+  if (!isSvgSource(source)) {
+    return <PreviewNull path={path} />;
+  }
+  const variables =
+    "data" in schemaAtPath && schemaAtPath.data?.type === "svg"
+      ? ((schemaAtPath.data.options?.variables ?? {}) as Variables)
+      : {};
+  return (
+    <SvgRender
+      source={source}
+      variables={variables}
+      size={20}
+      className="inline-block"
+    />
+  );
+}
diff --git a/packages/ui/spa/components/fields/emptyOf.ts b/packages/ui/spa/components/fields/emptyOf.ts
index d1237585d..63380d3d9 100644
--- a/packages/ui/spa/components/fields/emptyOf.ts
+++ b/packages/ui/spa/components/fields/emptyOf.ts
@@ -49,6 +49,13 @@ export function emptyOf(schema: SerializedSchema): Json {
     return null;
   } else if (schema.type === "richtext") {
     return [];
+  } else if (schema.type === "svg") {
+    return {
+      viewBox: "0 0 24 24",
+      width: null,
+      height: null,
+      children: [],
+    };
   } else if (schema.type === "string") {
     return "";
   } else if (schema.type === "boolean") {
diff --git a/packages/ui/spa/components/getKeysOf.ts b/packages/ui/spa/components/getKeysOf.ts
index 371636c1a..66e08a5eb 100644
--- a/packages/ui/spa/components/getKeysOf.ts
+++ b/packages/ui/spa/components/getKeysOf.ts
@@ -61,6 +61,7 @@ export function getKeysOf(
       schema.type === "image" ||
       schema.type === "file" ||
       schema.type === "richtext" ||
+      schema.type === "svg" ||
       schema.type === "route"
     ) {
       // ignore these
diff --git a/packages/ui/spa/components/getReferencedFiles.ts b/packages/ui/spa/components/getReferencedFiles.ts
index 69d005b3c..0dad59d28 100644
--- a/packages/ui/spa/components/getReferencedFiles.ts
+++ b/packages/ui/spa/components/getReferencedFiles.ts
@@ -49,6 +49,7 @@ export function getReferencedFiles(
       schema.type === "image" ||
       schema.type === "file" ||
       schema.type === "richtext" ||
+      schema.type === "svg" ||
       schema.type === "route"
     ) {
       // ignore these
diff --git a/packages/ui/spa/components/jsonValuesLoadRequirements.ts b/packages/ui/spa/components/jsonValuesLoadRequirements.ts
index 69bb9353e..dff2654d1 100644
--- a/packages/ui/spa/components/jsonValuesLoadRequirements.ts
+++ b/packages/ui/spa/components/jsonValuesLoadRequirements.ts
@@ -143,6 +143,7 @@ function containsReferrer(
     case "date":
     case "dateTime":
     case "color":
+    case "svg":
     case "richtext":
       return false;
     default: {
diff --git a/packages/ui/spa/resolvePatchPath.ts b/packages/ui/spa/resolvePatchPath.ts
index 331ea933d..cdc99e4eb 100644
--- a/packages/ui/spa/resolvePatchPath.ts
+++ b/packages/ui/spa/resolvePatchPath.ts
@@ -263,13 +263,16 @@ export function resolvePatchPath(
       }
       currentSource = currentObjectSourceRes.source[part];
       addPart(JSON.stringify(part));
-    } else if (currentSchema.type === "richtext") {
+    } else if (
+      currentSchema.type === "richtext" ||
+      currentSchema.type === "svg"
+    ) {
       for (const part of patchPath.slice(i)) {
         i++;
         if (currentSource === null) {
           return {
             success: false,
-            error: `Invalid source type in rich text: '${patchPath.join(
+            error: `Invalid source type in ${currentSchema.type}: '${patchPath.join(
               "/",
             )}'. Expected an object but got 'null' at part ${i} (sliced: ${patchPath
               .slice(0, i + 1)
@@ -282,7 +285,7 @@ export function resolvePatchPath(
           if (!Number.isSafeInteger(Number(part))) {
             return {
               success: false,
-              error: `Invalid array index in rich text: '${patchPath.join(
+              error: `Invalid array index in ${currentSchema.type}: '${patchPath.join(
                 "/",
               )}'. Expected an integer but got '${part}' at part ${i} (sliced: ${patchPath
                 .slice(0, i + 1)
@@ -310,7 +313,7 @@ export function resolvePatchPath(
         } else {
           return {
             success: false,
-            error: `Invalid source type in rich text: '${patchPath.join(
+            error: `Invalid source type in ${currentSchema.type}: '${patchPath.join(
               "/",
             )}'. Expected an object but got '${typeof currentSource}' at part ${i} (sliced: ${patchPath
               .slice(0, i + 1)
diff --git a/packages/ui/spa/search/searchIndex.ts b/packages/ui/spa/search/searchIndex.ts
index 7183fc79f..3270b3c27 100644
--- a/packages/ui/spa/search/searchIndex.ts
+++ b/packages/ui/spa/search/searchIndex.ts
@@ -77,6 +77,15 @@ export function buildSearchIndex(
         // Use first 50 chars as label
         label = searchText.substring(0, 50) || "richtext";
       }
+      // Nothing inside an icon is searchable text, so index it by its path
+      // only - `index.add` below already prefixes the cleaned path, and a
+      // non-empty searchText is what gets the entry in at all. "svg" doubles as
+      // a way to list every icon, the same way "richtext" is a richtext's
+      // fallback label.
+      else if (schema.type === "svg") {
+        searchText = "svg";
+        label = "svg";
+      }
       // Handle file/image - extract filename from _ref
       else if (schema.type === "file" || schema.type === "image") {
         if (
diff --git a/packages/ui/spa/utils/findRequiredRemoteFiles.ts b/packages/ui/spa/utils/findRequiredRemoteFiles.ts
index f284a1bc4..4cd49721d 100644
--- a/packages/ui/spa/utils/findRequiredRemoteFiles.ts
+++ b/packages/ui/spa/utils/findRequiredRemoteFiles.ts
@@ -40,6 +40,7 @@ export function findRequiredRemoteFiles(schema: SerializedSchema) {
     schema.type === "color" ||
     schema.type === "keyOf" ||
     schema.type === "route" ||
+    schema.type === "svg" ||
     schema.type === "literal"
   ) {
     return false;
diff --git a/packages/ui/spa/utils/getDependentModuleFiles.ts b/packages/ui/spa/utils/getDependentModuleFiles.ts
index dcbe50cd7..a656c18f4 100644
--- a/packages/ui/spa/utils/getDependentModuleFiles.ts
+++ b/packages/ui/spa/utils/getDependentModuleFiles.ts
@@ -42,6 +42,7 @@ export function getDependentModuleFiles(
       }
     } else if (
       schemaNode.type === "richtext" ||
+      schemaNode.type === "svg" ||
       schemaNode.type === "boolean" ||
       schemaNode.type === "string" ||
       schemaNode.type === "literal" ||
diff --git a/packages/ui/spa/utils/runtimeKind.test.ts b/packages/ui/spa/utils/runtimeKind.test.ts
new file mode 100644
index 000000000..22ace8b19
--- /dev/null
+++ b/packages/ui/spa/utils/runtimeKind.test.ts
@@ -0,0 +1,15 @@
+import { runtimeKind } from "./runtimeKind";
+
+describe("runtimeKind", () => {
+  test("separates the three things typeof calls 'object'", () => {
+    expect(runtimeKind({})).toBe("object");
+    expect(runtimeKind([])).toBe("array");
+    expect(runtimeKind(null)).toBe("null");
+  });
+
+  test("agrees with typeof everywhere else", () => {
+    for (const value of ["s", 1, true, undefined, () => {}, Symbol("s")]) {
+      expect(runtimeKind(value)).toBe(typeof value);
+    }
+  });
+});
diff --git a/packages/ui/spa/utils/runtimeKind.ts b/packages/ui/spa/utils/runtimeKind.ts
new file mode 100644
index 000000000..8a84dec5c
--- /dev/null
+++ b/packages/ui/spa/utils/runtimeKind.ts
@@ -0,0 +1,16 @@
+/**
+ * The runtime kind of a value, for error messages.
+ *
+ * `typeof` reports both `null` and an array as `"object"`, which is exactly the
+ * distinction that matters when a field says it got an object but the value is
+ * an array or a null.
+ */
+export function runtimeKind(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  return typeof value;
+}
diff --git a/packages/ui/spa/utils/schemaTypesOfPath.ts b/packages/ui/spa/utils/schemaTypesOfPath.ts
index cb578c90a..7caad0bb3 100644
--- a/packages/ui/spa/utils/schemaTypesOfPath.ts
+++ b/packages/ui/spa/utils/schemaTypesOfPath.ts
@@ -27,6 +27,9 @@ export function schemaTypesOfPath(
     } else if (current.type === "richtext") {
       // richtext has internal structure (nodes with indices and tags), allow traversal
       break;
+    } else if (current.type === "svg") {
+      // svg has internal structure (nodes, attrs), allow traversal
+      break;
     } else if (current.type === "union") {
       if (typeof current.key === "string") {
         const types = current.items;
diff --git a/packages/ui/spa/utils/traverseSchemaSource.ts b/packages/ui/spa/utils/traverseSchemaSource.ts
index da0cd6ae5..79eaee1db 100644
--- a/packages/ui/spa/utils/traverseSchemaSource.ts
+++ b/packages/ui/spa/utils/traverseSchemaSource.ts
@@ -75,6 +75,12 @@ export function traverseSchemaSource(
     return;
   }
 
+  // Handle svg - the whole icon is one leaf
+  if (schema.type === "svg") {
+    callback({ source, schema, path });
+    return;
+  }
+
   // Handle file/image - extract filename from _ref
   if (schema.type === "file" || schema.type === "image") {
     if (
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index cfc1358e8..f3dcfab6e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -422,6 +422,9 @@ importers:
       '@types/react':
         specifier: ^18.2.38
         version: 18.2.38
+      '@types/react-dom':
+        specifier: ^18.2.0
+        version: 18.2.17
       jest-environment-jsdom:
         specifier: ^29.5.0
         version: 29.7.0
@@ -2705,72 +2708,84 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@next/swc-linux-arm64-gnu@13.5.9':
     resolution: {integrity: sha512-wdQsKsIsGSNdFojvjW3Ozrh8Q00+GqL3wTaMjDkQxVtRbAqfFBtrLPO0IuWChVUP2UeuQcHpVeUvu0YgOP00+g==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@next/swc-linux-arm64-gnu@14.2.33':
     resolution: {integrity: sha512-JXMBka6lNNmqbkvcTtaX8Gu5by9547bukHQvPoLe9VRBx1gHwzf5tdt4AaezW85HAB3pikcvyqBToRTDA4DeLw==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@next/swc-linux-arm64-musl@13.1.2':
     resolution: {integrity: sha512-JmNimDkcCRq7P5zpkdqeaSZ69qKDntEPtyIaMNWqy5M0WUJxGim0Fs6Qzxayiyvuuh9Guxks4woQ/j/ZvX/c8Q==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@next/swc-linux-arm64-musl@13.5.9':
     resolution: {integrity: sha512-6VpS+bodQqzOeCwGxoimlRoosiWlSc0C224I7SQWJZoyJuT1ChNCo+45QQH+/GtbR/s7nhaUqmiHdzZC9TXnXA==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@next/swc-linux-arm64-musl@14.2.33':
     resolution: {integrity: sha512-Bm+QulsAItD/x6Ih8wGIMfRJy4G73tu1HJsrccPW6AfqdZd0Sfm5Imhgkgq2+kly065rYMnCOxTBvmvFY1BKfg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@next/swc-linux-x64-gnu@13.1.2':
     resolution: {integrity: sha512-TsLsjZwUlgmvI42neTuIoD6K9RlXCUzqPtvIClgXxVO0um0DiZwK+M+0zX/uVXhMVphfPY2c5YeR1zFSIONY4A==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@next/swc-linux-x64-gnu@13.5.9':
     resolution: {integrity: sha512-XxG3yj61WDd28NA8gFASIR+2viQaYZEFQagEodhI/R49gXWnYhiflTeeEmCn7Vgnxa/OfK81h1gvhUZ66lozpw==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@next/swc-linux-x64-gnu@14.2.33':
     resolution: {integrity: sha512-FnFn+ZBgsVMbGDsTqo8zsnRzydvsGV8vfiWwUo1LD8FTmPTdV+otGSWKc4LJec0oSexFnCYVO4hX8P8qQKaSlg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@next/swc-linux-x64-musl@13.1.2':
     resolution: {integrity: sha512-eSkyXgCXydEFPTkcncQOGepafedPte6JT/OofB9uvruucrrMVBagCASOuPxodWEMrlfEKSXVnExMKIlfmQMD7A==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@next/swc-linux-x64-musl@13.5.9':
     resolution: {integrity: sha512-/dnscWqfO3+U8asd+Fc6dwL2l9AZDl7eKtPNKW8mKLh4Y4wOpjJiamhe8Dx+D+Oq0GYVjuW0WwjIxYWVozt2bA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@next/swc-linux-x64-musl@14.2.33':
     resolution: {integrity: sha512-345tsIWMzoXaQndUTDv1qypDRiebFxGYx9pYkhwY4hBRaOLt8UGfiWKr9FSSHs25dFIf8ZqIFaPdy5MljdoawA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@next/swc-win32-arm64-msvc@13.1.2':
     resolution: {integrity: sha512-DmXFaRTgt2KrV9dmRLifDJE+cYiutHVFIw5/C9BtnwXH39uf3YbPxeD98vNrtqqqZVVLXY/1ySaSIwzYnqeY9g==}
@@ -3863,66 +3878,79 @@ packages:
     resolution: {integrity: sha512-E8jKK87uOvLrrLN28jnAAAChNq5LeCd2mGgZF+fGF5D507WlG/Noct3lP/QzQ6MrqJ5BCKNwI9ipADB6jyiq2A==}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm-musleabihf@4.56.0':
     resolution: {integrity: sha512-jQosa5FMYF5Z6prEpTCCmzCXz6eKr/tCBssSmQGEeozA9tkRUty/5Vx06ibaOP9RCrW1Pvb8yp3gvZhHwTDsJw==}
     cpu: [arm]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-arm64-gnu@4.56.0':
     resolution: {integrity: sha512-uQVoKkrC1KGEV6udrdVahASIsaF8h7iLG0U0W+Xn14ucFwi6uS539PsAr24IEF9/FoDtzMeeJXJIBo5RkbNWvQ==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-musl@4.56.0':
     resolution: {integrity: sha512-vLZ1yJKLxhQLFKTs42RwTwa6zkGln+bnXc8ueFGMYmBTLfNu58sl5/eXyxRa2RarTkJbXl8TKPgfS6V5ijNqEA==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-loong64-gnu@4.56.0':
     resolution: {integrity: sha512-FWfHOCub564kSE3xJQLLIC/hbKqHSVxy8vY75/YHHzWvbJL7aYJkdgwD/xGfUlL5UV2SB7otapLrcCj2xnF1dg==}
     cpu: [loong64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-loong64-musl@4.56.0':
     resolution: {integrity: sha512-z1EkujxIh7nbrKL1lmIpqFTc/sr0u8Uk0zK/qIEFldbt6EDKWFk/pxFq3gYj4Bjn3aa9eEhYRlL3H8ZbPT1xvA==}
     cpu: [loong64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-ppc64-gnu@4.56.0':
     resolution: {integrity: sha512-iNFTluqgdoQC7AIE8Q34R3AuPrJGJirj5wMUErxj22deOcY7XwZRaqYmB6ZKFHoVGqRcRd0mqO+845jAibKCkw==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-ppc64-musl@4.56.0':
     resolution: {integrity: sha512-MtMeFVlD2LIKjp2sE2xM2slq3Zxf9zwVuw0jemsxvh1QOpHSsSzfNOTH9uYW9i1MXFxUSMmLpeVeUzoNOKBaWg==}
     cpu: [ppc64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-riscv64-gnu@4.56.0':
     resolution: {integrity: sha512-in+v6wiHdzzVhYKXIk5U74dEZHdKN9KH0Q4ANHOTvyXPG41bajYRsy7a8TPKbYPl34hU7PP7hMVHRvv/5aCSew==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-musl@4.56.0':
     resolution: {integrity: sha512-yni2raKHB8m9NQpI9fPVwN754mn6dHQSbDTwxdr9SE0ks38DTjLMMBjrwvB5+mXrX+C0npX0CVeCUcvvvD8CNQ==}
     cpu: [riscv64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-linux-s390x-gnu@4.56.0':
     resolution: {integrity: sha512-zhLLJx9nQPu7wezbxt2ut+CI4YlXi68ndEve16tPc/iwoylWS9B3FxpLS2PkmfYgDQtosah07Mj9E0khc3Y+vQ==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.56.0':
     resolution: {integrity: sha512-MVC6UDp16ZSH7x4rtuJPAEoE1RwS8N4oK9DLHy3FTEdFoUTCFVzMfJl/BVJ330C+hx8FfprA5Wqx4FhZXkj2Kw==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@rollup/rollup-linux-x64-musl@4.56.0':
     resolution: {integrity: sha512-ZhGH1eA4Qv0lxaV00azCIS1ChedK0V32952Md3FtnxSqZTBTd6tgil4nZT5cU8B+SIw3PFYkvyR4FKo2oyZIHA==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@rollup/rollup-openbsd-x64@4.56.0':
     resolution: {integrity: sha512-O16XcmyDeFI9879pEcmtWvD/2nyxR9mF7Gs44lf1vGGx8Vg2DRNx11aVXBEqOQhWb92WN4z7fW/q4+2NYzCbBA==}
@@ -4716,41 +4744,49 @@ packages:
     resolution: {integrity: sha512-34gw7PjDGB9JgePJEmhEqBhWvCiiWCuXsL9hYphDF7crW7UgI05gyBAi6MF58uGcMOiOqSJ2ybEeCvHcq0BCmQ==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-arm64-musl@1.11.1':
     resolution: {integrity: sha512-RyMIx6Uf53hhOtJDIamSbTskA99sPHS96wxVE/bJtePJJtpdKGXO1wY90oRdXuYOGOTuqjT8ACccMc4K6QmT3w==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
 
   '@unrs/resolver-binding-linux-ppc64-gnu@1.11.1':
     resolution: {integrity: sha512-D8Vae74A4/a+mZH0FbOkFJL9DSK2R6TFPC9M+jCWYia/q2einCubX10pecpDiTmkJVUH+y8K3BZClycD8nCShA==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-riscv64-gnu@1.11.1':
     resolution: {integrity: sha512-frxL4OrzOWVVsOc96+V3aqTIQl1O2TjgExV4EKgRY09AJ9leZpEg8Ak9phadbuX0BA4k8U5qtvMSQQGGmaJqcQ==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-riscv64-musl@1.11.1':
     resolution: {integrity: sha512-mJ5vuDaIZ+l/acv01sHoXfpnyrNKOk/3aDoEdLO/Xtn9HuZlDD6jKxHlkN8ZhWyLJsRBxfv9GYM2utQ1SChKew==}
     cpu: [riscv64]
     os: [linux]
+    libc: [musl]
 
   '@unrs/resolver-binding-linux-s390x-gnu@1.11.1':
     resolution: {integrity: sha512-kELo8ebBVtb9sA7rMe1Cph4QHreByhaZ2QEADd9NzIQsYNQpt9UkM9iqr2lhGr5afh885d/cB5QeTXSbZHTYPg==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-x64-gnu@1.11.1':
     resolution: {integrity: sha512-C3ZAHugKgovV5YvAMsxhq0gtXuwESUKc5MhEtjBpLoHPLYM+iuwSj3lflFwK3DPm68660rZ7G8BMcwSro7hD5w==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
 
   '@unrs/resolver-binding-linux-x64-musl@1.11.1':
     resolution: {integrity: sha512-rV0YSoyhK2nZ4vEswT/QwqzqQXw5I6CjoaYMOX0TqBlWhojUf8P94mvI7nuJTeaCkkds3QE4+zS8Ko+GdXuZtA==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
 
   '@unrs/resolver-binding-wasm32-wasi@1.11.1':
     resolution: {integrity: sha512-5u4RkfxJm+Ng7IWgkzi3qrFOvLvQYnPBmjmZQ8+szTK/b31fQCnleNl1GgEt7nIsZRIf5PLhPwT0WM+q45x/UQ==}