Validate SVG import (icon and illustration) against the live instance #211

New issue

Closed

opened 2026-09-14 23:14:09 +00:00 by david · 1 comment

david commented

2026-09-14 23:14:09 +00:00

Owner

Summary

Validate the SVG import path against the live instance with two real inputs — an icon and a small illustration — confirming the result is an editable shape tree, that matching colours resolve to library assets, and that unsupported nodes land as svg-raw rather than disappearing.

Background

Depends on: #210

The converter is deliberately a bounded subset with an explicit fallback, so this gate is about verifying the promises the tool makes rather than achieving high fidelity: no silent drops, honest reporting, and editable output. Fidelity gaps are expected and must be documented so the skill can tell a user what to expect.

The two inputs exercise different parts of the converter: an icon typically uses path with curves and a single fill (stressing path conversion and colour matching), while a small illustration brings multiple nodes, groups, transforms and probably at least one unsupported feature (stressing the fallback path and the report).

Prefer inputs from a real project where available; otherwise generate a small illustration that deliberately includes a gradient, a filter or a mask so the fallback is exercised rather than assumed.

Documentation Required

A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting.

docs/reference/svg/

https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element — the supported element set, so the validation can state what "unsupported" means for each node in the fixtures.
https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/d and .../Attribute/transform — the path/transform semantics behind the fidelity observations.
https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths — reference examples for interpreting differences between the source and the result.

docs/reference/penpot-api/

https://raw.githubusercontent.com/penpot/penpot/2.17.2/common/src/app/common/types/shape.cljc — shape/svg-raw fields, for interpreting the imported object in the file data.
https://help.penpot.app/user-guide/design-systems/assets/ — what a linked swatch looks like in the UI, for the colour-resolution check.
https://help.penpot.app/user-guide/ — how imported artwork behaves in the Layers panel and inspector (selecting individual nodes, editing fills), which is the "editable" claim under test.

docs/reference/librsvg/

https://wiki.gnome.org/action/show/Projects/LibRsvg or https://github.com/GNOME/librsvg/blob/main/rsvg-convert.rst — the rsvg-convert(1) manual: used only to render the source SVG to PNG so the imported result can be compared visually. It is a validation aid, not part of the extension.

Implementation Details

Icon. Import an icon SVG (a single path or a couple of rect/circle nodes) into a scratch file with the library colours present:
- confirm the resulting shapes are individually selectable and editable in the Penpot UI;
- confirm layer names come from the SVG's id/name attributes;
- confirm the geometry visually matches the source (render the source with rsvg-convert and compare side by side);
- confirm a fill matching a library colour appears as a linked swatch.
Small illustration. Import an SVG with several nodes, at least one g group and at least one deliberately unsupported feature (gradient fill, filter or mask):
- confirm supported nodes converted to native shapes and the unsupported ones to svg-raw objects that are visible on the canvas;
- confirm the tool's report lists every fallback with its reason and that the counts add up (converted + fallback = input nodes);
- confirm the overall composition is recognisable as the source.
Transform handling. Import an SVG using translate/scale and confirm the result's position/size matches the source; import one using rotate and confirm the node is reported as unsupported rather than silently misplaced.
Malformed input. Import a broken SVG and confirm the tool errors with the offending position and leaves the file's revn unchanged.

Record in extensions/penpot/findings.md under "SVG import": the two fixtures used (with their commands/elements), the converted-vs-fallback breakdown per fixture, the UI observations, a plain statement of the fidelity limits discovered, and any case where the output was wrong rather than merely approximate.

Acceptance Criteria

An icon SVG imports as a set of native, individually editable shapes with id/name-derived layer names, visually matching the source.
An SVG fill whose colour matches a library asset imports as a linked swatch; the matching is reported by the tool.
A small illustration imports with supported nodes converted and unsupported nodes present as svg-raw objects — nothing is missing from the canvas.
The tool's report accounts for every input node: converted + fallback = total, each fallback with a reason.
translate/scale are applied correctly; a rotate node is reported unsupported rather than silently misplaced.
A malformed SVG errors with the offending position and leaves the file's revision unchanged.
extensions/penpot/findings.md records both fixtures, the converted/fallback breakdown, the visual comparison, and the fidelity limits stated plainly.
Any defect found in the converter or the tool is fixed in code, not merely noted.

Test Plan

Manual, against the live instance:

# in pi
/reload
# penpot_authorize_target(file_id=<scratch file>)
# penpot_add_svg(file_id=<scratch file>, path=<icon.svg>, x=40, y=40, scale=2)
# penpot_commit(file_id=<scratch file>)
# penpot_add_svg(file_id=<scratch file>, path=<illustration.svg>, x=40, y=200)
# penpot_commit(file_id=<scratch file>)

Rendering the source for comparison:

rsvg-convert --output=/tmp/icon-source.png icon.svg

Then in the Penpot UI:

Select an individual node of the imported icon and edit its fill — proving it is a real shape.
Inspect the illustration's layers: converted shapes plus svg-raw objects; confirm the fallback objects are visible and named.
Compare the canvas against the rendered source PNG and record the differences.

