docs: Add new section on 'Wrap Property Not Working Reliably' to PITFALLS.md, detailing issues and solutions for layout management in Pencil design.

.agent/skills/pencil-design/references/PITFALLS.md

@@ -15,6 +15,7 @@ Comprehensive list of common mistakes when working with Pencil `.pen` files and
 9. [Using Emoji Text for Icons](#9-using-emoji-text-for-icons)
 10. [Build Script Not Scanning Subdirectories](#10-build-script-not-scanning-subdirectories)
 11. [Components at Root Level](#11-components-at-root-level)
+12. [Wrap Property Not Working Reliably](#12-wrap-property-not-working-reliably)
 
 ---
 
@@ -301,6 +302,75 @@ for pen_file in sorted(dir_path.rglob('*.pen')):
 
 ---
 
+## 12. Wrap Property Not Working Reliably
+
+**Problem**: Setting `wrap: true` on a frame expects children to wrap to next row when exceeding container width. However, Pencil's wrap behavior is unreliable and often causes overflow instead of wrapping.
+
+**Symptom**: Elements overflow beyond container boundary instead of wrapping.
+
+**Solution**: Use manual rows with explicit horizontal layout instead of relying on wrap.
+
+```json
+// ❌ BAD: wrap không hoạt động như mong đợi
+{
+  "type": "frame",
+  "id": "TableGrid",
+  "width": "fill_container",
+  "layout": "horizontal",
+  "wrap": true,
+  "gap": 8,
+  "children": [
+    {"type": "frame", "id": "Table1", "width": 72, "height": 72},
+    {"type": "frame", "id": "Table2", "width": 72, "height": 72},
+    {"type": "frame", "id": "Table3", "width": 72, "height": 72},
+    {"type": "frame", "id": "Table4", "width": 72, "height": 72},
+    {"type": "frame", "id": "Table5", "width": 72, "height": 72},
+    {"type": "frame", "id": "Table6", "width": 72, "height": 72}
+  ]
+}
+
+// ✅ GOOD: Manual rows - chắc chắn layout đúng
+{
+  "type": "frame",
+  "id": "TableGrid",
+  "width": "fill_container",
+  "layout": "vertical",
+  "gap": 8,
+  "clip": true,
+  "children": [
+    {
+      "type": "frame", 
+      "id": "Row1", 
+      "width": "fill_container", 
+      "gap": 8, 
+      "children": [
+        {"type": "frame", "id": "Table1", "width": 72, "height": 72},
+        {"type": "frame", "id": "Table2", "width": 72, "height": 72},
+        {"type": "frame", "id": "Table3", "width": 72, "height": 72}
+      ]
+    },
+    {
+      "type": "frame", 
+      "id": "Row2", 
+      "width": "fill_container", 
+      "gap": 8, 
+      "children": [
+        {"type": "frame", "id": "Table4", "width": 72, "height": 72},
+        {"type": "frame", "id": "Table5", "width": 72, "height": 72},
+        {"type": "frame", "id": "Table6", "width": 72, "height": 72}
+      ]
+    }
+  ]
+}
+```
+
+**Tip**: Khi cần grid layout trong container có chiều rộng cố định:
+- Dùng `layout: vertical` cho container chính
+- Tạo các row con với `layout: horizontal` (mặc định)
+- Thêm `clip: true` để tránh overflow
+
+---
+
 ## Quick Checklist / Checklist Nhanh
 
 Before committing `.pen` files:
@@ -311,5 +381,6 @@ Before committing `.pen` files:
 - [ ] Icons use `icon_font` not emoji text
 - [ ] Build script uses `rglob()` for subdirectories
 - [ ] Components wrapped in layout frames, not at root level
+- [ ] **Avoid `wrap: true` - use manual rows instead**
 - [ ] Run `jq empty file.pen` to validate JSON syntax
 - [ ] Run `python3 scripts/build.py --library` before testing