| name | Lark PlantUML Standards |
| description | 11 กฎ mandatory สำหรับเขียน .puml ให้ render ผ่าน Lark Docs + layout สวย — ต้อง load ทุกครั้งที่เขียน/แก้ .puml |
PMO Skill: PlantUML Coding Standards for Lark (Strict Mode)
Related Skills: Load this skill whenever writing/editing any .puml file.
Often loaded alongside: pmo-activity-diagram, pmo-use-case-diagram
11 rules below are MANDATORY for every .puml file (SystemFlow, UserFlow, UseCase).
Rule 1-7: Lark Docs rendering compatibility (strict parser).
Rule 8-11: Layout quality (ป้องกันเส้นทับกัน, กล่องล้น lane, diagram กว้างเกิน).
Rule 1: FLAT CODE 100% (No Leading Whitespace)
Every line must start at column 0 - no space, tab, or NBSP prefix allowed.
' WRONG
:1. ทำงานแรก;
note right
**รายละเอียด**
end note
' CORRECT
:1. ทำงานแรก;
note right
**รายละเอียด**
end note
Verify: grep -c '^[[:space:]]' FILE must return 0
Rule 2: NO AMPERSAND (& -> and)
Never use & anywhere in the file - PlantUML uses & as a parallel operator, causing Lark parser crash when found in text.
' WRONG
:2. ตรวจสอบ Session & Authorization;
' CORRECT
:2. ตรวจสอบ Session and Authorization;
Verify: grep -c '&' FILE must return 0
Rule 3: START KEYWORD
Must have start after the first Swimlane declaration.
' WRONG
|#FCE4EC|Customer|
:1. เข้าหน้า Profile;
' CORRECT
|#FCE4EC|Customer|
start
:1. เข้าหน้า Profile;
Verify: grep -c '^start$' FILE must return >= 1
Rule 4: SINGLE-LINE ACTION (No multi-line :...; blocks)
Action block (:...;) must not have newlines - use \n for wrapping within a single line.
' WRONG
:13e. แสดง "กรุณาลองใหม่"
(เหลืออีก {N} ครั้ง);
' CORRECT
:13e. แสดง "กรุณาลองใหม่\n(เหลืออีก {N} ครั้ง)";
Verify: grep '^:' FILE | grep -vc ';$' must return 0
Rule 5: ELSEIF WITH LABEL
Every elseif must have a label in () after then.
' WRONG
elseif (แก้ไขที่อยู่) then
' CORRECT
elseif (ต้องการทำอะไร?) then (แก้ไขที่อยู่)
Verify: grep -c 'elseif.*then$' FILE must return 0
Rule 6: NO LEGEND BLOCK (legend/end legend -> comments)
Do not use legend right ... end legend - Lark does not support it in Swimlane Activity Diagrams. Convert to comment blocks instead.
' WRONG
legend right
**Cases Covered:**
✓ Happy Case: ...
end legend
' CORRECT - place between last stop/endif and @enduml
' ==========================================
' SUMMARY AND TRACEABILITY (Lark-safe comments)
' ==========================================
' Cases Covered (XX-X):
' + Happy Case: ...
' + Alt Case: ...
' + Exception: ...
' ----
' MOM Validation Result (XX-X):
' - Ref: MOM#X - ...
' - Validated Date: YYYY-MM-DD
' - Checklist Result:
' + 1. Requirement Coverage - ...
' + 2. Business Rule - ...
' + 3. Actor ครบ - ...
' + 4. Case ครบ - ...
' + 5. ไม่มีของเกิน - ...
' + 6. Terminology ตรง - ...
' + 7. Phase ถูกต้อง - ...
' - Status: VALIDATED
' ==========================================
Verify: grep -c '^legend' FILE must return 0; grep -c '^end legend' FILE must return 0
Rule 7: SAFE ASCII (No special Unicode characters)
Replace Unicode special characters with ASCII equivalents.
Character Replacement Map:
| Original | Replacement | Name |
|---|
-> (U+2192) | -> | Right arrow |
-- (U+2014) | - | Em dash |
| checkmark (U+2713) | + | Check mark |
| ballot X (U+2717) | x | Ballot X |
| warning (U+26A0) | [!] | Warning sign |
| cross mark (U+274C) | [X] | Cross mark |
' WRONG
' ✓ 1. Requirement Coverage — ครบทุก FR
' → ปุ่มดำเนินการ
' CORRECT
' + 1. Requirement Coverage - ครบทุก FR
' -> ปุ่มดำเนินการ
Verify: Each command must return 0:
grep -cP '\x{2192}' FILE (right arrow)grep -cP '\x{2014}' FILE (em dash)grep -cP '\x{2713}' FILE (check mark)grep -cP '\x{2717}' FILE (ballot X)grep -cP '\x{26a0}' FILE (warning sign)grep -cP '\x{274c}' FILE (cross mark)
Rule 8: SKINPARAM LAYOUT BLOCK
ทุกไฟล์ .puml ต้องมี 3 บรรทัดนี้หลัง @startuml เสมอ
' CORRECT — ใส่ทันทีหลัง @startuml (ก่อน title)
@startuml
skinparam conditionStyle inside
skinparam ActivityPadding 10
skinparam ActivityFontSize 13
title Module ...
ทำไม:
conditionStyle inside — เปลี่ยน diamond เป็นกล่องสี่เหลี่ยม ลดพื้นที่แนวนอน ลดเส้นตัดกันActivityPadding 10 — เพิ่มระยะห่างระหว่าง elements ไม่ชิดกันเกินActivityFontSize 13 — ขนาดอ่านง่ายเมื่อ export PDF
Verify: grep -c 'skinparam conditionStyle inside' FILE must return >= 1
Rule 9: DETACH FOR DEAD-END BRANCH
ใช้ detach แทน stop สำหรับ branch ที่จบกลางทาง — ให้ stop มีแค่ 1 ตัวสุดท้าย (happy path end ก่อน @enduml)
' WRONG — stop กลาง flow ลากเส้นกลับไป merge = เส้นทับกล่อง
if (เงื่อนไข?) then (ผ่าน)
:ทำงานต่อ;
else (ไม่ผ่าน)
:แสดง Error;
stop
endif
' CORRECT — detach ตัดเส้นเลย ไม่ลากกลับ
if (เงื่อนไข?) then (ผ่าน)
:ทำงานต่อ;
else (ไม่ผ่าน)
:แสดง Error;
detach
endif
ทำไม: stop กลาง flow บังคับให้ PlantUML ลากเส้นกลับไปจุด merge → เส้นทับกล่อง/เส้นอื่น (known bug: PlantUML Issue #1040, #2161)
Verify: grep -c '^stop' FILE must return exactly 1 (the final stop)
Rule 10: MAX 2 ELSEIF PER CHAIN
ถ้า elseif มากกว่า 2 ทาง (รวมแล้ว 3+ branches ข้างกัน) → ต้องเปลี่ยนเป็น sequential if/endif เรียงแนวตั้ง
' WRONG — 4 branches ข้างกันแนวนอน = diagram กว้างยับ อ่านไม่ได้
if (action?) then (A)
:...;
elseif (B) then (B)
:...;
elseif (C) then (C)
:...;
else (D)
:...;
endif
' CORRECT — เรียงแนวตั้ง แต่ละ scenario จบด้วย detach
if (Scenario A?) then (Yes)
:...;
detach
else (No)
endif
if (Scenario B?) then (Yes)
:...;
detach
else (No)
endif
if (Scenario C?) then (Yes)
:...;
detach
else (No)
endif
ทำไม: PlantUML วาง elseif ทุก branch ข้างกันแนวนอน → diagram กว้างจนอ่านไม่ได้เมื่อ export PDF, sequential if เรียงลงล่างแทน
หมายเหตุ: elseif 1-2 ทาง (2-3 branches) ยังใช้ได้ถ้าแต่ละ branch สั้น (1-3 activities)
Rule 11: TEXT WIDTH MAX 35 CHARS
ข้อความในกล่อง activity ต้องไม่เกิน ~35 ตัวอักษรต่อบรรทัด — ถ้ายาวกว่าให้ตัดด้วย \n
' WRONG — กล่องกว้างล้น lane ข้างๆ
:ระบบตรวจสอบข้อมูลและบันทึกผลการทำรายการลงฐานข้อมูล;
' CORRECT — กล่องแคบ สูงขึ้นแต่ไม่ล้น lane
:ระบบตรวจสอบข้อมูล\nและบันทึกผลการทำรายการ\nลงฐานข้อมูล;
ทำไม: กล่องที่กว้างเกินจะขยายทับ swimlane ข้างเคียง โดยเฉพาะเมื่อ if/else วาง 2 กล่องข้างกัน ตัดเป็นบรรทัดสั้นๆ ทำให้กล่องสูงขึ้นแต่อยู่ใน lane ตัวเอง
Quick Verification Script (All 11 Rules)
FILE="path/to/file.puml"
echo "=== Lark Rendering (Rule 1-7) ==="
echo "Rule 1 (Flat Code):" && grep -c '^[[:space:]]' "$FILE" || echo "0"
echo "Rule 2 (No Ampersand):" && grep -c '&' "$FILE" || echo "0"
echo "Rule 3 (Start Keyword):" && grep -c '^start$' "$FILE"
echo "Rule 4 (Single-line Action):" && grep '^:' "$FILE" | grep -vc ';$' || echo "0"
echo "Rule 5 (Elseif Label):" && grep -c 'elseif.*then$' "$FILE" || echo "0"
echo "Rule 6 (No Legend):" && grep -c '^legend\|^end legend' "$FILE" || echo "0"
echo "Rule 7 (Safe ASCII):" && grep -cP '[\x{2192}\x{2014}\x{2713}\x{2717}\x{26a0}\x{274c}]' "$FILE" || echo "0"
echo "=== Layout Quality (Rule 8-11) ==="
echo "Rule 8 (Skinparam Block):" && grep -c 'skinparam conditionStyle inside' "$FILE"
echo "Rule 9 (Stop Count):" && grep -c '^stop' "$FILE"
echo "Rule 10 (Elseif Chain):" && awk '/^if /{n=0} /^elseif/{n++} /^endif/{if(n>2)print FILENAME": "n" elseif chain"; n=0}' "$FILE"
Expected:
- Rule 1,2,4,5,6,7 = 0
- Rule 3 >= 1
- Rule 8 >= 1
- Rule 9 = 1 (exactly one final stop)
- Rule 10 = no output (no chain with 3+ elseif)
Summary Table
| # | Rule | Summary | Applies to | Category |
|---|
| 1 | FLAT CODE 100% | Every line at column 0 | All lines | Lark Rendering |
| 2 | NO AMPERSAND | & -> and | All lines | Lark Rendering |
| 3 | START KEYWORD | Must have start after first swimlane | After |#...|Actor| | Lark Rendering |
| 4 | SINGLE-LINE ACTION | :...; on one line, use \n | Action blocks | Lark Rendering |
| 5 | ELSEIF WITH LABEL | elseif (cond) then (label) | elseif statements | Lark Rendering |
| 6 | NO LEGEND BLOCK | legend/end legend -> ' comments | Legend sections | Lark Rendering |
| 7 | SAFE ASCII | Replace Unicode with ASCII | All lines | Lark Rendering |
| 8 | SKINPARAM LAYOUT BLOCK | 3 skinparam lines after @startuml | File header | Layout Quality |
| 9 | DETACH FOR DEAD-END | detach mid-flow, stop only 1 ตัวสุดท้าย | Branch endings | Layout Quality |
| 10 | MAX 2 ELSEIF | 3+ branches -> sequential if/endif แนวตั้ง | elseif chains | Layout Quality |
| 11 | TEXT WIDTH MAX 35 | ตัดด้วย \n ทุก ~35 ตัวอักษร | Action text | Layout Quality |
Origin:
- Rule 1-7: Discovered debugging Lark PlantUML rendering failures of 14 SystemFlow files in P01-PROJECT (2026-02-24/25) - Lark uses a stricter parser than standard PlantUML server.
- Rule 8-11: Discovered fixing layout issues (เส้นทับกล่อง, กล่องล้น lane, diagram กว้างเกิน) in P07-PROJECT 33 SystemFlow files (2026-04-01) - PlantUML Activity Beta has known arrow-crossing bugs (Issue #1040, #2161, #2340).
