diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6680edbb..24ffab2be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,61 @@ follow semantic versioning; release dates are ISO 8601.
 
 ## v2.2.1 — Planned
 
+### Fixed
+
+- **The SVG reader honours the opacity family.** `opacity`, `fill-opacity` and
+  `stroke-opacity` — attribute or `style=""`, number or percentage, with SVG's
+  inheritance for the paint slots and composition for group `opacity` — now
+  multiply into each layer's flat paint alpha, on top of any alpha the colour
+  already carries from an 8-digit hex or `rgba()`. They were read from nowhere
+  before: a translucent logo landed on the page fully opaque, and the only fix
+  was editing the SVG. A slot whose product reaches zero is treated like
+  `fill="none"`, so an `opacity="0"` guide layer no longer paints at all. A
+  *partial* opacity cannot reach a gradient slot — the `DocumentPaint` contract
+  refuses translucent stops because shadings carry no alpha — so a gradient
+  under `fill-opacity="0.5"` still paints opaque, now with a one-line warning
+  naming the approximation. Group opacity is the per-layer approximation of SVG's
+  offscreen compositing — overlapping siblings inside one translucent group
+  darken where a browser would flatten them first — which is the same trade
+  every lightweight icon reader makes.
+
+- **What the SVG reader cannot honour now says so.** `fill-rule="evenodd"` was
+  read from nowhere and filled with non-zero winding — a donut whose hole is cut
+  by a same-direction subpath came out solid, silently; it still renders the
+  same way, but the icon now logs one warning naming the approximation (a
+  `fill-rule` value outside nonzero / evenodd / inherit, previously unread, is
+  now refused like any other bad presentation value). A `mask="url(#id)"` or
+  `filter="url(#id)"` attribute — whose definition sits in `<defs>`, where the
+  walk never looks — paints unmasked / unfiltered as before, but the
+  referencing attribute is now read and warned about, because that attribute is
+  the only place the divergence is observable. Element kinds outside the
+  reader's vocabulary (`mask`, `pattern`, `marker`, `<style>` CSS, `<a>`
+  wrappers…) joined the skip tally that previously only counted
+  text / image / `use` — one warning per kind, and a blank icon's "no drawable
+  geometry" error names them. The DOCX export gained the inline mirror of its
+  block-level drop warning: image / shape / SVG runs (emoji included) vanish
+  from a paragraph by contract, and now say so once per export instead of only
+  the block path warning.
+
+- **SVG reader errors keep their house style at the edges.** A malformed hex
+  colour (`#zzz`), a non-numeric `rgb()` channel or `rgba()` alpha, and a
+  unit-only length (`stroke-width="px"`) leaked the raw
+  `NumberFormatException` ("For input string: …") past the reader's
+  name-the-field-and-the-element convention; each now reports what was being
+  parsed and the offending input, with the JDK detail chained as the cause.
+
+### Documentation
+
+- **The SVG Javadoc stopped describing a younger reader.** `SvgGradients` claimed
+  focal radials and `stop-opacity` are "loudly refused" — both degrade
+  deliberately (centred-radial approximation, opaque stops, alpha-only overlay
+  layers dropped) and the class doc now says what actually happens. `SvgIcon`
+  still listed clip paths as out of scope and the skip-tally warning said "no
+  clips" — `clip-path:url(#id)` has rendered since 1.9.0, so the supported list
+  gained it (with its innermost-wins nesting rule) and the out-of-scope list,
+  the warning, and the empty-icon error text shrank to what is actually
+  dropped.
+
 ### Build
 
 - **The weekly benchmark run builds the modules it measures.** The JMH workflow