## Summary Validate the SVG import path against the live instance with two real inputs — an icon and a small illustration — confirming the result is an editable shape tree, that matching colours resolve to library assets, and that unsupported nodes land as `svg-raw` rather than disappearing. ## Background **Depends on:** #210 The converter is deliberately a bounded subset with an explicit fallback, so this gate is about verifying the *promises* the tool makes rather than achieving high fidelity: no silent drops, honest reporting, and editable output. Fidelity gaps are expected and must be documented so the skill can tell a user what to expect. The two inputs exercise different parts of the converter: an icon typically uses `path` with curves and a single fill (stressing path conversion and colour matching), while a small illustration brings multiple nodes, groups, transforms and probably at least one unsupported feature (stressing the fallback path and the report). Prefer inputs from a real project where available; otherwise generate a small illustration that deliberately includes a gradient, a filter or a mask so the fallback is exercised rather than assumed. ## Documentation Required A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting. **`docs/reference/svg/`** - https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element — the supported element set, so the validation can state what "unsupported" means for each node in the fixtures. - https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/d and .../Attribute/transform — the path/transform semantics behind the fidelity observations. - https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorials/SVG_from_scratch/Paths — reference examples for interpreting differences between the source and the result. **`docs/reference/penpot-api/`** - https://raw.githubusercontent.com/penpot/penpot/2.17.2/common/src/app/common/types/shape.cljc — shape/`svg-raw` fields, for interpreting the imported object in the file data. - https://help.penpot.app/user-guide/design-systems/assets/ — what a linked swatch looks like in the UI, for the colour-resolution check. - https://help.penpot.app/user-guide/ — how imported artwork behaves in the Layers panel and inspector (selecting individual nodes, editing fills), which is the "editable" claim under test. **`docs/reference/librsvg/`** - https://wiki.gnome.org/action/show/Projects/LibRsvg or https://github.com/GNOME/librsvg/blob/main/rsvg-convert.rst — the `rsvg-convert(1)` manual: used **only** to render the source SVG to PNG so the imported result can be compared visually. It is a validation aid, not part of the extension. ## Implementation Details 1. **Icon.** Import an icon SVG (a single `path` or a couple of `rect`/`circle` nodes) into a scratch file with the library colours present: - confirm the resulting shapes are individually selectable and editable in the Penpot UI; - confirm layer names come from the SVG's `id`/`name` attributes; - confirm the geometry visually matches the source (render the source with `rsvg-convert` and compare side by side); - confirm a fill matching a library colour appears as a **linked** swatch. 2. **Small illustration.** Import an SVG with several nodes, at least one `g` group and at least one deliberately unsupported feature (gradient fill, filter or mask): - confirm supported nodes converted to native shapes and the unsupported ones to `svg-raw` objects that are **visible** on the canvas; - confirm the tool's report lists every fallback with its reason and that the counts add up (converted + fallback = input nodes); - confirm the overall composition is recognisable as the source. 3. **Transform handling.** Import an SVG using `translate`/`scale` and confirm the result's position/size matches the source; import one using `rotate` and confirm the node is reported as unsupported rather than silently misplaced. 4. **Malformed input.** Import a broken SVG and confirm the tool errors with the offending position and leaves the file's `revn` unchanged. Record in `extensions/penpot/findings.md` under "SVG import": the two fixtures used (with their commands/elements), the converted-vs-fallback breakdown per fixture, the UI observations, a plain statement of the fidelity limits discovered, and any case where the output was wrong rather than merely approximate. ## Acceptance Criteria - [ ] An icon SVG imports as a set of native, individually editable shapes with `id`/`name`-derived layer names, visually matching the source. - [ ] An SVG fill whose colour matches a library asset imports as a **linked** swatch; the matching is reported by the tool. - [ ] A small illustration imports with supported nodes converted and unsupported nodes present as `svg-raw` objects — nothing is missing from the canvas. - [ ] The tool's report accounts for every input node: converted + fallback = total, each fallback with a reason. - [ ] `translate`/`scale` are applied correctly; a `rotate` node is reported unsupported rather than silently misplaced. - [ ] A malformed SVG errors with the offending position and leaves the file's revision unchanged. - [ ] `extensions/penpot/findings.md` records both fixtures, the converted/fallback breakdown, the visual comparison, and the fidelity limits stated plainly. - [ ] Any defect found in the converter or the tool is fixed in code, not merely noted. ## Test Plan Manual, against the live instance: ```bash # in pi /reload # penpot_authorize_target(file_id=<scratch file>) # penpot_add_svg(file_id=<scratch file>, path=<icon.svg>, x=40, y=40, scale=2) # penpot_commit(file_id=<scratch file>) # penpot_add_svg(file_id=<scratch file>, path=<illustration.svg>, x=40, y=200) # penpot_commit(file_id=<scratch file>) ``` Rendering the source for comparison: ```bash rsvg-convert --output=/tmp/icon-source.png icon.svg ``` Then in the Penpot UI: 1. Select an individual node of the imported icon and edit its fill — proving it is a real shape. 2. Inspect the illustration's layers: converted shapes plus `svg-raw` objects; confirm the fallback objects are visible and named. 3. Compare the canvas against the rendered source PNG and record the differences.

david added this to the Penpot: M6 - SVG input (code to design) milestone

2026-09-14 23:14:09 +00:00

david added the

feature

label

2026-09-14 23:14:09 +00:00

david referenced this issue from a pull request that will close it,

2026-09-15 07:08:11 +00:00

issue-211: Validate SVG import (icon and illustration) against the live instance #244

david closed this issue

2026-09-15 07:08:12 +00:00

david commented