docs: clarify LineWidth enum non-sequential style numbering

datawrapper/charts/enums/line_width.py

@@ -4,23 +4,29 @@
 class LineWidth(str, Enum):
     """Line width options for line charts.
 
-    These values control the stroke width of lines in charts:
-    - THINNEST (style3) = 1px stroke width
-    - THIN (style0) = 2px stroke width (default)
-    - MEDIUM (style1) = 3px stroke width
-    - THICK (style2) = 4px stroke width
-    - INVISIBLE = hidden line
+    These values control the stroke width of lines in charts.
+
+    ⚠️ IMPORTANT: The style numbers DO NOT increase with thickness!
+
+    Attributes:
+        THINNEST (style3): 1px stroke width - thinnest line
+        THIN (style0): 2px stroke width - default, despite being style0
+        MEDIUM (style1): 3px stroke width
+        THICK (style2): 4px stroke width - thickest line
+        INVISIBLE: Hidden line
 
     Examples:
-        >>> # Using enum (recommended - more readable)
-        >>> Line(column="sales", width=LineWidth.THICK)
+        >>> # Using enum (recommended - avoids confusion)
+        >>> Line(column="sales", width=LineWidth.THICK)  # ✓ Clearly 4px
+        >>> Line(column="sales", width=LineWidth.THINNEST)  # ✓ Clearly 1px
 
-        >>> # Using raw API values (also supported for backwards compatibility)
-        >>> Line(column="sales", width="style3")
+        >>> # Using raw API values (works but confusing)
+        >>> Line(column="sales", width="style2")  # 4px (thick, not thin!)
+        >>> Line(column="sales", width="style3")  # 1px (thinnest, not thickest!)
     """
 
-    THINNEST = "style3"
-    THIN = "style0"
-    MEDIUM = "style1"
-    THICK = "style2"
+    THINNEST = "style3"  # 1px - ⚠️ Highest number, thinnest line!
+    THIN = "style0"  # 2px (default)
+    MEDIUM = "style1"  # 3px
+    THICK = "style2"  # 4px - ⚠️ Not style3!
     INVISIBLE = "invisible"

datawrapper/charts/line.py

@@ -315,7 +315,16 @@ def validate_interpolation(
     #: The width of the line (use LineWidth enum or raw API values)
     width: LineWidth | str = Field(
         default="style1",
-        description="The width of the line. Use LineWidth enum for readability or raw API values (style0, style1, style2, style3, invisible).",
+        description=(
+            "The width of the line. Use LineWidth enum for readability or raw API values "
+            "(style0, style1, style2, style3, invisible).\n\n"
+            "Examples:\n"
+            "  Line(column='sales', width=LineWidth.THICK)  # style2 = 4px\n"
+            "  Line(column='sales', width='style2')  # Also 4px\n"
+            "  Line(column='sales', width=LineWidth.THINNEST)  # style3 = 1px\n\n"
+            "⚠️ Note: style numbers don't increase with thickness! "
+            "style0=2px (thin), style1=3px (medium), style2=4px (thick), style3=1px (thinnest)"
+        ),
     )
 
     #: The dashing of the line (use LineDash enum or raw API values)