diff --git a/assets/readme/examples/emoji-clip-path.pdf b/assets/readme/examples/emoji-clip-path.pdf
index a48ad21dc..4789b5204 100644
Binary files a/assets/readme/examples/emoji-clip-path.pdf and b/assets/readme/examples/emoji-clip-path.pdf differ
diff --git a/assets/readme/examples/emoji-shortcodes.pdf b/assets/readme/examples/emoji-shortcodes.pdf
index 3dd8457df..6ead4034a 100644
Binary files a/assets/readme/examples/emoji-shortcodes.pdf and b/assets/readme/examples/emoji-shortcodes.pdf differ
diff --git a/core/src/main/java/com/demcha/compose/document/style/DocumentPaint.java b/core/src/main/java/com/demcha/compose/document/style/DocumentPaint.java
index 39ab08c3f..0d8b1863e 100644
--- a/core/src/main/java/com/demcha/compose/document/style/DocumentPaint.java
+++ b/core/src/main/java/com/demcha/compose/document/style/DocumentPaint.java
@@ -227,8 +227,11 @@ private static void requireFinite(double value, String what) {
      * radial shadings, which carry no alpha channel, so a translucent stop
      * would silently render opaque. Rather than render wrong, a stop with
      * alpha below 255 is rejected at construction — flatten transparency into
-     * the stop colour, or apply opacity to the whole shape instead. This
-     * mirrors the SVG reader, which already refuses {@code stop-opacity}.
+     * the stop colour, or apply opacity to the whole shape instead. The SVG
+     * reader honours the same constraint from its side: {@code stop-opacity}
+     * and a partial element opacity on a gradient-painted shape paint opaque
+     * (warned once per icon), so no translucent stop ever reaches this
+     * constructor.
      *
      * @param offset position along the gradient axis in [0,1]
      * @param color  fully-opaque colour at this offset
diff --git a/core/src/main/java/com/demcha/compose/document/svg/SvgGradients.java b/core/src/main/java/com/demcha/compose/document/svg/SvgGradients.java
index b5ec2f097..689cdb116 100644
--- a/core/src/main/java/com/demcha/compose/document/svg/SvgGradients.java
+++ b/core/src/main/java/com/demcha/compose/document/svg/SvgGradients.java
@@ -26,9 +26,14 @@
  * One level of {@code href} / {@code xlink:href} indirection supplies
  * stops for the split-definition style Inkscape and Figma emit.</p>
  *
- * <p>Out of PDF reach and loudly refused: focal radials ({@code fx} /
- * {@code fy}), {@code spreadMethod} other than pad, and translucent stops
- * ({@code stop-opacity}).</p>
+ * <p>Loudly refused because PDF shadings cannot express it:
+ * {@code spreadMethod} other than pad. Approximated instead of refused,
+ * matching how real-world icons use them: focal radials ({@code fx} /
+ * {@code fy}) collapse to a plain radial about the centre, and translucent
+ * stops ({@code stop-opacity}) paint opaque — except a same-colour
+ * translucent gradient (a pure alpha overlay), which
+ * {@link #isAlphaOnlyOverlay} lets the reader drop entirely rather than
+ * blot out the art beneath it.</p>
  */
 final class SvgGradients {
 
diff --git a/core/src/main/java/com/demcha/compose/document/svg/SvgIcon.java b/core/src/main/java/com/demcha/compose/document/svg/SvgIcon.java
index ebb32e7ac..6d75bd948 100644
--- a/core/src/main/java/com/demcha/compose/document/svg/SvgIcon.java
+++ b/core/src/main/java/com/demcha/compose/document/svg/SvgIcon.java
@@ -27,9 +27,18 @@
  * {@code rotate} / {@code matrix} — affine maps are exact on Bézier control
  * points), per-element {@code fill} / {@code stroke} / {@code stroke-width}
  * styling with SVG's inheritance and defaults (missing {@code fill} paints
- * black, {@code fill="none"} skips the fill), and {@code linearGradient} /
- * {@code radialGradient} paints referenced via {@code url(#id)} — on fills
- * and strokes alike, rendered as native PDF shadings.
+ * black, {@code fill="none"} skips the fill), the opacity family
+ * ({@code opacity} / {@code fill-opacity} / {@code stroke-opacity},
+ * multiplied down the tree into each layer's paint alpha — the per-layer
+ * approximation of SVG's offscreen group compositing; zero hides the slot,
+ * and a partial opacity cannot reach a gradient slot because shadings carry
+ * no alpha — the gradient paints opaque, with a one-line warning),
+ * {@code clip-path:url(#id)} clipping (a clip on an element or group clips
+ * it and its descendants; nested clips are not intersected — the innermost
+ * wins, and a clip that cannot be resolved paints unclipped), and
+ * {@code linearGradient} / {@code radialGradient} paints referenced via
+ * {@code url(#id)} — on fills and strokes alike, rendered as native PDF
+ * shadings.
  *
  * <p>Each layer is one {@link SvgPath} with its resolved paint, in document
  * order — render them back-to-front. {@link #node(double)} packages the
@@ -38,11 +47,15 @@
  * requested width with the icon's own aspect ratio.</p>
  *
  * <p>Out of scope (deliberately, this is an icon reader, not a browser):
- * CSS stylesheets and classes, text, masks, clip paths, filters,
+ * CSS stylesheets and classes, text, masks, filters,
  * {@code <use>} references, nested {@code <svg>} viewBoxes (inner frames
  * recurse but their coordinates stay in the outer space), animations, and
- * the gradient corners that have no PDF analogue (focal points,
- * {@code spreadMethod} other than pad, stop opacity). A gradient's
+ * the gradient corners that have no PDF analogue ({@code spreadMethod}
+ * other than pad is refused; focal points collapse to a centred radial and
+ * translucent stops paint opaque). Fills always use non-zero winding —
+ * {@code fill-rule="evenodd"} renders, with a one-line warning, as if it
+ * were {@code nonzero}. Dropped elements and approximated features are
+ * each warned once per icon rather than silently ignored. A gradient's
  * {@code href} / {@code xlink:href} indirection inherits only the referenced
  * {@code <stop>} list — not its geometry attributes ({@code x1}/{@code y1}/
  * {@code x2}/{@code y2}, {@code cx}/{@code cy}/{@code r}, {@code gradientUnits},
diff --git a/core/src/main/java/com/demcha/compose/document/svg/SvgIconReader.java b/core/src/main/java/com/demcha/compose/document/svg/SvgIconReader.java
index b2021fb04..5ae76db38 100644
--- a/core/src/main/java/com/demcha/compose/document/svg/SvgIconReader.java
+++ b/core/src/main/java/com/demcha/compose/document/svg/SvgIconReader.java
@@ -26,10 +26,13 @@
  * (DOCTYPE refused, so XXE cannot reach the file system), viewBox
  * resolution, recursive {@code <g>} traversal with affine accumulation and
  * paint inheritance, shape-to-path lowering (every basic shape becomes
- * synthesized path data fed through the one tested parser), the icon
- * colour subset ({@code #rgb}, {@code #rrggbb}, {@code rgb(r,g,b)},
- * {@code none}, {@code currentColor} → default ink), and {@code url(#id)}
- * gradient references resolved through {@link SvgGradients}.
+ * synthesized path data fed through the one tested parser), the
+ * presentation-attribute grammar in {@link SvgStyles} (colours including
+ * alpha, lengths, stroke style), the opacity family ({@code opacity} /
+ * {@code fill-opacity} / {@code stroke-opacity}, multiplied down the tree
+ * into per-layer paint alpha), {@code clip-path:url(#id)} resolution, and
+ * {@code url(#id)} gradient references resolved through
+ * {@link SvgGradients}.
  */
 final class SvgIconReader {
 
@@ -44,6 +47,23 @@ final class SvgIconReader {
     private static final Set<String> DROPS_CONTENT = Set.of(
             "text", "tspan", "textPath", "image", "use", "foreignObject");
 
+    /** Shape elements the walk lowers to path data. */
+    private static final Set<String> KNOWN_SHAPES = Set.of(
+            "path", "rect", "circle", "ellipse", "line", "polyline", "polygon");
+
+    /**
+     * Elements that hold no direct geometry of their own — definitions the
+     * reader consumes elsewhere ({@code defs} content, gradients, stops,
+     * {@code clipPath}), document metadata, or {@code symbol} content that
+     * only becomes visible through a {@code <use>} (which warns on its own).
+     * Skipping these loses nothing, so they never reach the tally. Anything
+     * outside this set, {@link #KNOWN_SHAPES} and {@link #DROPS_CONTENT}
+     * is an element kind the reader does not know and is tallied.
+     */
+    private static final Set<String> STRUCTURE_ONLY = Set.of(
+            "defs", "title", "desc", "metadata", "symbol", "clipPath",
+            "linearGradient", "radialGradient", "stop");
+
     private SvgIconReader() {
     }
 
@@ -60,7 +80,8 @@ static SvgIcon read(String svgXml) {
         SkipTally skipped = new SkipTally();
         walk(root, identity(),
                 new Paint(new PaintValue(DocumentColor.rgb(0, 0, 0), null), PaintValue.NONE, 1.0,
-                        DocumentLineCap.BUTT, DocumentLineJoin.MITER, List.of()),
+                        DocumentLineCap.BUTT, DocumentLineJoin.MITER, List.of(),
+                        1.0, 1.0, 1.0, false),
                 null, box, gradients, ids, skipped, layers);
         if (layers.isEmpty()) {
             throw new IllegalArgumentException(
@@ -160,6 +181,7 @@ private static void walk(Element element, double[] transform, Paint inherited, S
             if (ownClip != null) {
                 activeClip = ownClip;
             }
+            noteIgnoredEffects(element, skipped);
             String d = switch (name) {
                 case "path" -> element.getAttribute("d");
                 case "rect" -> SvgShapeLowering.rect(num(element, "x"), num(element, "y"),
@@ -177,11 +199,18 @@ private static void walk(Element element, double[] transform, Paint inherited, S
             };
 
             if (d != null && !d.isBlank()) {
-                emitLayer(element, d, paint, matrix, activeClip, box, gradients, out);
+                emitLayer(element, d, paint, matrix, activeClip, box, gradients, skipped, out);
             } else if (DROPS_CONTENT.contains(name)) {
                 // A shape kind we deliberately don't render — count it so the icon
                 // surfaces one warning per kind instead of silently losing pixels.
                 skipped.note(name);
+            } else if (!name.equals("svg") && !name.equals("g")
+                       && !KNOWN_SHAPES.contains(name) && !STRUCTURE_ONLY.contains(name)) {
+                // An element kind the reader does not know (mask, filter, pattern,
+                // marker, <style> CSS, <a> wrappers…). Its subtree is not walked,
+                // so any ink it carries is lost — tally it like the known drops
+                // instead of losing it silently.
+                skipped.note(name);
             }
         } catch (IllegalArgumentException e) {
             throw new IllegalArgumentException(
@@ -204,9 +233,15 @@ private static void walk(Element element, double[] transform, Paint inherited, S
     /** Builds and appends the layer for a drawable element (curve geometry + paint). */
     private static void emitLayer(Element element, String d, Paint paint,
                                   double[] matrix, SvgPath clip, double[] box, Map<String, Element> gradients,
-                                  List<SvgIcon.Layer> out) {
-        boolean strokeVisible = paint.stroke().visible() && paint.strokeWidth() > 0;
-        if (!paint.fill().visible() && !strokeVisible) {
+                                  SkipTally skipped, List<SvgIcon.Layer> out) {
+        // Group opacity multiplies into both paint slots; fill-opacity and
+        // stroke-opacity multiply into theirs. A slot whose product reaches
+        // zero is invisible — the same fast-path as fill="none".
+        double fillAlpha = paint.fillOpacity() * paint.groupOpacity();
+        double strokeAlpha = paint.strokeOpacity() * paint.groupOpacity();
+        boolean fillVisible = paint.fill().visible() && fillAlpha > 0;
+        boolean strokeVisible = paint.stroke().visible() && paint.strokeWidth() > 0 && strokeAlpha > 0;
+        if (!fillVisible && !strokeVisible) {
             return;
         }
         SvgPath geometry = SvgPath.parseTransformed(d, matrix, box[0], box[1], box[2], box[3]);
@@ -222,35 +257,80 @@ private static void emitLayer(Element element, String d, Paint paint,
         // objectBoundingBox reference) and accumulated affine exist. The flat
         // colour keeps the gradient's first stop so backends without shadings
         // degrade per the DocumentPaint contract.
-        DocumentColor fillColor = paint.fill().color();
+        DocumentColor fillColor = null;
         DocumentPaint fillPaint = null;
-        if (paint.fill().gradient() != null) {
-            if (!strokeVisible && SvgGradients.isAlphaOnlyOverlay(paint.fill().gradient(), gradients)) {
-                // A same-colour translucent gradient is a pure alpha overlay (a
-                // soft shadow or edge highlight, e.g. the hair-edge darkening on
-                // the vampire glyphs). With no shading-alpha in the backend,
-                // painting it opaque would cover the art beneath it — drop the
-                // layer rather than blot out a face.
-                return;
+        if (fillVisible) {
+            if (paint.fill().gradient() != null) {
+                if (!strokeVisible && SvgGradients.isAlphaOnlyOverlay(paint.fill().gradient(), gradients)) {
+                    // A same-colour translucent gradient is a pure alpha overlay (a
+                    // soft shadow or edge highlight, e.g. the hair-edge darkening on
+                    // the vampire glyphs). With no shading-alpha in the backend,
+                    // painting it opaque would cover the art beneath it — drop the
+                    // layer rather than blot out a face.
+                    return;
+                }
+                if (fillAlpha < 1.0) {
+                    // The DocumentPaint contract refuses translucent stops
+                    // (shadings carry no alpha), so a partial opacity cannot
+                    // reach a gradient fill — it paints opaque, said once.
+                    // Zero opacity already hid the slot above.
+                    skipped.noteDegraded("opacity on a gradient fill (gradient paints opaque)");
+                }
+                fillPaint = SvgGradients.paint(paint.fill().gradient(), gradients, matrix, box, geometry);
+                fillColor = fillPaint.primaryColor();
+            } else {
+                fillColor = SvgStyles.multiplyAlpha(paint.fill().color(), fillAlpha);
             }
-            fillPaint = SvgGradients.paint(paint.fill().gradient(), gradients, matrix, box, geometry);
-            fillColor = fillPaint.primaryColor();
         }
         DocumentStroke stroke = null;
         DocumentPaint strokePaint = null;
         if (strokeVisible) {
             if (paint.stroke().gradient() != null) {
+                if (strokeAlpha < 1.0) {
+                    skipped.noteDegraded("opacity on a gradient stroke (gradient paints opaque)");
+                }
                 strokePaint = SvgGradients.paint(paint.stroke().gradient(), gradients, matrix, box, geometry);
                 stroke = DocumentStroke.of(strokePaint.primaryColor(), paint.strokeWidth());
             } else {
-                stroke = DocumentStroke.of(paint.stroke().color(), paint.strokeWidth());
+                stroke = DocumentStroke.of(
+                        SvgStyles.multiplyAlpha(paint.stroke().color(), strokeAlpha),
+                        paint.strokeWidth());
             }
         }
+        if (fillColor != null && paint.evenOddFill()) {
+            // The engine's fill contract is non-zero winding only. Most icons
+            // fill identically under both rules; the ones that differ (donut
+            // holes cut by same-direction subpaths) come out solid — say so
+            // once instead of silently filling the hole. Noted here, after the
+            // degenerate-geometry and overlay drops, so the tally never names
+            // a layer that was not actually painted.
+            skipped.noteDegraded("fill-rule=evenodd (filled with non-zero winding)");
+        }
         out.add(new SvgIcon.Layer(geometry, fillColor, fillPaint, stroke, strokePaint,
                 paint.lineCap(), paint.lineJoin(), paint.dashArray(),
                 clip != null && clip.hasDrawingSegment() ? clip : null));
     }
 
+    /**
+     * Tallies raster effects the reader deliberately ignores on the element it
+     * is about to paint: a {@code mask="url(#id)"} paints unmasked and a
+     * {@code filter="url(#id)"} paints unfiltered. The {@code <mask>} /
+     * {@code <filter>} definitions themselves usually sit inside
+     * {@code <defs>}, which the walk never visits — the referencing attribute
+     * is the only place the divergence is observable, so it is what gets
+     * warned about.
+     */
+    private static void noteIgnoredEffects(Element element, SkipTally skipped) {
+        String mask = attrOrStyle(element, "mask");
+        if (mask != null && !mask.trim().equalsIgnoreCase("none")) {
+            skipped.noteDegraded("mask (painted unmasked)");
+        }
+        String filter = attrOrStyle(element, "filter");
+        if (filter != null && !filter.trim().equalsIgnoreCase("none")) {
+            skipped.noteDegraded("filter (painted unfiltered)");
+        }
+    }
+
     // ------------------------------------------------------------------
     // Clipping (clip-path → a single clip shape in icon space)
     // ------------------------------------------------------------------
@@ -379,6 +459,10 @@ private static Paint stylize(Element element, Paint inherited, Map<String, Eleme
         DocumentLineCap lineCap = inherited.lineCap();
         DocumentLineJoin lineJoin = inherited.lineJoin();
         List<Double> dashArray = inherited.dashArray();
+        double fillOpacity = inherited.fillOpacity();
+        double strokeOpacity = inherited.strokeOpacity();
+        double groupOpacity = inherited.groupOpacity();
+        boolean evenOddFill = inherited.evenOddFill();
 
         String fillAttr = attrOrStyle(element, "fill");
         if (fillAttr != null) {
@@ -408,7 +492,36 @@ private static Paint stylize(Element element, Paint inherited, Map<String, Eleme
                     ? inherited.dashArray()
                     : SvgStyles.dashArray(dashAttr);
         }
-        return new Paint(fill, stroke, strokeWidth, lineCap, lineJoin, dashArray);
+        // fill-opacity and stroke-opacity are inherited properties — an
+        // attribute replaces the inherited value. opacity is not inherited:
+        // it composites, so each carrier multiplies into the accumulated
+        // product (the per-layer approximation of SVG's offscreen group
+        // compositing; overlapping siblings inside one translucent group
+        // darken where a browser would flatten them first).
+        String fillOpacityAttr = attrOrStyle(element, "fill-opacity");
+        if (fillOpacityAttr != null && !fillOpacityAttr.equalsIgnoreCase("inherit")) {
+            fillOpacity = SvgStyles.opacity(fillOpacityAttr, "fill-opacity");
+        }
+        String strokeOpacityAttr = attrOrStyle(element, "stroke-opacity");
+        if (strokeOpacityAttr != null && !strokeOpacityAttr.equalsIgnoreCase("inherit")) {
+            strokeOpacity = SvgStyles.opacity(strokeOpacityAttr, "stroke-opacity");
+        }
+        String opacityAttr = attrOrStyle(element, "opacity");
+        if (opacityAttr != null && !opacityAttr.equalsIgnoreCase("inherit")) {
+            groupOpacity = groupOpacity * SvgStyles.opacity(opacityAttr, "opacity");
+        }
+        String fillRuleAttr = attrOrStyle(element, "fill-rule");
+        if (fillRuleAttr != null) {
+            evenOddFill = switch (fillRuleAttr.trim().toLowerCase(java.util.Locale.ROOT)) {
+                case "nonzero" -> false;
+                case "evenodd" -> true;
+                case "inherit" -> inherited.evenOddFill();
+                default -> throw new IllegalArgumentException(
+                        "unsupported fill-rule '" + fillRuleAttr + "' — use nonzero, evenodd, or inherit");
+            };
+        }
+        return new Paint(fill, stroke, strokeWidth, lineCap, lineJoin, dashArray,
+                fillOpacity, strokeOpacity, groupOpacity, evenOddFill);
     }
 
     /**
@@ -576,31 +689,48 @@ boolean visible() {
 
     /**
      * Inherited paint state: SVG fills default to black, strokes to none.
-     * Stroke style (cap / join / dash) is inheritable too, so it rides here.
+     * Stroke style (cap / join / dash), the opacity slots and the fill rule
+     * are inheritable too, so they ride here. {@code groupOpacity} is the
+     * accumulated product of every {@code opacity} on the ancestor chain
+     * (opacity composites rather than inherits).
      */
     private record Paint(PaintValue fill, PaintValue stroke, double strokeWidth,
                          DocumentLineCap lineCap, DocumentLineJoin lineJoin,
-                         List<Double> dashArray) {
+                         List<Double> dashArray,
+                         double fillOpacity, double strokeOpacity, double groupOpacity,
+                         boolean evenOddFill) {
     }
 
     /**
-     * One-warning-per-kind tally for shape elements we deliberately drop
-     * (text, images, embedded references). Emitted once after the walk so a
-     * busy icon doesn't flood the log.
+     * One-warning-per-kind tally for elements we drop (text, images,
+     * embedded references, element kinds the reader does not know) and for
+     * features that render approximately rather than exactly
+     * ({@code fill-rule="evenodd"}). Emitted once after the walk so a busy
+     * icon doesn't flood the log.
      */
     private static final class SkipTally {
         private final Set<String> kinds = new java.util.LinkedHashSet<>();
+        private final Set<String> degraded = new java.util.LinkedHashSet<>();
 
         void note(String kind) {
             kinds.add(kind);
         }
 
+        void noteDegraded(String feature) {
+            degraded.add(feature);
+        }
+
         void flush() {
             if (!kinds.isEmpty()) {
                 LOG.warn("SvgIcon: skipped unsupported element(s) {} — this icon reader renders "
-                         + "vector geometry only (no text, images, <use>, masks, clips or filters)",
+                         + "vector shape geometry only (no text, images, <use> references, "
+                         + "masks, filters or CSS stylesheets)",
                         kinds);
             }
+            if (!degraded.isEmpty()) {
+                LOG.warn("SvgIcon: approximated unsupported feature(s) {} — the geometry "
+                         + "renders, but not exactly as a browser paints it", degraded);
+            }
         }
 
         /**
@@ -613,8 +743,8 @@ String reason() {
                 return "";
             }
             return " — skipped " + String.join(", ", kinds)
-                   + "; this reader renders vector shapes only (no text, images, <use>, "
-                   + "masks, clips or filters)";
+                   + "; this reader renders vector shapes only (no text, images, <use> "
+                   + "references, masks, filters or CSS stylesheets)";
         }
     }
 }
diff --git a/core/src/main/java/com/demcha/compose/document/svg/SvgStyles.java b/core/src/main/java/com/demcha/compose/document/svg/SvgStyles.java
index b204ced6d..d6f32f016 100644
--- a/core/src/main/java/com/demcha/compose/document/svg/SvgStyles.java
+++ b/core/src/main/java/com/demcha/compose/document/svg/SvgStyles.java
@@ -14,7 +14,9 @@
  * {@code rgba()} with numbers or percentages, the CSS named-colour table,
  * {@code none}, {@code currentColor}), absolute CSS lengths
  * ({@code px} = user units, {@code pt}, {@code in}, {@code mm}, {@code cm},
- * {@code pc}), and the stroke style trio {@code stroke-linecap} /
+ * {@code pc}), opacity values ({@code opacity} / {@code fill-opacity} /
+ * {@code stroke-opacity} — a number or percentage, clamped into [0,1]),
+ * and the stroke style trio {@code stroke-linecap} /
  * {@code stroke-linejoin} / {@code stroke-dasharray}.
  *
  * <p>Everything unsupported fails loudly with the supported alternatives
@@ -79,14 +81,19 @@ private static DocumentColor hexColor(String hex) {
         if (expanded == null) {
             return null;
         }
-        DocumentColor color = DocumentColor.rgb(
-                Integer.parseInt(expanded.substring(0, 2), 16),
-                Integer.parseInt(expanded.substring(2, 4), 16),
-                Integer.parseInt(expanded.substring(4, 6), 16));
-        if (expanded.length() == 8) {
-            color = color.withOpacity(Integer.parseInt(expanded.substring(6, 8), 16) / 255.0);
+        try {
+            DocumentColor color = DocumentColor.rgb(
+                    Integer.parseInt(expanded.substring(0, 2), 16),
+                    Integer.parseInt(expanded.substring(2, 4), 16),
+                    Integer.parseInt(expanded.substring(4, 6), 16));
+            if (expanded.length() == 8) {
+                color = color.withOpacity(Integer.parseInt(expanded.substring(6, 8), 16) / 255.0);
+            }
+            return color;
+        } catch (NumberFormatException e) {
+            throw new IllegalArgumentException(
+                    "invalid hex colour '#" + hex + "' — digits must be 0-9 / a-f", e);
         }
-        return color;
     }
 
     private static DocumentColor rgbColor(String v) {
@@ -108,22 +115,60 @@ private static DocumentColor rgbColor(String v) {
     private static int channel(String value) {
         String t = value.trim();
         if (t.endsWith("%")) {
-            double pct = Math.max(0, Math.min(100, Double.parseDouble(t.substring(0, t.length() - 1))));
+            double pct = Math.max(0, Math.min(100,
+                    number(t.substring(0, t.length() - 1), "rgb() channel percentage")));
             // pct/100*255 keeps 50% exact (127.5 → 128); pct*2.55 drifts to 127.
             return (int) Math.round(pct / 100.0 * 255.0);
         }
-        return Math.max(0, Math.min(255, (int) Math.round(Double.parseDouble(t))));
+        return Math.max(0, Math.min(255, (int) Math.round(number(t, "rgb() channel"))));
     }
 
     /** rgba() alpha: 0–1 number or percentage, clamped. */
     private static double alpha(String value) {
         String t = value.trim();
         double a = t.endsWith("%")
-                ? Double.parseDouble(t.substring(0, t.length() - 1)) / 100.0
-                : Double.parseDouble(t);
+                ? number(t.substring(0, t.length() - 1), "rgba() alpha percentage") / 100.0
+                : number(t, "rgba() alpha");
         return Math.max(0.0, Math.min(1.0, a));
     }
 
+    /**
+     * Parses an opacity value ({@code opacity} / {@code fill-opacity} /
+     * {@code stroke-opacity}): a number in [0,1] or a percentage, clamped
+     * per SVG rather than refused.
+     *
+     * @param value   raw attribute value
+     * @param context attribute name for the error message
+     * @return opacity in [0,1]
+     * @throws IllegalArgumentException when the value is not numeric
+     */
+    static double opacity(String value, String context) {
+        String t = value.trim();
+        double a = t.endsWith("%")
+                ? number(t.substring(0, t.length() - 1), context) / 100.0
+                : number(t, context);
+        if (Double.isNaN(a)) {
+            // Double.parseDouble accepts the literal "NaN"; letting it through
+            // would silently hide the subtree (NaN fails every > 0 check).
+            throw new IllegalArgumentException(
+                    context + " must be a number, got '" + value + "'");
+        }
+        return Math.max(0.0, Math.min(1.0, a));
+    }
+
+    /**
+     * Returns the colour with its alpha multiplied by {@code factor} — the
+     * compositing step for {@code fill-opacity} / {@code stroke-opacity} /
+     * group {@code opacity} on top of any alpha the colour already carries
+     * (e.g. from an 8-digit hex or {@code rgba()}).
+     */
+    static DocumentColor multiplyAlpha(DocumentColor color, double factor) {
+        if (factor >= 1.0) {
+            return color;
+        }
+        return color.withOpacity(color.color().getAlpha() / 255.0 * factor);
+    }
+
     // ------------------------------------------------------------------
     // Lengths
     // ------------------------------------------------------------------
@@ -144,7 +189,7 @@ static double length(String value, String context) {
             unitStart--;
         }
         String unit = v.substring(unitStart);
-        double number = Double.parseDouble(v.substring(0, unitStart).trim());
+        double number = number(v.substring(0, unitStart).trim(), context);
         return switch (unit) {
             case "", "px" -> number;
             case "pt" -> number * (96.0 / 72.0);
@@ -234,4 +279,20 @@ static List<Double> dashArray(String value) {
         }
         return List.copyOf(lengths);
     }
+
+    /**
+     * Parses a numeric presentation value, naming what failed and the
+     * offending input instead of leaking the raw
+     * {@link NumberFormatException} message ("For input string: …") — the
+     * same convention {@code SvgIconReader} and {@code SvgGradients} use.
+     * The cause is chained so the JDK detail survives.
+     */
+    private static double number(String value, String what) {
+        try {
+            return Double.parseDouble(value);
+        } catch (NumberFormatException e) {
+            throw new IllegalArgumentException(
+                    what + " must be a number, got '" + value + "'", e);
+        }
+    }
 }
diff --git a/core/src/test/java/com/demcha/compose/document/svg/SvgIconOpacityAndWarningsTest.java b/core/src/test/java/com/demcha/compose/document/svg/SvgIconOpacityAndWarningsTest.java
new file mode 100644
index 000000000..0d2e4ac1f
--- /dev/null
+++ b/core/src/test/java/com/demcha/compose/document/svg/SvgIconOpacityAndWarningsTest.java
@@ -0,0 +1,347 @@
+package com.demcha.compose.document.svg;
+
+import ch.qos.logback.classic.Level;
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.read.ListAppender;
+import com.demcha.compose.document.style.DocumentPaint;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.slf4j.LoggerFactory;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Reader coverage for the opacity family ({@code opacity} /
+ * {@code fill-opacity} / {@code stroke-opacity}, multiplied down the tree
+ * into per-layer paint alpha) and the two degradation signals: the
+ * {@code fill-rule="evenodd"} approximation warning and the
+ * unknown-element tally that keeps a mask or pattern from vanishing
+ * silently.
+ */
+class SvgIconOpacityAndWarningsTest {
+
+    private ListAppender<ILoggingEvent> appender;
+    private ch.qos.logback.classic.Logger logger;
+
+    @BeforeEach
+    void captureWarnings() {
+        logger = (ch.qos.logback.classic.Logger) LoggerFactory.getLogger(SvgIconReader.class);
+        appender = new ListAppender<>();
+        appender.start();
+        logger.addAppender(appender);
+    }
+
+    @AfterEach
+    void releaseAppender() {
+        logger.detachAppender(appender);
+    }
+
+    private List<String> warnings() {
+        return appender.list.stream()
+                .filter(event -> event.getLevel() == Level.WARN)
+                .map(ILoggingEvent::getFormattedMessage)
+                .toList();
+    }
+
+    // ------------------------------------------------------------------
+    // Opacity family
+    // ------------------------------------------------------------------
+
+    @Test
+    void fillOpacityScalesTheFlatFillAlpha() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill="#ff0000" fill-opacity="0.5"/>
+                </svg>""");
+
+        assertThat(icon.layers()).hasSize(1);
+        assertThat(icon.layers().get(0).fill().color().getAlpha()).isEqualTo(128);
+    }
+
+    @Test
+    void strokeOpacityScalesTheStrokeAlphaOnly() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <path d="M0 0 L10 10" fill="none" stroke="#000000"
+                        stroke-width="2" stroke-opacity="0.25"/>
+                </svg>""");
+
+        SvgIcon.Layer layer = icon.layers().get(0);
+        assertThat(layer.fill()).isNull();
+        assertThat(layer.stroke().color().color().getAlpha()).isEqualTo(64);
+    }
+
+    @Test
+    void groupOpacityMultipliesIntoDescendantPaint() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <g opacity="0.5">
+                    <rect width="10" height="10" fill="#ff0000" fill-opacity="0.5"/>
+                  </g>
+                </svg>""");
+
+        assertThat(icon.layers().get(0).fill().color().getAlpha()).isEqualTo(64);
+    }
+
+    @Test
+    void opacityMultipliesAlphaTheColourAlreadyCarries() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill="#ff000080" fill-opacity="0.5"/>
+                </svg>""");
+
+        // 8-digit hex alpha 0x80 (128/255) times fill-opacity 0.5 → 64.
+        assertThat(icon.layers().get(0).fill().color().getAlpha()).isEqualTo(64);
+    }
+
+    @Test
+    void percentageOpacityIsAccepted() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill="#ff0000" fill-opacity="50%"/>
+                </svg>""");
+
+        assertThat(icon.layers().get(0).fill().color().getAlpha()).isEqualTo(128);
+    }
+
+    @Test
+    void zeroFillOpacityHidesTheFillButKeepsTheStroke() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill="#ff0000" fill-opacity="0"
+                        stroke="#000000" stroke-width="1"/>
+                </svg>""");
+
+        SvgIcon.Layer layer = icon.layers().get(0);
+        assertThat(layer.fill()).isNull();
+        assertThat(layer.stroke()).isNotNull();
+    }
+
+    @Test
+    void zeroOpacityDropsTheLayerEntirely() {
+        assertThatThrownBy(() -> SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill="#ff0000" opacity="0"/>
+                </svg>"""))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("no drawable geometry");
+    }
+
+    @Test
+    void partialOpacityOnAGradientFillPaintsOpaqueAndWarns() {
+        // The DocumentPaint contract refuses translucent stops (shadings carry
+        // no alpha), so a partial opacity cannot reach a gradient fill — the
+        // gradient stays opaque and the degradation is said once.
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <linearGradient id="g">
+                    <stop offset="0" stop-color="#ff0000"/>
+                    <stop offset="1" stop-color="#0000ff"/>
+                  </linearGradient>
+                  <rect width="10" height="10" fill="url(#g)" fill-opacity="0.5"/>
+                </svg>""");
+
+        SvgIcon.Layer layer = icon.layers().get(0);
+        DocumentPaint.LinearAxis paint = (DocumentPaint.LinearAxis) layer.fillPaint();
+        assertThat(paint.stops()).allSatisfy(stop ->
+                assertThat(stop.color().color().getAlpha()).isEqualTo(255));
+        assertThat(warnings()).anyMatch(message ->
+                message.contains("opacity on a gradient fill"));
+    }
+
+    @Test
+    void zeroOpacityHidesAGradientFillEntirely() {
+        assertThatThrownBy(() -> SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <linearGradient id="g">
+                    <stop offset="0" stop-color="#ff0000"/>
+                    <stop offset="1" stop-color="#0000ff"/>
+                  </linearGradient>
+                  <rect width="10" height="10" fill="url(#g)" fill-opacity="0"/>
+                </svg>"""))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("no drawable geometry");
+    }
+
+    @Test
+    void malformedOpacityNamesTheAttributeAndTheElement() {
+        assertThatThrownBy(() -> SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill="#ff0000" fill-opacity="solid"/>
+                </svg>"""))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("fill-opacity")
+                .hasMessageContaining("must be a number")
+                .hasMessageContaining("<rect");
+    }
+
+    // ------------------------------------------------------------------
+    // fill-rule
+    // ------------------------------------------------------------------
+
+    @Test
+    void evenOddFillWarnsOncePerIconAndStillRenders() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <path d="M0 0 H10 V10 H0 Z M2 2 H8 V8 H2 Z" fill-rule="evenodd"/>
+                  <circle cx="5" cy="5" r="2" fill-rule="evenodd"/>
+                </svg>""");
+
+        assertThat(icon.layers()).hasSize(2);
+        List<String> warned = warnings().stream()
+                .filter(message -> message.contains("fill-rule=evenodd")).toList();
+        assertThat(warned).hasSize(1);
+        assertThat(warned.get(0)).contains("approximated");
+    }
+
+    @Test
+    void nonZeroAndInheritFillRulesStayQuiet() {
+        SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill-rule="nonzero"/>
+                  <circle cx="5" cy="5" r="2" fill-rule="inherit"/>
+                </svg>""");
+
+        assertThat(warnings()).noneMatch(message -> message.contains("fill-rule"));
+    }
+
+    @Test
+    void unknownFillRuleIsRefusedWithTheAlternatives() {
+        assertThatThrownBy(() -> SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill-rule="winding"/>
+                </svg>"""))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("unsupported fill-rule 'winding'");
+    }
+
+    // ------------------------------------------------------------------
+    // Unknown-element tally
+    // ------------------------------------------------------------------
+
+    @Test
+    void unknownElementsAreWarnedInsteadOfVanishing() {
+        SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <mask id="m"><rect width="10" height="10"/></mask>
+                  <rect width="10" height="10" fill="#ff0000"/>
+                </svg>""");
+
+        assertThat(warnings()).anyMatch(message ->
+                message.contains("skipped unsupported element(s)") && message.contains("mask"));
+    }
+
+    @Test
+    void unknownElementsAreNamedWhenTheIconEndsUpEmpty() {
+        assertThatThrownBy(() -> SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <pattern id="p"><rect width="2" height="2"/></pattern>
+                </svg>"""))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("no drawable geometry")
+                .hasMessageContaining("skipped pattern");
+    }
+
+    @Test
+    void maskAndFilterAttributesWarnEvenWithDefinitionsInDefs() {
+        // The standard exporter idiom: the <mask> definition sits in <defs>
+        // (never walked), only the referencing attribute is visible.
+        SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <defs><mask id="m"><rect width="5" height="5" fill="#fff"/></mask></defs>
+                  <rect width="10" height="10" fill="#ff0000" mask="url(#m)"/>
+                  <circle cx="5" cy="5" r="2" style="filter:url(#f)"/>
+                </svg>""");
+
+        List<String> degraded = warnings().stream()
+                .filter(message -> message.contains("approximated")).toList();
+        assertThat(degraded).hasSize(1);
+        assertThat(degraded.get(0))
+                .contains("mask (painted unmasked)")
+                .contains("filter (painted unfiltered)");
+    }
+
+    @Test
+    void gradientStrokePartialOpacityWarnsToo() {
+        SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <linearGradient id="g">
+                    <stop offset="0" stop-color="#ff0000"/>
+                    <stop offset="1" stop-color="#0000ff"/>
+                  </linearGradient>
+                  <path d="M0 0 L10 10" fill="none" stroke="url(#g)"
+                        stroke-width="2" stroke-opacity="0.5"/>
+                </svg>""");
+
+        assertThat(warnings()).anyMatch(message ->
+                message.contains("opacity on a gradient stroke"));
+    }
+
+    @Test
+    void fillOpacityInheritsAndAnExplicitValueReplacesIt() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <g fill-opacity="0.5">
+                    <rect width="10" height="4" fill="#ff0000"/>
+                    <rect y="6" width="10" height="4" fill="#ff0000" fill-opacity="0.25"/>
+                  </g>
+                </svg>""");
+
+        // First rect inherits 0.5; the second's own value replaces (not
+        // multiplies) the inherited one, per SVG property inheritance.
+        assertThat(icon.layers().get(0).fill().color().getAlpha()).isEqualTo(128);
+        assertThat(icon.layers().get(1).fill().color().getAlpha()).isEqualTo(64);
+    }
+
+    @Test
+    void opacityInStyleAttributeIsHonoured() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" style="fill:#ff0000;opacity:0.5"/>
+                </svg>""");
+
+        assertThat(icon.layers().get(0).fill().color().getAlpha()).isEqualTo(128);
+    }
+
+    @Test
+    void zeroStrokeOpacityHidesTheStrokeButKeepsTheFill() {
+        SvgIcon icon = SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill="#ff0000"
+                        stroke="#000000" stroke-width="1" stroke-opacity="0"/>
+                </svg>""");
+
+        SvgIcon.Layer layer = icon.layers().get(0);
+        assertThat(layer.fill()).isNotNull();
+        assertThat(layer.stroke()).isNull();
+    }
+
+    @Test
+    void nanOpacityIsRefusedNotSilentlyHidden() {
+        assertThatThrownBy(() -> SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <rect width="10" height="10" fill="#ff0000" opacity="NaN"/>
+                </svg>"""))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("opacity")
+                .hasMessageContaining("must be a number");
+    }
+
+    @Test
+    void structureOnlyElementsStayOutOfTheTally() {
+        SvgIcon.parse("""
+                <svg viewBox="0 0 10 10">
+                  <title>icon</title>
+                  <desc>a square</desc>
+                  <defs><clipPath id="c"><rect width="5" height="5"/></clipPath></defs>
+                  <rect width="10" height="10" fill="#ff0000"/>
+                </svg>""");
+
+        assertThat(warnings()).noneMatch(message ->
+                message.contains("skipped unsupported element(s)"));
+    }
+}
diff --git a/core/src/test/java/com/demcha/compose/document/svg/SvgPathTest.java b/core/src/test/java/com/demcha/compose/document/svg/SvgPathTest.java
index 039910863..e90c820a7 100644
--- a/core/src/test/java/com/demcha/compose/document/svg/SvgPathTest.java
+++ b/core/src/test/java/com/demcha/compose/document/svg/SvgPathTest.java
@@ -217,4 +217,37 @@ void strayTokenAfterCloseIsRejectedAndDoesNotHang() {
                             .hasMessageContaining("position");
                 });
     }
+
+    @Test
+    void scientificNotationNumbersParse() {
+        // Optimizing exporters (SVGO) emit exponents: 1e1 = 10, 2E1 = 20,
+        // 5e-1 = 0.5. Same square as "M0 0 L10 0 L10 10 L0 10 Z".
+        SvgPath path = SvgPath.parse("M0 0 L1e1 0 L1E1 1e+1 L0 10 Z", 0, 0, 10, 10);
+
+        List<DocumentPathSegment> s = path.segments();
+        assertThat(s).hasSize(5);
+        LineTo corner = (LineTo) s.get(2);
+        assertThat(corner.x()).isCloseTo(1.0, within(1e-9));
+        // SVG y=10 is the viewBox bottom → flipped to 0.
+        assertThat(corner.y()).isCloseTo(0.0, within(1e-9));
+        LineTo half = (LineTo) SvgPath.parse("M0 0 L5e-1 0 L0.5 1 Z", 0, 0, 1, 1)
+                .segments().get(1);
+        assertThat(half.x()).isCloseTo(0.5, within(1e-9));
+    }
+
+    @Test
+    void rotatedArcLandsOnItsEndpoint() {
+        // x-axis-rotation only shapes the interior of the arc; the endpoint
+        // contract holds regardless. Pin it for a non-zero rotation, which no
+        // other test exercises.
+        SvgPath path = SvgPath.parse("M0 5 A5 2.5 45 0 1 10 5", 0, 0, 10, 10);
+
+        List<DocumentPathSegment> s = path.segments();
+        assertThat(s.get(0)).isInstanceOf(MoveTo.class);
+        assertThat(s.size()).isGreaterThanOrEqualTo(2);
+        assertThat(s.subList(1, s.size())).allMatch(segment -> segment instanceof CubicTo);
+        CubicTo last = (CubicTo) s.get(s.size() - 1);
+        assertThat(last.x()).isCloseTo(1.0, within(1e-9));
+        assertThat(last.y()).isCloseTo(0.5, within(1e-9));
+    }
 }
diff --git a/core/src/test/java/com/demcha/compose/document/svg/SvgStylesTest.java b/core/src/test/java/com/demcha/compose/document/svg/SvgStylesTest.java
index 7a0f1642a..4ccba9d21 100644
--- a/core/src/test/java/com/demcha/compose/document/svg/SvgStylesTest.java
+++ b/core/src/test/java/com/demcha/compose/document/svg/SvgStylesTest.java
@@ -102,4 +102,50 @@ void dashArrayReturnsImmutableList() {
         assertThatThrownBy(() -> dashes.add(1.0))
                 .isInstanceOf(UnsupportedOperationException.class);
     }
+
+    @Test
+    void malformedHexDigitsFailWithContextNotARawNumberFormatException() {
+        assertThatThrownBy(() -> SvgStyles.color("#zzz", INK))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("invalid hex colour '#zzz'")
+                .hasCauseInstanceOf(NumberFormatException.class);
+    }
+
+    @Test
+    void malformedRgbChannelsFailWithContextNotARawNumberFormatException() {
+        assertThatThrownBy(() -> SvgStyles.color("rgb(1, 2, wide)", INK))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("rgb() channel")
+                .hasMessageContaining("must be a number");
+        assertThatThrownBy(() -> SvgStyles.color("rgba(1, 2, 3, dim)", INK))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("rgba() alpha");
+    }
+
+    @Test
+    void rgbChannelsClampIntoRange() {
+        Color clamped = SvgStyles.color("rgb(300, -20, 128)", INK).color();
+        assertThat(clamped.getRed()).isEqualTo(255);
+        assertThat(clamped.getGreen()).isZero();
+        assertThat(clamped.getBlue()).isEqualTo(128);
+    }
+
+    @Test
+    void lengthWithoutANumberNamesTheAttribute() {
+        assertThatThrownBy(() -> SvgStyles.length("px", "stroke-width"))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("stroke-width")
+                .hasMessageContaining("must be a number");
+    }
+
+    @Test
+    void opacityParsesNumbersAndPercentagesAndClamps() {
+        assertThat(SvgStyles.opacity("0.5", "opacity")).isCloseTo(0.5, within(1e-9));
+        assertThat(SvgStyles.opacity("50%", "opacity")).isCloseTo(0.5, within(1e-9));
+        assertThat(SvgStyles.opacity("1.5", "opacity")).isCloseTo(1.0, within(1e-9));
+        assertThat(SvgStyles.opacity("-0.5", "opacity")).isCloseTo(0.0, within(1e-9));
+        assertThatThrownBy(() -> SvgStyles.opacity("solid", "fill-opacity"))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("fill-opacity");
+    }
 }
diff --git a/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java b/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java
index edba51a18..9cabfcc0d 100644
--- a/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java
+++ b/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java
@@ -19,6 +19,8 @@
 import com.demcha.compose.document.node.DocumentNode;
 import com.demcha.compose.document.node.ImageNode;
 import com.demcha.compose.document.node.PageBreakNode;
+import com.demcha.compose.document.node.InlineHighlightRun;
+import com.demcha.compose.document.node.InlineRun;
 import com.demcha.compose.document.node.InlineTextRun;
 import com.demcha.compose.document.node.ParagraphNode;
 import com.demcha.compose.document.node.TextDirection;
@@ -207,6 +209,28 @@ private void warnUnsupported(DocumentNode node) {
         }
     }
 
+    /**
+     * One warning per dropped inline-run kind, deduplicated across the
+     * export — the inline mirror of {@link #warnUnsupported(DocumentNode)}.
+     * {@code inlineTextRuns()} keeps text and highlight chips but drops
+     * image / shape / SVG runs (emoji lower to SVG runs, so they drop too);
+     * without this the paragraph text survives while its icons vanish with
+     * no signal at all, weaker than the block-level drop path.
+     */
+    private void warnDroppedInlineRuns(ParagraphNode node) {
+        for (InlineRun run : node.inlineRuns()) {
+            if (run instanceof InlineTextRun || run instanceof InlineHighlightRun) {
+                continue;
+            }
+            String kind = run.getClass().getSimpleName();
+            if (warnedNodeKinds.add("inline:" + kind)) {
+                LOG.warn("DocxSemanticBackend: dropping inline '{}' run(s) — no semantic Word "
+                         + "analogue; the paragraph text renders without them, use the PDF "
+                         + "backend for full fidelity", kind);
+            }
+        }
+    }
+
     /**
      * Semantic list mapping: each item becomes a marker-prefixed paragraph in
      * the list's text style. Flat items run through the same
@@ -392,6 +416,7 @@ private static void applyDirection(XWPFParagraph para, boolean rightToLeft) {
      * {@code inlineTextRuns()} returns, highlight chips included.</p>
      */
     private void writeParagraphRuns(XWPFParagraph para, ParagraphNode node, boolean rightToLeft) {
+        warnDroppedInlineRuns(node);
         List<InlineTextRun> runs = node.inlineTextRuns();
         if (runs.isEmpty()) {
             XWPFRun docRun = para.createRun();
diff --git a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxInlineRunDropWarningTest.java b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxInlineRunDropWarningTest.java
new file mode 100644
index 000000000..f278d4444
--- /dev/null
+++ b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxInlineRunDropWarningTest.java
@@ -0,0 +1,104 @@
+package com.demcha.compose.document.backend.semantic.docx;
+
+import ch.qos.logback.classic.Level;
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import ch.qos.logback.core.read.ListAppender;
+import com.demcha.compose.GraphCompose;
+import com.demcha.compose.document.api.DocumentSession;
+import com.demcha.compose.document.style.DocumentInsets;
+import com.demcha.compose.document.svg.SvgIcon;
+import org.apache.poi.xwpf.usermodel.XWPFDocument;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.slf4j.LoggerFactory;
+
+import java.io.ByteArrayInputStream;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Covers the signal for inline runs the DOCX export cannot carry.
+ *
+ * <p>{@code ParagraphNode.inlineTextRuns()} keeps text and highlight chips but
+ * drops image / shape / SVG runs by contract, so a paragraph's icons vanish
+ * from the DOCX while its text survives. Block-level drops already warn once
+ * per node kind; without the inline mirror the only observable difference
+ * between "rendered" and "lost" was opening the file. The warning is the
+ * whole of what makes the inline drop visible, which makes it worth a test.</p>
+ */
+class DocxInlineRunDropWarningTest {
+
+    private static final String ICON = """
+            <svg viewBox="0 0 10 10"><rect width="10" height="10" fill="#ff0000"/></svg>""";
+
+    private ListAppender<ILoggingEvent> appender;
+    private ch.qos.logback.classic.Logger logger;
+
+    @BeforeEach
+    void captureWarnings() {
+        logger = (ch.qos.logback.classic.Logger) LoggerFactory.getLogger(DocxSemanticBackend.class);
+        appender = new ListAppender<>();
+        appender.start();
+        logger.addAppender(appender);
+    }
+
+    @AfterEach
+    void releaseAppender() {
+        logger.detachAppender(appender);
+    }
+
+    private List<String> inlineDropWarnings() {
+        return appender.list.stream()
+                .filter(event -> event.getLevel() == Level.WARN)
+                .map(ILoggingEvent::getFormattedMessage)
+                .filter(message -> message.contains("dropping inline"))
+                .toList();
+    }
+
+    @Test
+    void droppedInlineSvgRunsWarnOncePerExportAndKeepTheText() throws Exception {
+        SvgIcon icon = SvgIcon.parse(ICON);
+        byte[] docx;
+        try (DocumentSession document = GraphCompose.document()
+                .pageSize(400, 200)
+                .margin(DocumentInsets.of(20))
+                .create()) {
+            document.pageFlow(page -> {
+                page.addParagraph(p -> p
+                        .inlineText("before ")
+                        .inlineSvgIcon(icon, 10)
+                        .inlineText(" after"));
+                page.addParagraph(p -> p
+                        .inlineText("second ")
+                        .inlineSvgIcon(icon, 10));
+            });
+            docx = document.export(new DocxSemanticBackend());
+        }
+
+        List<String> warned = inlineDropWarnings();
+        assertThat(warned).hasSize(1);
+        assertThat(warned.get(0)).contains("InlineSvgRun");
+
+        try (XWPFDocument opened = new XWPFDocument(new ByteArrayInputStream(docx))) {
+            String text = opened.getParagraphs().stream()
+                    .map(paragraph -> paragraph.getText())
+                    .reduce("", (a, b) -> a + "\n" + b);
+            assertThat(text).contains("before").contains("after").contains("second");
+        }
+    }
+
+    @Test
+    void textOnlyParagraphsStayQuiet() throws Exception {
+        try (DocumentSession document = GraphCompose.document()
+                .pageSize(400, 200)
+                .margin(DocumentInsets.of(20))
+                .create()) {
+            document.pageFlow(page -> page.addParagraph("plain text only"));
+            document.export(new DocxSemanticBackend());
+        }
+
+        assertThat(inlineDropWarnings()).isEmpty();
+    }
+}