diff --git a/docs/astro/src/content/docs/reference/common.mdx b/docs/astro/src/content/docs/reference/common.mdx
index 0a7a55b58c9..bbc1b202fb8 100644
--- a/docs/astro/src/content/docs/reference/common.mdx
+++ b/docs/astro/src/content/docs/reference/common.mdx
@@ -49,39 +49,57 @@ the element and its children with transparency.
 The opacity is applied to the tree of child elements as if they
 were first drawn into an intermediate layer, and then the whole layer is rendered with this opacity.
 
-:::tip[Tip]
-When an element has 0 opacity it will still take up layout space and any gesture handling will continue
-to work. If the intent is to hide an element so it has no gesture handling or no longer takes up layout space,
-use the `visible` property instead.
-:::
+<CodeSnippetMD imagePath="/src/assets/generated/rectangle-opacity.png" scale="3" imageWidth="100" imageHeight="310"  imageAlt='rectangle opacity'>
+```slint playground
+component ImageInfo inherits Rectangle {
+    in property <float> img-opacity: 1.0;
+    background: transparent;
+    VerticalLayout {
+        spacing: 5px;
+        Image {
+            source: @image-url("elements/slint-logo.png");
+            opacity: img-opacity;
+        }
+        Text {
+            text: "opacity: " + img-opacity;
+            color: white;
+            horizontal-alignment: center;
+        }
+    }
+}
+export component Example inherits Window {
+    width: 100px;
+    height: 310px;
+    background: transparent;
+    Rectangle {
+        background: #141414df;
+        border-radius: 10px;
+    }
+    VerticalLayout {
+        spacing: 15px;
+        padding-top: 10px;
+        padding-bottom: 10px;
+        ImageInfo {
+            img-opacity: 1.0;
+        }
+        ImageInfo {
+            img-opacity: 0.6;
+        }
+        ImageInfo {
+            img-opacity: 0.3;
+        }
+    }
+}
+```
+</CodeSnippetMD>
+
 </SlintProperty>
 
 ### visible
 <SlintProperty propName="visible" typeName="bool" defaultValue="true">
-When set to `false`, the element and all his children won't be drawn and not react to mouse input.
-
-The following example demonstrates the `opacity` property with children. An opacity is applied to the red rectangle. Since the green rectangle is a child of the red one, you can see the gradient underneath it, but you can't see the red rectangle through the green one.
-<CodeSnippetMD imagePath="/src/assets/generated/rectangle-opacity.png"  imageWidth="200" imageHeight="200"  imageAlt='rectangle opacity'>
-```slint
-Rectangle {
-    x: 10px;
-    y: 10px;
-    width: 180px;
-    height: 180px;
-    background: #315afd;
-    opacity: 0.5;
-}
+When set to `false`, the element and all his children won't be drawn and not react to mouse input. The element
+will still take up layout space within any layout container.
 
-Rectangle {
-    x: 10px;
-    y: 210px;
-    width: 180px;
-    height: 180px;
-    background: green;
-    opacity: 0.5;
-}
-```
-</CodeSnippetMD>
 </SlintProperty>
 
 ### absolute-position