diff --git a/docs/contribute/icons/design-principles.md b/docs/contribute/icons/design-principles.md
index d9827d560..d79a0e91c 100644
--- a/docs/contribute/icons/design-principles.md
+++ b/docs/contribute/icons/design-principles.md
@@ -8,230 +8,190 @@ Lucide is designed as a consistent icon set, not just a collection of individual
This guide explains the visual principles behind Lucide icons and how to apply them when designing new icons.
-For concrete requirements such as canvas size, stroke width, spacing, and corner radii, see the [Icon Design Specification](./specification).
+For concrete requirements, see the [Icon Design Specification](./specification).
## 1. Use a 24 × 24 pixel canvas
-:::: example
-
Icons **must** be designed on a 24 × 24 pixel canvas.
+:::: example
::: do ../../images/24px-24px.svg?raw=true
Use a **24 × 24 pixel** canvas.
:::
-
::: dont ../../images/24px-24px-violation.svg?raw=true
Use a larger or smaller canvas, or one that's not square.
:::
-
::::
## 2. Keep 1 pixel of safe zone
-:::: example
-
Icons **must** have at least 1 pixel of padding between their strokes and the edge of the canvas.
+:::: example
::: do ../../images/1px-padding.svg?raw=true
Keep at least **1 pixel of padding** around the icon.
:::
-
-::: dont ../../images/0px-padding.svg?raw=true
-Failing to keep this safe zone will result in trimmed visuals.
+::: dont ../../images/1px-padding-violation.svg?raw=true
+You must leave this safe zone, otherwise it might result in trimmed visuals.
:::
-
::::
## 3. Use 2 pixel strokes
-:::: example
-
Strokes **must** be 2 pixels wide.
+:::: example
::: do ../../images/2px-stroke.svg?raw=true
Use a **2 pixel stroke width**.
:::
-
::: dont ../../images/2px-stroke-violation.svg?raw=true
-Avoid thicker or thinner strokes.
+Avoid **thicker or thinner** strokes, or **mixing stroke widths**.
:::
-
::::
-
## 4. Use round line joins
-:::: example
-
Strokes **must** use round line joins.
+:::: example
::: do ../../images/round-joints.svg?raw=true
Use **round line joins**.
:::
-
::: dont ../../images/round-joints-violation.svg?raw=true
You **must not** use **miter or bevel** line joins.
:::
-
::::
+::: tip
+Even though round line joins are used, you should still add corner rounding to most sharp corners.
+:::
+
## 5. Use round line caps
-:::: example
-
Open paths **must** use round line caps.
+:::: example
::: do ../../images/round-caps.svg?raw=true
Use **round line caps** on open paths.
:::
-
::: dont ../../images/round-caps-violation.svg?raw=true
You **must not** use **butt or square** line caps.
:::
-
::::
## 6. Use centered strokes
-:::: example
-
Strokes **must** be centered on their paths.
+:::: example
::: do ../../images/centered-strokes.svg?raw=true
Keep strokes **centered** on their paths.
:::
-
::: dont ../../images/centered-strokes-violation.svg?raw=true
-You **must not** use **inside or outside** strokes.
+You **must not** use **inside or outside** strokes, as they alter the intended appearance of line joins.
:::
-
::::
## 7. Use consistent corner radii
+Almost every sharp corner **should** be rounded.
+
:::: example
-
-Almost all sharp corners **should** be rounded:
-
::: do ../../images/border-radius-correct.svg?raw=true
-Use rounded corners.
+Use **rounded corners**.
:::
-
::: dont ../../images/border-radius-violation.svg?raw=true
-Avoid sharp corners.
+Avoid **sharp corners**.
:::
-
::::
-:::: example
-
The corner radius depends on the size of the element and the angle. For 90° angles you should:
+:::: example
::: do ../../images/2px-border-radius.svg?raw=true
Use a **2 pixel corner radius** for shapes that are at least 8 pixels wide or tall.
:::
-
::: do ../../images/1px-border-radius.svg?raw=true
Use a **1 pixel corner radius** for shapes smaller than 8 pixels.
:::
-
::::
+But there are always exceptions to the rule:
+
:::: example
-
-But there are always exceptions to the rule.
-
::: do ../../images/border-radius-90deg.svg?raw=true
-Diagonal lines meeting at a right angle are usually rounded to 2.41 pixels in order to be perfectly grid aligned.
+Diagonal lines meeting at a right angle are usually rounded to **2.41 pixels** (1+√2) in order for the lines to be **perfectly grid aligned**.
:::
-
::: do ../../images/border-radius-arbitrary.svg?raw=true
-Even very sharp corners should have a minor amount of rounding applied, but how much exactly will vary on the geometry of the icon.
+Even **very sharp corners** should have a _minor_ amount of rounding applied, but how much exactly will vary on the geometry of the icon.
:::
-
::::
+Avoid rounding corners **where multiple lines meet**.
+
:::: example
-
-Again, _almost_ every sharp corner should be rounded, but there are exceptions to the rule.
-
::: do ../../images/border-radius-line-join.svg?raw=true
-Keep corners sharp if multiple lines meet.
+Keep corners sharp if multiple lines meet, this will ensure the icon scales in a consistent way.
:::
-
::: dont ../../images/border-radius-line-join-violation.svg?raw=true
-Make icons consistent at different scales by not rounding these corners.
+Make icons consistent at different scales by **not rounding** corners where more than two lines meet.
:::
-
::::
## 8. Keep 2 pixels of gap
-:::: example
-
Distinct elements **must** have at least 2 pixels of visual spacing between them.
+:::: example
::: do ../../images/2px-element-spacing.svg?raw=true
Keep **2 pixels of spacing** between distinct elements.
:::
-
::: dont ../../images/1px-element-spacing.svg?raw=true
Never use gaps smaller than **2 pixels** between distinct elements.
:::
-
::::
-:::: example
-
This includes the inside of shapes, so most inner gaps **should** be at least 2 pixels wide.
+:::: example
::: do ../../images/2px-inner-spacing.svg?raw=true
Keep at least **2 pixels of spacing** inside shapes.
:::
-
::: dont ../../images/1px-inner-spacing.svg?raw=true
Avoid inner gaps smaller than **2 pixels**.
:::
-
::::
+You can also visualize this rule by trying to place a **2 pixel wide circle** within your shape.
+
:::: example
-
-You can visualize this by trying to place a 2 pixel wide circle within your shape.
-
::: do ../../images/2px-inner-gap.svg?raw=true
-If a **2 pixel wide circle** fits inside the shape without overlapping, the gap is wide enough.
+If a **2 pixel wide circle** fits inside the shape without overlapping, the gap is **wide enough**.
:::
-
::: dont ../../images/1px-inner-gap.svg?raw=true
-If a **2 pixel wide circle** overlaps the shape, the inner gap should be wider.
+If a **2 pixel wide circle** overlaps the shape, the inner gap should be **wider**.
:::
-
::::
-
-:::: example
-
The 2 pixel spacing also applies when elements visually connect or intersect.
+:::: example
::: dont ../../images/2px-element-spacing-connected.svg?raw=true
-Maintain 2 pixels of spacing where elements visually connect.
+Maintain 2 pixels of spacing where elements **visually connect**.
:::
-
::: dont ../../images/2px-element-spacing-abrupt-cut.svg?raw=true
-Avoid abrupt cuts where one element meets another.
+Avoid **abrupt cuts** where one element meets another.
:::
-
::::
## 9. Aim for uniform volume
-:::: example
-
Icons should have a similar visual weight when viewed alongside each other.
+:::: example
+
::: do ../../images/visual-weight-consistent.svg?raw=true
Match the visual weight of `circle` and `square`.
:::
@@ -243,41 +203,33 @@ The second icon is **too large**, the fourth is **too small**.
::::
::: tip
-
The amount and distribution of strokes affect how heavy an icon appears. An icon with many closely spaced elements can appear much heavier than a simpler icon, even when both use the same stroke width.
Place your icon next to `circle` or `square` and blur them. Your icon should not appear significantly lighter or darker than the reference icon.
-
:::
## 10. Balance icons visually
-:::: example
-
Icons should appear centered and balanced within the canvas.
+:::: example
::: do ../../images/visually-centered-do.svg?raw=true
Keep your icons visually centered.
:::
-
::: dont ../../images/visually-centered-dont.svg?raw=true
The optical volume of this icon is offset to the top left.
:::
-
::::
-:::: example
Symmetrical icons should remain geometrically centered.
+:::: example
::: do ../../images/visually-centered-symmetrical-do.svg?raw=true
:::
-
::: dont ../../images/visually-centered-symmetrical-dont.svg?raw=true
:::
-
::::
-
::: tip
Geometric centering does not always produce a visually centered icon. Asymmetrical shapes may need to be moved slightly to compensate for their visual center of gravity.
@@ -286,18 +238,15 @@ Compare your icon with `circle` or `square` both side by side and vertically. If
## 11. Keep density low
-:::: example
-
Lucide icons should have a similar visual density and level of detail.
+:::: example
::: do ../../images/density-optimal.svg?raw=true
Simplify complex subjects, preserving the features that make them identifiable.
:::
-
::: dont ../../images/density-too-dense.svg?raw=true
Avoid adding unnecessary details that make the design dense.
:::
-
::::
::: tip
@@ -310,17 +259,14 @@ View the icon at its intended size and try blurring it. Areas that become notice
## 12. Use smooth, simple curves
-
-:::: example
-
Curves should be smooth and use the simplest geometry that accurately describes the shape.
+:::: example
::: do ../../images/curvature-smooth.svg?raw=true
-Prefer simple arcs and quadratic curves where possible.
+Prefer **simple arcs** and **quadratic curves** where possible.
:::
-
::: dont ../../images/curvature-uneven.svg?raw=true
-Avoid uneven or unnecessarily complex curves.
+Avoid **uneven or unnecessarily complex** curves.
:::
::::
@@ -332,8 +278,9 @@ Avoid unnecessary control points. They make shapes harder to maintain and can in
## 13. Design for the pixel grid
-:::: example
Lucide icons should appear sharp and intentional at small sizes, including on low-density displays.
+
+:::: example
::: do ../../images/pixel-perfection-ideal.svg?raw=true
Align coordinates and the centers of arcs and other geometric elements to the pixel grid where possible.
:::
@@ -342,39 +289,51 @@ Avoid placing geometry off the pixel grid without a visual reason.
:::
::::
+:::: example
+::: do ../../images/pixel-perfection-subelement-do.svg?raw=true
+Also **align subelements** to the pixel grid.
+:::
+::: dont ../../images/pixel-perfection-subelement-dont.svg?raw=true
+You **must not** place subelements off-grid, as they'll become blurry on low density displays.
+:::
+::::
+
::: tip
Pixel alignment should support the overall appearance of the icon rather than come at the expense of recognizable shapes, smooth curves, or visual balance.
:::
## 14. Reuse established shapes
-:::: example
When creating variant icons, preserve the geometry of the base icon unless the new concept requires a change.
+
+:::: example
::: do ../../images/established-shapes-base-do.svg?raw=true
-Reuse existing base icons exactly as they appear.
+Reuse existing base icons **exactly as they appear**.
:::
::: dont ../../images/established-shapes-base-dont.svg?raw=true
Avoid altering the **geometry, placement and orientation** of base shapes.
:::
::::
-:::: example
Related icons should share the same shapes and visual patterns wherever possible.
+
+:::: example
::: do ../../images/established-shapes-sub-do.svg?raw=true
-Reuse elements from existing icons without change.
+Reuse elements from existing icons **without change**.
:::
::: dont ../../images/established-shapes-sub-dont.svg?raw=true
-Avoid creating new designs for existing elements.
+Avoid creating **new designs for existing elements**.
:::
::::
+Common modifiers and elements should behave and appear consistently across both icon sets and the library.
+
:::: example
-Common modifiers and elements should behave consistently across both icon sets and the library.
::: do ../../images/established-shapes-consistency-do.svg?raw=true
-Maintain consistency between the placement and size of addons.
+Maintain consistency between the **placement and size** of addons.
:::
::: dont ../../images/established-shapes-consistency-dont.svg?raw=true
-Avoid using irregular placements and sizes compared to existing icons.
+Avoid using **irregular placements and sizes** compared to existing icons.
:::
::::
@@ -399,4 +358,4 @@ When designing a Lucide icon:
9. **Align geometry to the pixel grid** where possible.
10. **Reuse established shapes and geometry** from existing Lucide icons.
-When these guidelines conflict, prioritize **clarity, visual balance, and consistency with the rest of Lucide**.
+When these guidelines conflict, you should prioritize **clarity, visual balance, and consistency** with the rest of the Lucide set.
diff --git a/docs/images/0px-padding.svg b/docs/images/0px-padding.svg
deleted file mode 100644
index 554fbca94..000000000
--- a/docs/images/0px-padding.svg
+++ /dev/null
@@ -1,63 +0,0 @@
-
diff --git a/docs/images/1px-element-spacing.svg b/docs/images/1px-element-spacing.svg
index e7461269e..6a5a976f0 100644
--- a/docs/images/1px-element-spacing.svg
+++ b/docs/images/1px-element-spacing.svg
@@ -53,14 +53,14 @@
-
-
-
+
+
+
-
-
-
+
+
+
diff --git a/docs/images/1px-padding-violation.svg b/docs/images/1px-padding-violation.svg
new file mode 100644
index 000000000..d9538fac6
--- /dev/null
+++ b/docs/images/1px-padding-violation.svg
@@ -0,0 +1,67 @@
+
diff --git a/docs/images/1px-padding.svg b/docs/images/1px-padding.svg
index 4c08aafb9..313a8c5a3 100644
--- a/docs/images/1px-padding.svg
+++ b/docs/images/1px-padding.svg
@@ -1,57 +1,61 @@
-
diff --git a/docs/images/established-shapes-base-do.svg b/docs/images/established-shapes-base-do.svg
index 8b1caab9d..54fb7f61f 100644
--- a/docs/images/established-shapes-base-do.svg
+++ b/docs/images/established-shapes-base-do.svg
@@ -1,14 +1,18 @@
-