UX Principles Reference

หลักการ UX พื้นฐานที่ต้องอ่านอิงในทุก Design Spec ไม่ว่าจะใช้ platform ใด

---

Table of Contents

1. Nielsen's 10 Usability Heuristics
2. Laws of UX
3. Gestalt Principles
4. How to Apply in Spec

---

Nielsen's 10 Usability Heuristics

1. Visibility of System Status

ระบบควรแจ้งให้ผู้ใช้ทราบสถานะอยู่เสมอ ผ่าน feedback ที่เหมาะสมและทันเวลา

ใช้เมื่อ: ออกแบบ loading states, progress indicators, status badges, toast notifications Spec checklist:

• ทุก action ที่ใช้เวลา > 1 วินาที ต้องมี loading indicator
• ระบุ loading pattern: skeleton, spinner, หรือ progress bar
• ระบุ success/error feedback สำหรับทุก form submission

2. Match Between System and the Real World

ใช้ภาษาและแนวคิดที่ผู้ใช้คุ้นเคย ไม่ใช้ศัพท์เทคนิคภายใน

ใช้เมื่อ: เขียน labels, button text, error messages, navigation names Spec checklist:

• ระบุ copy/text ที่ใช้ในแต่ละ component
• ใช้ icon ที่เป็นมาตรฐานสากล (เช่น 🔍 สำหรับ search, 🏠 สำหรับ home)

3. User Control and Freedom

ให้ทางออกฉุกเฉิน (emergency exit) เสมอ — undo, redo, cancel, back

ใช้เมื่อ: ออกแบบ destructive actions, forms, wizards, modals Spec checklist:

• ทุก modal ต้องมีปุ่ม close
• Destructive actions ต้องมี confirmation dialog
• Forms ต้อง save draft อัตโนมัติ หรือเตือนก่อน discard

4. Consistency and Standards

ปฏิบัติตาม platform conventions — อย่าสร้างสิ่งใหม่โดยไม่จำเป็น

ใช้เมื่อ: เลือก UI patterns, icon meanings, navigation models Spec checklist:

• ระบุ design system ที่ใช้ (Material / HIG / Custom)
• ใช้ component ที่มีอยู่ใน design system ก่อน สร้างใหม่เป็นทางเลือกสุดท้าย

5. Error Prevention

ป้องกันข้อผิดพลาดก่อนที่จะเกิด ดีกว่าใช้ error message

ใช้เมื่อ: ออกแบบ form validation, destructive actions, input constraints Spec checklist:

• ระบุ inline validation สำหรับทุก input field
• ระบุ disabled states เมื่อ action ยังทำไม่ได้
• ระบุ input masks และ constraints (max length, format)

6. Recognition Rather Than Recall

ลด memory load — แสดงตัวเลือก, actions, ข้อมูลที่ต้องการให้เห็น

ใช้เมื่อ: ออกแบบ navigation, search, form fields Spec checklist:

• ใช้ dropdown/picker แทน free-text เมื่อมีตัวเลือกจำกัด
• แสดง recent items, suggestions, autocomplete
• ระบุ placeholder text ที่ให้ตัวอย่างรูปแบบ

7. Flexibility and Efficiency of Use

รองรับทั้ง novice และ expert users — shortcuts, customization

ใช้เมื่อ: ออกแบบ features ที่ใช้บ่อย, power user flows Spec checklist:

• ระบุ keyboard shortcuts (สำหรับ web/desktop)
• ระบุ swipe actions (สำหรับ mobile)
• พิจารณา progressive disclosure สำหรับ advanced options

8. Aesthetic and Minimalist Design

แสดงเฉพาะข้อมูลที่จำเป็น — ทุก element ที่เพิ่มเข้ามาจะเยื้อง attention

ใช้เมื่อ: ตัดสินใจว่าจะแสดงอะไรบนหน้าจอ Spec checklist:

• ระบุ information hierarchy อย่างชัดเจน
• ใช้ progressive disclosure — ซ่อนรายละเอียดที่ไม่จำเป็นในตอนนี้
• จำกัด primary action ได้แค่ 1 ต่อหน้าจอ

9. Help Users Recognize, Diagnose, and Recover from Errors

Error messages ต้องชัดเจน บอกปัญหา และเสนอวิธีแก้

ใช้เมื่อ: ออกแบบ error states, validation messages Spec checklist:

• ระบุ error message text สำหรับทุก error case
• Error message ต้อง: (1) บอกว่าเกิดอะไร (2) เสนอวิธีแก้
• ระบุตำแหน่ง error message (inline vs toast vs dialog)

10. Help and Documentation

ให้ความช่วยเหลือเมื่อจำเป็น — tooltips, onboarding, contextual help

ใช้เมื่อ: ออกแบบ features ใหม่, complex workflows Spec checklist:

• ระบุ tooltip text สำหรับ icon-only buttons
• พิจารณา onboarding flow สำหรับ first-time users
• ระบุ empty state ที่ให้คำแนะนำ

---

Laws of UX

Fitts's Law

เวลาในการเข้าถึง target ขึ้นกับระยะทางและขนาด — ปุ่มสำคัญต้องใหญ่และเข้าถึงง่าย

Application in Spec:

• Primary CTA: minimum 48x48dp (Android), 44x44pt (iOS)
• ปุ่มสำคัญวางใกล้ thumb zone (mobile) หรือ center of attention (web)
• ระบุ touch target size สำหรับทุก interactive element

Hick's Law

เวลาตัดสินใจเพิ่มตาม log ของจำนวนตัวเลือก — ลดตัวเลือกให้น้อยลง

Application in Spec:

• Navigation items: ไม่เกิน 5-7 items
• Action buttons ต่อหน้าจอ: 1 primary, 1-2 secondary
• ใช้ categorization สำหรับรายการยาว

Jakob's Law

ผู้ใช้คาดหวังว่าเว็บ/แอปของคุณจะทำงานเหมือนที่อื่นที่ทวงเขาใช้

Application in Spec:

• ใช้ standard patterns (hamburger menu, tab bar, pull-to-refresh)
• ระบุ platform conventions ที่ต้องปฏิบัติตาม
• อธิบายเหตุผลถ้าเบี่ยงเบนจาก conventions

Miller's Law

คนจำข้อมูลได้ประมาณ 7±2 ชิ้นใน short-term memory

Application in Spec:

• Chunk ข้อมูลเป็นกลุ่ม (เช่น เบอร์โทร 0XX-XXX-XXXX)
• Section headers ทุก 5-7 items ในรายการยาว
• ระบุ grouping strategy สำหรับ complex forms

Doherty Threshold

ระบบต้องตอบสนองภายใน 400ms เพื่อรักษา engagement

Application in Spec:

• ระบุ perceived performance strategy (skeleton screens, optimistic UI)
• Animations ไม่ควรเกิน 300ms สำหรับ micro-interactions
• ระบุ transition timing สำหรับ page/screen changes

Von Restorff Effect (Isolation Effect)

สิ่งที่แตกต่างจะจำได้ดีกว่า — ใช้เพื่อเน้น primary action

Application in Spec:

• Primary CTA ต้องมีสีและขนาดที่แตกต่างจาก secondary actions
• ระบุ visual hierarchy อย่างชัดเจน
• ใช้ color, size, position เพื่อสร้าง emphasis

Postel's Law (Robustness Principle)

รับ input ให้กว้าง แต่ output ให้เข้มงวด

Application in Spec:

• ยอมรับ input หลายรูปแบบ (เช่น เบอร์โทรทั้งมี/ไม่มี -)
• แสดงผลในรูปแบบมาตรฐานเสมอ
• ระบุ input parsing/formatting rules

Peak-End Rule

คนจำประสบการณ์จาก peak moment และ ending — ทำให้ทุกสำคัญและจุดจบดี

Application in Spec:

• ออกแบบ success state ให้น่าจดจำ (celebration animation, confetti)
• Completion screen ควรมี next step หรือ CTA ที่ชัดเจน

---

Gestalt Principles

Proximity

สิ่งที่อยู่ใกล้กันจะถูกมองเป็นกลุ่มเดียว

Spec: ระบุ spacing ระหว่าง groups ให้มากกว่า spacing ภายใน group (เช่น 24px ระหว่าง sections, 8px ระหว่าง items ใน section)

Similarity

สิ่งที่ดูเหมือนกันจะถูกมองเป็นกลุ่มเดียว

Spec: ใช้ consistent styling สำหรับ components ที่มีหน้าที่เหมือนกัน (เช่น ปุ่ม primary ทุกที่ต้องเหมือนกัน)

Continuity

สายตาจะตามแนวเส้นหรือทิศทาง

Spec: จัด elements ให้อยู่ในแนวเดียวกัน (alignment) ใช้ grid system

Closure

สมองจะเติมเต็มรูปร่างที่ไม่สมบูรณ์

Spec: ใช้ card patterns, containers เพื่อจัดกลุ่มข้อมูล — ไม่จำเป็นต้องมีเส้นขอบทุกด้าน

Common Region

สิ่งที่อยู่ในพื้นที่เดียวกันจะถูกมองเป็นกลุ่ม

Spec: ใช้ background color, cards, dividers เพื่อแบ่งกลุ่มข้อมูล ระบุ container styles ชัดเจน

---

How to Apply in Spec

เมื่อเขียน Design Spec ให้อ้างอิงหลักการเหล่านี้ในส่วน "UX Principles Applied" ใช้แบบ:

## UX Principles Applied

| Decision | Principle | Rationale |
|----------|-----------|-----------|
| Primary CTA อยู่ล่างสุดของ form | Fitts's Law | ใกล้ thumb zone, ลดระยะทาง |
| แสดง inline validation ทันที | Error Prevention (H5) | ป้องกัน error ก่อนเกิด |
| จำกัด nav items เหลือ 5 | Hick's Law + Miller's Law | ลดเวลาตัดสินใจ |
| Skeleton screen ขณะโหลด | Visibility of Status (H1) | ผู้ใช้รู้ว่าระบบกำลังทำงาน |
| ใช้ standard tab bar | Jakob's Law + Consistency (H4) | ตรงกับ mental model ของผู้ใช้ |

ตาราง "Principle" ใช้อ้างอิงแบบย่อ:

• H1-H10: Nielsen's Heuristic #1-10
• ชื่อ Law: เช่น Fitts's Law, Hick's Law
• G-xxx: Gestalt Principle (G-Proximity, G-Similarity, etc.)

Apple Human Interface Guidelines (HIG) Reference

อ้างอิงจาก Apple Human Interface Guidelines สำหรับ iOS, iPadOS, macOS

---

Table of Contents

1. Design Principles
2. Typography
3. Color System
4. Layout & Spacing
5. Components
6. Navigation Patterns
7. Motion & Animation
8. Accessibility
9. Platform Differences

---

Design Principles

Apple HIG ยึดหลักสำคัญ 6 ข้อ:

1. Aesthetic Integrity — ความสวยงามสอดคล้องกับฟังก์ชัน
2. Consistency — ใช้ system-provided components และ patterns
3. Direct Manipulation — interact กับ content โดยตรง (gestures)
4. Feedback — ตอบสนองทุก action ด้วย visual/haptic feedback
5. Metaphors — ใช้สิ่งที่คุ้นเคยในโลกจริง
6. User Control — ให้ผู้ใช้ควบคุม ไม่ใช้ระบบตัดสินใจเอง

---

Typography

iOS Type Scale (SF Pro)

Style	Weight	Size	Leading	Tracking
Large Title	Bold	34pt	41pt	0.37
Title 1	Bold	28pt	34pt	0.36
Title 2	Bold	22pt	28pt	0.35
Title 3	Semibold	20pt	25pt	0.38
Headline	Semibold	17pt	22pt	-0.41
Body	Regular	17pt	22pt	-0.41
Callout	Regular	16pt	21pt	-0.32
Subheadline	Regular	15pt	20pt	-0.24
Footnote	Regular	13pt	18pt	-0.08
Caption 1	Regular	12pt	16pt	0
Caption 2	Regular	11pt	13pt	0.07

Dynamic Type Support

• ทุก text style ต้องรองรับ Dynamic Type (scalable)
• Test ที่ accessibility size xLarge ขึ้นไป
• ใช้ system font (SF Pro) ไว้ก่อนไม่มีเหตุผลด้าน branding

---

Color System

System Colors (iOS 17+)

Color	Light	Dark	Usage
systemBlue	#007AFF	#0A84FF	Links, tappable text
systemGreen	#34C759	#30D158	Success, positive
systemRed	#FF3B30	#FF453A	Destructive, errors
systemOrange	#FF9500	#FF9F0A	Warnings
systemYellow	#FFCC00	#FFD60A	Caution
systemPurple	#AF52DE	#BF5AF2	—
systemPink	#FF2D55	#FF375F	—
systemTeal	#5AC8FA	#64D2FF	—

Background Colors

Color	Light	Dark	Usage
systemBackground	#FFFFFF	#000000	Primary bg
secondarySystemBackground	#F2F2F7	#1C1C1E	Grouped content bg
tertiarySystemBackground	#FFFFFF	#2C2C2E	Elevated grouped bg
systemGroupedBackground	#F2F2F7	#000000	Grouped table bg

Label Colors

Color	Light	Dark	Usage
label	#000000	#FFFFFF	Primary text
secondaryLabel	#3C3C43 (60%)	#EBEBF5 (60%)	Secondary text
tertiaryLabel	#3C3C43 (30%)	#EBEBF5 (30%)	Tertiary text
quaternaryLabel	#3C3C43 (18%)	#EBEBF5 (18%)	Placeholders

Separator Colors

Color	Light	Dark
separator	#3C3C43 (29%)	#545458 (60%)
opaqueSeparator	#C6C6C8	#38383A

---

Layout & Spacing

Safe Areas & Margins

Device	Leading Margin	Content Width
iPhone SE	16pt	343pt
iPhone 15	16pt	361pt
iPhone 15 Pro Max	16pt	398pt
iPad Mini	20pt	—
iPad Pro 11"	20pt	—
iPad Pro 12.9"	20pt	—

Standard Spacing

Value	Usage
4pt	Minimal (between related icons)
8pt	Tight (related elements)
12pt	Compact (list item internal)
16pt	Standard (content margins, section gaps)
20pt	Comfortable (iPad margins)
24pt	Spacious (between major sections)
32pt	Section breaks

Layout Grid

• Base unit: 8pt
• ใช้ Auto Layout ใน Figma เพื่อจำลอง iOS layout behavior
• ระยะห่างระหว่าง list items: 44pt (minimum tap height)

---

Key Components

Navigation Bar (UINavigationBar)

• Height: 44pt (compact), 96pt (large title)
• Large Title: 34pt, Bold, left-aligned
• Back button: chevron + previous title
• Bar buttons: SF Symbols (28pt), max 2 trailing

Tab Bar (UITabBar)

• Height: 49pt (iPhone), 50pt (iPad)
• Items: 2-5
• Icon: 25pt x 25pt (SF Symbols)
• Label: Caption 2 (10pt)
• Active: tint color, Inactive: systemGray

Buttons

Type	Height	Corner	Usage
Bordered Prominent	50pt	12pt	Primary CTA
Bordered	50pt	12pt	Secondary
Plain	44pt tap target	None	Tertiary, text-style
Destructive	50pt	12pt	Delete, remove (red)

Lists / Tables

Style	Usage
Inset Grouped	Default for settings, forms (rounded corners, inset from edges)
Grouped	Classic grouped (full width per section)
Plain	Simple list, continuous (contacts, messages)

• Row height: 44pt minimum
• Cell padding: 16pt leading, 16pt trailing
• Disclosure indicator: chevron.right (for drill-down navigation)
• Swipe actions: leading (positive), trailing (destructive)

Sheets

Type	Usage
Sheet (.sheet)	Non-blocking, drag to dismiss
Full-screen cover	Blocking, needs explicit dismiss
Popover	iPad only, arrow points to source

• Sheet corner radius: 10pt
• Grabber: 36pt x 5pt, centered

Alerts

• Title: Headline (17pt, Semibold)
• Message: Footnote (13pt, Regular)
• Buttons: 1-2 preferred, max 3
• Destructive button: Red, on the left
• Default/Cancel: Bold

Text Fields

• Height: 36pt
• Corner radius: 10pt
• Background: tertiarySystemFill
• Placeholder: tertiaryLabel color
• Clear button on trailing edge when editing

Search Bar

• Height: 36pt
• Corner radius: 10pt
• Magnifying glass icon on leading
• Cancel button appears on focus

---

Navigation Patterns

iPhone

1. Tab Bar + Navigation Stack — most common
   • Tab bar: top-level destinations (3-5)
   • Navigation stack: drill-down within each tab
2. Modal Sheets — for focused tasks
   • Present modally for creation/editing flows
   • Swipe down to dismiss (non-blocking)

iPad

1. Split View — master-detail
   • Sidebar: 320pt width
   • Content: fills remaining
2. Tab Bar (compact) — Sidebar (regular)
   • Adaptive navigation

Transitions

Type	Usage	Direction
Push	Navigate deeper	Left to right (LTR)
Pop	Navigate back	Right to left
Modal present	Show sheet/fullscreen	Bottom to top
Modal dismiss	Close sheet	Top to bottom / swipe down

---

Motion & Animation

Duration Guidelines

Type	Duration	Usage
Quick feedback	100ms	Toggle, selection
Standard	250ms	Sheet present, nav push
Complex	350-500ms	Full-screen transitions

Spring Animation (preferred)

• iOS prefers spring-based animation over easing curves
• Default spring: response: 0.3, dampingFraction: 0.8
• Bouncy: response: 0.4, dampingFraction: 0.6

Haptic Feedback

Type	Usage
Impact (light)	Button tap, toggle
Impact (medium)	Snap to position
Impact (heavy)	Significant action complete
Notification (success)	Task complete
Notification (warning)	Caution action
Notification (error)	Error occurred
Selection	Scrolling through picker

ระบุ haptic feedback ใน spec สำหรับ iOS apps

---

Accessibility

Minimum Sizes

• Touch target: 44pt x 44pt minimum
• Spacing between targets: >= 8pt
• Text: ระบุ Dynamic Type support

VoiceOver

• ทุก interactive element ต้องมี accessibility label
• Images: accessibilityLabel สำหรับ meaningful images
• Decorative images: isAccessibilityElement = false
• Group related elements ด้วย accessibilityElement container

Color Contrast

• Text: 4.5:1 minimum (AA)
• Large text (>= 18pt): 3:1
• ใช้ system colors ซึ่งรองรับ accessibility แล้ว
• Support Increase Contrast mode

Reduce Motion

• ต้องรองรับ Reduce Motion preference
• แทนที่ animation ด้วย cross-dissolve เมื่อ Reduce Motion เปิดอยู่

---

Platform Differences

iOS vs Android — สิ่งที่ต้องระวังใน Spec

Feature	iOS (HIG)	Android (Material)
Primary nav	Tab Bar (bottom)	Bottom Nav / Nav Rail
Back	Swipe from left edge	System back button/gesture
Action placement	Top-right in nav bar	FAB or top app bar
Destructive	Leading swipe (red)	Trailing swipe or dialog
Sheet	Drag handle, swipe dismiss	Bottom sheet with handle
Font	SF Pro (system)	Roboto (system)
Units	pt (points)	dp (density-independent pixels)
Min touch	44pt x 44pt	48dp x 48dp
Alert buttons	Stacked or side-by-side	Always side-by-side

Material Design 3 (M3) Reference

อ้างอิงจาก Material Design 3 guidelines สำหรับ Android และ Web applications

---

Table of Contents

1. Design Tokens
2. Typography
3. Color System
4. Layout & Grid
5. Elevation & Shadows
6. Components
7. Motion
8. Accessibility

---

Design Tokens

Spacing (Base unit: 4dp)

Token	Value	Usage
spacing-xs	4dp	Icon padding
spacing-sm	8dp	Tight element spacing
spacing-md	16dp	Default content padding
spacing-lg	24dp	Section spacing
spacing-xl	32dp	Large section spacing
spacing-2xl	48dp	Page margins (compact)

Shape (Corner Radius)

Shape	Radius	Usage
None	0dp	Full-width containers
Extra Small	4dp	Small components (chips)
Small	8dp	Buttons, text fields
Medium	12dp	Cards, dialogs
Large	16dp	FABs, large cards
Extra Large	28dp	Bottom sheets
Full	50%	Circular elements

---

Typography

Type Scale (M3 Default: Roboto)

Style	Font	Weight	Size	Line Height	Tracking
Display Large	Roboto	400	57sp	64sp	-0.25
Display Medium	Roboto	400	45sp	52sp	0
Display Small	Roboto	400	36sp	44sp	0
Headline Large	Roboto	400	32sp	40sp	0
Headline Medium	Roboto	400	28sp	36sp	0
Headline Small	Roboto	400	24sp	32sp	0
Title Large	Roboto	400	22sp	28sp	0
Title Medium	Roboto	500	16sp	24sp	0.15
Title Small	Roboto	500	14sp	20sp	0.1
Body Large	Roboto	400	16sp	24sp	0.5
Body Medium	Roboto	400	14sp	20sp	0.25
Body Small	Roboto	400	12sp	16sp	0.4
Label Large	Roboto	500	14sp	20sp	0.1
Label Medium	Roboto	500	12sp	16sp	0.5
Label Small	Roboto	500	11sp	16sp	0.5

---

Color System

M3 Dynamic Color Roles

Role	Light Theme	Dark Theme	Usage
Primary	seed color	lighter seed	Key actions, active states
On Primary	White	Dark	Text/icons on primary
Primary Container	Very light primary	Muted dark primary	Filled buttons bg, FABs
Secondary	Muted seed	Lighter muted	Supporting actions
Tertiary	Complementary	Lighter complementary	Accents, tags
Surface	#FFFBFE	#1C1B1F	Page backgrounds
Surface Variant	#E7E0EC	#49454F	Cards, elevated surfaces
On Surface	#1C1B1F	#E6E1E5	Primary text
On Surface Variant	#49454F	#CAC4D0	Secondary text
Outline	#79747E	#938F99	Borders, dividers
Outline Variant	#CAC4D0	#49454F	Subtle dividers
Error	#B3261E	#F2B8B5	Error states
On Error	White	#601410	Text on error

Spec Template

เมื่อกำหนดสี ให้ระบุทั้ง Light และ Dark theme:

Primary: #6750A4 (Light) / #D0BCFF (Dark)
On Primary: #FFFFFF / #381E72

---

Layout & Grid

Responsive Grid

Window Class	Width	Columns	Margins	Gutter
Compact	< 600dp	4	16dp	8dp
Medium	600-839dp	8	24dp	16dp
Expanded	840-1199dp	12	24dp	24dp
Large	1200-1599dp	12	24dp	24dp
Extra Large	>= 1600dp	12	24dp	24dp

Navigation Patterns by Window Class

Window Class	Primary Nav	Secondary Nav
Compact	Bottom Navigation Bar (3-5 items)	Navigation Drawer (hamburger)
Medium	Navigation Rail (side)	Navigation Drawer
Expanded	Navigation Drawer (permanent)	Tabs

---

Elevation & Shadows

Elevation Levels

Level	Elevation	Shadow	Usage
0	0dp	None	Surface, backgrounds
1	1dp	Subtle	Cards, App Bar
2	3dp	Light	Snackbar, Nav Drawer
3	6dp	Medium	FAB, Bottom Sheet
4	8dp	Pronounced	Nav Drawer (modal)
5	12dp	Strong	Dialog

M3 ใช้ tonal elevation (surface tint color) แทน shadow ใน dark theme

---

Key Components

Buttons

Type	Height	Min Width	Corner	Usage
Filled	40dp	48dp	20dp (full)	Primary CTA
Outlined	40dp	48dp	20dp	Secondary actions
Text	40dp	48dp	20dp	Low-emphasis
Elevated	40dp	48dp	20dp	Medium emphasis with shadow
Tonal	40dp	48dp	20dp	Medium emphasis, no shadow
FAB	56dp	56dp	16dp	Primary floating action
Extended FAB	56dp	-	16dp	FAB with label

Text Fields

Type	Height	Usage
Filled	56dp	Default, high density forms
Outlined	56dp	Lower density, clearer boundaries

States: Rest, Focused, Error, Disabled

• Label floats on focus
• Helper text below (12sp, Body Small)
• Error text replaces helper in error state (Error color)

Cards

Type	Elevation	Border	Usage
Elevated	Level 1	None	Default
Filled	Level 0	None	Secondary surface color
Outlined	Level 0	1dp outline	Clear boundaries

Padding: 16dp all sides (minimum) Corner radius: 12dp (Medium)

Dialogs

• Width: 280-560dp
• Corner radius: 28dp (Extra Large)
• Elevation: Level 5
• Title: Headline Small (24sp)
• Body: Body Medium (14sp)
• Actions: Text buttons, right-aligned

Bottom Sheets

• Corner radius: 28dp (top corners only)
• Handle: 32dp x 4dp, centered, 22dp from top
• Standard: pushes content up
• Modal: overlay with scrim

Navigation Bar (Bottom)

• Height: 80dp
• Items: 3-5
• Icon: 24dp
• Label: Label Medium (12sp)
• Active indicator: pill shape (64dp x 32dp)

---

Motion

Duration

Category	Duration	Usage
Short 1	50ms	Hover feedback
Short 2	100ms	Selection, toggle
Short 3	150ms	Icon animation
Short 4	200ms	Small expand/collapse
Medium 1	250ms	Menu open
Medium 2	300ms	Page transition
Medium 3	350ms	Complex transition
Medium 4	400ms	Full-screen transition
Long 1	450ms	Large complex animation
Long 2	500ms	Sheet, dialog entry

Easing

Type	Curve	Usage
Emphasized	cubic-bezier(0.2, 0, 0, 1)	Most transitions
Emphasized Decelerate	cubic-bezier(0, 0, 0, 1)	Enter/appear
Emphasized Accelerate	cubic-bezier(0.3, 0, 0.8, 0.15)	Exit/disappear
Standard	cubic-bezier(0.2, 0, 0, 1)	Layout changes

---

Accessibility

Touch Targets

• Minimum: 48dp x 48dp
• Recommended: 56dp x 56dp สำหรับ primary actions
• Spacing between targets: >= 8dp

Color Contrast (WCAG 2.1)

• Normal text: 4.5:1 minimum (AA)
• Large text (>= 18sp regular, >= 14sp bold): 3:1 minimum
• Icons and UI components: 3:1 minimum

Content Descriptions

• ทุก icon button ต้องมี contentDescription
• Decorative icons ใช้ contentDescription = null
• Images ที่ให้ข้อมูล ต้องมี alt text

Design Tokens Reference

คู่มือสร้าง Design Tokens สำหรับ Custom Design System ที่ใช้ร่วมกัน Figma

---

Table of Contents

1. What Are Design Tokens
2. Token Naming Convention
3. Token Categories
4. Token Template
5. Figma Integration Notes

---

What Are Design Tokens

Design Tokens คือค่าคงที่ของ design decisions ที่ใช้ร่วมกันทั้ง design (Figma) และ code — เช่น สี, font size, spacing, border-radius

เมื่อผู้ใช้มี custom design system หรือต้องการสร้างใหม่ ให้กำหนด tokens เหล่านี้ใน spec

---

Token Naming Convention

ใช้รูปแบบ: semantic/{category}/{property}/{variant}

ตัวอย่าง:

semantic/gray-neutral/fg/high            → #1B1D22
semantic/gray-neutral/fg/mid-on-white    → #6A6E83
semantic/gray-neutral/bg/white           → #FFFFFF
semantic/gray-neutral/bg/lightgray       → #F8F8F9

semantic/primary/fg/high                 → #EC599D
semantic/primary/bg/mid                  → #EC599D
semantic/primary/border/high             → #EC599D

semantic/secondary/fg/high               → #7279FB
semantic/error/fg/high                   → #EA244F
semantic/success/bg/high                 → #559652
semantic/info/border/low                 → #CDEDF9

semantic/alpha-black/bg/mid              → #101114 @ 70%
semantic/alpha-white/fg/low              → #FFFFFF @ 50%

semantic/support/red/fg/low              → #EA244F
semantic/support/violet/bg/mid           → #AAAFFD

spacing-xs                               → 4px
spacing-sm                               → 8px
spacing-md                               → 16px
spacing-lg                               → 24px

font-size-body-md                        → 14px
font-weight-heading                      → 700
font-family-primary                      → "Inter"

radius-sm                                → 4px
radius-md                                → 8px
radius-lg                                → 16px
radius-full                              → 9999px

shadow-sm                                → 0 1px 2px rgba(0,0,0,0.1)
shadow-md                                → 0 4px 8px rgba(0,0,0,0.12)

z-index-dropdown                         → 100
z-index-modal                            → 200
z-index-toast                            → 300

---

Token Categories

1. Color Tokens (Semantic System)

Source: Figma Tokens export (Mode 1). Token paths use semantic/{category}/{property}/{variant} format. For alpha colors, value is shown as hex @ opacity%.

1.1 Gray-Neutral

Token	Hex	Alpha	Description
semantic/gray-neutral/fg/white	#FFFFFF	100%	White foreground
semantic/gray-neutral/fg/low-on-white	#9A9DAD	100%	Low-contrast text on white
semantic/gray-neutral/fg/mid-on-white	#6A6E83	100%	Medium-contrast text on white
semantic/gray-neutral/fg/mid-on-gray	#3F414E	100%	Medium-contrast text on gray
semantic/gray-neutral/fg/high	#1B1D22	100%	High-contrast foreground (near-black)
semantic/gray-neutral/bg/white	#FFFFFF	100%	White background
semantic/gray-neutral/bg/lightgray	#F8F8F9	100%	Light gray background
semantic/gray-neutral/bg/midgray	#EBECEF	100%	Medium gray background
semantic/gray-neutral/bg/darkgray	#CFD1D9	100%	Dark gray background
semantic/gray-neutral/bg/black	#1B1D22	100%	Black background
semantic/gray-neutral/border/white	#FFFFFF	100%	White border
semantic/gray-neutral/border/lightgray	#F8F8F9	100%	Light gray border
semantic/gray-neutral/border/midgray	#EBECEF	100%	Medium gray border
semantic/gray-neutral/border/darkgray	#CFD1D9	100%	Dark gray border

1.2 Disabled

Token	Hex	Alpha	Description
semantic/disabled/fg/on-white	#9A9DAD	100%	Disabled foreground on white
semantic/disabled/bg/low	#EBECEF	100%	Disabled background
semantic/disabled/border/low	#9A9DAD	100%	Disabled border

1.3 Primary

Token	Hex	Alpha	Description
semantic/primary/fg/low	#F3E2EA	100%	Primary tint foreground
semantic/primary/fg/high	#EC599D	100%	Primary strong foreground
semantic/primary/bg/lowest	#FDEFF5	100%	Primary lightest background
semantic/primary/bg/low-on-gray	#FBDEED	100%	Primary light bg on gray surfaces
semantic/primary/bg/mid	#EC599D	100%	Primary solid background
semantic/primary/border/mid	#F7BDD8	100%	Primary medium border
semantic/primary/border/high	#EC599D	100%	Primary strong border

1.4 Secondary

Token	Hex	Alpha	Description
semantic/secondary/fg/low	#F1F2FF	100%	Secondary tint foreground
semantic/secondary/fg/high	#7279FB	100%	Secondary strong foreground
semantic/secondary/bg/lowest	#F1F2FF	100%	Secondary lightest background
semantic/secondary/bg/low-on-gray	#E3E4FE	100%	Secondary light bg on gray
semantic/secondary/bg/mid	#7279FB	100%	Secondary solid background
semantic/secondary/border/mid	#C7C9FD	100%	Secondary medium border
semantic/secondary/border/high	#7279FB	100%	Secondary strong border

1.5 Error

Token	Hex	Alpha	Description
semantic/error/fg/low	#FDE9ED	100%	Error tint foreground
semantic/error/fg/high	#EA244F	100%	Error strong foreground
semantic/error/bg/lowest	#FDE9ED	100%	Error lightest background
semantic/error/bg/low	#FBD3DC	100%	Error light background
semantic/error/bg/mid	#EA244F	100%	Error solid background
semantic/error/bg/high	#BB1D3F	100%	Error darkest background
semantic/error/border/mid	#F7A7B9	100%	Error medium border
semantic/error/border/high	#EA244F	100%	Error strong border

1.6 Warning

Token	Hex	Alpha	Description
semantic/warning/fg/low	#FEF9EB	100%	Warning tint foreground
semantic/warning/fg/high	#C69A2A	100%	Warning strong foreground
semantic/warning/bg/lowest	#FEF9EB	100%	Warning lightest background
semantic/warning/bg/low	#FEF3D7	100%	Warning light background
semantic/warning/bg/high	#F8C135	100%	Warning solid background
semantic/warning/border/low	#FBDA86	100%	Warning light border
semantic/warning/border/high	#F8C135	100%	Warning strong border

1.7 Success

Token	Hex	Alpha	Description
semantic/success/fg/low	#E1F2E0	100%	Success tint foreground
semantic/success/fg/high	#559652	100%	Success strong foreground
semantic/success/bg/lowest	#F0F8F0	100%	Success lightest background
semantic/success/bg/low	#E1F2E0	100%	Success light background
semantic/success/bg/high	#559652	100%	Success solid background
semantic/success/border/low	#A6D7A3	100%	Success light border
semantic/success/border/high	#559652	100%	Success strong border

1.8 Info

Token	Hex	Alpha	Description
semantic/info/fg/low	#CDEDF9	100%	Info tint foreground
semantic/info/fg/high	#026486	100%	Info strong foreground
semantic/info/bg/lowest	#E6F6FC	100%	Info lightest background
semantic/info/bg/low	#CDEDF9	100%	Info light background
semantic/info/bg/mid	#68CAEC	100%	Info medium background
semantic/info/bg/high	#0386B3	100%	Info solid background
semantic/info/border/low	#CDEDF9	100%	Info light border
semantic/info/border/high	#9BDCF3	100%	Info strong border

1.9 Alpha-Black (Overlay)

Token	Hex	Alpha	Description
semantic/alpha-black/bg/low	#101114	50%	Light overlay
semantic/alpha-black/bg/mid	#101114	70%	Medium overlay
semantic/alpha-black/bg/high	#101114	80%	Heavy overlay

1.10 Alpha-White (Inverse Overlay)

Token	Hex	Alpha	Description
semantic/alpha-white/fg/low	#FFFFFF	50%	Semi-transparent white text
semantic/alpha-white/fg/mid	#FFFFFF	70%	Visible white text
semantic/alpha-white/bg/low	#FFFFFF	10%	Subtle white overlay
semantic/alpha-white/bg/mid	#FFFFFF	35%	Light white overlay

1.11 Support Colors

Extended palette for tags, badges, illustrations, and decorative elements.

Red

Token	Hex	Description
semantic/support/red/fg/low	#EA244F	Red foreground
semantic/support/red/fg/mid	#8C162F	Red dark foreground
semantic/support/red/bg/lowest	#FDE9ED	Red lightest bg
semantic/support/red/bg/low	#FBD3DC	Red light bg
semantic/support/red/bg/mid	#F27C95	Red medium bg
semantic/support/red/bg/high	#BB1D3F	Red dark bg
semantic/support/red/border/low	#FBD3DC	Red light border
semantic/support/red/border/mid	#FBD3DC	Red medium border

Orange

Token	Hex	Description
semantic/support/orange/fg/low	#EC6F45	Orange foreground
semantic/support/orange/fg/mid	#8E4329	Orange dark foreground
semantic/support/orange/bg/lowest	#FDF1EC	Orange lightest bg
semantic/support/orange/bg/low	#FBE2DA	Orange light bg
semantic/support/orange/bg/mid	#F4A98F	Orange medium bg
semantic/support/orange/bg/high	#BD5937	Orange dark bg
semantic/support/orange/border/low	#FBE2DA	Orange light border
semantic/support/orange/border/mid	#F7C5B5	Orange medium border

Yellow

Token	Hex	Description
semantic/support/yellow/fg/low	#F8C135	Yellow foreground
semantic/support/yellow/fg/mid	#957420	Yellow dark foreground
semantic/support/yellow/bg/lowest	#FEF9EB	Yellow lightest bg
semantic/support/yellow/bg/low	#FEF3D7	Yellow light bg
semantic/support/yellow/bg/mid	#FBDA86	Yellow medium bg
semantic/support/yellow/bg/high	#C69A2A	Yellow dark bg
semantic/support/yellow/border/low	#FEF3D7	Yellow light border
semantic/support/yellow/border/mid	#FCE6AE	Yellow medium border

Green

Token	Hex	Description
semantic/support/green/fg/low	#6ABC66	Green foreground
semantic/support/green/fg/mid	#40713D	Green dark foreground
semantic/support/green/bg/lowest	#F0F8F0	Green lightest bg
semantic/support/green/bg/low	#E1F2E0	Green light bg
semantic/support/green/bg/mid	#A6D7A3	Green medium bg
semantic/support/green/bg/high	#559652	Green dark bg
semantic/support/green/border/low	#E1F2E0	Green light border
semantic/support/green/border/mid	#C3E4C2	Green medium border

Sky

Token	Hex	Description
semantic/support/sky/fg/low	#36B9E6	Sky foreground
semantic/support/sky/fg/mid	#026486	Sky dark foreground
semantic/support/sky/bg/lowest	#E6F6FC	Sky lightest bg
semantic/support/sky/bg/low	#CDEDF9	Sky light bg
semantic/support/sky/bg/mid	#68CAEC	Sky medium bg
semantic/support/sky/bg/high	#0386B3	Sky dark bg
semantic/support/sky/border/low	#CDEDF9	Sky light border
semantic/support/sky/border/mid	#9BDCF3	Sky medium border

Blue

Token	Hex	Description
semantic/support/blue/fg/low	#2346EB	Blue foreground
semantic/support/blue/fg/mid	#152A8D	Blue dark foreground
semantic/support/blue/bg/lowest	#E9EDFD	Blue lightest bg
semantic/support/blue/bg/low	#D3DAFB	Blue light bg
semantic/support/blue/bg/mid	#7B90F3	Blue medium bg
semantic/support/blue/bg/high	#1C38BC	Blue dark bg
semantic/support/blue/border/low	#D3DAFB	Blue light border
semantic/support/blue/border/mid	#A7B5F7	Blue medium border

Pink

Token	Hex	Description
semantic/support/pink/fg/low	#EC599D	Pink foreground
semantic/support/pink/fg/mid	#8E355E	Pink dark foreground
semantic/support/pink/bg/lowest	#FDEEF5	Pink lightest bg
semantic/support/pink/bg/low	#FBDEEB	Pink light bg
semantic/support/pink/bg/mid	#F49BC4	Pink medium bg
semantic/support/pink/bg/high	#BD477E	Pink dark bg
semantic/support/pink/border/low	#FBDEEB	Pink light border
semantic/support/pink/border/mid	#F7BDD8	Pink medium border

Violet

Token	Hex	Description
semantic/support/violet/fg/low	#7279FB	Violet foreground
semantic/support/violet/fg/mid	#444997	Violet dark foreground
semantic/support/violet/bg/lowest	#FFFFFF	Violet lightest bg
semantic/support/violet/bg/low	#E3E4FE	Violet light bg
semantic/support/violet/bg/mid	#AAAFFD	Violet medium bg
semantic/support/violet/bg/high	#5B61C9	Violet dark bg
semantic/support/violet/border/low	#E3E4FE	Violet light border
semantic/support/violet/border/mid	#C7C9FD	Violet medium border

2. Typography Tokens

Font Family: LINE Seed Sans TH Weights: Regular (400), Bold (700), ExtraBold (800)

Heading

Token	Font Size	Line Height	Weight	Usage
Heading.1	48px	58px	Bold	Page titles, hero text
Heading.2	40px	52px	Bold	Section headers
Heading.3	32px	40px	Bold	Sub-section headers
Heading.4	28px	36px	Bold	Card titles, dialog headers
Heading.5	24px	32px	Bold	Small headings, list titles

Label

Token	Font Size	Line Height	Weight	Usage
Label.1	20px	28px	Bold	Large labels, prominent UI text
Label.2	18px	26px	Bold	Medium labels
Label.3	16px	24px	Bold	Standard labels, button text
Label.4	14px	22px	Bold	Small labels, tags
Label.5	12px	20px	Bold	Micro labels, badges

Caption

Token	Font Size	Line Height	Weight	Usage
Caption.1	20px	36px	Regular	Large body text
Caption.2	18px	26px	Regular	Medium body text
Caption.3	16px	24px	Regular	Standard body text
Caption.4	14px	22px	Regular	Small body text, captions
Caption.5	12px	20px	Regular	Micro text, footnotes

3. Spacing Tokens

ใช้ 4px base unit (4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96)

Token	Value	Common Usage
spacing-0	0px	No spacing
spacing-1	4px	Icon gap
spacing-2	8px	Inline element gap
spacing-3	12px	List item padding
spacing-4	16px	Content padding, card padding
spacing-5	20px	iPad margins
spacing-6	24px	Section gaps
spacing-8	32px	Large section gaps
spacing-10	40px	Page section breaks
spacing-12	48px	Hero sections

4. Shape / Radius Tokens

Token	Value	Usage
radius-none	0px	Sharp corners
radius-sm	4px	Tags, badges
radius-md	8px	Buttons, inputs
radius-lg	12px	Cards
radius-xl	16px	Modals, large cards
radius-2xl	24px	Bottom sheets
radius-full	9999px	Pills, avatars

5. Shadow / Elevation Tokens

Token	Value	Usage
shadow-none	none	Flat elements
shadow-xs	0 1px 2px rgba(0,0,0,0.05)	Subtle lift
shadow-sm	0 1px 3px rgba(0,0,0,0.1)	Cards (rest)
shadow-md	0 4px 6px rgba(0,0,0,0.1)	Dropdowns, popovers
shadow-lg	0 10px 15px rgba(0,0,0,0.1)	Modals
shadow-xl	0 20px 25px rgba(0,0,0,0.1)	Dialogs

6. Motion Tokens

Token	Value	Usage
duration-instant	100ms	Toggle, micro feedback
duration-fast	200ms	Hover, small transitions
duration-normal	300ms	Standard transitions
duration-slow	500ms	Complex animations
easing-default	ease-in-out	General transitions
easing-enter	ease-out	Elements appearing
easing-exit	ease-in	Elements disappearing
easing-spring	cubic-bezier(0.34, 1.56, 0.64, 1)	Bouncy interactions

7. Breakpoint Tokens

Token	Value	Layout
breakpoint-sm	640px	Mobile landscape
breakpoint-md	768px	Tablet portrait
breakpoint-lg	1024px	Tablet landscape / small desktop
breakpoint-xl	1280px	Desktop
breakpoint-2xl	1536px	Large desktop

8. Z-Index Tokens

Token	Value
z-base	0
z-dropdown	100
z-sticky	200
z-overlay	300
z-modal	400
z-popover	500
z-toast	600
z-tooltip	700

---

Token Template for Spec

เมื่อสร้าง Design Spec ที่รวม Design Tokens ให้ใช้ format นี้:

## Design Tokens

### Colors
| Token | Value | Usage |
|-------|-------|-------|
| semantic/primary/fg/high | #EC599D | Primary actions, buttons |
| semantic/primary/bg/mid | #EC599D | Solid primary backgrounds |
| semantic/primary/bg/lowest | #FDEFF5 | Subtle primary tints |
| semantic/secondary/fg/high | #7279FB | Secondary actions |
| semantic/gray-neutral/fg/high | #1B1D22 | Body text |
| semantic/gray-neutral/fg/mid-on-white | #6A6E83 | Supporting text |
| semantic/gray-neutral/bg/white | #FFFFFF | Page background |
| semantic/error/fg/high | #EA244F | Error states |
| ... | ... | ... |

### Typography
| Token | Value | Usage |
|-------|-------|-------|
| font-family-primary | "Inter" | All UI text |
| font-size-body | 14px | Default body |
| ... | ... | ... |

### Spacing
Based on 4px grid:
| Token | Value |
|-------|-------|
| spacing-1 | 4px |
| spacing-2 | 8px |
| ... | ... |

---

Figma Integration Notes

สำหรับ Designer ที่จะทำ Tokens ให้ใช้ได้ใน Figma

1. Figma Variables: สร้าง Color, Number, String variables ตาม token ที่กำหนด

   • จัดกลุ่มเป็น Collections: Colors, Typography, Spacing, etc.
   • สร้าง modes: Light / Dark สำหรับ color tokens

2. Figma Styles: สร้าง Text Styles, Color Styles, Effect Styles

   • ใช้ชื่อตาม token naming convention

3. Component Properties: ใช้ Figma component properties เพื่อสร้าง variants

   • State: default, hover, pressed, focused, disabled
   • Size: small, medium, large
   • Type: primary, secondary, tertiary

4. Auto Layout: ใช้ spacing tokens ใน auto layout settings

   • Item spacing = spacing token
   • Padding = spacing token

5. Plugins ที่ช่วย:

   • Tokens Studio for Figma: จัดการ design tokens
   • Figma Variables: native Figma feature (preferred)

FontAwesome Icons Reference for Figma MCP

เนื่องจาก MCP ไม่สามารถสร้าง vector icon ได้โดยตรง ให้ใช้ text placeholder แทน แล้ว dev จะแปลงเป็น FontAwesome component ตอน implement จริง

---

วิธีใช้ Icon ใน Figma MCP

Pattern: Icon Placeholder

create_text({
  text: "⬜",           // placeholder character
  name: "icon/fa-home", // ใช้ชื่อ layer เป็น FA icon name
  fontSize: 20,
  fontColor: {r, g, b},
  parentId: "container-id"
})

ข้อตกลง Naming Convention

• Layer name: icon/fa-{icon-name}
• ตัวอย่าง: icon/fa-calendar, icon/fa-user, icon/fa-bell
• Dev จะ map ชื่อ layer → <FontAwesomeIcon icon="fa-{name}" />

---

Icon Categories & Common Icons

Navigation

Icon Name	Placeholder	Usage
fa-home	⌂	Home/หน้าแรก
fa-arrow-left	←	Back/ย้อนกลับ
fa-arrow-right	→	Forward/ไปต่อ
fa-bars	☰	Menu/เมนู
fa-xmark	✕	Close/ปิด
fa-chevron-down	▾	Dropdown
fa-chevron-right	▸	Expand/ขยาย
fa-ellipsis	⋯	More options
fa-ellipsis-vertical	⋮	More options (vertical)

Actions

Icon Name	Placeholder	Usage
fa-plus	+	Add/เพิ่ม
fa-minus	−	Remove/ลบ
fa-pen	✎	Edit/แก้ไข
fa-trash	🗑	Delete/ลบ
fa-magnifying-glass	⌕	Search/ค้นหา
fa-filter	▿	Filter/กรอง
fa-sort	⇅	Sort/เรียง
fa-share	↗	Share/แชร์
fa-download	↓	Download
fa-upload	↑	Upload
fa-copy	⧉	Copy/คัดลอก
fa-check	✓	Confirm/ยืนยัน

User & Account

Icon Name	Placeholder	Usage
fa-user	👤	User/ผู้ใช้
fa-user-plus	👤+	Add user
fa-users	👥	Group/กลุ่ม
fa-circle-user	◉	Avatar/รูปโปรไฟล์
fa-gear	⚙	Settings/ตั้งค่า
fa-right-from-bracket	⎋	Logout/ออกจากระบบ
fa-lock	🔒	Password/รหัสผ่าน
fa-key	🔑	Authentication

Communication

Icon Name	Placeholder	Usage
fa-bell	🔔	Notification/แจ้งเตือน
fa-envelope	✉	Email/อีเมล
fa-comment	💬	Chat/แชท
fa-phone	📞	Call/โทร
fa-paper-plane	➤	Send/ส่ง

Content & Media

Icon Name	Placeholder	Usage
fa-image	🖼	Image/รูปภาพ
fa-camera	📷	Camera/กล้อง
fa-file	📄	File/ไฟล์
fa-folder	📁	Folder/โฟลเดอร์
fa-link	🔗	Link/ลิงก์
fa-video	🎥	Video/วิดีโอ

Calendar & Time

Icon Name	Placeholder	Usage
fa-calendar	📅	Calendar/ปฏิทิน
fa-calendar-days	📆	Calendar view
fa-clock	🕐	Time/เวลา
fa-stopwatch	⏱	Timer/จับเวลา

Status & Feedback

Icon Name	Placeholder	Usage
fa-circle-check	✅	Success/สำเร็จ
fa-circle-xmark	❌	Error/ผิดพลาด
fa-circle-exclamation	⚠	Warning/เตือน
fa-circle-info	ℹ	Info/ข้อมูล
fa-spinner	◌	Loading
fa-star	★	Favorite/ชอบ
fa-heart	♥	Like/ถูกใจ
fa-thumbs-up	👍	Approve

E-Commerce

Icon Name	Placeholder	Usage
fa-cart-shopping	🛒	Cart/ตะกร้า
fa-bag-shopping	🛍	Shopping bag
fa-credit-card	💳	Payment/ชำระเงิน
fa-receipt	🧾	Receipt/ใบเสร็จ
fa-tag	🏷	Tag/ป้าย
fa-percent	%	Discount/ส่วนลด

Map & Location

Icon Name	Placeholder	Usage
fa-location-dot	📍	Location/ตำแหน่ง
fa-map	🗺	Map/แผนที่
fa-compass	🧭	Direction/ทิศทาง
fa-route	🛣	Route/เส้นทาง

Social

Icon Name	Placeholder	Usage
fa-brands fa-facebook	f	Facebook
fa-brands fa-google	G	Google
fa-brands fa-apple	``	Apple
fa-brands fa-line	L	LINE
fa-brands fa-github	⌥	GitHub

---

Size Mapping

Token	Size	FA class
icon.xs	12px	fa-xs
icon.sm	16px	fa-sm
icon.md	20px	— (default)
icon.lg	24px	fa-lg
icon.xl	32px	fa-xl
icon.2xl	48px	fa-2xl

---

Install FontAwesome (for Dev)

React

npm install @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome

CDN

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" />

Usage in React

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faCalendar, faUser, faBell } from '@fortawesome/free-solid-svg-icons'

<FontAwesomeIcon icon={faCalendar} size="lg" color="#EC599D" />

Figma MCP Commands Reference

คู่มือ commands ทั้งหมดที่ใช้ได้จริงสำหรับทำงานกับ Figma ผ่าน MCP Servers 2 ตัว

---

MCP Servers ที่ใช้

Server	ประเภท	หน้าที่หลัก
figma (remote)	Figma API	อ่าน design, screenshot, generate code, diagrams
html-to-design (remote)	html.to.design Plugin	ส่ง HTML ไปสร้างเป็น Figma layers อัตโนมัติ

Architecture

Claude ─┬─→ Figma MCP (read)           → อ่าน design, screenshot, metadata
        └─→ html-to-design MCP (write)  → ส่ง HTML/CSS ไปสร้างใน Figma

---

Table of Contents

Figma Remote MCP (อ่าน Design)

1. Screenshot & Design Context
2. Diagrams
3. Code Connect

html-to-design MCP (สร้าง Design)

4. Import HTML to Figma

Workflow & Patterns

5. Design Workflow
6. HTML Best Practices สำหรับ Figma
7. CSS-to-Figma Mapping Table
8. Post-Import Verification
9. Font Handling
10. Icon Pattern

---

1. Screenshot & Design Context (Figma Remote MCP)

ใช้ server figma (remote) — ต้องมี fileKey และ nodeId จาก URL

แยก fileKey และ nodeId จาก URL

URL: https://figma.com/design/ABC123/MyFile?node-id=1-2
→ fileKey = "ABC123"
→ nodeId = "1:2"  (เปลี่ยน - เป็น :)

Command	Parameters	Description
get_screenshot	fileKey, nodeId	ถ่ายภาพหน้าจอของ node
get_design_context	fileKey, nodeId	อ่าน design + generate UI code
get_metadata	fileKey, nodeId	ดู structure ในรูปแบบ XML (node IDs, types, positions)
get_variable_defs	fileKey, nodeId	ดู design variables ที่ใช้ใน node
whoami	—	ดูข้อมูลผู้ใช้ที่ login อยู่

Use Cases

• get_screenshot: ดู preview ของ design ที่สร้างแล้ว หรือ reference design
• get_design_context: อ่าน design เพื่อ generate code หรือทำความเข้าใจ design
• get_metadata: ดู structure ของ file เพื่อหา node IDs
• get_variable_defs: ดู design tokens/variables ที่ใช้ใน design

---

2. Diagrams (Figma Remote MCP)

Command	Parameters	Description
generate_diagram	name, mermaidSyntax, userIntent?	สร้าง diagram ใน FigJam จาก Mermaid.js

รองรับ: flowchart, sequenceDiagram, stateDiagram, gantt

---

3. Code Connect (Figma Remote MCP)

Command	Parameters	Description
get_code_connect_map	fileKey, nodeId	ดู mapping ระหว่าง Figma node กับ code component
get_code_connect_suggestions	fileKey, nodeId	ดูคำแนะนำ mapping
add_code_connect_map	fileKey, nodeId, source, componentName, label	เพิ่ม mapping
send_code_connect_mappings	fileKey, nodeId, mappings[]	ส่ง mappings หลายตัว
create_design_system_rules	—	สร้าง design system rules สำหรับ repo

---

4. Import HTML to Figma (html-to-design MCP)

ใช้ server html-to-design (remote) — ส่ง HTML ไปสร้างเป็น Figma layers ได้โดยตรงจาก Claude

Prerequisites

1. ติดตั้ง plugin html.to.design (by divRIOTS) ใน Figma
2. เปิด plugin → tab MCP → เปิด toggle "Enable MCP endpoint"
3. ตรวจว่า STATUS: connected (จุดเขียว) ใน plugin

Available Tools

Command	Parameters	Description
import_html	html, css?, js?, name?	ส่ง HTML code ไปสร้างเป็น Figma layers
import_url	url, name?	ส่ง URL ไป import ทั้งหน้าเว็บเป็น Figma layers

import_html — ส่ง HTML Code

import_html({
  html: "<div class='card'>...</div>",
  css: ".card { display: flex; ... }",
  name: "Login Screen"
})

• ส่ง HTML + CSS ไปตรง → plugin แปลงเป็น Figma layers ทันที
• ไม่ต้อง serve file ผ่าน URL
• ไม่ต้อง manual copy/paste ใน plugin
• Class names จะกลายเป็น Figma layer names

import_url — ส่ง URL

import_url({
  url: "http://localhost:3000/login-preview.html",
  name: "Login Screen"
})

• ส่ง URL ของหน้าเว็บ → plugin import ทั้งหน้า
• ต้อง serve file ก่อน (Live Server, npx serve .)
• เหมาะกับ HTML preview ที่ซับซ้อน (multi-page, external assets)

Tips

• ใช้ import_html เมื่อ HTML ไม่ซับซ้อนมาก (single component, single screen)
• ใช้ import_url เมื่อ HTML มี external assets (fonts, images) หรือหลายหน้า
• บอก "send to Figma" หรือ "send to html.to.design" ใน prompt เพื่อ trigger import
• ตรวจว่า plugin เปิด MCP endpoint อยู่ก่อน import

---

5. Design Workflow

Standard Flow: Claude → HTML → Figma

1. Claude สร้าง HTML preview (Static HTML file)
2. User เปิดใน browser + review + iterate จนพอใจ
3. Claude ส่ง HTML ไป Figma ผ่าน import_html หรือ import_url
4. Plugin แปลง HTML → Figma layers อัตโนมัติ
5. User fine-tune ใน Figma (font, sizing, components)

Pattern 1: สร้างหน้าจอ Mobile (iPhone 15 Pro)

<!-- สร้าง HTML preview 393x852 -->
<div class="login-screen" style="width:393px; min-height:852px; display:flex; flex-direction:column; background:#fff;">
  <header class="status-bar" style="display:flex; justify-content:space-between; padding:12px 24px;">
    <span>9:41</span>
    <span>...</span>
  </header>
  <main style="flex:1; display:flex; flex-direction:column; padding:0 16px; gap:16px;">
    <!-- Content -->
  </main>
</div>

จากนั้นส่งเข้า Figma:

import_html({ html: "...", css: "...", name: "Login Screen" })

Pattern 2: สร้าง Component (Button)

<button class="login-button" style="
  display:flex; align-items:center; justify-content:center;
  width:361px; height:50px;
  background:#007AFF; color:#fff;
  border:none; border-radius:12px;
  font-size:17px; font-weight:700;
">Log In</button>

Pattern 3: สร้าง Card

<div class="notification-card" style="
  display:flex; flex-direction:column; gap:8px;
  width:361px; padding:16px;
  background:#fff; border:1px solid #E3E3E8; border-radius:12px;
">
  <h3 class="card-title" style="font-size:16px; font-weight:700; color:#1B1D22;">Title</h3>
  <p class="card-body" style="font-size:14px; color:#6A6E83;">Description text here</p>
</div>

Pattern 4: สร้าง Text Field

<div class="email-field" style="
  display:flex; align-items:center; gap:10px;
  width:361px; height:50px; padding:0 12px;
  background:rgba(118,118,128,0.12); border-radius:10px;
">
  <span class="field-placeholder" style="font-size:17px; color:rgba(60,60,67,0.6);">Email address</span>
</div>

Pattern 5: อ่าน Design เดิม แล้วสร้างใหม่

// 1. อ่าน design จาก Figma
get_screenshot(fileKey, nodeId)
get_design_context(fileKey, nodeId)

// 2. Claude วิเคราะห์ design → สร้าง HTML preview

// 3. User review + iterate

// 4. ส่งเข้า Figma
import_html({ html: "...", css: "...", name: "Redesigned Screen" })

Pattern 6: Responsive Design (หลาย breakpoint)

// ส่งแต่ละ breakpoint แยก
import_html({ html: "...", css: "...", name: "Login - Mobile (393px)" })
import_html({ html: "...", css: "...", name: "Login - Tablet (834px)" })
import_html({ html: "...", css: "...", name: "Login - Desktop (1440px)" })

---

6. HTML Best Practices สำหรับ Figma

เพื่อให้ผลลัพธ์ใน Figma ดีที่สุด ให้เขียน HTML/CSS ตามกฎเหล่านี้:

สิ่งที่ควรทำ

• ใช้ flexbox/grid (ไม่ใช้ absolute position) → Auto Layout
• ใช้ CSS Variables สำหรับ colors → ง่ายต่อการปรับ
• ตั้ง class names ให้มีความหมาย → Figma layer names ที่อ่านได้
• ใช้ semantic HTML (<header>, <main>, <section>) → clean hierarchy
• ใช้ Google Fonts → font จะถูก map (อาจต้องปรับใน Figma)
• ใช้ inline SVG สำหรับ icons → จะกลายเป็น vector ใน Figma
• ใช้ CSS hex colors ตรง → สีจะแม่นยำ

สิ่งที่ควรหลีกเลี่ยง

• absolute/fixed position → จะไม่ได้ Auto Layout
• Tailwind/Bootstrap class names → layer names ไม่มีความหมาย
• Complex CSS animations → ไม่รองรับใน Figma
• External images via URL → อาจโหลดไม่ได้ ใช้ inline SVG หรือ base64 แทน
• Nested flex ลึกเกินไป → Figma layer hierarchy จะซับซ้อน

Class Names → Layer Names

Plugin จะใช้ class name เป็น layer name ใน Figma:

<!-- ✅ ดี — layer name มีความหมาย -->
<div class="login-form">
  <input class="email-field" />
  <button class="login-button">เข้าสู่ระบบ</button>
</div>

<!-- ❌ ไม่ดี — layer name ไม่มีความหมาย -->
<div class="flex-col p-4">
  <input class="w-full" />
  <button class="bg-pink-500">เข้าสู่ระบบ</button>
</div>

---

7. CSS-to-Figma Mapping Table

Layout Direction

CSS	Figma Result
display: flex; flex-direction: row	Horizontal Auto Layout
display: flex; flex-direction: column	Vertical Auto Layout
display: block (default)	No Auto Layout

Spacing

CSS	Figma Result
gap: 12px	Item Spacing = 12
padding: 16px	Padding = 16 (all sides)
padding: 12px 16px	paddingTop/Bottom = 12, Left/Right = 16

Sizing

CSS	Figma Result	หมายเหตุ
width: 393px	Fixed Width = 393	ขนาดคงที่
height: 852px	Fixed Height = 852	ขนาดคงที่
width: 100% (flex child)	Layout Sizing = Fill	ยืดเต็ม parent
height: auto / fit-content	Layout Sizing = Hug	ขนาดตาม content
flex: 1	Layout Sizing = Fill	ขยายเต็มพื้นที่ว่าง

Alignment

CSS	Figma Result
justify-content: flex-start	Primary Align = Min
justify-content: center	Primary Align = Center
justify-content: flex-end	Primary Align = Max
justify-content: space-between	Primary Align = Space Between
align-items: flex-start	Counter Align = Min
align-items: center	Counter Align = Center
align-items: flex-end	Counter Align = Max
align-items: baseline	Counter Align = Baseline

Visual Properties

CSS	Figma Result
background-color: #F5F5F5	Fill Color
color: #333	Text Color
border: 1px solid #ccc	Stroke + Stroke Weight
border-radius: 12px	Corner Radius = 12
box-shadow: ...	Drop Shadow (บาง plugin รองรับ)
font-size: 17px	Font Size = 17
font-weight: bold / 700	Font Weight = Bold

Wrap

CSS	Figma Result
flex-wrap: nowrap	Wrap = No Wrap
flex-wrap: wrap	Wrap = Wrap

CSS ≠ Figma (ข้อควรระวัง)

CSS Behavior	Figma Behavior	วิธีแก้
margin สร้าง space รอบ element	ไม่มี margin — ใช้ gap ของ parent	ใช้ gap ที่ parent container
margin: auto จัดกลาง	ไม่มี — ใช้ alignment	ใช้ justify-content: center
position: absolute	ใส่ไม่ได้ Auto Layout	ใช้ flex layout แทน
overflow: hidden	Figma clip content อยู่แล้ว	ไม่ต้องทำอะไร
box-sizing: border-box	Figma ทำ border-box เสมอ	ไม่ต้องทำอะไร

---

8. Post-Import Verification

หลัง import HTML ไป Figma ทุกครั้ง ควร verify ว่าผลลัพธ์ตรงกับ preview

Pattern: Verify ด้วย Screenshot

// หลัง import เสร็จ — ใช้ Figma Remote MCP ตรวจ
get_screenshot(fileKey, nodeId)

// เทียบกับ HTML preview:
// - Layout structure ถูกต้อง (Auto Layout direction, spacing)
// - สีถูกต้อง (fill, text color, border)
// - ขนาดถูกต้อง (width, height)
// - Text content ครบ

สิ่งที่ต้องตรวจหลัง Import

จุดตรวจ	วิธีตรวจ
Layout structure	get_screenshot → เทียบ visual
Colors	get_design_context → ตรวจ fill/stroke values
Dimensions	get_metadata → ตรวจ width/height
Text content	get_design_context → ตรวจ text nodes
Layer names	get_metadata → ตรวจว่า class names ถูกแปลง

สิ่งที่อาจต้องปรับหลัง Import

1. Font: เปลี่ยนเป็น font ที่ต้องการ (LINE Seed Sans TH, SF Pro, Roboto)
2. Sizing mode: ตรวจ FILL/HUG/FIXED ให้ถูกต้อง
3. Layer names: ปรับ rename ถ้าต้องการ
4. Components: แปลง repeated elements เป็น Figma components
5. Styles: สร้าง color styles / text styles จาก imported values

---

9. Font Handling

HTML → Figma Font Flow

ขั้นตอน	รายละเอียด
HTML	ใช้ Google Fonts (เช่น LINE Seed Sans TH) ผ่าน <link>
Import	html.to.design พยายาม map font ให้
หลัง Import	อาจต้องเปลี่ยน font ใน Figma ถ้า font ไม่ตรง

CSS fontWeight → Figma

CSS font-weight	ค่า	Figma Result
100-300 (Thin-Light)	100-300	Light
normal / 400 (Regular)	400	Regular
500 (Medium)	500	Medium
600 (SemiBold)	600	SemiBold
bold / 700 (Bold)	700	Bold
800-900 (ExtraBold-Black)	800-900	ExtraBold/Black

หมายเหตุ: html.to.design รองรับ font weight range กว้างกว่า approach เดิม — ไม่จำกัดแค่ 400 กับ 700

ขั้นตอนหลัง Import

บอกผู้ใช้:

"HTML ถูก import เข้า Figma แล้ว — font อาจต้องเปลี่ยนใน Figma:

1. เลือก text ทั้งหมด (Cmd+A ภายใน frame)
2. เปลี่ยน font ใน Properties panel ทางขวา
3. iOS → SF Pro / Android → Roboto / Custom → ตาม brand"

---

10. Icon Pattern

ใช้ Inline SVG ใน HTML

<!-- ✅ ดี — inline SVG จะกลายเป็น vector ใน Figma -->
<svg class="icon-calendar" width="20" height="20" viewBox="0 0 20 20" fill="none">
  <path d="M6 2V4M14 2V4M3 8H17M5 4H15C16.1 4 17 4.9 17 6V16C17 17.1 16.1 18 15 18H5C3.9 18 3 17.1 3 16V6C3 4.9 3.9 4 5 4Z" stroke="#6A7287" stroke-width="1.5" stroke-linecap="round"/>
</svg>

<!-- ✅ ดี — FontAwesome ผ่าน CDN (ถ้า import_url) -->
<i class="icon-calendar fa-solid fa-calendar" style="font-size:20px; color:#6A7287;"></i>

Naming Convention สำหรับ Layer Names

• ตั้ง class name เป็น icon-{name} → Figma layer name อ่านง่าย
• ดูรายละเอียด icon ทั้งหมดที่ references/fontawesome-icons.md

Placeholder (ถ้าไม่มี SVG)

<!-- ใช้ emoji + class name ที่มีความหมาย -->
<span class="icon-calendar" style="font-size:20px;">📅</span>

---

Quick Reference: เลือกใช้ Tool ไหน

ต้องการทำอะไร	ใช้ Tool	Server
ดู design ที่มีอยู่	get_screenshot	figma
อ่าน design details	get_design_context	figma
ดู structure	get_metadata	figma
ดู design variables	get_variable_defs	figma
สร้าง design ใหม่	import_html / import_url	html-to-design
สร้าง diagram	generate_diagram	figma
ตรวจ code mapping	get_code_connect_map	figma

Slide Templates Reference

CSS, HTML, JavaScript templates สำหรับ html-presentation-slide skill

---

Design Tokens (CSS Variables)

ต้องมีเสมอ — ใส่ใน :root ของ <style>:

:root {
  /* Primary */
  --primary-fg-high: #EC599D;
  --primary-bg-lowest: #FDEFF5;
  --primary-bg-mid: #EC599D;
  --primary-border-mid: #F7BDD8;

  /* Secondary */
  --secondary-fg-high: #7279FB;
  --secondary-bg-lowest: #F1F2FF;
  --secondary-bg-mid: #7279FB;
  --secondary-border-mid: #C7C9FD;

  /* Gray Neutral */
  --gray-fg-high: #1B1D22;
  --gray-fg-mid-on-white: #6A6E83;
  --gray-fg-low-on-white: #9A9DAD;
  --gray-bg-white: #FFFFFF;
  --gray-bg-lightgray: #F8F8F9;
  --gray-bg-midgray: #EBECEF;
  --gray-bg-black: #1B1D22;

  /* Spacing */
  --spacing-1: 4px;  --spacing-2: 8px;  --spacing-3: 12px;
  --spacing-4: 16px; --spacing-5: 20px; --spacing-6: 24px;
  --spacing-8: 32px; --spacing-10: 40px; --spacing-12: 48px;

  /* Radius */
  --radius-sm: 4px;  --radius-md: 8px;  --radius-lg: 12px;
  --radius-xl: 16px; --radius-2xl: 24px; --radius-full: 9999px;

  /* Shadow */
  --shadow-sm: 0 1px 3px rgba(0,0,0,0.1);
  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);

  /* Motion */
  --duration-fast: 200ms;
  --duration-normal: 300ms;
  --duration-slow: 500ms;
  --easing-default: ease-in-out;
  --easing-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
}

---

Slide Viewport (16:9)

ต้องมีเสมอ — Container หลักรักษา aspect ratio 16:9:

body {
  font-family: 'LINE Seed Sans TH', sans-serif;
  background: #0e0e12;
  display: flex;
  justify-content: center;
  align-items: center;
  min-height: 100vh;
  overflow: hidden;
}

.slide-viewport {
  position: relative;
  width: 100vw;
  height: 56.25vw;       /* 16:9 */
  max-height: 100vh;
  max-width: 177.78vh;   /* 16:9 inverse */
  overflow: hidden;
  background: var(--gray-bg-white);
  box-shadow: 0 0 60px rgba(0,0,0,0.3);
}

---

Slide Structure

แต่ละ slide เป็น <div class="slide" data-slide="N"> อยู่ใน .slide-viewport:

<div class="slide-viewport">
  <!-- Slide 1 -->
  <div class="slide bg-gradient-pastel active" data-slide="0">
    <!-- content -->
  </div>
  <!-- Slide 2 -->
  <div class="slide bg-gradient-violet" data-slide="1">
    <!-- content -->
  </div>
  <!-- ... more slides ... -->

  <!-- TOP BAR (อยู่นอก slide, ใน viewport) -->
  <!-- NAV BAR (อยู่นอก slide, ใน viewport) -->
</div>

---

Slide Transition CSS

ต้องมีเสมอ — Smooth slide-left/slide-right animation:

.slide {
  position: absolute;
  inset: 0;
  display: flex;
  flex-direction: column;
  opacity: 0;
  visibility: hidden;
  transform: translateX(80px);
  transition: opacity var(--duration-slow) var(--easing-default),
              transform var(--duration-slow) var(--easing-default),
              visibility 0s linear var(--duration-slow);
  pointer-events: none;
  overflow: hidden;
  z-index: 0;
}

.slide.active {
  opacity: 1;
  visibility: visible;
  transform: translateX(0);
  pointer-events: auto;
  z-index: 2;
  transition: opacity var(--duration-slow) var(--easing-default),
              transform var(--duration-slow) var(--easing-default),
              visibility 0s linear 0s;
}

.slide.exit-left  { opacity:0; visibility:hidden; transform:translateX(-80px); z-index:1; }
.slide.exit-right { opacity:0; visibility:hidden; transform:translateX(80px);  z-index:1; }
.slide.enter-from-left  { transform: translateX(-80px); }
.slide.enter-from-right { transform: translateX(80px);  }

---

Background Gradient Presets

สลับ gradient แต่ละ slide เพื่อ visual variety:

.bg-gradient-pastel { background: linear-gradient(135deg, #f3e8ff 0%, #fce7f3 25%, #e0e7ff 50%, #f0f9ff 75%, #fdf2f8 100%); }
.bg-gradient-dark   { background: linear-gradient(135deg, #1B1D22 0%, #282160 50%, #1B1D22 100%); }
.bg-gradient-violet { background: linear-gradient(135deg, #F1F2FF 0%, #FDEFF5 50%, #E6F6FC 100%); }
.bg-gradient-warm   { background: linear-gradient(135deg, #FDEFF5 0%, #FEF9EB 50%, #F1F2FF 100%); }
.bg-gradient-cool   { background: linear-gradient(135deg, #E6F6FC 0%, #F1F2FF 50%, #FDEFF5 100%); }

Dark slide: เพิ่ม class dark-slide เพื่อให้ nav ปรับเป็น dark mode อัตโนมัติ

---

Decorative Elements

เพิ่มความสวยด้วย circle blur + dot pattern:

.deco-circle {
  position: absolute;
  border-radius: 50%;
  opacity: 0.15;
  pointer-events: none;
}

.deco-dots {
  position: absolute;
  width: 120px; height: 120px;
  opacity: 0.08;
  background-image: radial-gradient(circle, var(--secondary-fg-high) 2px, transparent 2px);
  background-size: 16px 16px;
  pointer-events: none;
}

---

Slide Content Layouts

/* Header bar (logo + section label) */
.slide-header {
  display: flex;
  align-items: center;
  gap: var(--spacing-3);
  padding: 2.5% 4%;
  flex-shrink: 0;
}

/* Content area */
.slide-content {
  flex: 1;
  display: flex;
  padding: 0 5% 3%;
  gap: 4%;
  min-height: 0;
}

/* Layout variants */
.slide-content.centered   { justify-content:center; align-items:center; text-align:center; }
.slide-content.two-col    { flex-direction:row; align-items:center; }

---

Typography (clamp responsive)

ใช้ clamp() เสมอเพื่อให้ scale กับ viewport:

.title-xl  { font-size: clamp(32px, 3.5vw, 56px); font-weight: 800; line-height: 1.15; }
.title-lg  { font-size: clamp(22px, 2.5vw, 40px); font-weight: 700; line-height: 1.2; }
.title-md  { font-size: clamp(18px, 2vw, 32px);   font-weight: 700; line-height: 1.25; }
.body-lg   { font-size: clamp(14px, 1.4vw, 22px);  font-weight: 400; line-height: 1.5; }
.body-md   { font-size: clamp(12px, 1.2vw, 19px);  font-weight: 400; line-height: 1.5; }
.body-sm   { font-size: clamp(10px, 1vw, 16px);    font-weight: 400; line-height: 1.5; }

.gradient-text {
  background: linear-gradient(135deg, var(--primary-fg-high), var(--secondary-fg-high));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

---

Navigation Components

Present Button — แสดงเฉพาะ Slide แรก (Cover) เมื่อไม่ได้ fullscreen

<div style="position:absolute;top:1.5%;right:4%;z-index:200;display:flex;align-items:center;gap:var(--spacing-2);" id="topBar">
  <button class="present-btn" id="presentBtn" onclick="enterPresent()" title="เข้าโหมด Present (F)">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="15 3 21 3 21 9"/><polyline points="9 21 3 21 3 15"/><line x1="21" y1="3" x2="14" y2="10"/><line x1="3" y1="21" x2="10" y2="14"/></svg>
    <span>Present</span>
  </button>
  <!-- Pages Dropdown อยู่ถัดไป -->
</div>

CSS:

.present-btn {
  display: flex;
  align-items: center;
  gap: var(--spacing-2);
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--radius-md);
  border: none;
  background: var(--secondary-fg-high);
  cursor: pointer;
  font-family: 'LINE Seed Sans TH', sans-serif;
  font-size: clamp(11px, 1vw, 14px);
  font-weight: 700;
  color: #fff;
  transition: all var(--duration-fast) var(--easing-default);
  box-shadow: var(--shadow-md);
}
.present-btn:hover { background: #5a60e8; box-shadow: var(--shadow-lg); transform: translateY(-1px); }
.present-btn:active { transform: scale(0.97); }
.present-btn svg { width: clamp(14px, 1.1vw, 18px); height: clamp(14px, 1.1vw, 18px); }

Pages Dropdown — แสดงทุกหน้ายกเว้น Slide แรก (ยกเว้นตอน fullscreen จะแสดงทุกหน้า)

ปุ่ม Dropdown: บาง จาง opacity 0.45 -> hover แล้วชัดขึ้น

.page-dropdown-btn {
  display: flex;
  align-items: center;
  gap: var(--spacing-2);
  padding: var(--spacing-1) var(--spacing-3);
  border-radius: var(--radius-full);
  border: 1px solid transparent;
  background: transparent;
  cursor: pointer;
  font-family: 'LINE Seed Sans TH', sans-serif;
  font-size: clamp(10px, 0.9vw, 13px);
  font-weight: 600;
  color: var(--gray-fg-low-on-white);
  opacity: 0.45;
  transition: all var(--duration-fast) var(--easing-default);
}
.page-dropdown-btn:hover {
  opacity: 1;
  background: rgba(0,0,0,0.04);
  border-color: var(--gray-bg-midgray);
  color: var(--gray-fg-high);
}
.page-dropdown-wrap.open .page-dropdown-btn {
  opacity: 1;
  background: var(--gray-bg-white);
  border-color: var(--gray-bg-midgray);
  color: var(--gray-fg-high);
  box-shadow: var(--shadow-sm);
}

Dropdown Menu: สร้างด้วย JS — แสดงรายการ slide เป็น หน้า {N} : {Title}:

const slideTitles = [
  'Cover',
  'Agenda',
  // ... ชื่อ slide ทั้งหมด
];

function buildDropdownMenu() {
  const menu = document.getElementById('pageDropdownMenu');
  menu.innerHTML = '';
  slideTitles.forEach((title, i) => {
    const item = document.createElement('button');
    item.className = 'page-dropdown-item' + (i === currentSlide ? ' active-page' : '');
    item.innerHTML = `<span class="slide-num">${i + 1}</span> ${title}`;
    item.onclick = () => { goToSlide(i); document.getElementById('pageDropdown').classList.remove('open'); };
    menu.appendChild(item);
  });
}

Dropdown item styling:

.page-dropdown-item {
  display: flex;
  align-items: center;
  gap: var(--spacing-2);
  width: 100%;
  padding: var(--spacing-2) var(--spacing-3);
  border: none;
  background: none;
  cursor: pointer;
  font-family: 'LINE Seed Sans TH', sans-serif;
  font-size: clamp(10px, 0.9vw, 13px);
  font-weight: 500;
  color: var(--gray-fg-mid-on-white);
  text-align: left;
  white-space: nowrap;
}
.page-dropdown-item:hover { background: var(--gray-bg-lightgray); color: var(--gray-fg-high); }
.page-dropdown-item.active-page { color: var(--secondary-fg-high); font-weight: 700; background: var(--secondary-bg-lowest); }

.page-dropdown-item .slide-num {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-width: clamp(18px, 1.6vw, 22px);
  height: clamp(18px, 1.6vw, 22px);
  border-radius: var(--radius-sm);
  background: var(--gray-bg-lightgray);
  font-size: clamp(9px, 0.75vw, 11px);
  font-weight: 700;
}

Bottom Nav Bar (Position: absolute bottom ใน viewport)

<div class="nav-bar" id="navBar">
  <button class="nav-home-btn" onclick="goToSlide(0)" title="Go to first slide">
    <!-- House SVG icon -->
  </button>
  <div class="nav-buttons">
    <button class="nav-btn" onclick="prevSlide()"><!-- Left chevron --></button>
    <span class="nav-counter" id="navCounter">1/16</span>
    <button class="nav-btn" onclick="nextSlide()"><!-- Right chevron --></button>
  </div>
</div>

CSS:

.nav-bar {
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  display: flex;
  align-items: center;
  justify-content: flex-end;
  padding: 1.5% 4%;
  z-index: 100;
}

.nav-btn, .nav-home-btn {
  display: flex;
  align-items: center;
  justify-content: center;
  width: clamp(32px, 3vw, 44px);
  height: clamp(32px, 3vw, 44px);
  border-radius: var(--radius-md);
  border: 1px solid var(--gray-bg-midgray);
  background: var(--gray-bg-white);
  cursor: pointer;
  color: var(--gray-fg-mid-on-white);
  transition: all var(--duration-fast) var(--easing-default);
}

.nav-btn:hover, .nav-home-btn:hover {
  background: var(--gray-bg-lightgray);
  color: var(--gray-fg-high);
}

.nav-counter {
  font-size: clamp(11px, 1vw, 14px);
  color: var(--gray-fg-mid-on-white);
  font-weight: 700;
  min-width: 50px;
  text-align: center;
  font-variant-numeric: tabular-nums;
}

/* Dark variant (for dark-slide backgrounds) */
.nav-bar.dark-nav .nav-btn,
.nav-bar.dark-nav .nav-home-btn {
  background: rgba(255,255,255,0.1);
  border-color: rgba(255,255,255,0.15);
  color: rgba(255,255,255,0.7);
}

Present Hint Text — เฉพาะ Cover Slide

ข้อความเล็กๆ บอก shortcut:

<!-- Inside cover slide -->
<div class="present-hint" id="presentHint">
  กดปุ่ม <kbd>F</kbd> เพื่อเข้าโหมด Present
</div>

.present-hint {
  position: absolute;
  bottom: 12%;
  left: 50%;
  transform: translateX(-50%);
  font-size: clamp(10px, 0.85vw, 13px);
  color: var(--gray-fg-low-on-white);
  opacity: 0.7;
  pointer-events: none;
}
.present-hint kbd {
  padding: 1px 6px;
  font-weight: 700;
  background: var(--gray-bg-white);
  border: 1px solid var(--gray-bg-midgray);
  border-radius: var(--radius-sm);
  box-shadow: 0 1px 0 var(--gray-bg-midgray);
}

---

JavaScript (Navigation Engine)

ต้องมีเสมอ — ใส่ก่อน </body>:

const slides = document.querySelectorAll('.slide');
const totalSlides = slides.length;
let currentSlide = 0;
let isAnimating = false;

// === Update Nav Bar State ===
function updateNavBar() {
  document.getElementById('navCounter').textContent = `${currentSlide + 1}/${totalSlides}`;

  // Dark nav for dark slides
  const navBar = document.getElementById('navBar');
  const isDark = slides[currentSlide].classList.contains('dark-slide');
  navBar.classList.toggle('dark-nav', isDark);

  const pageDropdown = document.getElementById('pageDropdown');
  pageDropdown.classList.toggle('dark-dropdown', isDark);

  // First slide (not fullscreen): show Present, hide dropdown
  const isFS = !!document.fullscreenElement;
  const showPresent = currentSlide === 0 && !isFS;
  document.getElementById('presentBtn').style.display = showPresent ? '' : 'none';
  pageDropdown.style.display = showPresent ? 'none' : '';

  // Rebuild dropdown
  if (typeof buildDropdownMenu === 'function') buildDropdownMenu();
}

// === Slide Navigation ===
function goToSlide(index) {
  if (index === currentSlide || index < 0 || index >= totalSlides || isAnimating) return;
  isAnimating = true;

  const goingForward = index > currentSlide;
  const oldSlide = slides[currentSlide];
  const newSlide = slides[index];

  oldSlide.classList.remove('active');
  oldSlide.classList.add(goingForward ? 'exit-left' : 'exit-right');

  newSlide.style.transition = 'none';
  newSlide.classList.remove('exit-left', 'exit-right');
  newSlide.classList.add(goingForward ? 'enter-from-right' : 'enter-from-left');

  newSlide.offsetHeight; // force reflow
  newSlide.style.transition = '';
  newSlide.classList.remove('enter-from-right', 'enter-from-left');
  newSlide.classList.add('active');

  currentSlide = index;
  updateNavBar();

  setTimeout(() => {
    oldSlide.classList.remove('exit-left', 'exit-right');
    isAnimating = false;
  }, 500);
}

function nextSlide() { if (currentSlide < totalSlides - 1) goToSlide(currentSlide + 1); }
function prevSlide() { if (currentSlide > 0) goToSlide(currentSlide - 1); }

// === Keyboard Navigation ===
document.addEventListener('keydown', (e) => {
  switch(e.key) {
    case 'ArrowRight': case 'ArrowDown': case ' ':
      e.preventDefault(); nextSlide(); break;
    case 'ArrowLeft': case 'ArrowUp':
      e.preventDefault(); prevSlide(); break;
    case 'Home': e.preventDefault(); goToSlide(0); break;
    case 'End':  e.preventDefault(); goToSlide(totalSlides - 1); break;
    case 'f': case 'F': e.preventDefault(); enterPresent(); break;
  }
});

// === Touch Support ===
let touchStartX = 0;
document.addEventListener('touchstart', (e) => { touchStartX = e.touches[0].clientX; });
document.addEventListener('touchend', (e) => {
  const diff = touchStartX - e.changedTouches[0].clientX;
  if (Math.abs(diff) > 50) { diff > 0 ? nextSlide() : prevSlide(); }
});

// === Fullscreen / Present Mode ===
function enterPresent() {
  const el = document.querySelector('.slide-viewport');
  if (!document.fullscreenElement) {
    (el.requestFullscreen || el.webkitRequestFullscreen || el.msRequestFullscreen).call(el);
  } else {
    (document.exitFullscreen || document.webkitExitFullscreen || document.msExitFullscreen).call(document);
  }
}

document.addEventListener('fullscreenchange', () => { updateNavBar(); });

// === Pages Dropdown ===
const slideTitles = [/* fill per project */];

function buildDropdownMenu() { /* ... */ }
function togglePageDropdown() { /* ... */ }

document.addEventListener('click', (e) => {
  const dropdown = document.getElementById('pageDropdown');
  if (!dropdown.contains(e.target)) dropdown.classList.remove('open');
});

// === Init ===
buildDropdownMenu();
updateNavBar();

QA Gate Audit Criteria Reference

รายละเอียดการตรวจแต่ละจุดของ html-qa-gate skill — 3 Part / 10 Point

---

PART 1: Functional Intent

1. User Flow Clarity — รายละเอียดตรวจ

ตรวจ:
- หน้านี้คือหน้าอะไร → purpose ชัดจาก layout (มี heading, context)
- Primary action คืออะไร → ต้องมี 1 main CTA ที่โดดเด่นที่สุด
- Secondary action ไม่แย่งสายตา → ขนาด/สี/น้ำหนักต่ำกว่า primary
- Flow หลักดูได้จากสายตา → visual hierarchy ลำดับถูกต้อง (top-down หรือ left-right)

วิธีเช็ก: Dev เปิดหน้า → ต้องบอกได้ทันทีว่า "ผู้ใช้ต้องทำอะไร"

ตรวจใน HTML:
- มี <h1> หรือ heading ที่บอก purpose ของหน้า
- มี element ที่เป็น primary action (ปุ่มหลัก): ต้องมีขนาดใหญ่สุด / สีเข้มสุด / ตำแหน่งเด่นสุด
- ถ้ามี secondary actions (ปุ่มรอง): ต้อง visually subdued กว่า primary
  (เช่น outline style, สีอ่อนกว่า, ขนาดเล็กกว่า)
- ไม่มีปุ่มหลาย CTA ที่แข่งกัน (ขนาด/สี/น้ำหนักเท่ากัน > 1 ตัว = red flag)

Auto-fix: ปรับ visual weight ของ secondary buttons ให้ต่ำกว่า primary (เช่น เปลี่ยนเป็น outline, ลด font-weight, ลดขนาด)

---

2. State Coverage — รายละเอียดตรวจ

อย่างน้อยต้องมี 4 states หลัก:

State	คำอธิบาย	ต้องมี?
Default	หน้าตาตอนเปิดหน้า (มีข้อมูลปกติ)	ต้องมี
Loading	skeleton / spinner / placeholder	ต้องมี
Empty	ไม่มีข้อมูล — หน้าตาเป็นยังไง	ต้องมี
Error	อย่างน้อย 1 ตัวอย่าง (API fail, validation)	ต้องมี

ตรวจใน HTML:
- มี [data-state="default"] หรือ default view ที่แสดงตอนโหลด
- มี [data-state="loading"] หรือ loading indicator (skeleton, spinner, .loading class)
- มี [data-state="empty"] หรือ empty state UI (ข้อความ + illustration/icon)
- มี [data-state="error"] หรือ error UI (error message, retry button)
- ถ้ามี setState() function → ตรวจว่า handle อย่างน้อย 4 states ข้างต้น

Red flags:

• วาดแต่ happy path อย่างเดียว (มีแค่ default state)
• เขียนว่า "แล้วแต่ระบบ" โดยไม่มี visual hint

Auto-fix: ถ้าขาด state → เพิ่ม placeholder state ที่มี:

• Loading: skeleton placeholder
• Empty: icon + "ยังไม่มีข้อมูล" message
• Error: error icon + message + retry button
• เพิ่ม state switcher buttons ใน control panel

---

3. Interaction Intent — รายละเอียดตรวจ

ไม่ต้อง motion ละเอียด แต่ต้องสื่อเจตนา:

ตรวจ:
- Interactive elements (button, link, input) ต้องมี visual cue ว่า "กดได้"
  → มี cursor: pointer
  → มี hover state (background/color/shadow เปลี่ยน)
  → มี :active / :pressed feedback
- Disabled elements ต้อง look disabled
  → opacity ลดลง, cursor: not-allowed, สี subdued
- Static vs Dynamic elements แยกชัด
  → text ธรรมดา ไม่มี hover effect
  → interactive elements มี hover/active
- Modal / Drawer / Dropdown: ต้องระบุใน HTML ว่าเปิดจากตรงไหน
  → มี data-trigger, onclick, หรือ aria-controls attribute ชี้ไปที่ modal

Auto-fix:

• เพิ่ม cursor: pointer ให้ clickable elements ที่ขาด
• เพิ่ม hover styles ให้ buttons/links ที่ไม่มี (:hover { opacity: 0.85 })
• เพิ่ม opacity: 0.5; cursor: not-allowed; ให้ disabled elements ที่ไม่มี visual cue

---

4. Form Logic — รายละเอียดตรวจ

ไม่ต้อง validate rule ละเอียด แค่บอก Dev ว่า design คิดเรื่องนี้แล้ว:

ตรวจ (ถ้ามี form/input ในหน้า):
- Required fields มองออก
  → มี * หรือ (required) label หรือ visual indicator
  → มี required attribute ใน <input>
- Error message มีตำแหน่ง
  → มี error message element (แม้จะ hidden อยู่)
  → ตำแหน่ง error ใกล้กับ input ที่เกี่ยวข้อง (ไม่ใช่ไปอยู่ห่าง)
- Disabled state ถูกวางไว้แล้ว
  → มี disabled attribute หรือ .disabled class สำหรับ conditional inputs
- Long text / short text ไม่พัง layout
  → input มี max-width หรืออยู่ใน container ที่ constrain width
  → text ที่อาจยาว มี overflow handling (ellipsis, word-break, scroll)

Auto-fix:

• เพิ่ม required attribute ที่ input ที่มี * label
• เพิ่ม error message placeholder (<span class="error-msg" style="display:none">)
• เพิ่ม overflow: hidden; text-overflow: ellipsis; ที่ text ที่อาจยาว

---

PART 2: Component & Visual Readiness

5. Component Hygiene — รายละเอียดตรวจ

ตรวจ:
- ปุ่มทั้งหน้าใช้ style เดียวกัน (ไม่มีปุ่มหน้าละ style)
  → ทุก <button> / .btn ใช้ class เดียวกัน หรือ variant ของ class เดียวกัน
  → Primary button: 1 style, Secondary button: 1 style, Tertiary: 1 style
- Input fields ใช้ style เดียวกัน
  → ทุก <input>, <select>, <textarea> มี base style ร่วมกัน
- Card / container ใช้ pattern เดียวกัน
  → border-radius, padding, shadow consistent
- สีเดียวกันต้องเป็น token เดียวกัน (ไม่ใช่คนละ hex)
  → เช็คว่าไม่มี hardcoded hex ที่ใกล้เคียงกัน แต่ไม่เท่ากัน
  → เช่น #EC599D กับ #EC589D = red flag (ควรเป็น var เดียวกัน)

Red flags: ปุ่มหน้าละ style, สีเดียวกันแต่คนละ hex, component ที่ copy แล้วหลุดระบบ

Auto-fix:

• Normalize button styles → ใช้ class เดียวกัน
• แปลง duplicate hex → CSS variable เดียวกัน
• ทำให้ card/container padding + radius consistent

---

6. Naming & Structure — รายละเอียดตรวจ

ตรวจ:
- Class names สื่อความหมาย (ไม่ใช่ .div1, .box2, .temp)
  → ชื่อบอกว่า element นี้คืออะไร: .login-form, .product-card, .nav-bar
- HTML structure เป็น semantic
  → ใช้ <header>, <main>, <nav>, <section>, <footer>, <aside> ตามเหมาะสม
  → ไม่ใช่ <div> ซ้อน <div> ทั้งหมด
- Heading hierarchy ถูกต้อง
  → h1 → h2 → h3 ไม่กระโดดข้าม
- <html> มี lang attribute

เป้าหมาย: Dev ไม่ต้องถามว่า "อันไหนใช้จริง?"

Auto-fix:

• Rename generic classes → semantic names (เดาจาก context)
• เพิ่ม lang="th" ที่ <html> ถ้าไม่มี
• แปลง <div> ที่ชัดเจนเป็น semantic tags (เช่น div ที่มี class nav → <nav>)

---

7. Layout & Spacing — รายละเอียดตรวจ

ตรวจ:
- Spacing ใช้ระบบ 4px/8px grid
  → padding, margin, gap ควรเป็นค่าที่ตรง: 0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48px
  → หรือใช้ var(--spacing-*) tokens
  → ค่า %, vw, vh, clamp(), auto → OK (responsive values ไม่ต้องตรวจ)
- Padding/margin ไม่สุ่ม
  → sibling elements ที่เหมือนกัน (เช่น .card หลายตัว) ต้อง spacing เท่ากัน
  → section padding ทั้งหน้าควรใช้ค่าเดียวกัน
- Alignment ตรง (ไม่ลอย 1-2px แบบไม่มีเหตุผล)
  → elements ใน flex/grid container ควร align consistently
- Grid / column ชัด (โดยเฉพาะ desktop layout)
  → มี grid system หรือ flex layout ที่ชัดเจน

ไม่ต้อง pixel perfect แต่ต้อง มีเหตุผล

Auto-fix:

• แปลง magic numbers → ค่า grid ที่ใกล้ที่สุด (เช่น 15px → 16px/var(--spacing-4))
• ทำให้ sibling spacing consistent
• แปลง hardcoded spacing → CSS variables

---

8. Typography — รายละเอียดตรวจ

ตรวจ:
- ใช้ text style system (CSS class หรือ CSS variable)
  → ไม่พิมพ์ font-size/font-weight สดทุกที่
  → ควรมี .title-xl, .title-lg, .body-md ฯลฯ หรือ font shorthand variables
- Heading / body / caption แยกชัด
  → font-size ต่างกันอย่างน้อย 2px ระหว่าง levels
  → font-weight ต่างกัน (heading = bold/800, body = regular/400)
- Line height อ่านสบาย
  → body text: line-height >= 1.4 (แนะนำ 1.5)
  → heading: line-height >= 1.15
- ตัวหนังสือไม่ชนขอบ
  → text container มี padding อย่างน้อย 8px
  → ไม่มี text ที่ถูก clip/hidden โดยไม่ตั้งใจ

ภาษาไทยเพิ่มเติม:

• วรรณยุกต์ไม่ชน → line-height เพียงพอ (>= 1.5 สำหรับ Thai body text)
• ข้อความยาวแล้วไม่แตก → word-break ถูกต้อง

Auto-fix:

• แปลง inline font styles → text style classes
• ปรับ line-height ที่ต่ำเกินไป
• เพิ่ม padding ให้ text ที่ชนขอบ

---

9. Color & Token — รายละเอียดตรวจ

ตรวจ:
- ใช้สีจาก CSS variable system (ไม่ hardcode hex ตรง)
  → ทุก color property ควรเป็น var(--xxx)
  → ยกเว้น: gradient stops, rgba overlays, #fff, #000
- สีสถานะถูกต้อง
  → error/danger = โทนแดง (--error-fg-high)
  → success = โทนเขียว (--success-fg-high)
  → warning = โทนเหลือง/ส้ม (--warning-fg-high)
  → info = โทนฟ้า (--info-fg-high)
  → ไม่ใช้สีมั่ว (เช่น success เป็นสีแดง)
- ไม่ใช้สีใกล้กันจนแยกไม่ออก
  → 2 สีที่ใช้ต่างกันต้อง contrast >= 3:1 ระหว่างกัน
  → ไม่มี 2 สีที่ hex ต่างกัน < 10% แต่ใช้ต่างบทบาท
- Disabled state ดู disabled จริง
  → opacity <= 0.5 หรือ สี subdued ชัดเจน
  → cursor: not-allowed

WCAG Contrast Check (บังคับ):

Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)
Relative Luminance = 0.2126*R + 0.7152*G + 0.0722*B

เกณฑ์:
- Normal text: >= 4.5:1 (AA)
- Large text (>= 18pt bold / >= 24pt): >= 3:1
- UI components, icons: >= 3:1

คู่สีที่ต้องตรวจ:

• Text on background (ทุก element)
• Button text on button fill
• Placeholder on input background
• Nav text on nav background
• Dark slide text on dark gradient
• Badge/tag text on badge background
• Disabled text on background (ไม่ต้องผ่าน WCAG แต่ต้อง readable)

Auto-fix:

• แปลง hardcoded hex → CSS variable ที่ใกล้เคียงที่สุด
• ปรับ contrast ให้ผ่าน WCAG AA (ปรับ text ให้เข้มขึ้น/อ่อนลง โดยไม่เปลี่ยน design intent)
• เพิ่ม opacity + cursor: not-allowed ให้ disabled elements

---

10. Responsive Intent — รายละเอียดตรวจ

ไม่ต้องวาดครบทุก breakpoint แต่ต้องมีอย่างน้อย:

ตรวจ:
- Desktop layout มีอยู่ (เป็น default)
- Mobile intent ชัดเจน → Dev ต้องดูออกว่า:
  → อะไร stack (flex-direction: column)
  → อะไรซ่อน (display: none ที่ breakpoint)
  → อะไรเลื่อน (overflow-x: auto/scroll)

สำหรับ HTML preview (mobile app):

ตรวจ:
- มี phone frame container (width ~393px)
- Content อยู่ใน frame ไม่ overflow
- ทุก element มี max-width: 100% หรือ constrained width

สำหรับ HTML presentation (slide):

ตรวจ:
- viewport 16:9 ด้วย max-height: 100vh + max-width: 177.78vh
- Typography ใช้ clamp() responsive
- Images มี object-fit
- Touch targets >= 44px (nav buttons)

Slide-specific Navigation (ตรวจเฉพาะเมื่อเป็น slide):

ตรวจ:
- ทุก slide มี data-slide attribute เรียง 0, 1, 2, ...
- Slide แรกมี class "active"
- slideTitles array ตรงกับจำนวน slide
- Keyboard: ArrowRight/Left, Space, Home, End, F
- Touch: swipe support
- Fullscreen: requestFullscreen + exitFullscreen
- Nav components: Home, Prev/Next, Counter, Dropdown, Present btn
- Transition CSS: .slide.active, .exit-left, .exit-right

Auto-fix:

• เพิ่ม max-width: 100% ให้ elements ที่ overflow
• เพิ่ม object-fit: cover/contain ให้ images
• แก้ slide data attributes, slideTitles array
• เพิ่ม keyboard/touch handlers ถ้าขาด

---

PART 3: Handoff Check — รายละเอียดตรวจ

ตรวจ:
- Inline styles: นับ inline style ทั้งหมด → ถ้า > 20% ของ styled elements = red flag
- Placeholder text: scan หา "Lorem", "ipsum", "test", "xxx", "placeholder", "TBD", "TODO"
  → ถ้าเจอ = FAIL (ยกเว้นอยู่ใน comment)
- Component consistency: เปรียบเทียบ styles ของ elements ที่เป็น type เดียวกัน
  → ทุก button ต้อง share base class
  → ทุก input ต้อง share base class
  → ทุก card ต้อง share base class

Auto-fix:

• แทนที่ placeholder text → ข้อความสมจริง (เดาจาก context ของหน้า)
• ย้าย inline styles → CSS class (ถ้า pattern ชัดเจน)

---

Design Token Quick Lookup

Color Tokens

Primary:   --primary-fg-high (#EC599D), --primary-bg-lowest (#FDEFF5)
Secondary: --secondary-fg-high (#7279FB), --secondary-bg-lowest (#F1F2FF)
Gray:      --gray-fg-high (#1B1D22), --gray-fg-mid-on-white (#6A6E83), --gray-fg-low-on-white (#9A9DAD)
           --gray-bg-white (#FFFFFF), --gray-bg-lightgray (#F8F8F9), --gray-bg-midgray (#EBECEF)
Status:    --error-fg-high (#EA244F), --success-fg-high (#559652), --warning-fg-high (#F8C135), --info-fg-high (#0386B3)

Spacing Tokens

--spacing-1: 4px    --spacing-2: 8px    --spacing-3: 12px
--spacing-4: 16px   --spacing-5: 20px   --spacing-6: 24px
--spacing-8: 32px   --spacing-10: 40px  --spacing-12: 48px

Acceptable Values (4px grid)

0, 2px, 4px, 8px, 12px, 16px, 20px, 24px, 32px, 40px, 48px, 56px, 64px
%, vw, vh, em, rem, clamp(), auto → OK

UX Writing Spell Check Reference

ตารางตรวจคำผิด/ไวยากรณ์ สำหรับ figma-ux-writer skill

---

คำภาษาไทยที่มักสะกดผิด (Common Thai Misspellings)

ผิด (Wrong)	ถูก (Correct)	ประเภท
เว็ปไซต์ / เว็ปไซด์	เว็บไซต์	ทับศัพท์ผิด
อีเมล์	อีเมล	ทับศัพท์ไม่ต้องมีการันต์
แอปพลิเคชั่น	แอปพลิเคชัน	ทับศัพท์ไม่ต้องมีไม้เอก
ล็อกอิน / ล็อคอิน	เข้าสู่ระบบ	ใช้คำไทยแทน (ตาม terminology)
โปรไฟล์	โพรไฟล์	ทับศัพท์ตามราชบัณฑิตฯ
เซิฟเวอร์ / เซิร์ฟเวอร์	เซิร์ฟเวอร์	ทับศัพท์ผิด
ซอฟแวร์	ซอฟต์แวร์	ขาด ต์
ดีไซน์	ดีไซน์	ถูกแล้ว (แต่ถ้าเป็นทางการใช้ "การออกแบบ")
เบราเซอร์ / บราวเซอร์	เบราว์เซอร์	ทับศัพท์ผิด
คอนเท็นต์ / คอนเท้นท์	คอนเทนต์	ทับศัพท์ผิด
โน๊ตบุ๊ค	โน้ตบุ๊ก	ใช้ไม้ตรีแทนไม้โท + ค→ก
อัพเดท / อัพเดต	อัปเดต	พ→ป, ท→ต
อัพโหลด	อัปโหลด	พ→ป
ดาวน์โหลด	ดาวน์โหลด	ถูกแล้ว
เปอร์เซนต์ / เปอร์เซนท์	เปอร์เซ็นต์	ขาดไม้ไต่คู้
ไฮไลท์	ไฮไลต์	ท→ต
คลิ๊ก	คลิก	ไม่ต้องมีไม้ตรี
ดีเลท	ลบ	ใช้คำไทย (ตาม terminology)
แคนเซิล	ยกเลิก	ใช้คำไทย (ตาม terminology)
เซฟ	บันทึก	ใช้คำไทย (ตาม terminology)
ออฟไลน์ / ออฟไลน	ออฟไลน์	ต้องมีการันต์
ออนไลน์ / ออนไลน	ออนไลน์	ต้องมีการันต์
สมาทโฟน / สมาร์ทโฟน	สมาร์ตโฟน	ท→ต
แท็ปเล็ต / แท๊บเล็ต	แท็บเล็ต	สะกดผิด
บลูทูธ / บลูทูท	บลูทูท	ไม่มีการันต์ (ตามราชบัณฑิตฯ)
เทคโนโลยี่	เทคโนโลยี	ไม่ต้องมีไม้เอก

---

คำภาษาไทยที่มักสับสน (Commonly Confused Thai Words)

มักใช้ผิด	ที่ถูกต้อง	หลักการ
กรุณณา	กรุณา	ณ ตัวเดียว
ทะเบียร	ทะเบียน
รายละเอีัยด	รายละเอียด
ลงทะเบียร	ลงทะเบียน
นิติบุคล	นิติบุคคล
ปฎิบัติ	ปฏิบัติ
สังเกตุ	สังเกต	ไม่มีการันต์
ภาพยนต์	ภาพยนตร์
บรรได	บันได
สดวก	สะดวก	ขาดสระอะ
ปะกัน	ประกัน

---

คำภาษาอังกฤษที่มักสะกดผิดใน UX (Common English UX Misspellings)

ผิด (Wrong)	ถูก (Correct)	หมายเหตุ
Recieve	Receive	i before e, except after c
Occured / Occured	Occurred	ต้อง rr
Succesful / Successfull	Successful	ss + single l
Seperate	Separate	a ไม่ใช่ e
Neccessary	Necessary	c ตัวเดียว, s สองตัว
Definately	Definitely	ite ไม่ใช่ ate
Accomodate	Accommodate	cc + mm
Calender	Calendar	ar ไม่ใช่ er
Untill	Until	l ตัวเดียว
Permisson	Permission	ss
Notifcation	Notification	ขาด i
Authentification	Authentication	tion ไม่ใช่ fication
Cancelling (US)	Canceling	ใน US English ใช้ l เดียว
Canceled / Cancelled	ใช้ให้สม่ำเสมอ	US: canceled, UK: cancelled — เลือกอย่างเดียวทั้ง app
Disbale	Disable	สลับ a กับ l
Confrim	Confirm	สลับ i กับ r

---

ไวยากรณ์ที่มักผิดใน UX Copy (Common Grammar Issues)

ภาษาไทย

ผิด	ถูก	หลักการ
"ทำการ + กริยา" ซ้ำซ้อน	ใช้กริยาตรงๆ	"ทำการบันทึก" → "บันทึก"
"สามารถ...ได้" ที่ไม่จำเป็น	ตัดออกถ้าไม่เพิ่มความหมาย	"คุณสามารถแก้ไขได้" → "แก้ไขได้"
เว้นวรรคผิดจุด	เว้นวรรคระหว่างข้อความ ไม่ติดกัน	ตรวจตามบริบท
"ของ" ซ้ำซ้อน	ตัด "ของ" ที่ไม่จำเป็น	"ข้อมูลของบัญชีของคุณ" → "ข้อมูลบัญชี"
"การ" นำหน้าโดยไม่จำเป็น	ใช้กริยาตรงๆ	"ทำการตั้งค่า" → "ตั้งค่า"

ภาษาอังกฤษ

ผิด	ถูก	หลักการ
"Login" (as verb)	"Log in" (verb), "Login" (noun/adj)	แยก verb กับ noun
"Setup" (as verb)	"Set up" (verb), "Setup" (noun/adj)	แยก verb กับ noun
"Signin" / "Signout"	"Sign in" / "Sign out"	ต้องเว้นวรรคเมื่อเป็น verb
"Its" vs "It's"	"It's" = it is, "Its" = possessive	มักสลับกัน
"Your" vs "You're"	"You're" = you are	ตรวจบริบทให้ถูก
Subject-verb disagreement	ตรวจ singular/plural	"...has been saved" → "...have been saved"
Double negatives	ใช้ positive form	"Not uncommon" → "Common"

---

Correction Log Format

เมื่อตรวจเสร็จ ให้สร้าง Correction Log:

## Correction Log: [Screen/Feature Name]

| # | ตำแหน่ง (Location) | ข้อความเดิม (Original) | ข้อความที่แก้ (Corrected) | ประเภทข้อผิด (Error Type) | เหตุผล (Reason) |
|---|---------------------|------------------------|---------------------------|---------------------------|-----------------|
| 1 | Login button | "ล็อกอิน" | "เข้าสู่ระบบ" | ทับศัพท์ → ใช้คำไทย | ตาม terminology table |
| 2 | Error message | "กรุณณาลองใหม่" | "กรุณาลองใหม่อีกครั้ง" | สะกดผิด + ไวยากรณ์ | "กรุณณา" → "กรุณา" |

### สรุป (Summary)
- ตรวจทั้งหมด: X ข้อความ
- พบข้อผิด: Y จุด
- สะกดผิด (Spelling): N จุด
- ไวยากรณ์ (Grammar): N จุด
- ทับศัพท์ผิด (Transliteration): N จุด
- Terminology ไม่ตรง: N จุด
- ข้อความที่ถูกต้องแล้ว: N ข้อความ

---

Character Count Guidelines

Element	Max (ไทย)	Max (EN)	หมายเหตุ
Button	12 ตัวอักษร	20 characters	ยิ่งสั้นยิ่งดี
Tab label	8 ตัวอักษร	12 characters	ไม่ควรตัด
Nav item	8 ตัวอักษร	12 characters	ไม่ควร 2 บรรทัด
Toast/Snackbar	40 ตัวอักษร	60 characters	อ่านเร็ว
Title	20 ตัวอักษร	30 characters	1 บรรทัด
Body text	ตามกรอบ	ตามกรอบ	Line length 45-75 chars
Tooltip	30 ตัวอักษร	50 characters	สั้นและชัด
Error (inline)	40 ตัวอักษร	60 characters	พอดี 2 บรรทัด

Skill Building Guide — คู่มือสร้าง Skill สำหรับ Claude

คู่มืออ้างอิงหลักทุกครั้งที่ต้องสร้างหรือปรับปรุง Claude Skill อิงจาก Anthropic Official Guide + Best Practices จากประสบการณ์จริง

---

ขั้นตอนสร้าง Skill (Overview)

1. วิเคราะห์ — ระบุ use case 2-3 อัน, เลือกประเภท Skill, กำหนด success criteria
2. ออกแบบ — วาง folder structure, เขียน frontmatter, เลือก workflow pattern
3. เขียน — สร้าง SKILL.md + scripts/references/assets ตามจำเป็น
4. ทดสอบ — Triggering tests, Functional tests, Performance comparison
5. ปรับปรุง — Iterate จาก feedback (under/over-triggering, execution issues)
6. แจกจ่าย — Upload to Claude.ai / Claude Code / API

---

1. วิเคราะห์ก่อนเขียน

เลือกประเภท Skill

ประเภท	ใช้เมื่อ	ต้องการ Script?	ตัวอย่าง
Document/Asset Creation	สร้างเอกสาร, design, code ที่มีรูปแบบคงที่	ไม่จำเป็น	frontend-design, docx, pptx
Workflow Automation	กระบวนการหลายขั้นตอนที่ต้องทำซ้ำ	อาจจะ	skill-creator, research pipeline
MCP Enhancement	เสริม workflow ให้ MCP server	อาจจะ	sentry-code-review
Knowledge-only	ความรู้เฉพาะทาง, guidelines	ไม่	brand guidelines, policies

คำถามวิเคราะห์

ถามตัวเองก่อนเขียน:

1. Skill แก้ปัญหาอะไร? — ระบุให้ชัด
2. Claude ยังไม่รู้อะไร? — เพิ่มเฉพาะ context ที่ขาด
3. ต้องการ executable code ไหม? — Skill จำนวนมากใช้แค่ instructions
4. User จะพูดว่าอะไรเพื่อ trigger? — คิด trigger phrases
5. Output ที่คาดหวังคืออะไร? — document, code, analysis, etc.

กำหนด Use Case (ตัวอย่าง)

Use Case: Project Sprint Planning
Trigger: "help me plan this sprint", "create sprint tasks"
Steps:
  1. Fetch current project status
  2. Analyze team velocity
  3. Suggest task prioritization
  4. Create tasks with labels and estimates
Result: Fully planned sprint with tasks created

Success Criteria

เชิงปริมาณ:

• Skill triggers ถูกต้อง ≥90% ของ relevant queries
• Workflow จบใน X tool calls
• 0 failed API calls ต่อ workflow

เชิงคุณภาพ:

• User ไม่ต้อง prompt เพิ่มเกี่ยวกับ next steps
• ผลลัพธ์สม่ำเสมอข้าม sessions
• User ใหม่ทำสำเร็จตั้งแต่ครั้งแรก

---

2. โครงสร้าง Folder

your-skill-name/
├── SKILL.md              # ✅ REQUIRED — ไฟล์หลัก
├── scripts/              # ⚪ Optional — executable code
│   ├── process_data.py
│   └── validate.sh
├── references/           # ⚪ Optional — เอกสารเพิ่มเติม
│   ├── api-guide.md
│   └── examples/
└── assets/               # ⚪ Optional — templates, fonts, icons
    └── report-template.md

กฎเหล็กที่ต้องปฏิบัติ

กฎ	ถูก ✅	ผิด ❌
ชื่อไฟล์	SKILL.md (exact case)	skill.md, SKILL.MD
ชื่อ folder	my-cool-skill (kebab-case)	My Cool Skill, my_cool_skill
README	ห้ามใส่ README.md ใน skill folder	มี README.md ข้างใน
Frontmatter	ต้องมี --- เปิดปิด	ไม่มี delimiters
Name field	kebab-case, ไม่มี spaces/capitals	My Cool Skill
Security	ห้าม XML brackets < >	มี <tag> ใน frontmatter
Reserved names	ห้ามใช้ "claude" หรือ "anthropic" ในชื่อ	claude-helper

---

3. เขียน YAML Frontmatter

Minimal (ใช้ได้เลย)

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

Full Options

---
name: your-skill-name
description: >
  [สิ่งที่ทำ] + [เมื่อไหร่ใช้] + [ความสามารถหลัก]
  Use when user says "phrase1", "phrase2", or mentions "keyword".
  Do NOT use for [negative triggers].
license: MIT
compatibility: claude.ai, claude-code
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
---

Field Requirements

Field	Required?	ข้อจำกัด
name	✅ Yes	kebab-case, ≤64 chars, letters/numbers/hyphens
description	✅ Yes	≤1024 chars, ต้องมี WHAT + WHEN, ห้าม XML tags
license	Optional	e.g. MIT, Apache-2.0
compatibility	Optional	1-500 chars, ระบุ environment requirements
metadata	Optional	key-value pairs อะไรก็ได้

ตัวอย่าง Description ที่ดี vs ไม่ดี

ดี:

description: >
  Analyzes Figma design files and generates developer handoff documentation.
  Use when user uploads .fig files, asks for "design specs",
  "component documentation", or "design-to-code handoff".

ดี (มี negative triggers):

description: >
  Advanced data analysis for CSV files. Use for statistical modeling,
  regression, clustering. Do NOT use for simple data exploration
  (use data-viz skill instead).

ไม่ดี:

description: Helps with projects.  # เกินไปกว้าง
description: Creates sophisticated multi-page documentation systems.  # ไม่มี triggers
description: Implements the Project entity model with hierarchical relationships.  # technical เกินไป

---

4. Progressive Disclosure (3 ระดับ)

Skill ใช้ระบบ 3 ระดับเพื่อประหยัด tokens:

ระดับ	อะไร	โหลดเมื่อไหร่
Level 1	YAML frontmatter	เสมอ (อยู่ใน system prompt)
Level 2	SKILL.md body	เมื่อ Claude คิดว่า skill เกี่ยวข้อง
Level 3	Linked files (references/, scripts/)	เมื่อ Claude ต้องการข้อมูลเพิ่ม

แนวปฏิบัติ:

• SKILL.md body ≤500 บรรทัด (ควร ≤5,000 words)
• ถ้าเกิน → ย้ายรายละเอียดไป references/
• Link ชัดเจน: See references/api-patterns.md for rate limiting guidance
• ใช้ progressive disclosure เมื่อ SKILL.md เกิน ~300 บรรทัดเท่านั้น

---

5. เขียน Instructions

Template โครงสร้างหลัก

---
name: your-skill
description: [description with triggers]
---

# Your Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

Example:
  python scripts/fetch_data.py --project-id PROJECT_ID
  Expected output: [describe what success looks like]

### Step 2: [Next Step]
...

## Examples

### Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
  1. Fetch existing campaigns
  2. Create new campaign with parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [Common error message]
Cause: [Why it happens]
Solution: [How to fix]

Best Practices สำหรับ Instructions

เฉพาะเจาะจง ไม่คลุมเครือ:

# ✅ ดี
Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails:
- Missing required fields → add them to the CSV
- Invalid date formats → use YYYY-MM-DD

# ❌ ไม่ดี
Validate the data before proceeding.

ใส่ error handling:

# MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Your Service] > Reconnect

อ้างอิง bundled resources ชัดเจน:

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

กำหนด degrees of freedom:

ระดับ	ใช้เมื่อ	ตัวอย่าง
สูง (text instructions)	หลายวิธีเป็นไปได้	Code review guidelines
กลาง (scripts + params)	มี pattern ที่ดี แต่ยืดหยุ่นได้	Report generator
ต่ำ (specific scripts)	ต้องแม่นยำ, fragile operations	Database migration

สำหรับ validations สำคัญ: ใช้ script แทน language instructions เมื่อเป็นไปได้ — code กำหนดผลลัพธ์แน่นอน, ภาษาตีความได้หลายแบบ

---

6. Workflow Patterns (5 แบบ)

Pattern 1: Sequential Workflow Orchestration

ใช้เมื่อ: กระบวนการหลายขั้นตอนตามลำดับ

# Step 1: Create Account → create_customer(name, email)
# Step 2: Setup Payment → setup_payment_method() → wait for verification
# Step 3: Create Subscription → create_subscription(plan_id, customer_id from Step 1)
# Step 4: Send Welcome Email → send_email(template: welcome)

เทคนิค: explicit ordering, dependencies ระหว่าง steps, validation ทุกขั้น, rollback instructions

Pattern 2: Multi-MCP Coordination

ใช้เมื่อ: Workflow ข้ามหลาย services

# Phase 1: Design Export (Figma MCP)
# Phase 2: Asset Storage (Drive MCP)
# Phase 3: Task Creation (Linear MCP)
# Phase 4: Notification (Slack MCP)

เทคนิค: แยก phase ชัดเจน, data passing ระหว่าง MCPs, validate ก่อนไป phase ถัดไป

Pattern 3: Iterative Refinement

ใช้เมื่อ: คุณภาพ output ดีขึ้นเมื่อ iterate

# Initial Draft → Quality Check (scripts/check_report.py)
# → Refinement Loop (fix issues, re-validate)
# → Repeat until quality threshold met → Finalization

เทคนิค: explicit quality criteria, validation scripts, รู้ว่าเมื่อไหร่ควรหยุด iterate

Pattern 4: Context-Aware Tool Selection

ใช้เมื่อ: ผลลัพธ์เดียวกัน แต่ใช้ tools ต่างกันตาม context

# Decision Tree:
# Large files (>10MB) → cloud storage MCP
# Collaborative docs → Notion/Docs MCP
# Code files → GitHub MCP
# Temporary files → local storage

เทคนิค: decision criteria ชัดเจน, fallback options, บอก user ว่าเลือกทำไม

Pattern 5: Domain-Specific Intelligence

ใช้เมื่อ: Skill เพิ่มความรู้เฉพาะทางนอกเหนือจาก tool access

# Before Processing: compliance check (sanctions, jurisdiction, risk)
# IF passed → process transaction with fraud checks
# ELSE → flag for review, create compliance case
# Always: audit trail logging

เทคนิค: domain expertise ฝังใน logic, compliance ก่อน action, audit trail

---

7. Testing

7.1 Triggering Tests

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather?"
- "Help me write Python code"
- "Create a spreadsheet"

Debug: ถาม Claude: "When would you use the [skill name] skill?" — Claude จะ quote description กลับมา

7.2 Functional Tests

Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
  - Project created
  - 5 tasks with correct properties
  - All tasks linked
  - No API errors

7.3 Performance Comparison

Without skill: 15 messages, 3 failed API calls, 12,000 tokens
With skill: 2 clarifying questions, 0 failures, 6,000 tokens

วิธี iterate

สัญญาณ	ปัญหา	แก้ไข
Skill ไม่โหลดเมื่อควรโหลด	Under-triggering	เพิ่ม trigger phrases ใน description
Skill โหลดตอนไม่เกี่ยว	Over-triggering	เพิ่ม negative triggers, เจาะจงมากขึ้น
ผลลัพธ์ไม่สม่ำเสมอ	Execution issues	ปรับ instructions, เพิ่ม error handling
Claude ไม่ทำตาม instructions	Instructions ไม่ชัด	ใส่ CRITICAL header, ใช้ numbered lists

---

8. Troubleshooting

Skill ไม่ยอม Upload

Error	สาเหตุ	แก้
"Could not find SKILL.md"	ชื่อไฟล์ผิด	ตั้งชื่อเป็น SKILL.md (case-sensitive)
"Invalid frontmatter"	YAML format ผิด	ตรวจ --- delimiters, ปิด quotes
"Invalid skill name"	มี spaces/capitals	ใช้ kebab-case: my-cool-skill

Claude ไม่ทำตาม Instructions

1. Instructions ยาวเกินไป → ตัดให้กระชับ, ย้ายไป references/
2. Instructions อยู่ลึก → ย้าย critical instructions ขึ้นบนสุด, ใช้ ## CRITICAL header
3. ภาษาคลุมเครือ → เปลี่ยนจาก "validate things properly" เป็น checklist ชัดเจน
4. Model laziness → เพิ่มใน user prompt: "Take your time, quality over speed"

Context ใหญ่เกินไป

• SKILL.md ≤5,000 words, ย้ายรายละเอียดไป references/
• ลด skills ที่ enable พร้อมกัน (อย่าเกิน 20-50)
• ใช้ progressive disclosure ให้เต็มที่

---

9. Distribution

Upload to Claude.ai

1. Zip skill folder
2. Settings > Capabilities > Skills > Upload
3. Toggle on

Claude Code

วาง skill folder ในตำแหน่งที่ Claude Code อ่านได้

API

• /v1/skills endpoint สำหรับ manage skills
• container.skills parameter ใน Messages API
• ต้องเปิด Code Execution Tool beta

GitHub (แนะนำ)

• Public repo + clear README (ข้างนอก skill folder)
• Example usage + screenshots
• Link จาก MCP docs ถ้ามี

---

10. Checklist สุดท้าย

ก่อนเริ่ม

• ระบุ 2-3 use cases แล้ว
• เลือก tools ที่ต้องใช้แล้ว (built-in or MCP)
• วาง folder structure แล้ว

ระหว่างพัฒนา

• Folder ชื่อ kebab-case
• SKILL.md มีอยู่ (exact spelling)
• YAML frontmatter มี --- เปิดปิด
• name: kebab-case, ไม่มี spaces/capitals
• description: มีทั้ง WHAT และ WHEN
• ไม่มี XML tags < > ที่ไหนเลย
• Instructions ชัดเจน actionable
• มี error handling
• มี examples
• References link ชัดเจน

ก่อน Upload

• ทดสอบ triggering กับ obvious tasks
• ทดสอบ triggering กับ paraphrased requests
• ยืนยันว่าไม่ trigger กับ unrelated topics
• Functional tests ผ่าน
• Zip folder แล้ว

หลัง Upload

• ทดสอบใน conversation จริง
• Monitor under/over-triggering
• เก็บ feedback จาก users
• Iterate description + instructions

Visual Design Principles Reference

ความรู้เชิงลึกด้าน Visual Design — สกัดจาก UI/UX Design Library (100+ books) ครอบคลุม Visual Hierarchy, Color Theory, White Space, Typography, Composition

---

1. Visual Hierarchy Framework

ลำดับชั้นภาพ — สิ่งที่ดึงความสนใจก่อน:

Hierarchy Levers (เรียงตาม impact)

#	Lever	Effect	Example
1	Size	ใหญ่กว่า = สำคัญกว่า	Heading > Body text
2	Color/Contrast	สีเข้ม/สด = สำคัญกว่า	Primary CTA สีสด vs Secondary สีจาง
3	Weight	หนาแน่น = สำคัญกว่า	Bold heading vs Regular body
4	Position	บน/ซ้าย = อ่านก่อน (LTR)	Title อยู่บน, details อยู่ล่าง
5	Spacing	มี space รอบ = โดดเด่น	CTA มี whitespace ล้อมรอบ
6	Depth	เงา/ชั้น = อยู่ข้างหน้า	Modal มี shadow ทับ content
7	Motion	เคลื่อนไหว = ดึงตา	Notification badge pulse

Reading Patterns

F-Pattern (Content-heavy pages):

████████████████████
████████████████████
████████████
████████████████████
████████
████████████████████
█████

ผู้ใช้อ่านบรรทัดแรกเต็ม → scan ซ้ายลงมา → อ่านบางจุดที่สนใจ

Z-Pattern (Landing pages / simple layouts):

█────────────────█
       ╲
        ╲
█────────────────█

ผู้ใช้มอง: ซ้ายบน → ขวาบน → ซ้ายล่าง → ขวาล่าง (CTA ควรอยู่ขวาล่าง)

Gutenberg Diagram (Even content distribution):

Primary Optical    Strong Fallow
Area (ซ้ายบน)     Area (ขวาบน)
        ╲
          ╲
Weak Fallow        Terminal Area
Area (ซ้ายล่าง)    (ขวาล่าง) ← CTA here

Hierarchy Checklist

• มี 1 element ที่โดดเด่นที่สุดบนหน้า (hero / CTA)
• Content มี 3 ระดับ hierarchy ชัดเจน (primary, secondary, tertiary)
• Typography hierarchy ใช้ size + weight ร่วมกัน (ไม่ใช่แค่ size)
• CTA มี visual prominence สูงสุด
• Secondary actions ดู "เบากว่า" primary
• White space ช่วย group related content

---

2. Color Theory

Color Wheel & Harmony

Harmony	คู่สี	Feeling	ใช้เมื่อ
Complementary	ตรงข้าม (180°)	High contrast, vibrant	CTA vs background, accent
Analogous	ข้างเคียง (±30°)	Harmonious, calm	UI themes, gradients
Triadic	3 จุด (120°)	Vibrant, balanced	Complex UI with multiple accents
Split-Complementary	1 + 2 ข้าง complementary	Contrast + harmony	Safer than complementary
Monochromatic	สีเดียว ต่าง shade	Clean, cohesive	Minimal UI, single-brand

Color Psychology

Color	Emotion	Common Use in UI
Red	Urgency, danger, passion	Error, destructive action, sale
Orange	Energy, warmth, confidence	Warning, CTA (secondary)
Yellow	Optimism, attention, caution	Warning, highlight, badges
Green	Success, growth, safety	Success, confirm, positive
Blue	Trust, calm, professional	Primary, links, info
Purple	Luxury, creativity, wisdom	Premium, creative apps
Pink	Playful, feminine, warm	Social, lifestyle, fun
Black	Elegance, power, authority	Premium, text, luxury
White	Clean, simple, space	Background, breathing room
Gray	Neutral, professional	Text secondary, borders, disabled

Color in UI — Rules

1. 60-30-10 Rule: 60% neutral (bg), 30% secondary, 10% accent (CTA)
2. Semantic Colors: Error=Red, Warning=Yellow/Orange, Success=Green, Info=Blue — สากล
3. Contrast First: Text contrast >= 4.5:1 (WCAG AA) เสมอ
4. Color + Shape: ห้ามใช้สีอย่างเดียว — ต้องมี icon/shape ด้วย (color-blind safe)
5. Limit Palette: ไม่เกิน 5-6 สีหลัก + shades
6. Dark Mode: ไม่ใช่แค่ invert — ต้อง reduce contrast, use muted colors

Contrast Calculation

Relative Luminance (L):
  L = 0.2126 × R_linear + 0.7152 × G_linear + 0.0722 × B_linear

  where:
    sRGB <= 0.03928 → linear = sRGB / 12.92
    sRGB > 0.03928  → linear = ((sRGB + 0.055) / 1.055) ^ 2.4

Contrast Ratio = (L_lighter + 0.05) / (L_darker + 0.05)

Element	WCAG AA	WCAG AAA
Normal text	4.5:1	7:1
Large text (>= 18pt / 14pt bold)	3:1	4.5:1
UI components	3:1	—

---

3. White Space (Negative Space)

Types of White Space

Type	Description	Example
Micro white space	ระหว่าง elements เล็กๆ	Letter spacing, line height, padding ใน button
Macro white space	ระหว่าง sections ใหญ่	Section gaps, page margins, content blocks
Active white space	ตั้งใจเว้น เพื่อ guide attention	Space รอบ CTA, hero section breathing room
Passive white space	เกิดตามธรรมชาติ	Space ระหว่าง paragraphs, list items

White Space Rules

1. More space = More importance: element ที่มี space รอบมากกว่า = สำคัญกว่า
2. Group by proximity: elements ที่ใกล้กัน = เกี่ยวข้องกัน (Gestalt: Proximity)
3. Consistent spacing: ใช้ spacing system (4px/8px grid)
4. Don't fear empty: white space ไม่ใช่ "ว่าง" — มันคือ design element
5. Content density balance: mobile ต้องการ space มากกว่า desktop (touch targets)

Spacing Ratios

Relationship	Ratio	Example
Related elements	1x	Items ใน card: 8px gap
Semi-related	2x	Card padding: 16px
Sections	3-4x	Section gap: 24-32px
Major sections	5-6x	Page sections: 40-48px

---

4. Typography Principles

Type Scale

Modular Scale (recommended): ใช้ ratio เดียวกันทั้ง scale เพื่อ harmony

Ratio	Name	Scale Example (base 16px)
1.125	Major Second	16, 18, 20, 23, 25, 28
1.200	Minor Third	16, 19, 23, 28, 33, 40
1.250	Major Third	16, 20, 25, 31, 39, 49
1.333	Perfect Fourth	16, 21, 28, 38, 50, 67
1.500	Perfect Fifth	16, 24, 36, 54, 81

Typography Rules for UI

1. Body text minimum: 16px (mobile), 14px (desktop — ถ้าจำเป็น)
2. Line height: body 1.4-1.6, heading 1.1-1.3
3. Line length: 45-75 characters (optimal: 66)
4. Font families: ไม่เกิน 2 (heading + body)
5. Font weights: ใช้ 2-3 weights max (Regular, Medium/Semibold, Bold)
6. All caps: ใช้เฉพาะ labels/buttons สั้นๆ ไม่ใช่ paragraphs
7. Alignment: Left-aligned ดีที่สุด (Thai + English), avoid justified
8. Paragraph spacing: >= line height × 0.5 ระหว่าง paragraphs

Font Pairing Principles

Strategy	Example	Effect
Serif + Sans-serif	Playfair + Open Sans	Classic + modern
Same family, different weights	Inter Bold + Inter Regular	Clean, consistent
Geometric + Humanist	Poppins + Source Sans	Modern + friendly
Display + Text	Lobster + Roboto	Personality + readability

Thai Typography Notes

• LINE Seed Sans TH: sans-serif ที่ design สำหรับ digital Thai
• Thai characters สูงกว่า Latin → ต้องเพิ่ม line-height (1.5-1.8 for body)
• Thai ไม่มี spaces ระหว่างคำ → word-break: break-all ไม่เหมาะ
• Thai numbers vs Arabic numbers: ใช้ตามที่ target audience คุ้นเคย

---

5. Gestalt Principles for UI

Principle	Description	UI Application
Proximity	ใกล้กัน = เกี่ยวข้องกัน	Group form fields, card content
Similarity	เหมือนกัน = ประเภทเดียวกัน	Same style buttons = same importance
Continuity	ตาเคลื่อนตาม path	Aligned elements, step indicators
Closure	สมองเติมส่วนที่ขาด	Card with partial image (hint scroll)
Figure-Ground	แยก foreground จาก background	Modal overlay, card elevation
Common Region	ล้อมรอบด้วยกรอบเดียวกัน = กลุ่มเดียวกัน	Cards, containers, sections
Common Fate	เคลื่อนไหวเหมือนกัน = กลุ่มเดียวกัน	Carousel items, list animations

---

6. Composition & Layout

Grid Systems

Grid Type	Use Case	Example
Column grid	Content alignment, responsive	4-col mobile, 8-col tablet, 12-col desktop
Modular grid	Complex layouts, dashboards	Grid of equal cards
Baseline grid	Typography alignment	4px/8px baseline
Hierarchical grid	Magazine-style, editorial	Featured + supporting content

Golden Ratio (1.618)

• Content area vs sidebar: ~62% vs ~38%
• Hero image proportion: 1.618:1
• Card image to content ratio: ~60% image, ~40% content

Layout Principles

1. Alignment: ทุก element ต้อง align กับ grid line อย่างน้อย 1 ด้าน
2. Repetition: ใช้ pattern เดียวกันซ้ำ สร้าง consistency
3. Contrast: สร้างความแตกต่างเมื่อต้องการ differentiate
4. Balance: Symmetrical (formal) vs Asymmetrical (dynamic)

---

7. Flat Design Principles

Core Characteristics

1. No skeuomorphism: ไม่เลียนแบบ physical world
2. Bold, flat colors: ไม่มี gradients (หรือมีน้อย)
3. Simple shapes: Geometric, clean edges
4. Typography-driven: Type เป็น visual element หลัก
5. Grid-based: Strict alignment
6. Minimal shadows: None หรือ subtle

Modern Flat (Flat 2.0 / Material)

Flat design ที่เพิ่ม:

• Subtle shadows: เพื่อ depth/elevation
• Micro-interactions: เพื่อ feedback
• Gradients: Subtle, purposeful
• Illustrations: Flat-style illustrations

---

8. Card-Based Design Patterns

Card Anatomy

┌────────────────────────┐
│  ┌──────────────────┐  │  ← Image (optional)
│  │     IMAGE        │  │
│  └──────────────────┘  │
│                        │
│  Title                 │  ← Primary text (Label.3+)
│  Subtitle/Description  │  ← Secondary text (Caption.4)
│                        │
│  [Action 1]  [Action 2]│  ← Actions (optional)
│                        │
└────────────────────────┘

Card Rules

1. One idea per card: card = content unit
2. Consistent structure: ทุก card ใน grid ต้อง structure เดียวกัน
3. Visual peek: แสดง content ที่เหลือให้เห็นนิดหน่อย (hint scroll)
4. Tappable area: ทั้ง card ควร tappable (ไม่ใช่แค่ text)
5. Shadow for elevation: card ใช้ shadow สร้าง depth
6. Rounded corners: modern feel, softer than sharp corners

---

9. Minimalism Checklist

"Remove until it breaks, then add back one thing"

• ทุก element มีเหตุผลที่ต้องอยู่? (ถ้าเอาออกแล้วไม่เสีย = เอาออก)
• ใช้สีน้อยกว่า 5 สีไหม?
• Font families ไม่เกิน 2?
• ไม่มี decoration ที่ไม่ serve function?
• White space เพียงพอ?
• Content density ไม่แน่นจนอึดอัด?
• Navigation มี items น้อยที่สุดเท่าที่ serve user goals?
• ทุก section มี 1 clear message?

---

10. Von Restorff Effect (Isolation Effect)

สิ่งที่ "แตกต่าง" จากรอบข้างจะถูกจำ/สังเกตก่อน

Application in UI:

• Primary CTA สีต่างจาก background + secondary buttons
• Important card ใหญ่กว่า/สีต่างจาก cards อื่น
• Badge/notification ใช้สีสด (เช่น แดง) บน UI สีเรียบ
• Sale price สีแดง vs regular price สีเทา
• "Recommended" plan มี border/highlight ต่าง

---

Quick Reference: Visual Design Checklist

Before Shipping

• Visual hierarchy ชัดเจน — มองปราดเดียวรู้ว่าสำคัญอะไร
• Color contrast ผ่าน WCAG AA (4.5:1 text, 3:1 UI)
• Typography ใช้ 2-3 sizes max + 2-3 weights
• White space สม่ำเสมอ ใช้ spacing system
• Alignment ตรง — ทุก element อยู่บน grid
• CTA โดดเด่นที่สุดบนหน้า
• Card/component design consistent ทั้งหน้า
• Color สื่อ semantic meaning ถูกต้อง
• No unnecessary decoration
• Reading pattern (F/Z) ถูก guide ไป CTA

UI Preview Quality Rules

กฎ Visual Design สำหรับสร้าง HTML Preview คุณภาพสูง — สกัดจาก Refactoring UI, Practical UI, Laws of UX, Don't Make Me Think, Design of Everyday Things, Designing Interfaces + 60 เล่ม (ytx-readings/design-ui-ux + justinhartman/ui-ux-design-library)

ใช้เมื่อ: สร้าง HTML Preview, ตรวจ QA, Review Design, สร้าง Handoff Spec

---

1. Visual Hierarchy (จาก Refactoring UI + NNGroup)

กฎ Hierarchy

• Size ไม่ใช่เครื่องมือเดียว — ใช้ font weight + color + spacing ร่วมกัน
• De-emphasize ตัวรอง สำคัญกว่า emphasize ตัวหลัก — ลด contrast/weight ของ secondary content
• Labels เป็นทางเลือกสุดท้าย — ถ้า visual design ชัดเจนพอ ไม่ต้องมี label
• 3 ระดับ hierarchy เพียงพอ — Primary, Secondary, Tertiary (ไม่เกิน 3 size levels)
• CTA ต้อง pop — Von Restorff Effect: สิ่งที่แตกต่างจะถูกสังเกต

Reading Patterns

• F-Pattern: สำหรับ content-heavy (list, feed) — อ่านบรรทัดแรกเต็ม แล้ว scan ซ้ายลงมา
• Z-Pattern: สำหรับ landing page — ซ้ายบน → ขวาบน → ซ้ายล่าง → ขวาล่าง (CTA ที่ขวาล่าง)

---

2. Color Rules (จาก Refactoring UI + Color Theory books)

พื้นฐาน

• 60-30-10: 60% neutral (bg), 30% secondary, 10% accent (CTA)
• จำกัด 3 สีหลัก + shades (9-10 shades ต่อ hue)
• ใช้ HSL ไม่ใช่ hex สำหรับสร้าง shade — ปรับ saturation + lightness ได้ intuitive
• Near-black/near-white แทน pure #000/#FFF — เช่น #1B1D22 แทน #000000
• Neutral ไม่จำเป็นต้อง gray แท้ — เติม warm/cool hue เล็กน้อย (saturation < 5% ใน HSB)
• สีต่าง hue ต้องมี distinct brightness — ป้องกัน visual competition
• Saturate neutrals ทิศทางเดียว — warm ทั้งหมด หรือ cool ทั้งหมด ห้ามผสม

Semantic Colors (สากล)

สี	ใช้สำหรับ	ห้ามใช้สำหรับ
Red	Error, destructive, urgent	Success, neutral info
Green	Success, positive, confirm	Error, warning
Yellow/Amber	Warning, caution	Error, success
Blue	Info, primary action, links	Error, warning

Dark Mode Rules

• ไม่ใช่แค่ invert สี — ต้อง reduce contrast, ใช้ muted colors
• Container brightness ต่างกันไม่เกิน 12% (HSB) ใน dark mode, 7% ใน light mode
• Lighter = ใกล้ผู้ใช้ — surface ที่ "ลอย" ต้องสว่างกว่า background
• ไม่ใช้ shadow ใน dark mode — ไม่สมเหตุผลและมองไม่เห็น
• Font เล็ก อ่านยากขึ้น ใน dark mode — ควรเพิ่ม weight หรือ size

---

3. Typography Rules (จาก Refactoring UI + Typography books)

Scale

• Proportional type scale — ใช้ ratio เดียวกัน (เช่น 1.25) ห้ามสุ่มขนาด
• Body text >= 16px — ไม่เล็กกว่านี้บน mobile
• Max 2 typefaces — heading + body (เดียวกันก็ได้ถ้า weight ต่างกัน)
• 2-3 weights เพียงพอ — Regular, Semibold/Bold, Heavy (ไม่ต้องใช้ทุก weight)

Readability

• Line length 60-80 characters (optimal: 66) — ยาวกว่านี้ตาเหนื่อย
• Line-height สัมพันธ์กับ size — text ใหญ่ = line-height ต่ำลง, text เล็ก = line-height สูงขึ้น
• Letter-spacing สัมพันธ์กับ size — heading ใหญ่อาจต้อง negative tracking
• Left-aligned เสมอ (Thai + English) — ห้าม justify (อ่านยาก)
• All caps เฉพาะ labels/buttons สั้นๆ — ห้ามใช้กับ paragraph

Links & Text

• ไม่จำเป็นต้องใช้สีสำหรับทุก link — ใช้ underline หรือ weight แทนได้
• ห้ามลด contrast เพื่อ de-emphasize text — ใช้ font size/weight เล็กลงแทน (contrast ต่ำ = อ่านไม่ออก)

---

4. Spacing Rules (จาก Refactoring UI + Grid Systems)

System

• ใช้ spacing system — ค่าที่ mathematically related (4px grid: 4, 8, 12, 16, 20, 24, 32, 40, 48)
• เริ่มจาก space มากไป แล้วค่อยลด — ไม่ใช่เริ่มแน่นแล้วเพิ่ม
• ไม่ต้องเติมเต็มทุกพื้นที่ — white space คือ design element

Relationships

• Outer padding >= Inner padding — padding นอก container ต้อง >= padding ใน container
• วัด spacing ระหว่าง high-contrast edges — ไม่ใช่ center-to-center
• ห้าม ambiguous spacing — ต้องชัดว่า element ไหนกลุ่มเดียวกัน (Gestalt: Proximity)
• Spacing ratio: related items = 1x, semi-related = 2x, sections = 3-4x, major sections = 5-6x

Layout

• 12-column grid สำหรับ horizontal layouts — divisible by 2, 3, 4, 6
• Grids are overrated — ใช้ flexible spacing logic ดีกว่า strict grid ทุกกรณี
• Content ไม่จำเป็นต้องเต็ม width — max-width ช่วย readability

---

5. Borders & Separation (จาก Refactoring UI)

• ใช้ border น้อยลง — แทนด้วย box-shadow, background contrast, หรือ spacing
• Container border ต้อง contrast กับทั้ง fill AND background — ไม่ใช่แค่อันเดียว
• ห้ามมี adjacent hard divides ซ้อนกัน — background transition + container edge + dividing line ใน 1 จุด = รกเกินไป

---

6. Shadows & Depth (จาก Refactoring UI + Practical UI)

• แสงมาจากทิศเดียว — consistent ทั้งหน้า
• Shadow blur = 2x distance value — เช่น offset-y: 4px → blur: 8px
• ลด opacity เมื่อ element ใกล้ viewer — elevated element ควรมี shadow จางกว่า
• ใช้ shadow approach เดียว ทั้ง project — ห้ามผสม soft/hard/no-shadow
• ห้ามใช้ shadow ใน dark mode — ไม่สมจริงและมองไม่เห็น
• Lighter = ใกล้ — ทั้ง light mode และ dark mode

---

7. Button Design (จาก Refactoring UI + Practical UI)

• Horizontal padding = 2x Vertical padding — เช่น padding: 12px 24px
• Button hierarchy ชัดเจน — Primary (solid, bold color) > Secondary (outlined/muted) > Tertiary (text only)
• High contrast สำหรับ important elements — minimal contrast สำหรับ structural elements
• Gray button อาจดูเหมือน disabled — ระวังใช้สีเทาเป็น secondary button

---

8. Corner Radius (จาก Practical UI)

• Nested radius = outer radius - gap — ถ้า outer = 16px, gap = 8px → inner = 8px
• Consistent radius ทั้ง app — ห้ามผสม sharp + rounded โดยไม่มีเหตุผล

---

9. Icons (จาก NNGroup + Refactoring UI)

• ลด contrast ของ icon เมื่ออยู่คู่กับ text — ใช้ opacity หรือสีจางกว่า text
• Icon ต้องมี text label เสมอ — "word is worth a thousand pictures"
• มีแค่ 3 icon ที่ universal: home, print, magnifying glass — อื่นๆ ต้องมี label
• ถ้าคิด icon ไม่ออกใน 5 วินาที — concept นั้นซับซ้อนเกินกว่า icon จะสื่อได้

---

10. Component Patterns (จาก Designing Interfaces + Practical UI)

Cards

• ใช้สำหรับ browsing heterogeneous content (ไม่เหมาะกับ search/comparison)
• Variable height, consistent width — ไม่ force เท่ากันหมด
• Summary + link pattern: condensed teaser → fuller details

Forms

• Label ต้องเห็นตลอด — ห้ามใช้ placeholder แทน label
• Floating labels ได้ แต่ยังมี issues — visible label ดีกว่าเสมอ
• Placeholder = hint format ไม่ใช่ label (strain short-term memory, สับสนกับ default value)
• Error ต้องอยู่ใกล้ input — ใช้สีแดง + icon + text (ไม่ใช่แค่สี)
• ห้ามลบ input ที่ user กรอก เมื่อเกิด error — preserve user input เสมอ

Toggles

• Immediate effect ไม่ต้องกด Save — ถ้าต้อง Save → ใช้ radio/checkbox แทน
• Label อธิบาย ON state — ไม่ใช่คำถาม

Modals

• ห้ามแสดงก่อน user engage กับ content
• ห้ามขัดจังหวะ critical task กลางทาง
• ห้ามซ้อน modal — popup ทับ popup = nightmare
• Focus trap บังคับ สำหรับ modal dialog — keyboard ต้องอยู่ใน modal

Empty States

• ห้ามปล่อยว่าง — ต้องมี: status message + learning cue + actionable pathway
• ใช้เป็นโอกาส สอน user ว่า feature ทำอะไร

Loading States

ระยะเวลา	Pattern	Notes
< 1 วินาที	ไม่ต้อง	ให้รู้สึก instant
1-3 วินาที	Spinner / inline text	สำหรับ individual actions
2-10 วินาที	Skeleton screen	Mirror final layout structure
> 10 วินาที	Progress bar	ต้อง determinate

---

11. Accessibility Quick Rules

• Text contrast >= 4.5:1 (WCAG AA) — ตรวจทุกคู่สี
• Touch target >= 44px + spacing >= 2mm (8px)
• สีไม่ใช่ตัวบ่งชี้เดียว — ต้องมี icon/shape/text ด้วย
• Focus indicator ต้องเห็นชัด (contrast >= 3:1)
• รองรับ prefers-reduced-motion สำหรับทุก animation

---

12. Animation Rules

• ทุก animation ต้องมี purpose — guide attention, show connection, provide feedback
• User-triggered < 0.1s เริ่มต้น — Doherty Threshold
• Animation ที่เล่นซ้ำกลายเป็น roadblock — ห้าม force animation ที่ user เจอบ่อย
• Background = ช้ากว่า, Foreground = เร็วกว่า — direct interaction ต้องเร็ว
• No animation > bad animation — ถ้าไม่มีเหตุผล อย่ามี
• Reduced-motion alternative เสมอ

---

13. UX Writing Quick Rules (จาก Don't Make Me Think + Strategic Writing)

• User scan ไม่ได้อ่าน — ออกแบบสำหรับ scanning (F/Z pattern)
• 2 คำแรกของ heading/link สำคัญที่สุด — front-load keyword
• Plain language — หลีกเลี่ยง jargon แม้กับ expert audience
• Error = ปัญหา + วิธีแก้ ด้วยน้ำเสียงไม่ตำหนิ
• Button = action verb — "บันทึก" ไม่ใช่ "ตกลง"
• Link = promise — text ต้องบอกว่าไปไหน (ห้าม "Click here", "Learn More")
• ตัวเลขใช้ digits ไม่ใช่คำ ในสื่อ digital

---

14. Don't Make Me Think — Core Principles

1. Self-evident > Self-explanatory > Need explanation — ถ้าต้องคิด แปลว่ายังไม่ดีพอ
2. ลด noise — ทุก element ที่ไม่จำเป็นแข่งกับ element ที่จำเป็น
3. Create clear visual hierarchy — สิ่งสำคัญ ต้อง look important
4. Convention ดีกว่า innovation — ถ้า standard pattern ทำงานได้ อย่าประดิษฐ์ใหม่ (Jakob's Law)
5. Omit needless words — ลดข้อความ 50% แล้วลดอีก 50%

---

15. Laws of UX — Quick Reference

Law	กฎ 1 บรรทัด	ตรวจอะไรใน Preview
Aesthetic-Usability	สวย = ใช้ง่ายกว่า (รับรู้)	Polish visual details
Hick's Law	ตัวเลือกมาก = ตัดสินใจช้า	จำกัด CTA/options ต่อ section
Fitts's Law	เป้าใหญ่ + ใกล้ = เร็วกว่า	CTA ใหญ่พอ + ใกล้ cursor
Miller's Law	จำได้ 7±2 items	chunk ข้อมูลเป็นกลุ่ม 5-9
Jakob's Law	ชอบ pattern ที่คุ้นเคย	follow platform conventions
Doherty Threshold	< 400ms = flow state	skeleton screens, instant feedback
Von Restorff	สิ่งที่ต่าง ถูกจำ	CTA ต่างจากรอบข้าง
Serial Position	จำตัวแรก + ตัวสุดท้าย	ข้อมูลสำคัญ ต้น + ท้าย list
Peak-End Rule	peak + ending = ความทรงจำ	optimize จุดสูงสุด + จุดจบ
Proximity	ใกล้ = เกี่ยวข้อง	spacing ต้อง group ถูก
Similarity	เหมือน = ประเภทเดียวกัน	consistent styling = same meaning
Occam's Razor	เรียบง่ายที่สุด ชนะ	ลบทุกอย่างที่ไม่ serve user goal
Tesler's Law	complexity ลดไม่ได้ จัดการได้	ซ่อน complexity ไว้ในระบบ ไม่ใช่ user

---

MASTER CHECKLIST — ตรวจก่อนส่ง Preview

Visual Quality

• Typography ใช้ defined scale (ไม่มีขนาดสุ่ม)
• Body text >= 16px; line length 60-80 chars
• Line-height สัมพันธ์กับ text size
• Max 2 typefaces, 2-3 weights
• Spacing ใช้ 4px grid system
• Outer padding >= inner padding
• สีจาก palette เท่านั้น; 60-30-10 ratio
• Near-black/near-white (ไม่ใช่ pure #000/#FFF)
• Neutral greys มี subtle hue shift
• Shadows consistent จาก single light source
• Shadow blur = 2x distance
• Nested corner radius = outer - gap
• ไม่มี adjacent hard divides ซ้อนกัน

Hierarchy & Composition

• Visual hierarchy ชัดเจน 3 ระดับ
• CTA โดดเด่นที่สุดบนหน้า
• Gestalt grouping ถูกต้อง (proximity, similarity, common region)
• F/Z reading pattern ถูก guide ไป CTA

Interaction Quality

• Interactive elements มี affordance ชัดเจน
• Button hierarchy: Primary > Secondary > Tertiary
• Button padding: horizontal = 2x vertical
• Touch targets >= 44px + spacing >= 8px
• ทุก state ครบ: default, hover, pressed, focused, disabled, error, loading
• Toggle = immediate effect (ไม่ต้อง Save)
• Form labels เห็นตลอด (ไม่หายเมื่อ focus)
• Error = adjacent + red + icon + problem + solution

Accessibility

• Text contrast >= 4.5:1 (AA)
• สีไม่ใช่ตัวบ่งชี้เดียว
• Icon มี text label
• Focus indicators เห็นชัด
• Reduced-motion alternatives

Content & UX Writing

• Heading: keyword-first, scannable
• Button: action verbs (ไม่ใช่ "ตกลง/OK")
• Error: non-judgmental, constructive
• Empty state: status + learning + action
• Link text: specific (ไม่ใช่ "Click here")
• Numbers: digits ไม่ใช่คำ

Performance Perception

• Skeleton screens สำหรับ 2-10s loads
• No skeleton สำหรับ < 1s
• Progress bar สำหรับ > 10s
• Animation เริ่มใน < 0.1s
• ไม่มี gratuitous/repeated animation

UX Writing Patterns Reference

รวม patterns จากหนังสือ UX Writing ชั้นนำ: Strategic Writing for UX (Torrey Podmajersky), Nicely Said (Nicole Fenton & Kate Kifer Lee), Because Internet (Gretchen McCulloch)

---

Voice Chart System (6 Dimensions)

ใช้กำหนด Brand Voice อย่างเป็นระบบ — ทุก dimension ต้องมีทั้ง "ใช่" และ "ไม่ใช่":

Dimension	คำอธิบาย	ตัวอย่าง "ใช่"	ตัวอย่าง "ไม่ใช่"
Concepts	แนวคิด/metaphor ที่ brand ใช้	ใช้คำเปรียบเทียบจากธรรมชาติ	ไม่ใช้ศัพท์เทคนิค/jargon
Vocabulary	ระดับคำศัพท์	ใช้คำง่ายที่คนทั่วไปเข้าใจ	ไม่ใช้คำทางการเกินไป
Verbosity	ความยาว/รายละเอียด	กระชับ ตรงประเด็น	ไม่ยืดเยื้อ ไม่ซ้ำซ้อน
Grammar	โครงสร้างประโยค	ใช้ active voice, ประโยคสั้น	ไม่ใช้ passive voice ยกเว้นจำเป็น
Punctuation	เครื่องหมายวรรคตอน	ใช้ ... สำหรับ loading states	ไม่ใช้ ! มากเกินไป (>1 ต่อหน้า)
Capitalization	ตัวพิมพ์ใหญ่-เล็ก (EN)	Sentence case ทุกที่	ไม่ใช้ ALL CAPS ยกเว้น acronym

Voice Chart Template

## Voice Chart: [Brand Name]

### Concepts
- ✅ ใช้: [metaphor/แนวคิดที่ตรงกับ brand]
- ❌ ไม่ใช้: [metaphor ที่ขัดกับ brand]

### Vocabulary
- ✅ ใช้: [ระดับคำศัพท์ที่เหมาะสม]
- ❌ ไม่ใช้: [คำที่หลีกเลี่ยง]

### Verbosity
- ✅ ใช้: [ระดับความยาว/รายละเอียด]
- ❌ ไม่ใช้: [ระดับที่ไม่เหมาะ]

### Grammar
- ✅ ใช้: [โครงสร้างที่ใช้]
- ❌ ไม่ใช้: [โครงสร้างที่หลีกเลี่ยง]

### Punctuation
- ✅ ใช้: [เครื่องหมายที่ใช้ + เมื่อไหร่]
- ❌ ไม่ใช้: [เครื่องหมายที่หลีกเลี่ยง]

### Capitalization (EN)
- ✅ ใช้: [รูปแบบที่ใช้]
- ❌ ไม่ใช้: [รูปแบบที่หลีกเลี่ยง]

---

11 UX Text Patterns

Pattern 1: Titles (หัวข้อ)

• หน้าที่: บอก user ว่าอยู่ที่ไหน / กำลังทำอะไร
• ความยาว: 1-5 คำ (ยิ่งสั้นยิ่งดี)
• กฎ: ใช้ noun phrase หรือ verb phrase สั้นๆ
• ไทย: "ตั้งค่า", "ประวัติการสั่งซื้อ", "บัญชีของฉัน"
• EN: "Settings", "Order history", "My account"

Pattern 2: Buttons / Links / Commands (1-2 คำ ดีที่สุด)

• หน้าที่: บอก user ว่ากดแล้วจะเกิดอะไร
• ความยาว: 1-2 คำ perform ดีที่สุด, สูงสุด 4 คำ
• กฎ:
  • เริ่มด้วย verb เสมอ: "บันทึก", "ส่ง", "ยกเลิก"
  • Match button text กับ title: ถ้า title คือ "ลบบัญชี" → button = "ลบบัญชี" ไม่ใช่ "ตกลง"
  • Destructive: ใช้คำตรง "ลบ", "ยกเลิกการสมัคร" ไม่ใช่ "ตกลง"
  • คู่ปุ่ม: Primary action ชัดเจน + Secondary ใช้ "ยกเลิก" หรือ "ย้อนกลับ"

Pattern	ไทย	EN	ใช้เมื่อ
Verb-only	บันทึก	Save	Action ชัดเจนจาก context
Verb + Object	บันทึกที่อยู่	Save address	ต้องการความชัดเจน
Verb + Benefit	เริ่มทดลองฟรี	Start free trial	CTA ที่ต้องการ conversion

Pattern 3: Descriptions (คำอธิบาย)

• หน้าที่: อธิบายเพิ่มเติมจาก title
• ความยาว: < 40 ตัวอักษรกว้าง, ไม่เกิน 3 บรรทัด
• กฎ: ตอบ "ทำไมต้องสนใจ?" ไม่ใช่ "มันคืออะไร?"
• ไทย: "เพิ่มที่อยู่จัดส่งเพื่อให้สั่งซื้อได้เร็วขึ้น"
• EN: "Add a shipping address to check out faster"

Pattern 4: Empty States

• สูตร: "หากต้องการ [ผลลัพธ์] ให้ [ทำ action]"
• หน้าที่: บอก (1) สิ่งที่จะอยู่ตรงนี้ + (2) วิธีให้มัน appear
• ไทย: "ยังไม่มีรายการโปรด แตะ ♡ บนสินค้าที่ชอบ"
• EN: "No favorites yet. Tap ♡ on items you like"
• ห้าม: ไม่ใช้ "ไม่มีข้อมูล" / "No data" — ไม่ช่วยอะไร

Pattern 5: Labels (ป้ายกำกับ)

• หน้าที่: ระบุชื่อ element อย่างชัดเจน
• ความยาว: 1-3 คำ
• กฎ: ใช้ noun, ไม่ลงท้ายด้วย : (colon)
• ไทย: "ชื่อ", "อีเมล", "เบอร์โทรศัพท์"
• EN: "Name", "Email", "Phone number"

Pattern 6: Controls (ตัวควบคุม)

• หน้าที่: อธิบาย toggle, checkbox, radio, dropdown
• กฎ: ใช้ phrase ที่อ่านเป็นประโยคได้เมื่อรวมกับ control
  • Toggle: "รับการแจ้งเตือน" → on = ใช่ / off = ไม่
  • Checkbox: "ฉันยอมรับเงื่อนไขการใช้งาน"
  • Radio: แต่ละตัวเลือกเป็น noun phrase
• ไทย: "รับข่าวสารทางอีเมล", "จดจำอุปกรณ์นี้"
• EN: "Receive email updates", "Remember this device"

Pattern 7: Text Input Fields (ช่อง input)

• องค์ประกอบ: Label + Placeholder + Helper + Error
• Placeholder: ใช้ตัวอย่างจริง ไม่ใช่ "กรอก..."
  • ✅ "name@example.com"
  • ❌ "กรอกอีเมลของคุณ"
• Helper text: แสดงก่อนกรอก (format, ข้อจำกัด)
  • ✅ "ใช้ตัวอักษร 8-20 ตัว รวมตัวเลขอย่างน้อย 1 ตัว"
• Error text: แสดงเมื่อผิด (ดู Pattern 11)

Pattern 8: Transitional Text (ข้อความระหว่างทาง)

• หน้าที่: บอก user ว่าระบบกำลังทำอะไร
• กฎ: บอก "กำลังทำอะไร" ไม่ใช่แค่ "กำลังโหลด"
• ตัวอย่าง:
  • ✅ "กำลังบันทึกการเปลี่ยนแปลง..."
  • ✅ "กำลังตรวจสอบข้อมูล..."
  • ❌ "กำลังโหลด..."
  • ❌ "กรุณารอสักครู่..."
• Progress: ถ้ารู้ % → บอก %, ถ้าไม่รู้ → ใช้ ... (ellipsis)

Pattern 9: Confirmation Messages (ข้อความยืนยัน)

• สูตร: "[Action] + [ผลลัพธ์] + [ขั้นตอนถัดไป (ถ้ามี)]"
• ไทย: "สั่งซื้อเรียบร้อย จะจัดส่งภายใน 3-5 วัน"
• EN: "Order confirmed. You'll receive it in 3-5 days."
• กฎ:
  • ใช้ past tense / สำเร็จแล้ว
  • ให้ข้อมูลสำคัญ (เลขออเดอร์, เวลาจัดส่ง, อีเมลที่ส่งไป)
  • มี next step ถ้า relevant

Pattern 10: Notifications (การแจ้งเตือน)

• Push notification สูตร: "[Source]: [Content] + [Action hint]"
  • ✅ "คำสั่งซื้อ #1234 กำลังจัดส่ง — ติดตามพัสดุ"
  • ❌ "มีข้อความใหม่" (ไม่ actionable)
• In-app notification:
  • Banner: สั้น 1 บรรทัด + action link
  • Toast: auto-dismiss 4-6 วินาที + optional undo
  • Badge: ตัวเลขเท่านั้น (ไม่มี text)
• Permission request สูตร: "[ทำไม] + [ประโยชน์ที่ได้]"
  • ✅ "เปิดการแจ้งเตือนเพื่อรับสถานะคำสั่งซื้อ"
  • ❌ "อนุญาตให้ส่งการแจ้งเตือน"

Pattern 11: Error Messages

• หลักการหลัก: "สอนวิธีทำให้ถูก อย่าบอกว่าทำผิด"
• ห้ามใช้คำ: "invalid", "failed", "disabled", "ไม่ถูกต้อง", "ผิดพลาด" (ถ้าเลี่ยงได้)

3 ประเภท Error:

Type	ตำแหน่ง	ตัวอย่างไทย	ตัวอย่าง EN
Inline	ใต้ input ที่ผิด	"ใช้ตัวอักษร 8-20 ตัว"	"Use 8-20 characters"
Detour	Banner/Toast	"อีเมลนี้มีบัญชีแล้ว — เข้าสู่ระบบ"	"This email has an account — sign in"
Blocking	Full-screen/Dialog	"ไม่สามารถเชื่อมต่อเซิร์ฟเวอร์ ลองอีกครั้ง"	"Can't reach the server. Try again."

Error Message Formula:

[สิ่งที่เกิดขึ้น (ถ้าจำเป็น)] + [วิธีแก้ไข]

• Inline: ข้ามส่วนแรก ไปที่วิธีแก้เลย
  • ✅ "ใช้ตัวอักษรอย่างน้อย 8 ตัว"
  • ❌ "รหัสผ่านสั้นเกินไป"
• Detour/Blocking: ทั้งสองส่วน
  • ✅ "การชำระเงินไม่สำเร็จ กรุณาตรวจสอบข้อมูลบัตร"

---

4-Phase Editing Process

ตรวจ copy ทุกครั้งด้วย 4 เฟส (จาก Nicely Said):

Phase 1: Purposeful (มีจุดประสงค์)

• ข้อความนี้ช่วย user ทำอะไร?
• ตัดข้อความที่ไม่มีจุดประสงค์ออก
• ทุกข้อความต้อง advance user's goal

Phase 2: Concise (กระชับ)

• ตัดคำที่ไม่เพิ่มความหมาย
• "ทำการบันทึก" → "บันทึก"
• "คุณสามารถแก้ไขได้" → "แก้ไขได้"
• "Please enter your email address" → "Enter your email"

Phase 3: Conversational (เป็นธรรมชาติ)

• อ่านออกเสียง — ถ้าพูดแบบนี้จริงไหม?
• ใช้ contractions (EN): "you'll", "we're", "can't"
• ไม่ทางการเกินไป ไม่ casual เกินไป
• ตรวจ: "ถ้าพูดกับเพื่อนจะพูดแบบนี้ไหม?"

Phase 4: Clear (ชัดเจน)

• อ่านครั้งเดียวเข้าใจไหม?
• ตัด ambiguity ทุกจุด
• ตรวจ: "คนที่ไม่รู้ context จะเข้าใจไหม?"

---

UX Content Heuristics Scorecard

ให้คะแนน copy ตาม 2 มิติ (น้ำหนัก: Usability 2/3, Voice 1/3):

Usability Heuristics (2/3 น้ำหนัก)

#	Heuristic	คำถาม	คะแนน (1-5)
1	Accessible	ผู้พิการใช้ได้ไหม? (screen reader, alt text, aria-label)	—
2	Findable	หาข้อความนี้เจอง่ายไหม? อยู่ถูกที่ไหม?	—
3	Clear	อ่านครั้งเดียวเข้าใจไหม? ไม่ ambiguous?	—
4	Useful	ช่วย user ทำสิ่งที่ต้องการได้จริงไหม?	—
5	Appropriate	เหมาะกับ context/สถานการณ์ไหม?	—
6	Translatable	แปลเป็นภาษาอื่นได้ง่ายไหม? ใช้ idiom ไหม?	—

Voice Heuristics (1/3 น้ำหนัก)

#	Heuristic	คำถาม	คะแนน (1-5)
1	Concepts	ใช้ metaphor/แนวคิดตรง brand voice ไหม?	—
2	Vocabulary	ใช้คำศัพท์ตรง voice chart ไหม?	—
3	Verbosity	ความยาวเหมาะสมตาม voice chart ไหม?	—
4	Grammar	โครงสร้างประโยคตรง voice chart ไหม?	—
5	Punctuation	เครื่องหมายวรรคตอนตรง voice chart ไหม?	—
6	Capitalization	ตัวพิมพ์ใหญ่-เล็กตรง voice chart ไหม?	—

คำนวณคะแนน

Usability Score = average(U1-U6) × (2/3)
Voice Score = average(V1-V6) × (1/3)
Total = Usability Score + Voice Score (out of 5)

คะแนน	ระดับ	ความหมาย
4.5-5.0	ดีเยี่ยม	Ship ได้เลย
3.5-4.4	ดี	ปรับเล็กน้อย
2.5-3.4	ปานกลาง	ต้อง revise
1.0-2.4	ต้องปรับปรุง	เขียนใหม่

---

Inclusivity & Sensitivity Rules

ภาษาที่ควรหลีกเลี่ยง

❌ หลีกเลี่ยง	✅ ใช้แทน	เหตุผล
คนพิการ	ผู้พิการ / คนที่มีความพิการ	People-first language
ปกติ / ไม่ปกติ	ทั่วไป / พบได้น้อย	"ปกติ" imply ว่าอีกอย่างผิดปกติ
ง่ายๆ / แค่...	(ตัดออก)	อาจไม่ง่ายสำหรับทุกคน
Master/Slave	Primary/Replica	Inclusive terminology
Whitelist/Blacklist	Allowlist/Blocklist	Inclusive terminology
Hey guys	ทุกคน / Hi everyone	Gender-neutral
He/She	They	Gender-neutral pronoun

กฎ Inclusive Writing

1. ไม่สมมติเพศ, อายุ, ความสามารถ, วัฒนธรรม
2. ไม่ใช้สำนวน/idiom ที่แปลยาก (localization)
3. ใช้ภาษา positive — บอกว่า "ทำได้" ไม่ใช่ "ทำไม่ได้"
4. ตรวจ alt text ทุกรูป, aria-label ทุก interactive element
5. ไม่ใช้สีเป็นตัวสื่อความหมายเพียงอย่างเดียว

---

Localization Considerations

กฎ 50-67%

เมื่อเขียนภาษาอังกฤษ ใช้พื้นที่เพียง 50-67% ของที่มี — เพราะเมื่อแปลเป็นภาษาอื่น text จะยาวขึ้น 30-50%

ภาษา EN	ภาษาอื่น (ประมาณ)	สัดส่วน
"Save"	"บันทึก"	1:1
"Sign in"	"เข้าสู่ระบบ"	1:2
"Forgot password?"	"ลืมรหัสผ่านใช่ไหม?"	1:1.5
"Delete account"	"ลบบัญชีผู้ใช้"	1:1.3

Localization-Friendly Writing

• ไม่ concatenate strings: ❌ "Hello " + name + "!" ✅ "Hello {name}!"
• ไม่ใช้ idiom: ❌ "a piece of cake" ✅ "easy"
• ไม่ hardcode วันที่/เวลา format
• ไม่ embed text ในรูปภาพ
• รองรับ text direction (LTR/RTL)

---

Internet Language Conventions (From "Because Internet")

Tone Indicators ในยุคดิจิทัล

• Period (.): ในข้อความสั้น "." อาจรู้สึก "โกรธ" หรือ "เย็นชา" → ใช้เฉพาะ UI formal, ไม่ใช้ใน chat/toast
• Exclamation (!): 1 ตัว = กระตือรือร้น, >1 ตัว = ไม่เป็นมืออาชีพ → ใช้ไม่เกิน 1 ต่อหน้า
• Ellipsis (...): สื่อ "กำลังคิด" หรือ "ยังไม่จบ" → ดีสำหรับ loading, ไม่ดีสำหรับ error
• Emoji: ช่วย convey tone ใน casual context → ใช้ได้ใน success/celebration, ไม่ใช้ใน error/formal
• ALL CAPS: = ตะโกน → ใช้เฉพาะ brand ที่ต้องการ bold personality, ไม่ใช้ใน body text

Formal vs Informal Spectrum

FORMAL ←──────────────────────────────────→ INFORMAL
Legal    Banking    E-com    Social    Gaming    Chat

ปรับ voice ตาม product type:

• Formal (Banking, Legal): ไม่ใช้ contractions, ไม่ใช้ emoji, ใช้ full sentences
• Neutral (E-com, Productivity): Contractions OK, no emoji in errors, sentence fragments OK
• Informal (Social, Gaming): Emoji OK, slang OK in moderation, fragments encouraged

---

Copy Audit Quick Reference

Red Flags (ต้องแก้ทันที)

1. Button ที่เขียน "ตกลง" / "OK" / "Submit" — ไม่บอกว่าจะเกิดอะไร
2. Error ที่เขียน "เกิดข้อผิดพลาด" — ไม่บอกวิธีแก้
3. Empty state ที่เขียน "ไม่มีข้อมูล" — ไม่กระตุ้น action
4. Loading ที่เขียน "กำลังโหลด..." — ไม่บอกว่าโหลดอะไร
5. Permission ที่ไม่อธิบายเหตุผล
6. Title ที่ยาวเกิน 5 คำ
7. Description ที่ยาวเกิน 3 บรรทัด
8. ใช้ passive voice: "ข้อมูลถูกบันทึก" → "บันทึกแล้ว"
9. ใช้ "กรุณา" ทุกที่ → ตัดออก ใช้เฉพาะเมื่อขอสิ่งพิเศษ
10. Inconsistent terminology — เรียกสิ่งเดียวกันหลายชื่อ

Green Flags (เขียนดีแล้ว)

1. Button text ตรงกับ context: "ลบบัญชี" ไม่ใช่ "ยืนยัน"
2. Error message บอกทั้งปัญหาและวิธีแก้
3. Empty state มี CTA ที่ actionable
4. Loading บอกว่ากำลังทำอะไร
5. Tone ตรงกับอารมณ์ของ user ณ จุดนั้น
6. ใช้ terminology เดียวกันทั้ง app
7. อ่านครั้งเดียวเข้าใจ
8. กระชับ — ตัดคำที่ไม่จำเป็นออกแล้ว

---
name: figma-ui-design-spec
description: "สร้าง UI Design Specification document สำหรับนำไปใช้งานใน Figma โดยอ้างอิง Design Principles หลักๆ ได้แก่ Material Design, Human Interface Guidelines (Apple), Nielsen's Heuristics, Laws of UX และ Custom Design System ของทีม ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ออกแบบ UI, สร้าง design spec, สร้าง wireframe spec, สร้าง hi-fi UI spec, ออกแบบหน้าจอแอป, ออกแบบ component, ทำ design document สำหรับ Figma, หรือเมื่อถูกพิมพ์ 'ออกแบบ UI', 'design spec', 'Figma design', 'wireframe', 'mockup spec', 'UI specification', 'component design', 'design system', 'layout design' ไม่ผู้ใช้จะไม่ได้ระบุคำว่า 'Figma' โดยตรง ให้ trigger skill นี้เมื่อให้ค่าว่าเป็นงาน UI/UX design"
---

# Figma UI Design Specification Skill

สร้างเอกสาร UI Design Specification ที่ครบถ้วน อ้างอิงหลักการออกแบบที่ได้มาตรฐาน พร้อม preview และสร้างหน้าจอจริงใน Figma ได้

## Pipeline Position

```
Jira BA → IA + User Flow → [UI Design] → QA Gate → ส่งมอบ
                              ▲ อยู่ตรงนี้
```

## Overall Flow

```
1. Requirements → 2. Read Design Principles → 3. Preview (HTML) → 4. Iterate (Browser) → 5. QA Gate → 6. Import to Figma (HTML to Figma MCP)
```

ทั้ง 6 ขั้นตอนคือ flow หลักของ skill:

1. **Requirements**: รวบรวมความต้องการจากผู้ใช้ (หรือจาก Jira card ผ่าน jira-req-analysis → figma-user-flow pipeline)
2. **Design Principles**: อ่าน references เพื่อออกแบบตามหลักการ
3. **Preview**: สร้าง Static HTML file (.html) ให้ดูหน้าจอจริงใน browser ก่อน import เข้า Figma
4. **Iterate**: User เปิด HTML ใน browser + บอก Claude แก้ไข → refresh ดูผลทันที
5. **QA Gate**: ส่ง HTML ไป **html-qa-gate** skill ตรวจคุณภาพ (Color, Accessibility, Navigation, Sizing, Spacing) — auto-fix + วนตรวจ max 3 รอบ
6. **Import to Figma**: ใช้ html-to-design MCP ส่ง HTML ไป Figma โดยตรง (`import_html` / `import_url`)

---

## Step 1: รวบรวม Requirements

Requirements อาจมาจาก:
- **IA + User Flow pipeline** → ถ้า user ผ่าน `jira-req-analysis` → `figma-user-flow` pipeline มาแล้ว จะมี structured data ครบ: Screen Map, Navigation Matrix, User Flows (happy + error paths), Feature Inventory, User Stories, State Matrix — ข้ามไป Step 2 ได้เลย
- **Jira card analysis** → ถ้า user ผ่าน `jira-req-analysis` skill มาแล้ว จะมี structured data (User Stories, Screen List, State Matrix, Components, User Flow) พร้อมใช้ — ข้ามไป Step 2 ได้เลย
- **User บอกตรง** → ถามข้อมูลเพิ่มตามรายการด้านล่าง
- **Figma reference design** → ใช้ get_screenshot/get_design_context อ่าน

ถ้ายังไม่มี structured requirements ถามข้อมูลเหล่านี้:

- **Platform**: Mobile (iOS/Android), Web, Desktop, หรือ Cross-platform?
- **Screen/Component**: จะออกแบบหน้าจอหรือ component อะไร?
- **User Goal**: ผู้ใช้ต้องการทำอะไรบนหน้าจอนี้?
- **Detail Level**: ต้องการ Wireframe (Lo-fi) หรือ Hi-fi UI spec?
- **Design System**: ใช้ Material Design, HIG, หรือ custom design system?
- **Constraints**: มี brand guidelines, สี, font ที่กำหนดไว้ไหม?
- **Reference Design**: มี Figma URL ที่อยากให้ดูเป็น reference ไหม? (ใช้ get_screenshot/get_design_context อ่านได้)

---

## Step 2: อ่าน Design Principles

อ่าน reference files ตาม platform:

```
references/ux-principles.md        → อ่านเสมอ (Nielsen's + Laws of UX + Gestalt)
references/material-design.md      → สำหรับ Android / Web (Material Design 3)
references/hig.md                  → สำหรับ iOS / macOS (Apple HIG)
references/design-tokens.md        → สำหรับ Custom Design System tokens
```

อ่าน `references/ux-principles.md` **เสมอทุกครั้ง**
อ่าน `references/ui-preview-quality-rules.md` **เสมอทุกครั้ง** — กฎ Visual Design จาก Refactoring UI, Practical UI, Laws of UX, Don't Make Me Think

สำหรับ platform-specific:
- Android / Material → อ่านเพิ่ม `references/material-design.md`
- iOS / Apple → อ่านเพิ่ม `references/hig.md`
- Cross-platform → อ่านทั้งสองไฟล์

ถ้าผู้ใช้มี reference design URL:
- ใช้ `get_screenshot(fileKey, nodeId)` เพื่อดู visual
- ใช้ `get_design_context(fileKey, nodeId)` เพื่ออ่าน design details
- ใช้ `get_metadata(fileKey, nodeId)` เพื่อดู structure

---

## Step 3: สร้าง Interactive Preview (Static HTML)

สร้างไฟล์ `.html` self-contained ที่เปิดใน browser ได้ทันที เพื่อให้ผู้ใช้เห็นหน้าตาก่อน import เข้า Figma

### Preview ต้องมี:

1. **iPhone/Android frame** จำลอง (เช่น 393x852 สำหรับ iPhone 15 Pro) — CSS-only
2. **Status bar** จำลอง (เวลา, battery, signal) — HTML+CSS
3. **ทุก component** ตาม spec — สีจาก Design Tokens (CSS Variables)
4. **Light/Dark mode toggle** สลับ theme ได้ (vanilla JS)
5. **State switcher** — ปุ่มเปลี่ยน state: empty, filled, error, loading, success (vanilla JS)
6. **Interactive elements** — กรอก input, กดปุ่ม ดู state จริง (vanilla JS)
7. **Spec info panel** — แสดงค่าสำคัญ (frame size, font, spacing, colors)

### HTML Template:

```html
<!DOCTYPE html>
<html lang="th">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[Screen Name] Preview</title>
  <link href="https://fonts.googleapis.com/css2?family=LINE+Seed+Sans+TH:wght@400;700;800&display=swap" rel="stylesheet">
  <style>
    :root {
      /* Design Tokens — จาก semantic system (references/design-tokens.md) */
      --primary-fg-high: #EC599D;
      --primary-fg-low: #FDEFF5;
      --primary-bg-mid: #EC599D;
      --primary-bg-low: #FBD5E5;
      --primary-bg-lowest: #FDEFF5;
      --secondary-fg-high: #7279FB;
      --secondary-bg-mid: #7279FB;
      --secondary-bg-lowest: #EEEFFE;
      --gray-fg-high: #1B1D22;
      --gray-fg-mid-on-white: #6A6E83;
      --gray-fg-mid-on-gray: #3F414E;
      --gray-fg-low: #9A9DAD;
      --gray-fg-white: #FFFFFF;
      --gray-bg-white: #FFFFFF;
      --gray-bg-lightgray: #F8F8F9;
      --gray-bg-midgray: #EBECEF;
      --gray-bg-darkgray: #CFD1D9;
      --gray-bg-black: #1B1D22;
      --gray-border-midgray: #EBECEF;
      --gray-border-darkgray: #CFD1D9;
      --error-fg-high: #EA244F;
      --error-bg-lowest: #FDECF0;
      --warning-fg-high: #F8C135;
      --warning-bg-lowest: #FEF8E8;
      --success-fg-high: #559652;
      --success-bg-lowest: #EEF6EE;
      --info-fg-high: #0386B3;
      --info-bg-lowest: #E6F4F9;

      /* Typography — LINE Seed Sans TH (ตรงกับ Figma Text Styles) */
      --font-family: 'LINE Seed Sans TH', sans-serif;
      --heading-1: 800 48px/58px var(--font-family);   /* Heading.1 */
      --heading-2: 700 40px/52px var(--font-family);   /* Heading.2 */
      --heading-3: 700 32px/40px var(--font-family);   /* Heading.3 */
      --heading-4: 700 28px/36px var(--font-family);   /* Heading.4 */
      --heading-5: 700 24px/32px var(--font-family);   /* Heading.5 */
      --label-1: 700 20px/28px var(--font-family);     /* Label.1 */
      --label-2: 700 18px/26px var(--font-family);     /* Label.2 */
      --label-3: 700 16px/24px var(--font-family);     /* Label.3 */
      --label-4: 700 14px/22px var(--font-family);     /* Label.4 */
      --label-5: 700 12px/20px var(--font-family);     /* Label.5 */
      --caption-1: 400 20px/36px var(--font-family);   /* Caption.1 */
      --caption-2: 400 18px/26px var(--font-family);   /* Caption.2 */
      --caption-3: 400 16px/24px var(--font-family);   /* Caption.3 */
      --caption-4: 400 14px/22px var(--font-family);   /* Caption.4 */
      --caption-5: 400 12px/20px var(--font-family);   /* Caption.5 */

      /* Spacing */
      --space-xs: 4px;
      --space-sm: 8px;
      --space-md: 12px;
      --space-lg: 16px;
      --space-xl: 20px;
      --space-2xl: 24px;
      --space-3xl: 32px;

      /* Shape */
      --radius-sm: 8px;
      --radius-md: 12px;
      --radius-lg: 16px;
      --radius-full: 9999px;
    }

    * { margin: 0; padding: 0; box-sizing: border-box; }
    body { font-family: var(--font-family); background: #E5E5E5; display: flex; justify-content: center; padding: 20px; }

    /* ใช้ flexbox layout (ไม่ใช้ absolute positioning) */
    /* ใช้ semantic HTML: header, main, nav, section, footer */
    /* Class names ตั้งชื่อมีความหมาย (จะกลายเป็น Figma layer names) */
  </style>
</head>
<body>
  <!-- Phone Frame -->
  <div class="phone-frame" style="width:393px; min-height:852px; background:var(--gray-bg-white); border-radius:40px; overflow:hidden; box-shadow:0 8px 32px rgba(0,0,0,0.12); display:flex; flex-direction:column;">
    <!-- Status Bar -->
    <div class="status-bar" style="display:flex; justify-content:space-between; align-items:center; padding:12px 24px; font:var(--caption-4); color:var(--gray-fg-high);">
      <span>9:41</span>
      <span><!-- signal + wifi + battery icons --></span>
    </div>

    <!-- Main Content -->
    <main style="flex:1; display:flex; flex-direction:column; padding:0 var(--space-lg);">
      <!-- Content here -->
    </main>
  </div>

  <!-- Control Panel (outside phone frame) -->
  <div class="control-panel" style="margin-left:24px; padding:16px; background:white; border-radius:12px; height:fit-content;">
    <button onclick="toggleTheme()">Light/Dark</button>
    <button onclick="setState('default')">Default</button>
    <button onclick="setState('filled')">Filled</button>
    <button onclick="setState('error')">Error</button>
    <button onclick="setState('loading')">Loading</button>
    <button onclick="setState('success')">Success</button>
    <button onclick="setState('empty')">Empty</button>
  </div>

  <script>
    // Vanilla JS สำหรับ toggle, state switch, interactions
    let currentTheme = 'light';
    let currentState = 'default';

    function toggleTheme() {
      currentTheme = currentTheme === 'light' ? 'dark' : 'light';
      document.body.setAttribute('data-theme', currentTheme);
      // Update CSS variables for dark mode
    }

    function setState(state) {
      currentState = state;
      document.querySelectorAll('[data-state]').forEach(el => {
        el.style.display = el.dataset.state === state ? '' : 'none';
      });
    }
  </script>
</body>
</html>
```

### Preview Quality Rules (บังคับ — จาก references/ui-preview-quality-rules.md):

**Visual Hierarchy:**
- De-emphasize ตัวรอง (ลด weight/color) สำคัญกว่า emphasize ตัวหลัก
- 3 ระดับ hierarchy เพียงพอ — Primary, Secondary, Tertiary
- CTA ต้อง pop ออกมาจากรอบข้าง (Von Restorff Effect)

**Color:**
- Near-black/near-white แทน pure #000/#FFF (เช่น #1B1D22 แทน #000)
- 60-30-10 ratio: neutral 60%, secondary 30%, accent 10%
- Neutral greys ควรมี subtle warm/cool hue shift

**Typography:**
- Line-height สัมพันธ์กับ size — text ใหญ่ = line-height ต่ำลง
- ห้ามลด contrast เพื่อ de-emphasize — ใช้ size/weight เล็กลงแทน
- Line length 60-80 chars (ใช้ max-width ช่วย)

**Spacing:**
- เริ่มจาก space มากไป แล้วค่อยลด
- Outer padding >= Inner padding เสมอ
- ห้ามมี ambiguous spacing — ต้องชัดว่า element ไหนกลุ่มเดียวกัน

**Shadows:**
- Shadow blur = 2x distance (offset-y: 4px → blur: 8px)
- แสงมาทิศเดียวทั้งหน้า
- ไม่ใช้ shadow ใน dark mode

**Borders:**
- ใช้ border น้อยลง — แทนด้วย shadow, background contrast, spacing
- ห้าม adjacent hard divides ซ้อนกัน

**Buttons:**
- Horizontal padding = 2x Vertical padding (เช่น padding: 12px 24px)
- Primary (solid) > Secondary (outlined) > Tertiary (text only)

**Corner Radius:**
- Nested radius = outer radius - gap (เช่น outer 16px, gap 8px → inner 8px)

**Components:**
- Empty state ห้ามปล่อยว่าง — ต้องมี status + learning cue + action
- Form labels เห็นตลอด — ห้ามใช้ placeholder แทน label
- Error = adjacent to input + icon + problem + solution
- Toggle = immediate effect (ไม่ต้องกด Save)

### Guidelines สำหรับ HTML Preview:

- ใช้ **CSS Variables** ตาม Design Tokens (`references/design-tokens.md`) — ห้าม hardcode สีตรง
- ใช้ **flexbox/grid** layout (ไม่ใช้ absolute position) → จะกลายเป็น Auto Layout ใน Figma
- ตั้ง **class names** ให้มีความหมาย → จะกลายเป็น Figma layer names
- ใช้ **semantic HTML**: `<header>`, `<main>`, `<nav>`, `<section>`, `<footer>`
- ใช้ **Google Fonts** (LINE Seed Sans TH) — load ผ่าน `<link>`
- ใช้ **inline SVG** หรือ placeholder สำหรับ icons/images
- **ห้ามใช้** external CSS frameworks (Bootstrap, Tailwind) — ใช้ CSS ตรงๆ
- **ห้ามใช้** React, Vue, หรือ JS framework ใดๆ — ใช้ vanilla JS เท่านั้น
- Animation ใช้ **CSS keyframes** ใน `<style>` tag
- Keep DOM structure clean → clean Figma layer hierarchy

### HTML Best Practices สำหรับ HTML to Figma:

| HTML/CSS | Figma Result |
|----------|-------------|
| `display: flex` | Auto Layout |
| `flex-direction: column` | Vertical Auto Layout |
| `gap: 16px` | Item Spacing = 16 |
| `padding: 16px` | Padding = 16 |
| `border-radius: 12px` | Corner Radius = 12 |
| `width: 100%` (ใน flex child) | Layout Sizing = Fill |
| Class name (เช่น `login-button`) | Layer name = "login-button" |
| Nested `<div>` | Nested frames |

### ตั้งชื่อไฟล์: `[screen-name]-preview.html`

---

## Step 4: Iterate จนพอใจ (Browser + Claude)

1. **User เปิด `.html` ใน browser** — double-click ไฟล์ หรือใช้ Live Preview ใน VSCode
2. **User ดูผล** แล้วบอก Claude ให้แก้ไข (เช่น "ปรับสีปุ่มเป็นสีเขียว", "เพิ่ม padding", "เปลี่ยน layout")
3. **Claude แก้ไฟล์ `.html`** → User refresh browser เห็นผลทันที
4. **วนจนพอใจ** — ปรับ layout, สี, ขนาด, spacing, state ต่างๆ
5. เมื่อพอใจแล้ว ถามผู้ใช้: "พร้อม import เข้า Figma ไหมครับ?"

---

## Step 5: QA Gate — ตรวจคุณภาพก่อนส่งมอบ

> **Pipeline**: `Jira BA` → `IA + User Flow` → `UI Design` → **QA Gate** → ส่งมอบ

เมื่อ user พอใจกับ HTML preview แล้ว **ต้องผ่าน QA Gate ก่อน import เข้า Figma**:

1. ใช้ **html-qa-gate** skill ตรวจ HTML file
2. ตรวจ 5 หมวด: Color, Accessibility, Navigation, Sizing, Spacing
3. ถ้าเจอ issues → auto-fix + วนตรวจ (max 3 รอบ)
4. ถ้าผ่าน → ถามว่าพร้อม import เข้า Figma ไหม
5. ถ้าไม่ผ่านหลัง 3 รอบ → แสดง report ให้ user ตัดสินใจ

> "ก่อน import เข้า Figma ขอตรวจคุณภาพ HTML ก่อนนะครับ — เช็ค Color, Accessibility, Sizing, Spacing"

---

## Step 6: Import เข้า Figma (HTML to Figma MCP)

เมื่อผู้ใช้พอใจกับ HTML preview แล้ว ใช้ **html-to-design MCP** ส่ง HTML ไป Figma โดยตรง

### 5.1 เตรียมตัว

1. ตรวจว่า user เปิด **html.to.design** plugin ใน Figma → tab **MCP** → toggle **"Enable MCP endpoint"** เปิดอยู่ (STATUS: connected)
2. ตรวจว่า HTML file พร้อม import:
   - ใช้ flexbox/grid (ไม่ใช้ absolute position)
   - Class names มีความหมาย
   - สีใช้ CSS Variables
   - DOM structure clean

### 5.2 Import ผ่าน MCP

ใช้ `import_html` ส่ง HTML ไป Figma โดยตรง:

```
import_html({
  html: "<div class='login-screen'>...</div>",
  css: ".login-screen { display: flex; ... }",
  name: "Login Screen"
})
```

หรือถ้า HTML ซับซ้อน/มี external assets ให้ serve file แล้วใช้ `import_url`:

```
import_url({
  url: "http://localhost:3000/login-preview.html",
  name: "Login Screen"
})
```

Plugin แปลง HTML → Figma layers:
- `display: flex` → Auto Layout
- `gap` → Item Spacing
- `padding` → Padding
- `border-radius` → Corner Radius
- Class names → Layer names
- Colors → Fill colors
- Text → Text nodes with font size/weight

### 5.3 Fine-tune ใน Figma

หลัง import:
1. ตรวจ Auto Layout structure — อาจต้องปรับ sizing mode (FILL/HUG/FIXED)
2. ตรวจ font — อาจต้องเปลี่ยนเป็น LINE Seed Sans TH ใน Figma
3. ตรวจ colors — ควรตรงกับ HTML preview
4. ปรับ layer names ถ้าต้องการ
5. เพิ่ม components, variants, styles ตามต้องการ

---

## Output Files

Skill นี้สร้าง output ได้หลายแบบ ขึ้นกับ step ที่อยู่:

| Step | Output | Format |
|------|--------|--------|
| 3 | Interactive Preview | `.html` (Static HTML — เปิดใน browser) |
| 3 | Design Spec Document | `.md` (optional, ถ้าผู้ใช้ขอ) |
| 5 | Figma Design | Import ผ่าน html-to-design MCP (`import_html` / `import_url`) |

---

## Design Spec Templates

ถ้าผู้ใช้ต้องการเอกสาร spec เพิ่มจาก preview ให้สร้าง `.md` ตาม template:

### Wireframe (Lo-fi) Template

```markdown
# [Screen Name] — Wireframe Specification

## 1. Overview
## 2. Layout Structure (with ASCII wireframe)
## 3. Component List (table)
## 4. Navigation Flow
## 5. UX Principles Applied (table with principle + rationale)
## 6. Notes for Figma Implementation
```

### Hi-fi Template

ใช้ Wireframe template + เพิ่ม:

```markdown
## 7. Visual Design (Colors, Typography, Spacing, Elevation)
## 8. Design Tokens (ถ้าใช้ custom design system)
## 9. Component Specifications (ทุก state: default, hover, pressed, focused, disabled, error)
## 10. Accessibility (contrast, touch targets, VoiceOver/TalkBack labels)
## 11. Responsive Behavior
## 12. Motion & Haptic (iOS)
```

---

## WCAG Color Contrast Checker (บังคับ)

ทุกครั้งที่เลือกสี **ต้องตรวจสอบ WCAG Color Contrast** ก่อนใช้งาน:

### เกณฑ์ที่ต้องผ่าน (WCAG 2.1)

| ประเภท | AA (ขั้นต่ำ) | AAA (แนะนำ) |
|--------|-------------|-------------|
| Normal text (< 18pt) | 4.5:1 | 7:1 |
| Large text (>= 18pt bold / >= 24pt regular) | 3:1 | 4.5:1 |
| UI components & icons | 3:1 | — |

### วิธีคำนวณ Contrast Ratio

ใช้สูตร relative luminance ในการคำนวณ:

```
Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)
โดย L1 = luminance ของสีที่สว่างกว่า, L2 = luminance ของสีที่มืดกว่า

Relative Luminance = 0.2126 * R + 0.7152 * G + 0.0722 * B
โดย R, G, B ผ่าน linearization:
  - ถ้า sRGB <= 0.03928 → linear = sRGB / 12.92
  - ถ้า sRGB > 0.03928 → linear = ((sRGB + 0.055) / 1.055) ^ 2.4
```

### ขั้นตอนการตรวจสอบ (ทำทุกครั้ง)

1. **ก่อนเลือกสี**: คำนวณ contrast ratio ระหว่าง text color กับ background color
2. **ระบุค่า contrast ratio** ใน spec เสมอ เช่น: `#F0E8FF on #0D0A14 → 15.2:1 ✅ AAA`
3. **ถ้าไม่ผ่าน AA**: ปรับสีให้ผ่านก่อนใช้ — ห้ามใช้สีที่ไม่ผ่านเกณฑ์
4. **สรุปตาราง contrast** ไว้ใน preview spec info panel

### ตัวอย่างการตรวจสอบ

```
✅ ผ่าน:
  #F0E8FF on #0D0A14 → 15.2:1 (AAA) — primary text on dark bg
  #4ADE80 on #0D2818 → 6.8:1 (AA)  — positive text on green bg

❌ ไม่ผ่าน:
  #7E6E98 on #1E1830 → 2.8:1 (FAIL) — ต้องปรับให้สว่างขึ้น
```

### ใช้กับทุก color pair ที่สำคัญ:

- Text on background (ทุก text level: primary, secondary, tertiary)
- Text on card surfaces
- Text on colored sections (DO/DON'T cards, alerts)
- Icon on background
- Button text on button background
- Placeholder text on input background

---

## หลักการสำคัญ

1. **เจาะจงและวัดผลได้**: ระบุค่าได้ตัวเลขเสมอ (px, dp, pt, hex color)
2. **อ้างอิง Design Principle**: ทุกการตัดสินใจต้องมีเหตุผลหลักการ
3. **Edge Cases**: empty, loading, error, long text, no data
4. **Accessibility First**: contrast ratio, touch target, screen reader
5. **WCAG Contrast Verified**: ทุกคู่สี text/bg ต้องผ่าน WCAG AA ขั้นต่ำ พร้อมระบุค่า ratio
6. **Platform-Aware**: เคารพ platform conventions
7. **Preview First**: ให้ดู HTML preview ใน browser ก่อน import เข้า Figma เสมอ
8. **Figma-Ready HTML**: ใช้ flexbox/grid, class names มีความหมาย, CSS Variables ตาม tokens
9. **HTML to Figma MCP**: ใช้ html-to-design MCP (`import_html` / `import_url`) ส่ง HTML ไป Figma โดยตรง
10. **Font ตั้งใน HTML**: ใช้ Google Fonts (LINE Seed Sans TH) — font อาจต้องปรับหลัง import Figma

---
name: figma-design-critique
description: "วิเคราะห์และ review design ที่มีอยู่แล้ว ให้ feedback ตาม UX principles, ให้คะแนน, ระบุจุดแข็ง/จุดอ่อน, เสนอ improvement ใช้ skill นี้เมื่อผู้ใช้ต้องการ: review design, วิเคราะห์ UI, critique หน้าจอ, ตรวจ design, ให้ feedback design, design audit, UX review, หรือเมื่อพิมพ์ 'review', 'critique', 'วิเคราะห์ design', 'ตรวจ UI', 'ให้ feedback', 'design review', 'UX audit'"
---

# Design Critique / Review Skill

วิเคราะห์ design ที่มีอยู่อย่างเป็นระบบ ให้ feedback เชิงลึกตาม UX principles พร้อมเสนอ improvement ที่ทำได้จริง

---

## Workflow Diagram

```
╔═══════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                                 ║
║                              DESIGN   CRITIQUE   PIPELINE                                       ║
║                                                                                                 ║
║                        สำหรับ Designer — Review ➜ Report ➜ Fix ➜ Annotate                        ║
║                                                                                                 ║
╚═══════════════════════════════════════════════════════════════════════════════════════════════════╝


         ╔═══════════════════════════════════════════════════════════════════╗
         ║                                                                 ║
         ║                        1 ·  รับ DESIGN                          ║
         ║                                                                 ║
         ║       Designer ส่ง design มาให้ review ได้ 4 ทาง                  ║
         ║                                                                 ║
         ║   ┌─────────────┐  ┌─────────────┐  ┌──────────┐  ┌─────────┐  ║
         ║   │             │  │             │  │          │  │         │  ║
         ║   │  Figma URL  │  │  เลือก Node │  │  HTML    │  │  รูป    │  ║
         ║   │  (link)     │  │  ใน Figma   │  │  Preview │  │  ภาพหน้า │  ║
         ║   │             │  │  Desktop    │  │  (.html) │  │  จอ     │  ║
         ║   │             │  │             │  │          │  │         │  ║
         ║   └──────┬──────┘  └──────┬──────┘  └────┬─────┘  └────┬────┘  ║
         ║          │                │               │             │       ║
         ╚══════════╪════════════════╪═══════════════╪═════════════╪═══════╝
                    │                │               │             │
                    └────────────────┴───────┬───────┴─────────────┘
                                             │
                                             ▼
         ╔═══════════════════════════════════════════════════════════════════╗
         ║                                                                 ║
         ║                     2 ·  อ่าน DESIGN PRINCIPLES                 ║
         ║                                                                 ║
         ║   ┌──────────────────────────────────────────────────────────┐   ║
         ║   │                                                          │   ║
         ║   │     UX Principles         Platform Guide     Tokens     │   ║
         ║   │   ┌──────────────┐     ┌──────────────┐   ┌─────────┐  │   ║
         ║   │   │ Nielsen's 10 │     │  Apple HIG   │   │ Colors  │  │   ║
         ║   │   │ Laws of UX   │     │  Material 3  │   │ Typo    │  │   ║
         ║   │   │ Gestalt      │     │  (ตาม target │   │ Spacing │  │   ║
         ║   │   │              │     │   platform)  │   │ Radius  │  │   ║
         ║   │   │  อ่านเสมอ     │     │              │   │ Shadow  │  │   ║
         ║   │   └──────────────┘     └──────────────┘   └─────────┘  │   ║
         ║   │                                                          │   ║
         ║   └──────────────────────────────────────────────────────────┘   ║
         ║                                                                 ║
         ╚════════════════════════════════╤════════════════════════════════╝
                                          │
                                          ▼
         ╔═══════════════════════════════════════════════════════════════════╗
         ║                                                                 ║
         ║                    3 ·  วิเคราะห์ 8 มิติ                         ║
         ║                                                                 ║
         ║   ┌───────────────────────────────────────────────────────────┐  ║
         ║   │                                                           │  ║
         ║   │   ┌──────────────────┐     ┌──────────────────┐          │  ║
         ║   │   │  Visual          │     │  Typography      │          │  ║
         ║   │   │  Hierarchy       │     │                  │          │  ║
         ║   │   │  & Layout        │     │  Scale, Weight,  │          │  ║
         ║   │   │                  │     │  Family,         │          │  ║
         ║   │   │  ■ hierarchy     │     │  Line-height     │          │  ║
         ║   │   │  ■ alignment     │     │                  │          │  ║
         ║   │   │  ■ whitespace    │     │  10%             │          │  ║
         ║   │   │  ■ gestalt       │     │                  │          │  ║
         ║   │   │                  │     └──────────────────┘          │  ║
         ║   │   │  15%             │                                   │  ║
         ║   │   └──────────────────┘     ┌──────────────────┐          │  ║
         ║   │                            │  Component       │          │  ║
         ║   │   ┌──────────────────┐     │  Design          │          │  ║
         ║   │   │  Color &         │     │                  │          │  ║
         ║   │   │  Contrast        │     │  ■ conventions   │          │  ║
         ║   │   │                  │     │  ■ btn hierarchy │          │  ║
         ║   │   │  ■ WCAG AA/AAA  │     │  ■ input states  │          │  ║
         ║   │   │  ■ semantic      │     │  ■ affordance    │          │  ║
         ║   │   │  ■ palette       │     │                  │          │  ║
         ║   │   │  ■ dark mode     │     │  15%             │          │  ║
         ║   │   │                  │     └──────────────────┘          │  ║
         ║   │   │  15%             │                                   │  ║
         ║   │   └──────────────────┘     ┌──────────────────┐          │  ║
         ║   │                            │  UX Heuristics   │          │  ║
         ║   │   ┌──────────────────┐     │  (Nielsen's 10)  │          │  ║
         ║   │   │  Spacing &       │     │                  │          │  ║
         ║   │   │  Consistency     │     │  H1  Status      │          │  ║
         ║   │   │                  │     │  H2  Real World  │          │  ║
         ║   │   │  ■ 4px grid      │     │  H3  Control     │          │  ║
         ║   │   │  ■ token match   │     │  H4  Consistency │          │  ║
         ║   │   │  ■ padding       │     │  H5  Prevention  │          │  ║
         ║   │   │                  │     │  H6  Recognition │          │  ║
         ║   │   │  10%             │     │  H7  Flexibility │          │  ║
         ║   │   └──────────────────┘     │  H8  Minimalist  │          │  ║
         ║   │                            │  H9  Recovery    │          │  ║
         ║   │   ┌──────────────────┐     │  H10 Help        │          │  ║
         ║   │   │  Accessibility   │     │                  │          │  ║
         ║   │   │                  │     │  20%             │          │  ║
         ║   │   │  ■ touch 44pt+   │     └──────────────────┘          │  ║
         ║   │   │  ■ color-blind   │                                   │  ║
         ║   │   │  ■ screen reader │     ┌──────────────────┐          │  ║
         ║   │   │  ■ contrast      │     │  Edge Cases      │          │  ║
         ║   │   │                  │     │                  │          │  ║
         ║   │   │  10%             │     │  ■ empty state   │          │  ║
         ║   │   └──────────────────┘     │  ■ loading       │          │  ║
         ║   │                            │  ■ error state   │          │  ║
         ║   │                            │  ■ overflow      │          │  ║
         ║   │                            │                  │          │  ║
         ║   │                            │  5%              │          │  ║
         ║   │                            └──────────────────┘          │  ║
         ║   │                                                           │  ║
         ║   └───────────────────────────────────────────────────────────┘  ║
         ║                                                                 ║
         ╚════════════════════════════════╤════════════════════════════════╝
                                          │
                                          ▼
         ╔═══════════════════════════════════════════════════════════════════╗
         ║                                                                 ║
         ║                      4 ·  ให้คะแนน                              ║
         ║                                                                 ║
         ║   ┌───────────────────────────────────────────────────────────┐  ║
         ║   │                                                           │  ║
         ║   │   Weighted Score =  ผลรวม (คะแนนมิติ × น้ำหนัก%)          │  ║
         ║   │                                                           │  ║
         ║   │   9-10         7-8          5-6           3-4       1-2   │  ║
         ║   │   ██████████   ████████     ██████████    ████████  ████  │  ║
         ║   │   World-class  ดี            ปานกลาง       ปรับปรุง   redo  │  ║
         ║   │   ไม่ต้องแก้    minor fix    แก้หลายจุด     พื้นฐานผิด       │  ║
         ║   │                                                           │  ║
         ║   │   แยก Issues เป็น 3 กลุ่ม:                                 │  ║
         ║   │                                                           │  ║
         ║   │   🔴 Critical      🟡 Major         🟣 Minor             │  ║
         ║   │   ต้องแก้ทันที       ควรแก้            แก้ได้ก็ดี            │  ║
         ║   │   contrast fail    touch target     token mismatch      │  ║
         ║   │   a11y broken      inconsistency    spacing off-grid    │  ║
         ║   │                                                           │  ║
         ║   └───────────────────────────────────────────────────────────┘  ║
         ║                                                                 ║
         ╚════════════════════════════════╤════════════════════════════════╝
                                          │
                                          ▼
         ╔═══════════════════════════════════════════════════════════════════╗
         ║                                                                 ║
         ║                 5 ·  สร้าง REVIEW NOTES (.html)                  ║
         ║                                                                 ║
         ║   ┌───────────────────────────────────────────────────────────┐  ║
         ║   │                                                           │  ║
         ║   │                    review-notes.html                      │  ║
         ║   │                                                           │  ║
         ║   │   ┌───────────────────────────────────────────────────┐   │  ║
         ║   │   │  🏆  HERO                                        │   │  ║
         ║   │   │      Overall Score  ·  Critical  ·  Major  ·  Minor │  ║
         ║   │   ├───────────────────────────────────────────────────┤   │  ║
         ║   │   │  📋  สารบัญ — กดชื่อ issue แล้วข้ามไปได้เลย        │   │  ║
         ║   │   ├───────────────────────────────────────────────────┤   │  ║
         ║   │   │                                                   │   │  ║
         ║   │   │  🔴 CRITICAL                                     │   │  ║
         ║   │   │  🟡 MAJOR           ┌──── Issue Card ────────┐   │   │  ║
         ║   │   │  🟣 MINOR           │                        │   │   ║
         ║   │   │                      │  ① WHERE              │   │   ║
         ║   │   │   ทุก issue          │     mockup + วงกลม     │   │   ║
         ║   │   │   ใช้โครงสร้าง ──────│     ชี้จุดที่มีปัญหา     │   │   ║
         ║   │   │   เดียวกัน           │                        │   │   ║
         ║   │   │                      │  ② VISUAL ก่อน/หลัง     │   │   ║
         ║   │   │                      │     เห็นสี ขนาดจริง     │   │   ║
         ║   │   │                      │     contrast ratio     │   │   ║
         ║   │   │                      │                        │   │   ║
         ║   │   │                      │  ③ FIX GUIDE           │   │   ║
         ║   │   │                      │     ขั้นตอนแก้ไข        │   │   ║
         ║   │   │                      │     ค่าเก่า → ค่าใหม่   │   │   ║
         ║   │   │                      │     token ที่ถูกต้อง    │   │   ║
         ║   │   │                      │                        │   │   ║
         ║   │   │                      └────────────────────────┘   │   ║
         ║   │   │                                                   │   ║
         ║   │   ├───────────────────────────────────────────────────┤   │  ║
         ║   │   │  👁  CONTRAST AUDIT — ตารางทุกคู่สี + ผ่าน/ไม่ผ่าน │   │  ║
         ║   │   ├───────────────────────────────────────────────────┤   │  ║
         ║   │   │  🎨  TOKEN ใหม่ที่ต้องเพิ่ม (ถ้ามี)                │   │  ║
         ║   │   ├───────────────────────────────────────────────────┤   │  ║
         ║   │   │  ✅  CHECKLIST สรุป — ทุก issue เรียงตาม priority  │   │  ║
         ║   │   └───────────────────────────────────────────────────┘   │  ║
         ║   │                                                           │  ║
         ║   └───────────────────────────────────────────────────────────┘  ║
         ║                                                                 ║
         ╚════════════════════════════════╤════════════════════════════════╝
                                          │
                            ┌─────────────┴──────────────┐
                            │                            │
                            ▼                            ▼
         ╔══════════════════════════════╗  ╔══════════════════════════════════╗
         ║                              ║  ║                                  ║
         ║     6 ·  แก้ไข DESIGN        ║  ║   7 ·  แปะลงบน FIGMA (Future)    ║
         ║         (Optional)           ║  ║                                  ║
         ║                              ║  ║                                  ║
         ║   Designer เปิด Figma        ║  ║   ┌──────────────────────────┐   ║
         ║   แก้ตาม Fix Guide:          ║  ║   │                          │   ║
         ║                              ║  ║   │  ทุก issue ที่พบ:         │   ║
         ║   ■ เปลี่ยนสี                ║  ║   │                          │   ║
         ║     (contrast ไม่ผ่าน)       ║  ║   │  📌  Annotation          │   ║
         ║                              ║  ║   │      ปักหมุดบน node      │   ║
         ║   ■ ปรับขนาด                 ║  ║   │      ที่มีปัญหา           │   ║
         ║     (touch target เล็ก)      ║  ║   │                          │   ║
         ║                              ║  ║   │  🔗  Figma Deep Link     │   ║
         ║   ■ แก้ spacing              ║  ║   │      link ตรงไป node     │   ║
         ║     (หลุด grid)              ║  ║   │      figma.com/design/   │   ║
         ║                              ║  ║   │      ...?node-id=xxx     │   ║
         ║   ■ เปลี่ยน font size        ║  ║   │                          │   ║
         ║     (หลุด token)             ║  ║   │  📄  Link ไป HTML Notes  │   ║
         ║                              ║  ║   │      แปะ link review-    │   ║
         ║   ■ เปลี่ยน radius           ║  ║   │      notes.html ไว้ใน    │   ║
         ║     (ไม่ consistent)         ║  ║   │      Figma annotation    │   ║
         ║                              ║  ║   │                          │   ║
         ║                              ║  ║   │  📋  Review Frame        │   ║
         ║   หรือใช้ MCP แก้ให้:        ║  ║   │      สร้าง frame สรุป    │   ║
         ║                              ║  ║   │      ทุก issue ไว้ใน     │   ║
         ║   ■ set_fill_color           ║  ║   │      Figma file เดียวกัน  │   ║
         ║   ■ resize_node              ║  ║   │                          │   ║
         ║   ■ set_padding              ║  ║   └──────────────────────────┘   ║
         ║   ■ set_item_spacing         ║  ║                                  ║
         ║   ■ set_corner_radius        ║  ╚══════════════════════════════════╝
         ║   ■ set_text_content         ║
         ║   ■ move_node                ║
         ║   ■ set_annotation           ║
         ║                              ║
         ╚══════════════════════════════╝
                            │                            │
                            └─────────────┬──────────────┘
                                          │
                                          ▼
         ╔═══════════════════════════════════════════════════════════════════╗
         ║                                                                 ║
         ║                       OUTPUT ที่ได้                              ║
         ║                                                                 ║
         ║   ┌───────────────┐   ┌──────────────────┐   ┌──────────────┐  ║
         ║   │               │   │                  │   │              │  ║
         ║   │  📄  HTML     │   │  🎨  Figma ที่    │   │  📌  Figma   │  ║
         ║   │  Review       │   │  แก้แล้ว          │   │  Annotated  │  ║
         ║   │  Notes        │   │                  │   │              │  ║
         ║   │               │   │  (ถ้า Designer   │   │  Annotation  │  ║
         ║   │  ■ mockup     │   │   แก้ตาม guide)  │   │  + deep link │  ║
         ║   │  ■ visual B/A │   │                  │   │  ทุก node    │  ║
         ║   │  ■ fix guide  │   │                  │   │              │  ║
         ║   │  ■ contrast   │   │                  │   │  (Future)    │  ║
         ║   │  ■ checklist  │   │                  │   │              │  ║
         ║   │               │   │                  │   │              │  ║
         ║   └───────────────┘   └──────────────────┘   └──────────────┘  ║
         ║                                                                 ║
         ╚═══════════════════════════════════════════════════════════════════╝
```

### Flow สรุปสั้น

```
รับ Design ──▶ อ่าน Principles ──▶ วิเคราะห์ 8 มิติ ──▶ ให้คะแนน ──▶ สร้าง Review Notes
                                                                              │
                                                                ┌─────────────┴──────────────┐
                                                                ▼                            ▼
                                                          แก้ไข Design                แปะลง Figma
                                                          (Designer แก้เอง)            + Deep Link
                                                                                      (Future)
```

---

## Step 1: รับ Design

ถามผู้ใช้ (ถ้ายังไม่ได้ระบุ):

- **Source**: Figma URL, screenshot path, **HTML preview file (.html)**, หรือจะเลือกใน Figma ตอนนี้?
- **Context**: หน้าจอนี้ใช้ทำอะไร? target user เป็นใคร?
- **Platform**: Mobile (iOS/Android), Web, Desktop?
- **Scope**: Review ทั้งหน้า หรือเฉพาะบาง component?
- **Focus Area**: มีจุดที่กังวลเป็นพิเศษไหม?

### วิธีอ่าน Design:

**จาก Figma URL (Remote MCP):**
- get_screenshot → ดู visual
- get_design_context → อ่าน design details (สี, font, spacing)
- get_metadata → ดู structure
- get_variable_defs → ดู design tokens ที่ใช้

**จาก Figma Selection (TalkToFigma MCP):**
- read_my_design → อ่าน design ที่เลือกอยู่
- get_node_info → ดูรายละเอียด node
- scan_text_nodes → scan text ทั้งหมด
- scan_nodes_by_types → scan components ตาม type

**จาก HTML Preview File:**
- อ่านไฟล์ .html preview ด้วย Read tool
- วิเคราะห์ styles, layout, colors, typography จาก source
- ตรวจ contrast, spacing, consistency โดยตรง

---

## Step 2: อ่าน Design Principles

อ่าน reference files เหล่านี้ก่อนวิเคราะห์:

- `references/ux-principles.md` → Nielsen's Heuristics + Laws of UX + Gestalt **(อ่านเสมอ)**
- `references/ui-preview-quality-rules.md` → กฎ Visual Design จาก Refactoring UI, Practical UI **(อ่านเสมอ)**
- `references/visual-design-principles.md` → Visual Hierarchy, Color Theory, White Space **(อ่านเสมอ)**
- `references/material-design.md` → ถ้า Android/Web
- `references/hig.md` → ถ้า iOS/macOS
- `references/design-tokens.md` → ถ้ามี custom design system

---

## Step 3: วิเคราะห์ 8 มิติ

### 3.1 Visual Hierarchy & Layout (15%)
- มี clear hierarchy ไหม? (primary → secondary → tertiary)
- Information architecture เหมาะสมไหม?
- Alignment และ grid consistency
- White space usage — แน่นไปหรือโล่งไป?
- Gestalt principles: Proximity, Similarity, Continuity

### 3.2 Typography (10%)
- Type scale เหมาะสมไหม? (ใช้กี่ขนาด, มี hierarchy ชัดเจนไหม)
- Font weight contrast เพียงพอไหม?
- Line height / letter spacing อ่านสบายไหม?
- จำนวน font families (ยิ่งน้อยยิ่งดี, ไม่ควรเกิน 2)

### 3.3 Color & Contrast (15%)
- **WCAG Contrast Check** (บังคับ):
  - Normal text: ต้อง >= 4.5:1 (AA)
  - Large text (>= 18pt bold / >= 24pt regular): ต้อง >= 3:1
  - UI components: ต้อง >= 3:1
- Color palette consistency — ใช้กี่สี, มี system ไหม?
- Semantic color usage — error=red, success=green ถูกต้องไหม?
- Dark mode compatibility (ถ้ามี)

### 3.4 Component Design (15%)
- ปฏิบัติตาม platform conventions ไหม? (Jakob's Law)
- Button hierarchy ชัดเจนไหม? (primary, secondary, tertiary)
- Input fields มี label, placeholder, helper text, error state ครบไหม?
- Card/container design consistent ไหม?
- Interactive elements มี visual affordance ชัดเจนไหม?

### 3.5 Spacing & Consistency (10%)
- ใช้ spacing system (4px/8px grid) ไหม?
- Padding/margin consistent ทั้งหน้าจอไหม?
- Component spacing มี pattern ที่ชัดเจนไหม?

### 3.6 UX Heuristics — Nielsen's 10 (20%)
- H1: Visibility of System Status — มี feedback ครบไหม?
- H2: Match Real World — ใช้ภาษาผู้ใช้ไหม?
- H3: User Control — มีทางกลับ/undo ไหม?
- H4: Consistency — follow platform standards ไหม?
- H5: Error Prevention — ป้องกัน error ไหม?
- H6: Recognition > Recall — ข้อมูลเห็นได้ง่ายไหม?
- H7: Flexibility — รองรับ novice & expert ไหม?
- H8: Aesthetic & Minimalist — มีข้อมูลเกินไหม?
- H9: Error Recovery — error message ดีไหม?
- H10: Help & Documentation — มี guidance ไหม?

### 3.7 Accessibility (10%)
- Touch targets >= 44pt (iOS) / 48dp (Android)?
- Color not the only indicator?
- Screen reader friendly? (labels, roles)
- Sufficient contrast? (checked in 3.3)

### 3.8 Edge Cases (5%)
- Empty state มีไหม?
- Loading state มีไหม?
- Error state มีไหม?
- Long text / overflow handling?
- No data / no results state?

---

## Step 4: ให้คะแนน

### Scoring Matrix

| มิติ | Weight | คะแนน (1-10) | หมายเหตุ |
|------|--------|-------------|----------|
| Visual Hierarchy & Layout | 15% | — | — |
| Typography | 10% | — | — |
| Color & Contrast | 15% | — | — |
| Component Design | 15% | — | — |
| Spacing & Consistency | 10% | — | — |
| UX Heuristics | 20% | — | — |
| Accessibility | 10% | — | — |
| Edge Cases | 5% | — | — |
| **Weighted Total** | **100%** | **—/10** | — |

### Rating Scale
- **9-10**: World-class — ไม่ต้องแก้อะไร
- **7-8**: ดี — มี minor improvements
- **5-6**: ปานกลาง — ต้องแก้หลายจุด
- **3-4**: ต้องปรับปรุง — มีปัญหาพื้นฐาน
- **1-2**: ต้อง redesign — ปัญหาร้ายแรง

---

## Step 5: สร้าง Review Notes

### Output Format: HTML Review Notes (Preferred)

สร้างไฟล์ `review-notes.html` ใน folder เดียวกับไฟล์ที่ review

**สำคัญ: เป้าหมายคือ Designer อ่านแล้วแก้ได้เลย — ไม่ต้องดูโค้ด**

### โครงสร้าง review-notes.html

```
review-notes.html
├── HERO — Score overview (Overall, Critical, Major, Minor counts)
├── TABLE OF CONTENTS — กด link ไปแต่ละ issue ได้
├── CRITICAL ISSUES section
│   └── Issue Card (C1, C2, C3, ...)
│       ├── Header — Badge + ชื่อปัญหา + WCAG ratio
│       ├── WHERE — mini phone mockup + วงกลมชี้จุดที่มีปัญหา
│       │          + อธิบายว่า element อยู่ตรงไหนบนหน้าจอ
│       ├── VISUAL ก่อน/หลัง — เห็นสีจริง ขนาดจริง contrast ratio
│       │          + swatch สี + hex code + FAIL/PASS tag
│       └── FIX GUIDE — ขั้นตอนแก้ใน Figma / Design Tool
│                  + ค่าเก่า → ค่าใหม่ (เป็นภาษา design ไม่ใช่ code)
│                  + token ที่ถูกต้อง
├── MAJOR ISSUES section (same structure)
├── MINOR ISSUES section (same structure)
├── CONTRAST AUDIT TABLE — ตารางคู่สีทั้งหมด + preview box + ratio + pass/fail
├── NEW TOKENS section — token ใหม่ที่ต้องเพิ่ม (ถ้ามี) + swatch
└── SUMMARY CHECKLIST — grid สรุปทุก issue
```

### Issue Card — ต้องมีครบ 3 ส่วน:

1. **WHERE** (อยู่ตรงไหน?) — **ใช้รูปจริง (screenshot) แล้ว mark ลงบนรูปจริง**:
   - ก็อปรูป screenshot มาไว้ folder เดียวกับ HTML → `<img src="ชื่อไฟล์.png">`
   - ใช้ `sips -g pixelWidth -g pixelHeight` หาขนาดรูปก่อนคำนวณ % ตำแหน่ง
   - ใช้ CSS `position:relative` บน container + `position:absolute` + `%` วาง marker ลงบนรูป
   - Marker = div border สี + border-radius + label ID (C1, M1, m1) + pulse animation
   - สี marker: แดง (#EA244F) = Critical, เหลือง (#D4920A) = Major, ม่วง (#7279FB) = Minor
   - **ห้ามวาด CSS mockup ขึ้นมาใหม่** — ต้องใช้รูปจริงเท่านั้น
   - คำอธิบายว่า element อยู่ส่วนไหนของ UI
   - ระบุ section / component ที่เกี่ยวข้อง

2. **VISUAL ก่อน/หลัง** — ต้องมี:
   - Preview สีจริง / ขนาดจริง เทียบกัน ก่อน-หลังแก้
   - Contrast ratio tags (FAIL/PASS)
   - Swatch สีพร้อม hex code + ชื่อ token

3. **FIX GUIDE** (วิธีแก้สำหรับ Designer) — ต้องมี:
   - ขั้นตอนแก้ไขที่ Designer ทำตามได้ทันที
   - ใช้ภาษา design เช่น "เปลี่ยนสี fill เป็น #D14A8A" ไม่ใช่ภาษาโค้ด
   - ระบุค่าเก่า → ค่าใหม่ ชัดเจน (hex, px, token name)
   - ระบุ token ที่ถูกต้องตาม Design System

### Annotated Overview (ด้านบนสุดของ report):
- รูปจริงขนาด ~320px width พร้อม marker ทุกจุด (ทุก issue) ในภาพเดียว
- Legend ข้างรูป: รายชื่อทุก issue + คลิกข้ามไปอ่านรายละเอียดได้

### โทน Designer-Friendly:
- **ห้ามใช้โทนตรวจงาน/audit** — ใช้โทนเพื่อนร่วมงานแนะนำ
- Section headers: "จุดที่อยากให้ดูก่อน" / "ปรับแล้วดีขึ้นชัด" / "ถ้ามีเวลาลองปรับดู"
- ทุก issue เขียนแบบ "จะดีกว่าไหมถ้า..." + เหตุผล WHY ใน blockquote
- ไม่ใช่ "ต้องแก้ทันที" แต่เป็น "อยากให้ดูก่อนเลย เพราะ..."

### Styling Guidelines:
- ใช้ Design Tokens ของระบบเป็น CSS variables
- Critical = สีแดง (#EA244F), Major = สีเหลือง (#D4920A), Minor = สีม่วง (#7279FB)
- ก่อน/หลัง ใช้ card สองข้าง: ซ้ายพื้นแดงอ่อน (before), ขวาพื้นเขียวอ่อน (after)

---

## Step 6: แก้ไข Design (Optional)

ถ้าผู้ใช้ต้องการให้แก้ผ่าน MCP:

1. อ่าน `references/figma-mcp-commands.md`
2. แก้ไขตาม action items:
   - set_fill_color / set_stroke_color — แก้สีที่ contrast ไม่ผ่าน
   - set_corner_radius — แก้ radius ให้ consistent
   - set_text_content — แก้ copy/text
   - resize_node — แก้ขนาด touch targets
   - set_padding / set_item_spacing — แก้ spacing
   - move_node — แก้ alignment
3. ใช้ set_multiple_annotations ใส่ annotation อธิบายการแก้ไข
4. set_focus(nodeId) ให้ผู้ใช้ดูผลลัพธ์

---

## Step 7: แปะลง Figma + Deep Link (Future)

Workflow อนาคต — แปะ annotation พร้อม link กลับไปหา review notes:

**สำหรับทุก issue ที่พบ:**

1. **Annotation บน Node** — ใช้ set_annotation ปักหมุดบน node ที่มีปัญหา
   - label: "C1: Contrast ไม่ผ่าน"
   - description: อธิบายสั้นๆ + วิธีแก้

2. **Figma Deep Link** — สร้าง link ที่กดแล้วกระโดดตรงไป node นั้น
   - Format: `https://www.figma.com/design/{fileKey}?node-id={nodeId}`
   - แปะลิงก์นี้ลงใน review-notes.html แต่ละ issue card

3. **Link กลับไป HTML Notes** — ใน annotation ของ Figma แปะ link ไปหา
   review-notes.html section ที่เกี่ยวข้อง

4. **Review Summary Frame** — สร้าง frame ใน Figma file เดียวกัน
   สรุปทุก issue + score + checklist ให้ทีมดูใน Figma ได้เลย

---

## หลักการสำคัญ

1. **Objective First**: วิเคราะห์ตามหลักการ ไม่ใช่ความชอบส่วนตัว
2. **Evidence-Based**: ทุก feedback ต้องอ้างอิง principle + ให้ค่าตัวเลขได้
3. **Actionable**: ทุก issue ต้องมี recommendation ที่ทำได้จริง
4. **Balanced**: ชมจุดดีด้วย ไม่ใช่แค่จับผิด
5. **Prioritized**: แยก Critical / Major / Minor ชัดเจน
6. **WCAG Verified**: ตรวจ contrast ทุกคู่สีเสมอ
7. **Designer-Friendly**: Report อ่านง่าย ไม่มีโค้ด ใช้ภาษา design + visual

---
name: figma-user-flow
description: "ออกแบบ User Flow, Information Architecture, Task Flow, Screen Map สำหรับ app/web ทั้งระบบ สร้าง flow diagram ใน FigJam หรือ Figma ได้ ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ออกแบบ flow, สร้าง user journey, วาง IA, task flow, screen map, navigation structure, sitemap, wireflow, หรือเมื่อพิมพ์ 'user flow', 'flow', 'IA', 'information architecture', 'journey', 'sitemap', 'screen map', 'navigation', 'task flow'"
---

# User Flow / Information Architecture Skill

ออกแบบ User Flow และ Information Architecture สำหรับ app/web ทั้งระบบ — ไม่ใช่แค่หน้าจอเดียว แต่มองภาพรวมทั้ง journey

## Pipeline Position

```
Jira BA → [IA + User Flow] → UI Design → QA Gate → ส่งมอบ
                ▲ อยู่ตรงนี้
```

## Overall Flow

```
1. Requirements → 2. Read Principles → 3. Map IA → 4. Design Flows → 5. Generate Diagrams → 6. Build in Figma (Optional) → 7. ส่งต่อไป UI Design
```

1. **Requirements**: เข้าใจ product, users, features (หรือรับต่อจาก **jira-req-analysis** skill)
2. **Read Principles**: อ่าน UX + navigation patterns
3. **Map IA**: วาง Information Architecture
4. **Design Flows**: สร้าง user flows สำหรับ key tasks
5. **Generate Diagrams**: สร้าง diagram ใน FigJam/Figma
6. **Build in Figma**: สร้าง screen map ใน Figma (optional)
7. **ส่งต่อ**: ส่ง IA + Flows ไป **figma-ui-design-spec** skill เพื่อสร้าง HTML preview

---

## Step 1: รวบรวม Requirements

Requirements อาจมาจาก:
- **Jira BA analysis** → ถ้า user ผ่าน `jira-req-analysis` skill มาแล้ว จะมี structured data (User Stories, Screen List, State Matrix, Components, User Flow Summary, Edge Cases) พร้อมใช้ — ข้ามไปข้อมูลที่มีแล้ว ถามแค่ที่ขาด
- **User บอกตรง** → ถามข้อมูลเพิ่มตามรายการด้านล่าง

ถามข้อมูลเหล่านี้ (ถ้ายังไม่ได้ระบุ):

- **Product**: แอป/เว็บอะไร? ทำหน้าที่อะไร?
- **Target Users**: กลุ่มผู้ใช้หลัก (1-3 personas)
- **Platform**: Mobile (iOS/Android), Web, Desktop, Cross-platform?
- **Key Features**: features หลักที่ต้องมี (list ออกมา)
- **User Goals**: ผู้ใช้ต้องการทำอะไรสำเร็จ? (top 3-5 goals)
- **Scope**: ออกแบบทั้ง app หรือเฉพาะบาง module?
- **Reference**: มี app ที่คล้ายกันอยากให้ดูเป็น reference ไหม?
- **Existing Design**: มี Figma URL ของ design ที่มีอยู่แล้วไหม?

---

## Step 2: อ่าน Design Principles

อ่าน reference files:

```
references/ux-principles.md        → อ่านเสมอ (โดยเฉพาะ Hick's Law, Miller's Law, Jakob's Law)
references/material-design.md      → Navigation patterns สำหรับ Android/Web
references/hig.md                  → Navigation patterns สำหรับ iOS
```

### Navigation Patterns ที่ต้องรู้:

**iOS (HIG):**
- Tab Bar (3-5 items) + Navigation Stack — most common
- Sidebar (iPad) → Tab Bar (iPhone)
- Modal Sheets — focused tasks

**Android (Material):**
- Bottom Navigation (3-5 items) — compact
- Navigation Rail — medium screens
- Navigation Drawer — expanded screens

**Web:**
- Top Navigation Bar + Side Navigation
- Breadcrumbs for deep hierarchy
- Tab-based navigation for related content

---

## Step 3: Map Information Architecture

### 3.1 Feature Inventory

จัดกลุ่ม features เป็น categories:

```markdown
## Feature Inventory

| Category | Features | Priority |
|----------|----------|----------|
| Authentication | Login, Register, Forgot Password, Social Login | Must Have |
| Profile | View Profile, Edit Profile, Settings | Must Have |
| [Core Feature] | [list features] | Must Have |
| [Secondary] | [list features] | Should Have |
| [Nice-to-have] | [list features] | Could Have |
```

### 3.2 Content Model

กำหนด entities และ relationships:

```markdown
## Content Model

| Entity | Key Attributes | Relationships |
|--------|---------------|---------------|
| User | name, email, avatar, role | has many Posts, has many Orders |
| Product | title, price, image, category | belongs to Category, has many Reviews |
| Order | items, total, status, date | belongs to User, has many Products |
```

### 3.3 Site Map / Screen Map

จัด hierarchy ของ screens:

```markdown
## Screen Map

### Level 0: Entry
- Splash / Onboarding

### Level 1: Main Navigation (Tab Bar / Bottom Nav)
- Home (Tab 1)
- Search (Tab 2)
- [Core Feature] (Tab 3)
- Profile (Tab 4)

### Level 2: Sub-screens
- Home → Product Detail
- Home → Category List → Product List
- Search → Search Results → Product Detail
- Profile → Settings → Edit Profile
- Profile → Order History → Order Detail

### Level 3: Modals / Overlays
- Cart Sheet
- Filter Sheet
- Login Modal
```

### 3.4 Navigation Matrix

```markdown
## Navigation Matrix

| From \ To | Home | Search | Detail | Cart | Profile |
|-----------|------|--------|--------|------|---------|
| Home | — | Tab | Push | Sheet | Tab |
| Search | Tab | — | Push | Sheet | Tab |
| Detail | Back | — | — | Sheet | — |
| Cart | Dismiss | — | Push | — | — |
| Profile | Tab | Tab | — | — | — |

Transition types: Tab (tab switch), Push (nav push), Sheet (modal), Back (pop), Dismiss (close modal)
```

---

## Step 4: Design User Flows

### 4.1 Identify Key Flows

เลือก top 3-5 flows ที่สำคัญที่สุด:

```markdown
## Key User Flows

| # | Flow Name | User Goal | Priority | Complexity |
|---|-----------|-----------|----------|------------|
| 1 | Onboarding | สมัครและเริ่มใช้งาน | Critical | Medium |
| 2 | [Core Task] | [goal] | Critical | High |
| 3 | Purchase | ซื้อสินค้าสำเร็จ | Critical | High |
| 4 | Search & Filter | หาสิ่งที่ต้องการ | High | Medium |
| 5 | Account Management | จัดการบัญชี | Medium | Low |
```

### 4.2 Flow Diagram Format

แต่ละ flow ใช้ format นี้:

```markdown
### Flow: [Flow Name]

**User Goal**: [ผู้ใช้ต้องการทำอะไร]
**Entry Point**: [เข้ามาจากไหน]
**Success State**: [สำเร็จแล้วเห็นอะไร]
**Happy Path Steps**: [จำนวน steps]

#### Happy Path:
1. [Screen A] → User action: [action] →
2. [Screen B] → User action: [action] →
3. [Screen C] → Success ✓

#### Error/Alternative Paths:
- Step 2 error: [validation fail] → Show inline error → Retry
- Step 2 alternative: [ผู้ใช้กด back] → Return to Screen A
- Step 3 timeout: [network error] → Error state → Retry button

#### Decision Points:
- [Screen B]: if logged in → skip to Step 3; if not → show login modal
- [Screen C]: if first time → show tutorial; if returning → skip

#### Edge Cases:
- No network → Offline state with cached data
- Session expired → Re-auth modal
- Deep link entry → Skip to Step 2 with prefilled data
```

### 4.3 Flow Principles

ตรวจสอบทุก flow ด้วยหลักการ:

- **Hick's Law**: แต่ละ step มีตัวเลือกไม่เกิน 5-7
- **Miller's Law**: ข้อมูลต่อหน้าจอไม่เกิน 7±2 chunks
- **Doherty Threshold**: แต่ละ transition ต้อง < 400ms (perceived)
- **H1 - Visibility**: ผู้ใช้รู้ว่าอยู่ step ไหนของ flow
- **H3 - User Control**: ทุก step มีทางกลับ/undo
- **H5 - Error Prevention**: ป้องกัน error ก่อน submit

---

## Step 5: Generate Diagrams

### 5.1 สร้าง Flow Diagram (ใช้ Figma Remote MCP)

ใช้ `generate_diagram` สร้าง Mermaid.js diagram:

```
generate_diagram({
  name: "User Registration Flow",
  mermaidSyntax: 'flowchart LR\n  A["Splash Screen"] -->|"Tap Get Started"| B["Sign Up Form"]\n  B -->|"Fill & Submit"| C{"Valid?"}\n  C -->|"Yes"| D["Verify Email"]\n  C -->|"No"| B\n  D -->|"Code Entered"| E["Welcome Screen"]\n  E -->|"Continue"| F["Home"]',
  userIntent: "Registration user flow diagram"
})
```

### Diagram Types ที่ใช้ได้:

| Type | Mermaid Syntax | Use Case |
|------|---------------|----------|
| Flowchart | `flowchart LR` | User flows, task flows |
| Sequence | `sequenceDiagram` | API interactions, system flows |
| State Diagram | `stateDiagram-v2` | Screen states, component states |
| Gantt | `gantt` | Project timeline, feature roadmap |

### 5.2 Flow Diagram Best Practices

- ใช้ `flowchart LR` (left-to-right) สำหรับ user flows
- ใช้ `flowchart TD` (top-down) สำหรับ decision trees
- ทุก node ต้องมี label ในเครื่องหมายคำพูด
- Decision points ใช้ rhombus `{"Decision?"}`
- Color coding: green=success, red=error, blue=action
- ไม่ใช้ emoji ใน Mermaid syntax

### 5.3 Screen Map ใน Figma (Optional — ใช้ TalkToFigma MCP)

ถ้าต้องการสร้าง visual screen map ใน Figma:

```
1. สร้าง frame สำหรับแต่ละ screen (create_frame with name)
2. ใส่ชื่อ screen (create_text)
3. ใช้ create_connections เชื่อม screens
4. จัด layout ตาม hierarchy
```

---

## Step 6: Build Screen Map in Figma (Optional)

ถ้าผู้ใช้ต้องการ screen map ใน Figma:

### 6.1 Screen Card Template

สร้าง card สำหรับแต่ละ screen:
```
create_frame({
  name: "Screen: Home",
  x, y, width: 200, height: 120,
  fillColor: { r: 0.95, g: 0.95, b: 1 },
  layoutMode: "VERTICAL",
  itemSpacing: 8,
  paddingTop: 12, paddingBottom: 12, paddingLeft: 16, paddingRight: 16
})
```

### 6.2 Connect Screens

ใช้ `create_connections` เชื่อม:
```
create_connections({
  connections: [
    { startNodeId: "home-id", endNodeId: "detail-id", text: "Tap Product" },
    { startNodeId: "home-id", endNodeId: "search-id", text: "Tab Switch" }
  ]
})
```

### 6.3 Annotate

ใส่ annotations อธิบาย flow logic:
```
set_multiple_annotations({
  nodeId: "flow-frame-id",
  annotations: [
    { nodeId: "decision-id", labelMarkdown: "**Decision**\nIf logged in → skip auth" }
  ]
})
```

---

## Output Formats

| Output | Format | เมื่อไหร่ |
|--------|--------|----------|
| Feature Inventory | Markdown table | เสมอ |
| Screen Map | Markdown hierarchy | เสมอ |
| Navigation Matrix | Markdown table | เสมอ |
| User Flows (text) | Markdown steps | เสมอ |
| Flow Diagrams | FigJam (via generate_diagram) | เมื่อผู้ใช้ต้องการ visual |
| Screen Map (visual) | Figma frames + connections | เมื่อผู้ใช้ต้องการใน Figma |

---

## Step 7: ส่งต่อไป UI Design

> **Pipeline**: `Jira BA` → `IA + User Flow` → **UI Design** → `QA Gate` → ส่งมอบ

เมื่อ user review IA + flows แล้ว ถาม:

> "IA และ User Flow พร้อมแล้วครับ พร้อมเริ่มออกแบบ UI ไหม? ผมจะสร้าง HTML preview สำหรับแต่ละหน้าจอให้ดูได้เลย"

เมื่อ user ตอบพร้อม:
- ใช้ข้อมูลจาก Step 1-6 เป็น input สำหรับ **figma-ui-design-spec** skill
- ส่ง: Screen Map, Navigation Matrix, User Flows (happy + error paths), Feature Inventory ไปเป็น requirements
- **figma-ui-design-spec** จะสร้าง HTML preview สำหรับแต่ละ screen
- เมื่อ HTML เสร็จ → **html-qa-gate** จะตรวจคุณภาพก่อนส่งมอบ

### Data Handoff:

| Data | จาก Step | ส่งต่อไป UI Design |
|------|---------|-------------------|
| Screen Map + hierarchy | Step 3.3 | กำหนด screens ที่ต้องออกแบบ |
| Navigation Matrix | Step 3.4 | กำหนด transitions ระหว่างหน้า |
| User Flows (happy + error) | Step 4 | กำหนด states + edge cases ต่อหน้า |
| Feature Inventory | Step 3.1 | กำหนด components ที่ต้องมี |
| Flow Diagrams | Step 5 | Reference สำหรับ design |

---

## หลักการสำคัญ

1. **Goal-Oriented**: เริ่มจาก user goal ไม่ใช่ feature list
2. **Happy Path First**: ออกแบบ happy path ก่อน แล้วค่อยคิด edge cases
3. **Minimal Steps**: ลด steps ให้น้อยที่สุด (3-click rule เป็น guideline)
4. **Clear Wayfinding**: ผู้ใช้ต้องรู้เสมอว่าอยู่ตรงไหน ไปไหนได้
5. **Consistent Navigation**: ใช้ pattern เดียวกันทั้ง app
6. **Error Recovery**: ทุก flow ต้องมีทางกลับและ error handling
7. **Platform Conventions**: ใช้ navigation patterns ตาม platform

---
name: figma-accessibility-audit
description: "ตรวจสอบ Accessibility อย่างละเอียดตาม WCAG 2.1 guidelines ครอบคลุม contrast, touch targets, screen reader, keyboard nav, cognitive accessibility, color blindness ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ตรวจ accessibility, a11y audit, WCAG check, ตรวจ contrast, ตรวจ touch target, screen reader test, หรือเมื่อพิมพ์ 'accessibility', 'a11y', 'WCAG', 'accessible', 'ตรวจการเข้าถึง'"
---

# Accessibility Audit Skill

ตรวจสอบ Accessibility อย่างครบถ้วนตาม WCAG 2.1 AA/AAA — ครอบคลุมทุกมิติ ไม่ใช่แค่สี

## Overall Flow

```
1. Capture → 2. Read Guidelines → 3. Audit (7 Categories) → 4. Score → 5. Report → 6. Fix
```

---

## Step 1: Capture Design

เหมือน Design Critique skill:

- **Figma URL** → `get_screenshot`, `get_design_context`, `get_metadata`
- **Figma Selection** → `read_my_design`, `scan_text_nodes`, `scan_nodes_by_types`
- **HTML Preview File** → อ่านไฟล์ `.html` ด้วย Read tool แล้วตรวจ contrast, touch targets, semantic HTML, ARIA attributes จาก source code โดยตรง (ตรวจได้ก่อน import Figma)
- **Context**: ถามว่า target WCAG level คือ AA หรือ AAA?

---

## Step 2: อ่าน Guidelines

```
references/ux-principles.md     → Accessibility sections
references/hig.md               → iOS Accessibility guidelines
references/material-design.md   → Material Accessibility guidelines
```

---

## Step 3: Audit — ตรวจ 7 หมวด

### Category 1: Color Contrast (WCAG 1.4.3 / 1.4.6)

**วิธีคำนวณ Contrast Ratio:**
```
Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)

Relative Luminance = 0.2126*R + 0.7152*G + 0.0722*B
โดย R, G, B linearized:
  sRGB <= 0.03928 → linear = sRGB / 12.92
  sRGB > 0.03928  → linear = ((sRGB + 0.055) / 1.055) ^ 2.4
```

**เกณฑ์:**

| Element | AA (ขั้นต่ำ) | AAA (แนะนำ) |
|---------|-------------|-------------|
| Normal text (< 18pt / < 14pt bold) | 4.5:1 | 7:1 |
| Large text (>= 18pt / >= 14pt bold) | 3:1 | 4.5:1 |
| UI components & icons | 3:1 | — |
| Non-text contrast (borders, inputs) | 3:1 | — |

**ตรวจทุกคู่สี:**
- Text on background (primary, secondary, tertiary, disabled)
- Text on cards / colored surfaces
- Text on images (ต้องมี overlay)
- Icon on background
- Button text on button fill
- Placeholder text on input background
- Link text vs surrounding text
- Focus indicator contrast
- Border / divider visibility

**Output Table:**
```markdown
| Element | Foreground | Background | Ratio | Size | AA | AAA |
|---------|-----------|------------|-------|------|----|-----|
| Body text | #1A1A1A | #FFFFFF | 16.6:1 | 14px | PASS | PASS |
| Secondary text | #666666 | #FFFFFF | 5.7:1 | 14px | PASS | FAIL |
| Button label | #FFFFFF | #007AFF | 4.6:1 | 14pt bold | PASS | PASS |
| Placeholder | #999999 | #F5F5F5 | 2.1:1 | 14px | FAIL | FAIL |
```

### Category 2: Touch Targets (WCAG 2.5.5 / 2.5.8)

**เกณฑ์:**

| Platform | Minimum Size | Recommended | Spacing |
|----------|-------------|-------------|---------|
| iOS | 44 x 44pt | 56 x 56pt (primary) | >= 8pt |
| Android | 48 x 48dp | 56 x 56dp (primary) | >= 8dp |
| Web | 44 x 44px (WCAG) | 48 x 48px | >= 8px |

**ตรวจ:**
- ทุก button, link, icon button, toggle, checkbox, radio
- ทุก interactive element ใน list (row tap area)
- Close buttons, back buttons
- Form elements (input tap area, dropdown)
- Navigation items (tab bar, nav bar buttons)

**Output Table:**
```markdown
| Element | Actual Size | Min Required | Status | Note |
|---------|------------|--------------|--------|------|
| Back button | 44x44pt | 44x44pt | PASS | — |
| Star rating icon | 24x24pt | 44x44pt | FAIL | Add padding to 44pt |
| List row | 44pt height | 44pt | PASS | Full-width tap area |
```

### Category 3: Screen Reader / Assistive Technology (WCAG 1.1.1 / 4.1.2)

**ตรวจ:**

| Check | Description | How to verify |
|-------|-------------|---------------|
| Image alt text | ทุก meaningful image ต้องมี alt text | ดู image nodes |
| Decorative images | ต้อง hide จาก screen reader | ดูว่าเป็น decorative ไหม |
| Button labels | ทุก button ต้องมี accessible label | ดู text content |
| Icon-only buttons | ต้องมี accessibilityLabel | เช็คว่ามี visible label หรือ aria-label |
| Form labels | ทุก input ต้อง associate กับ label | ดู label-input relationship |
| Heading structure | ต้องมี proper heading hierarchy (h1→h2→h3) | ดู text hierarchy |
| Reading order | ต้องอ่านตามลำดับที่ make sense | ดู visual order vs DOM order |
| Focus order | tab order ต้อง logical | ดู interactive element order |
| Link purpose | link text ต้องบอกว่าไปไหน (ไม่ใช่ "click here") | ดู link text |
| Error announcements | error ต้อง announce ให้ screen reader | ดู error handling |

**Output Table:**
```markdown
| Element | Check | Status | Issue | Fix |
|---------|-------|--------|-------|-----|
| Search icon | Label | FAIL | No accessible label | Add "Search" label |
| Hero image | Alt text | FAIL | Missing alt | Add descriptive alt |
| Email field | Form label | PASS | Has visible label | — |
| "Click here" link | Link purpose | FAIL | Vague text | Change to "View pricing" |
```

### Category 4: Color Independence (WCAG 1.4.1)

สีต้องไม่เป็นตัวบ่งชี้เพียงอย่างเดียว:

**ตรวจ:**
- Error states: มี icon หรือ text ประกอบ ไม่ใช่แค่สีแดง?
- Success states: มี checkmark ไม่ใช่แค่สีเขียว?
- Required fields: มี * หรือ text ไม่ใช่แค่สี?
- Active/selected states: มี indicator อื่นนอกจากสี?
- Charts/graphs: มี pattern/label ไม่ใช่แค่สี?
- Links in text: มี underline ไม่ใช่แค่สีฟ้า?
- Status badges: มี icon + text ไม่ใช่แค่สี?

**Color Blindness Simulation:**

ตรวจว่า design ยังใช้งานได้กับ color vision deficiencies:
- Protanopia (red-blind, ~1% males)
- Deuteranopia (green-blind, ~1% males)
- Tritanopia (blue-blind, rare)
- Achromatopsia (total color blind, very rare)

จุดที่ต้องระวัง:
- Red vs Green (เช่น error vs success) — ต้องมี shape/icon ด้วย
- Red vs Brown, Green vs Brown
- Blue vs Purple
- Light Green vs Light Yellow

### Category 5: Keyboard Navigation (WCAG 2.1.1 / 2.1.2 / 2.4.7)

สำหรับ Web / Desktop:

**ตรวจ:**
| Check | Description |
|-------|-------------|
| All interactive reachable | ทุก interactive element ต้อง tab ถึงได้ |
| Focus visible | focus indicator ต้องเห็นชัด (contrast >= 3:1) |
| Focus order | tab order logical ตาม visual layout |
| No keyboard trap | ต้องออกจากทุก element ได้ (especially modals) |
| Skip links | มี "Skip to main content" link |
| Shortcuts | keyboard shortcuts ไม่ conflict กับ screen reader |
| Modal focus trap | focus ต้อง trap ใน modal เมื่อเปิด แต่ออกได้เมื่อปิด |

**Focus Indicator Style:**
```
Focus ring: 2px solid, contrast >= 3:1 vs background AND focused element
Recommended: #005FCC (blue) on light, #66B2FF on dark
Offset: 2px from element edge
```

### Category 6: Text & Readability (WCAG 1.4.4 / 1.4.8 / 1.4.12)

**ตรวจ:**
| Check | Criteria |
|-------|----------|
| Text resize | ต้องรองรับ zoom 200% โดยไม่เสีย content |
| Line height | >= 1.5x font size สำหรับ body text |
| Paragraph spacing | >= 2x font size |
| Letter spacing | ต้อง adjust ได้ (ไม่ lock ใน image) |
| Text alignment | ไม่ justify (justified text อ่านยาก) |
| Line length | 45-75 characters per line (optimal: 66) |
| Font size minimum | >= 16px/16sp/16pt สำหรับ body text |
| Dynamic Type (iOS) | รองรับ Dynamic Type scaling |
| Text in images | หลีกเลี่ยง — ใช้ real text แทน |

### Category 7: Motion & Cognitive (WCAG 2.3.1 / 2.3.3)

**ตรวจ:**
| Check | Criteria |
|-------|----------|
| Reduce Motion | มี alternative เมื่อ Reduce Motion เปิด? |
| Auto-play | ไม่ auto-play video/animation > 5 วินาที |
| Flashing | ไม่มี content flash > 3 ครั้ง/วินาที |
| Parallax | ลดหรือเอาออกเมื่อ Reduce Motion |
| Timeout | แจ้งเตือนก่อน session timeout |
| Cognitive load | ข้อมูลต่อหน้าจอไม่มากเกินไป |
| Plain language | ใช้ภาษาง่าย ชัดเจน |
| Consistent layout | layout consistent ทั้ง app |
| Error recovery | ง่ายต่อการ recover จาก error |
| Predictable | interactions ทำงานตามที่คาดหวัง |

---

## Step 4: Score

### Scoring Matrix

| Category | Weight | Score (1-10) | Critical Issues | Notes |
|----------|--------|-------------|-----------------|-------|
| Color Contrast | 25% | — | — | — |
| Touch Targets | 15% | — | — | — |
| Screen Reader | 20% | — | — | — |
| Color Independence | 10% | — | — | — |
| Keyboard Navigation | 10% | — | — | — |
| Text & Readability | 10% | — | — | — |
| Motion & Cognitive | 10% | — | — | — |
| **Weighted Total** | **100%** | **—/10** | — | — |

### WCAG Compliance Level

| Level | Requirements |
|-------|-------------|
| A | ขั้นต่ำสุด — must fix |
| AA | มาตรฐานทั่วไป — target level |
| AAA | สูงสุด — recommended for government/health |

---

## Step 5: Report

### Report Template

```markdown
# Accessibility Audit Report: [Screen/App Name]

## Overview
- **Platform**: [iOS/Android/Web]
- **Target Level**: [WCAG 2.1 AA / AAA]
- **Audited**: [Date]
- **Overall Score**: [X/10]
- **WCAG Compliance**: [A / AA / Not Compliant]

## Executive Summary
[2-3 sentences: สรุปสถานะ a11y โดยรวม — มีอะไรดี มีอะไรต้องแก้]

## Score Breakdown
[Scoring Matrix table]

## Detailed Findings

### 1. Color Contrast
[Contrast audit table — ทุกคู่สี]

### 2. Touch Targets
[Touch target audit table]

### 3. Screen Reader
[Screen reader check table]

### 4. Color Independence
[Color-only indicators found]

### 5. Keyboard Navigation
[Keyboard nav checks — web/desktop only]

### 6. Text & Readability
[Text metrics checks]

### 7. Motion & Cognitive
[Motion/cognitive checks]

## WCAG Violations Summary

| # | WCAG Criterion | Level | Issue | Element | Fix |
|---|---------------|-------|-------|---------|-----|
| 1 | 1.4.3 Contrast | AA | Ratio 2.1:1 | Placeholder text | Darken to #767676 |
| 2 | 2.5.5 Target Size | AAA | 30x30pt | Star icon | Increase tap area to 44pt |

## Priority Action Items

### P0 — Legal Risk (WCAG A violations)
- [ ] [Fix 1]

### P1 — Must Fix (WCAG AA violations)
- [ ] [Fix 1]
- [ ] [Fix 2]

### P2 — Should Fix (WCAG AAA / Best Practices)
- [ ] [Fix 1]

### P3 — Nice to Have
- [ ] [Fix 1]
```

---

## Step 6: Fix in Figma

ถ้าผู้ใช้ต้องการแก้ไข:

อ่าน `references/figma-mcp-commands.md` แล้ว:

**Contrast fixes:**
- `set_fill_color(nodeId, r, g, b)` — เปลี่ยน text color ให้ contrast ผ่าน
- `set_fill_color(bgNodeId, r, g, b)` — เปลี่ยน background color

**Touch target fixes:**
- `resize_node(nodeId, width, height)` — ขยาย interactive elements
- `set_padding(nodeId, ...)` — เพิ่ม padding ให้ tap area ใหญ่ขึ้น

**Screen reader fixes:**
- `set_annotation(nodeId, labelMarkdown)` — เพิ่ม accessibility notes
- `set_text_content(nodeId, text)` — แก้ link text ให้ descriptive

**Visual indicator fixes:**
- `create_text(...)` — เพิ่ม text labels ให้ color-coded elements
- `create_rectangle(...)` — เพิ่ม icons/shapes ประกอบสี

---

## หลักการสำคัญ

1. **WCAG AA เป็นขั้นต่ำ**: ทุก design ต้องผ่าน AA เสมอ
2. **ไม่ใช่แค่สี**: Accessibility ครอบคลุม 7 หมวด ไม่ใช่แค่ contrast
3. **Test with Users**: ผลวิเคราะห์เป็น guideline ต้อง test กับ real users ด้วย
4. **Progressive Enhancement**: แก้ P0/P1 ก่อน แล้วค่อยทำ P2/P3
5. **Document Everything**: ทุก finding ต้อง reference WCAG criterion
6. **Inclusive Design**: Accessibility ดีขึ้น = UX ดีขึ้นสำหรับทุกคน

---
name: figma-design-system
description: "สร้าง Design System ทั้งระบบ — component library, token system, documentation ใน Figma ใช้ skill นี้เมื่อผู้ใช้ต้องการ: สร้าง design system, component library, สร้าง UI kit, สร้าง style guide, token system, pattern library, หรือเมื่อพิมพ์ 'design system', 'component library', 'UI kit', 'style guide', 'tokens', 'pattern library'"
---

# Design System Creation Skill

สร้าง Design System ทั้งระบบ — ตั้งแต่ tokens, typography scale, color system, components จนถึง documentation — พร้อมสร้างใน Figma

## Overall Flow

```
1. Requirements → 2. Read References → 3. Define Foundations → 4. Design Components → 5. Preview (HTML) → 6. Import to Figma (HTML to Figma MCP) → 7. Document
```

---

## Step 1: รวบรวม Requirements

ถามข้อมูลเหล่านี้:

- **Brand**: มี brand guidelines อยู่แล้วไหม? (สี, font, logo)
- **Platform**: Mobile, Web, Cross-platform?
- **Base System**: ต่อยอดจาก Material Design / HIG / เริ่มจากศูนย์?
- **Scale**: ใช้กี่คน? กี่ product? (กำหนดความซับซ้อน)
- **Components Needed**: ต้องการ components อะไรบ้าง? (หรือให้แนะนำ?)
- **Theme**: ต้องรองรับ Light/Dark mode ไหม?
- **Existing Design**: มี Figma URL ของ design ที่มีอยู่แล้วไหม?

---

## Step 2: อ่าน References

```
references/design-tokens.md       → Token naming & categories (อ่านเสมอ)
references/ux-principles.md       → Consistency principle (H4)
references/material-design.md     → ถ้า base = Material
references/hig.md                 → ถ้า base = HIG
```

ถ้ามี existing design:
```
get_screenshot(fileKey, nodeId)    → ดู visual style
get_design_context(fileKey, nodeId) → อ่าน design details
get_variable_defs(fileKey, nodeId) → ดู existing tokens
```

---

## Step 3: Define Foundations (Design Tokens)

### 3.1 Color System

**Step-by-step:**

1. **เลือก Primary Color** จาก brand (หรือกำหนดใหม่)
2. **Generate Color Scale** สำหรับแต่ละ hue:
   ```
   [color]-50:  lightest (background tint)
   [color]-100: very light
   [color]-200: light
   [color]-300: medium light
   [color]-400: medium
   [color]-500: base (primary)
   [color]-600: medium dark
   [color]-700: dark
   [color]-800: very dark
   [color]-900: darkest
   [color]-950: near black
   ```

3. **กำหนด Semantic Colors**:
   ```markdown
   | Token | Light Mode | Dark Mode | Usage |
   |-------|-----------|-----------|-------|
   | color-primary | blue-600 | blue-400 | Primary actions, links |
   | color-on-primary | white | blue-950 | Text on primary |
   | color-secondary | gray-600 | gray-400 | Secondary actions |
   | color-error | red-600 | red-400 | Error states |
   | color-warning | amber-600 | amber-400 | Warning states |
   | color-success | green-600 | green-400 | Success states |
   | color-info | blue-500 | blue-300 | Informational |
   | color-surface | white | gray-900 | Backgrounds |
   | color-on-surface | gray-900 | gray-50 | Primary text |
   | color-on-surface-variant | gray-600 | gray-400 | Secondary text |
   | color-outline | gray-300 | gray-700 | Borders |
   | color-outline-variant | gray-200 | gray-800 | Subtle borders |
   ```

4. **WCAG Contrast Check** (บังคับ):
   ตรวจทุกคู่ semantic color:
   ```
   color-on-surface on color-surface → ต้อง >= 4.5:1 (AA)
   color-on-primary on color-primary → ต้อง >= 4.5:1 (AA)
   color-on-surface-variant on color-surface → ต้อง >= 4.5:1 (AA)
   ```

### 3.2 Typography Scale

**กำหนด Type Scale (ตรงกับ Figma Text Styles):**

```markdown
| Token | Size | Weight | Line Height | Usage |
|-------|------|--------|-------------|-------|
| Heading.1 | 48px | Bold (700) | 58px | Page titles, hero text |
| Heading.2 | 40px | Bold (700) | 52px | Section headers |
| Heading.3 | 32px | Bold (700) | 40px | Sub-section headers |
| Heading.4 | 28px | Bold (700) | 36px | Card titles, dialog headers |
| Heading.5 | 24px | Bold (700) | 32px | Small headings, list titles |
| Label.1 | 20px | Bold (700) | 28px | Large labels |
| Label.2 | 18px | Bold (700) | 26px | Medium labels |
| Label.3 | 16px | Bold (700) | 24px | Buttons, standard labels |
| Label.4 | 14px | Bold (700) | 22px | Small labels, tags |
| Label.5 | 12px | Bold (700) | 20px | Micro labels, badges |
| Caption.1 | 20px | Regular (400) | 36px | Large body text |
| Caption.2 | 18px | Regular (400) | 26px | Medium body text |
| Caption.3 | 16px | Regular (400) | 24px | Standard body text |
| Caption.4 | 14px | Regular (400) | 22px | Small text, captions |
| Caption.5 | 12px | Regular (400) | 20px | Micro text, footnotes |
```

**Font Family:**
- Primary: LINE Seed Sans TH
- Weights: Regular (400), Bold (700), ExtraBold (800)
- Fallback: sans-serif

### 3.3 Spacing System

ใช้ 4px base unit:

```markdown
| Token | Value | Usage |
|-------|-------|-------|
| space-0 | 0px | — |
| space-1 | 4px | Icon padding, micro gaps |
| space-2 | 8px | Inline elements, tight |
| space-3 | 12px | List item internal |
| space-4 | 16px | Content padding (default) |
| space-5 | 20px | Card padding |
| space-6 | 24px | Section gaps |
| space-8 | 32px | Large gaps |
| space-10 | 40px | Section breaks |
| space-12 | 48px | Page sections |
| space-16 | 64px | Hero spacing |
| space-20 | 80px | Page top/bottom |
```

### 3.4 Shape (Corner Radius)

```markdown
| Token | Value | Usage |
|-------|-------|-------|
| radius-none | 0px | Sharp corners |
| radius-xs | 4px | Tags, badges, chips |
| radius-sm | 8px | Buttons, inputs, small cards |
| radius-md | 12px | Cards, dialogs |
| radius-lg | 16px | Large cards, FABs |
| radius-xl | 24px | Bottom sheets |
| radius-full | 9999px | Pills, avatars, circles |
```

### 3.5 Elevation

```markdown
| Token | Shadow | Usage |
|-------|--------|-------|
| elevation-0 | none | Flat surfaces |
| elevation-1 | 0 1px 3px rgba(0,0,0,0.12) | Cards (rest) |
| elevation-2 | 0 4px 6px rgba(0,0,0,0.1) | Dropdowns, popovers |
| elevation-3 | 0 8px 16px rgba(0,0,0,0.1) | FAB, bottom sheets |
| elevation-4 | 0 12px 24px rgba(0,0,0,0.12) | Dialogs, modals |
```

---

## Step 4: Design Components

### Atomic Design Hierarchy

```
Atoms → Molecules → Organisms → Templates → Pages
```

### 4.1 Atoms (พื้นฐาน)

| Component | Variants | States |
|-----------|----------|--------|
| Button | filled, outlined, text, tonal, icon | default, hover, pressed, focused, disabled, loading |
| Icon Button | filled, outlined, standard | default, hover, pressed, focused, disabled |
| Text Field | filled, outlined | default, focused, filled, error, disabled |
| Checkbox | — | unchecked, checked, indeterminate, disabled |
| Radio Button | — | unselected, selected, disabled |
| Toggle/Switch | — | off, on, disabled |
| Badge | number, dot | — |
| Chip | assist, filter, input, suggestion | default, selected, disabled |
| Divider | full-width, inset | — |
| Avatar | image, initials, icon | sizes: sm, md, lg |

### 4.2 Molecules (ประกอบจาก atoms)

| Component | Description |
|-----------|-------------|
| Search Bar | input + icon + clear button |
| List Item | avatar + text + trailing action |
| Form Field | label + input + helper text + error text |
| Menu Item | icon + label + shortcut |
| Snackbar / Toast | text + optional action button |
| Tab | icon + label + indicator |

### 4.3 Organisms (complex components)

| Component | Description |
|-----------|-------------|
| Top App Bar | nav icon + title + action icons |
| Bottom Navigation | 3-5 tab items |
| Navigation Rail | icon + label items |
| Navigation Drawer | header + menu items |
| Card | header + content + actions |
| Dialog / Modal | title + body + action buttons |
| Bottom Sheet | handle + content |
| Data Table | header + rows + pagination |
| Form | grouped form fields + submit |

### Component Spec Template

สำหรับแต่ละ component กำหนด:

```markdown
## Component: [Name]

### Anatomy
[รายการ sub-elements]

### Variants
| Variant | Visual Difference | When to Use |
|---------|------------------|-------------|
| Filled | Solid background | Primary actions |
| Outlined | Border only | Secondary actions |

### Sizes
| Size | Height | Padding | Font | Icon |
|------|--------|---------|------|------|
| Small | 32px | 12px H | label-md | 16px |
| Medium | 40px | 16px H | label-lg | 20px |
| Large | 48px | 20px H | body-lg | 24px |

### States
| State | Background | Text | Border | Opacity |
|-------|-----------|------|--------|---------|
| Default | primary | on-primary | — | 100% |
| Hover | primary-dark | on-primary | — | 100% |
| Pressed | primary-darker | on-primary | — | 100% |
| Focused | primary | on-primary | focus-ring | 100% |
| Disabled | on-surface | on-surface | — | 38% |
| Loading | primary | — | — | 70% + spinner |

### Accessibility
- Min touch target: 48x48dp / 44x44pt
- Focus indicator: 2px ring
- Disabled: opacity 38%, not focusable
- Screen reader: role="button", aria-label if icon-only

### Spacing Rules
- Internal padding: [values]
- Min gap between buttons: space-2 (8px)
- Margin from screen edge: space-4 (16px)
```

---

## Step 5: Preview (Static HTML)

สร้าง HTML preview แสดง Design System Overview — เปิดใน browser ได้ทันที:

### Preview ต้องมี:

1. **Color Palette** — แสดงทุก color token พร้อม hex (CSS Variables)
2. **Typography Scale** — แสดงทุก type style (Google Fonts: LINE Seed Sans TH)
3. **Spacing Scale** — visual representation
4. **Component Gallery** — ทุก component, ทุก variant, ทุก state
5. **Light/Dark Toggle** — สลับ theme ได้ (vanilla JS)
6. **Component State Switcher** — เปลี่ยน state ได้ (vanilla JS)

### Guidelines:

- ใช้ **CSS Variables** ตาม Design Tokens (`references/design-tokens.md`)
- ใช้ **flexbox/grid** layout → จะกลายเป็น Auto Layout ใน Figma
- ตั้ง **class names** ให้มีความหมาย → จะกลายเป็น Figma layer names
- ใช้ **semantic HTML** (`<header>`, `<section>`, `<main>`)
- **ห้ามใช้** React, Vue, หรือ JS framework — ใช้ vanilla JS เท่านั้น
- ใช้ **inline SVG** หรือ placeholder สำหรับ icons

ตั้งชื่อ: `[system-name]-design-system-preview.html`

---

## Step 6: Import เข้า Figma (HTML to Figma MCP)

ใช้ **html-to-design MCP** ส่ง HTML ไป Figma โดยตรง:

1. ตรวจว่า user เปิด html.to.design plugin ใน Figma → tab MCP → STATUS: connected
2. ใช้ `import_html` ส่ง HTML ไป Figma:
   ```
   import_html({ html: "...", css: "...", name: "Design System Overview" })
   ```
   หรือ serve file แล้วใช้ `import_url`:
   ```
   import_url({ url: "http://localhost:3000/design-system-preview.html", name: "Design System" })
   ```
3. Plugin แปลง HTML → Figma layers อัตโนมัติ
4. ปรับ fine-tune ใน Figma:
   - ตรวจ font — เปลี่ยนเป็น LINE Seed Sans TH ถ้าต้องการ
   - ตรวจ sizing mode (FILL/HUG/FIXED)
   - ปรับ layer names ถ้าต้องการ
   - สร้าง components, variants, styles ตาม design system

---

## Step 7: Document

### Design System Documentation Template

```markdown
# [System Name] Design System

## 1. Principles
- [Design principle 1]
- [Design principle 2]
- [Design principle 3]

## 2. Foundations
### Colors
[Color token table with light/dark modes]

### Typography
[Type scale table]

### Spacing
[Spacing scale]

### Shape & Elevation
[Radius and shadow tables]

## 3. Components
### [Component Name]
- Anatomy
- Variants (visual)
- States (interactive)
- Sizes
- Accessibility
- Usage guidelines (Do/Don't)

## 4. Patterns
### Common patterns
- Form layout
- List layout
- Navigation patterns
- Empty states
- Loading states
- Error handling

## 5. Accessibility Standards
- WCAG level target
- Contrast requirements
- Touch target requirements
- Screen reader guidelines
```

---

## Output Files

| Output | Format | เมื่อไหร่ |
|--------|--------|----------|
| Design Tokens | Markdown tables | เสมอ |
| Component Specs | Markdown with variants/states | เสมอ |
| Preview | `.html` (Static HTML — เปิดใน browser) | เสมอ |
| Figma Design | Import ผ่าน html-to-design MCP (`import_html` / `import_url`) | เมื่อ import เข้า Figma |
| Documentation | `.md` | เมื่อผู้ใช้ต้องการ |

---

## หลักการสำคัญ

1. **Token-First**: กำหนด tokens ก่อนออกแบบ component
2. **Consistent Naming**: ใช้ `{category}-{property}-{variant}` เสมอ
3. **Scalable**: ออกแบบให้เพิ่ม variant/component ได้ง่าย
4. **Accessible by Default**: ทุก component ต้องผ่าน WCAG AA
5. **Theme-Ready**: ทุก color token ต้องมี Light + Dark mode
6. **Platform-Aware**: ปรับ sizing/spacing ตาม platform (pt vs dp vs px)
7. **Document Everything**: ทุก component ต้องมี usage guideline
8. **Less is More**: เริ่มจาก minimal set แล้วค่อยเพิ่ม

---
name: figma-responsive-design
description: "ออกแบบ Responsive/Adaptive Design สำหรับหลาย screen size — Mobile, Tablet, Desktop พร้อมสร้าง multiple frames ใน Figma ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ออกแบบ responsive, adaptive layout, หลาย screen size, mobile + desktop, breakpoints, responsive UI, หรือเมื่อพิมพ์ 'responsive', 'adaptive', 'breakpoint', 'หลายขนาด', 'mobile tablet desktop', 'responsive design'"
---

# Responsive / Adaptive Design Skill

ออกแบบ UI ที่ทำงานได้ดีบนทุกขนาดหน้าจอ — จาก Mobile เล็กสุดไปจน Desktop จอใหญ่ พร้อมสร้างหลาย frames ใน Figma

## Overall Flow

```
1. Requirements → 2. Read References → 3. Define Breakpoints → 4. Design Adaptation Rules → 5. Preview (HTML) → 6. Import to Figma (HTML to Figma MCP)
```

---

## Step 1: รวบรวม Requirements

ถามข้อมูลเหล่านี้:

- **Primary Platform**: Mobile-first หรือ Desktop-first?
- **Target Breakpoints**: ต้องการกี่ขนาด? (Mobile / Tablet / Desktop / Large Desktop)
- **Screen/Feature**: จะ responsive อะไร? (หน้าจอเดียว / ทั้ง app)
- **Content Priority**: content ไหนสำคัญสุดบน mobile?
- **Navigation**: เปลี่ยน navigation pattern ตาม size ไหม?
- **Existing Design**: มี Figma URL ของ design ที่มีอยู่ (size เดียว) ไหม?
- **Framework**: ใช้ CSS framework ไหน? (Tailwind, Bootstrap, custom)

---

## Step 2: อ่าน References

```
references/ux-principles.md       → อ่านเสมอ
references/material-design.md     → Responsive grid & navigation patterns
references/hig.md                 → Size classes & adaptive layout (iOS)
references/design-tokens.md       → Breakpoint tokens
```

---

## Step 3: Define Breakpoints

### 3.1 Standard Breakpoints

| Breakpoint | Width | Device Category | Columns | Margin | Gutter |
|------------|-------|----------------|---------|--------|--------|
| xs | < 360px | Small phone | 4 | 16px | 8px |
| sm | 360-599px | Phone | 4 | 16px | 8px |
| md | 600-904px | Tablet portrait / Foldable | 8 | 24px | 16px |
| lg | 905-1239px | Tablet landscape / Small desktop | 12 | 24px | 24px |
| xl | 1240-1439px | Desktop | 12 | 24px | 24px |
| 2xl | >= 1440px | Large desktop | 12 | auto (max-width) | 24px |

### 3.2 Common Frame Sizes สำหรับ Figma

| Device | Width | Height | Use For |
|--------|-------|--------|---------|
| iPhone SE | 375px | 667px | Small phone |
| iPhone 15 Pro | 393px | 852px | Standard phone |
| iPhone 15 Pro Max | 430px | 932px | Large phone |
| iPad Mini | 744px | 1133px | Small tablet |
| iPad Pro 11" | 834px | 1194px | Tablet |
| iPad Pro 12.9" | 1024px | 1366px | Large tablet |
| MacBook Air | 1440px | 900px | Desktop |
| Desktop HD | 1920px | 1080px | Large desktop |

### 3.3 เลือก Target Sizes

**Minimum recommended (3 sizes):**
```
Mobile:  393 x 852px   (iPhone 15 Pro)
Tablet:  834 x 1194px  (iPad Pro 11")
Desktop: 1440 x 900px  (MacBook Air)
```

**Comprehensive (5 sizes):**
```
Small Phone:  375 x 667px
Phone:        393 x 852px
Tablet:       834 x 1194px
Desktop:      1440 x 900px
Large Desktop: 1920 x 1080px
```

---

## Step 4: Design Adaptation Rules

### 4.1 Layout Adaptation Strategies

| Strategy | Description | Example |
|----------|-------------|---------|
| **Reflow** | Stack → Row | Cards stack vertical on mobile, horizontal on desktop |
| **Expand** | เพิ่ม width | Sidebar เปลี่ยนจาก icon-only เป็น full-width |
| **Reveal** | Show more content | แสดง sidebar ที่ซ่อนบน mobile |
| **Hide** | ซ่อน non-essential | ซ่อน secondary info บน mobile |
| **Resize** | เปลี่ยนขนาด | Image full-width บน mobile, fixed width บน desktop |
| **Reposition** | ย้ายตำแหน่ง | FAB บน mobile → inline button บน desktop |
| **Transform** | เปลี่ยน component | Bottom sheet บน mobile → side panel บน desktop |

### 4.2 Navigation Adaptation

| Size | Primary Nav | Secondary Nav |
|------|-------------|---------------|
| Mobile (< 600) | Bottom Tab Bar (3-5 items) | Hamburger → Drawer |
| Tablet (600-904) | Navigation Rail (side icons) | Tab bar |
| Desktop (905+) | Sidebar Navigation (full) | Top tabs |

### 4.3 Content Adaptation Rules

สำหรับแต่ละ section กำหนด:

```markdown
## Content Adaptation

### Hero Section
| Breakpoint | Layout | Image | Text |
|------------|--------|-------|------|
| Mobile | Stack (image top, text bottom) | Full-width, 16:9 | heading-md, body-md |
| Tablet | Side-by-side (50/50) | 1:1 | heading-lg, body-lg |
| Desktop | Side-by-side (40/60) | Custom crop | display-sm, body-lg |

### Card Grid
| Breakpoint | Columns | Card Width | Gap |
|------------|---------|------------|-----|
| Mobile | 1 | 100% | 16px |
| Tablet | 2 | calc(50% - 12px) | 24px |
| Desktop | 3-4 | calc(33% - 16px) | 24px |

### Data Table
| Breakpoint | Adaptation |
|------------|------------|
| Mobile | Transform to card list (stack rows) |
| Tablet | Horizontal scroll with sticky first column |
| Desktop | Full table view |

### Form Layout
| Breakpoint | Columns | Input Width |
|------------|---------|-------------|
| Mobile | 1 | 100% |
| Tablet | 2 (side-by-side for short fields) | 50% |
| Desktop | 2-3 | 33-50% |
```

### 4.4 Typography Adaptation

```markdown
## Typography Scale by Breakpoint (ตรงกับ Figma Text Styles)

| Token | Mobile | Tablet | Desktop |
|-------|--------|--------|---------|
| Heading.1 | 32px/40px | 40px/52px | 48px/58px |
| Heading.2 | 28px/36px | 32px/40px | 40px/52px |
| Heading.3 | 24px/32px | 28px/36px | 32px/40px |
| Heading.4 | 20px/28px | 24px/32px | 28px/36px |
| Heading.5 | 18px/26px | 20px/28px | 24px/32px |
| Label.3 | 16px/24px | 16px/24px | 16px/24px |
| Caption.3 | 16px/24px | 16px/24px | 16px/24px |
| Caption.4 | 14px/22px | 14px/22px | 14px/22px |
```

Headings scale ลงบน mobile, ส่วน body/label/caption คงที่ทุก breakpoint

### 4.5 Spacing Adaptation

```markdown
## Spacing by Breakpoint

| Token | Mobile | Tablet | Desktop |
|-------|--------|--------|---------|
| page-margin | 16px | 24px | 24px (or auto center) |
| section-gap | 24px | 32px | 48px |
| card-padding | 16px | 20px | 24px |
| content-padding | 16px | 24px | 24px |
```

### 4.6 Touch Target Adaptation

| Breakpoint | Min Target | Reason |
|------------|-----------|--------|
| Mobile | 48 x 48px | Touch (finger) |
| Tablet | 44 x 44px | Touch + stylus |
| Desktop | 32 x 32px (click) | Mouse (but keep 44px accessible) |

---

## Step 5: Preview (Static HTML)

สร้าง HTML preview ที่ **resize ได้** — เปิดใน browser แล้วลาก resize หน้าต่างเห็นผลทันที:

### Preview ต้องมี:

1. **Responsive Container** — ใช้ CSS `resize: horizontal` หรือมีปุ่มสลับ breakpoint (vanilla JS)
2. **Breakpoint Indicator** — แสดง current breakpoint (xs/sm/md/lg/xl) ด้วย vanilla JS + `matchMedia()`
3. **Side-by-side View** — แสดง Mobile + Tablet + Desktop พร้อมกัน (ใช้ `<iframe>` หรือ CSS Grid)
4. **Layout Annotations** — แสดง grid columns, margins, gaps
5. **Light/Dark Toggle** — สลับ theme ได้ (vanilla JS)
6. **Content Priority Highlight** — แสดงว่า content ไหนหาย/ย้ายเมื่อ resize

### Guidelines:

- ใช้ **CSS media queries** (หรือ container queries) จริง
- แสดง breakpoint badge ที่มุมบนซ้าย
- มี ruler/grid overlay toggle (vanilla JS)
- ทุก adaptation rule ต้องเห็นผลจริงเมื่อ resize
- ใช้ **CSS Variables** ตาม Design Tokens (`references/design-tokens.md`)
- ใช้ **flexbox/grid** layout → Auto Layout ใน Figma
- **ห้ามใช้** React, Vue, หรือ JS framework — ใช้ vanilla JS เท่านั้น

ตั้งชื่อ: `[screen-name]-responsive-preview.html`

---

## Step 6: Import เข้า Figma (HTML to Figma MCP)

ใช้ **html-to-design MCP** ส่ง HTML ไป Figma โดยตรง:

1. ตรวจว่า user เปิด html.to.design plugin ใน Figma → tab MCP → STATUS: connected
2. ใช้ `import_html` ส่ง HTML แต่ละ breakpoint ไป Figma:
   ```
   import_html({ html: "...", css: "...", name: "Login - Mobile (393px)" })
   import_html({ html: "...", css: "...", name: "Login - Tablet (834px)" })
   import_html({ html: "...", css: "...", name: "Login - Desktop (1440px)" })
   ```
   หรือ serve file แล้วใช้ `import_url`:
   ```
   import_url({ url: "http://localhost:3000/login-responsive-preview.html", name: "Login Responsive" })
   ```
3. Plugin แปลง HTML → Figma layers อัตโนมัติ
4. ปรับ fine-tune ใน Figma:
   - ตรวจ font — เปลี่ยนเป็น LINE Seed Sans TH ถ้าต้องการ
   - ตรวจ sizing mode (FILL/HUG/FIXED)
   - ปรับ layer names ถ้าต้องการ
   - จัด frames เรียงกันตาม breakpoint (Mobile → Tablet → Desktop)

---

## Responsive Design Checklist

ตรวจสอบก่อนส่งมอบ:

### Layout
- [ ] ทุก breakpoint มี consistent visual identity
- [ ] Content priority ถูกต้อง (สำคัญสุดเห็นก่อน)
- [ ] Grid system consistent (columns, margins, gutters)
- [ ] Max-width กำหนดสำหรับ large screens (ไม่ stretch จนอ่านยาก)
- [ ] Line length ไม่เกิน 75 characters

### Navigation
- [ ] Navigation pattern เหมาะกับ screen size
- [ ] Navigation transitions smooth (ไม่ jump)
- [ ] ทุก page reachable จากทุก breakpoint

### Typography
- [ ] Display/heading sizes scale ตาม breakpoint
- [ ] Body text readable (>= 16px) ทุก size
- [ ] Line height comfortable ทุก size

### Touch & Interaction
- [ ] Touch targets >= 48px บน mobile/tablet
- [ ] Hover states สำหรับ desktop
- [ ] Touch-friendly spacing บน mobile

### Images & Media
- [ ] Images responsive (ไม่ overflow)
- [ ] Art direction ถูกต้อง (crop เหมาะสมกับ size)
- [ ] Video/media ไม่ทำให้ layout เพี้ยน

### Accessibility
- [ ] WCAG contrast ผ่านทุก breakpoint
- [ ] Focus order logical ทุก size
- [ ] Screen reader order ถูกต้อง

---

## Output Files

| Output | Format | เมื่อไหร่ |
|--------|--------|----------|
| Breakpoint Definition | Markdown tables | เสมอ |
| Adaptation Rules | Markdown tables per section | เสมอ |
| Responsive Preview | `.html` (Static HTML, resizable) | เสมอ |
| Figma Frames | Import ผ่าน html-to-design MCP (`import_html` / `import_url`) | เมื่อ import เข้า Figma |

---

## หลักการสำคัญ

1. **Content First**: เริ่มจาก content priority ไม่ใช่ layout
2. **Mobile First**: ออกแบบ mobile ก่อน แล้ว enhance ขึ้นไป (ถ้า primary = mobile)
3. **Progressive Enhancement**: เพิ่ม features/content ตาม screen ที่ใหญ่ขึ้น
4. **Consistent Identity**: ทุก breakpoint ต้องรู้สึกเป็น app เดียวกัน
5. **Test Real Content**: ใช้ real content length ทดสอบ ไม่ใช่ Lorem Ipsum
6. **Performance**: Mobile ต้องเร็ว — ลด content, optimize images
7. **Fluid > Fixed**: ใช้ relative units (%, fr, auto) มากกว่า fixed pixels
8. **Breakpoints ≠ Devices**: ออกแบบตาม content ไม่ใช่ตาม device ที่เฉพาะเจาะจง

---
name: figma-ux-writer
description: "เขียน UX Copy ระดับมืออาชีพทั้งภาษาไทยและอังกฤษ — ครอบคลุม microcopy, error messages, onboarding, CTA, empty states, notifications, tooltips, labels ทุกจุดสัมผัสกับผู้ใช้ พร้อมตรวจคำผิด/ไวยากรณ์ทั้งไทย-อังกฤษ และสร้าง Correction Log ใช้ skill นี้เมื่อผู้ใช้ต้องการ: เขียน copy, UX writing, แก้ข้อความ, ปรับภาษา, microcopy, error message, button text, onboarding text, เขียนไทย-อังกฤษ, ตรวจคำผิด, เช็คสะกด, spell check, grammar check, ตรวจสะกด, ตรวจไวยากรณ์, proofread, หรือเมื่อพิมพ์ 'UX writing', 'copy', 'เขียน copy', 'ข้อความ', 'microcopy', 'tone of voice', 'content design', 'ตรวจคำผิด', 'spell check', 'เช็คคำผิด', 'proofread'"
---

# UX Writer Skill

เขียน UX Copy ที่ผู้ใช้อ่านแล้วเข้าใจทันที ไม่มีข้อสงสัย — ทั้งภาษาไทย (หลัก) และอังกฤษ ในระดับมืออาชีพ

## Overall Flow

```
1. Context → 2. Voice & Tone → 3. Write (11 Patterns) → 4. Edit (4 Phases) → 5. Score → 6. Apply (Optional)
```

1. **Context**: เข้าใจหน้าจอ, ผู้ใช้, สถานการณ์
2. **Voice & Tone**: กำหนด voice/tone ด้วย Voice Chart (6 dimensions)
3. **Write**: เขียน copy ตาม 11 UX Text Patterns — ทั้งไทยและอังกฤษ
4. **Edit**: ตรวจด้วย 4-Phase Editing (Purposeful → Concise → Conversational → Clear) + ตรวจคำผิด/ไวยากรณ์
5. **Score**: ให้คะแนนด้วย UX Content Heuristics Scorecard
6. **Apply**: ใส่ text เข้า HTML preview หรือ Figma (optional)

### อ่าน References:
```
references/ux-writing-spellcheck.md    → ตารางคำผิด + Correction Log format (อ่านเสมอ)
references/ux-writing-patterns.md      → Voice Chart, 11 Patterns, 4-Phase Editing, Scorecard (อ่านเสมอ)
```

---

## Step 1: รวบรวม Context

ถามข้อมูลเหล่านี้ (ถ้ายังไม่ได้ระบุ):

- **Screen/Feature**: เขียน copy สำหรับหน้าจอหรือ feature อะไร?
- **User**: ผู้ใช้เป็นใคร? ระดับ tech-savviness?
- **Language**: ไทย, อังกฤษ, หรือทั้งสองภาษา?
- **Situation**: ผู้ใช้กำลังทำอะไรอยู่ตอนเห็นข้อความนี้? อารมณ์ขณะนั้นเป็นอย่างไร?
- **Tone**: มี brand voice/tone ที่กำหนดไว้หรือยัง? (ถ้ายังไม่มี จะใช้ Standard Tone)
- **Existing Design**: มี Figma URL ที่ต้องเขียน copy ใส่ไหม?
- **Scope**: เขียนทั้งหน้า หรือเฉพาะบาง element?

ถ้ามี Figma URL:
```
get_screenshot(fileKey, nodeId)       → ดู visual context
scan_text_nodes(nodeId)               → อ่าน text ที่มีอยู่ทั้งหมด
read_my_design()                      → ดู design ที่เลือก
```

---

## Step 2: Voice & Tone

### 2.1 Standard Voice (ค่าเริ่มต้น)

| Attribute | คำอธิบาย |
|-----------|----------|
| **ชัดเจน** | ตรงประเด็น ไม่อ้อมค้อม อ่านรู้เรื่องในครั้งเดียว |
| **เป็นมิตร** | เข้าถึงง่าย ไม่เป็นทางการเกินไป ไม่ใช่หุ่นยนต์ |
| **ช่วยเหลือ** | บอกสิ่งที่ต้องทำ ไม่ใช่แค่บอกปัญหา |
| **เคารพ** | ไม่โทษผู้ใช้ ไม่ใช้ศัพท์เทคนิคโดยไม่จำเป็น |
| **มั่นใจ** | สื่อสารอย่างแน่นอน ไม่คลุมเครือ |

### 2.2 Voice Chart (6 Dimensions)

สำหรับ brand ที่ต้องการกำหนด voice ละเอียด ใช้ Voice Chart จาก `references/ux-writing-patterns.md`:

| Dimension | Standard Voice Default |
|-----------|----------------------|
| **Concepts** | ใช้คำเรียบง่าย ไม่ใช้ metaphor ซับซ้อน |
| **Vocabulary** | คำทั่วไปที่คนทุกวัยเข้าใจ |
| **Verbosity** | กระชับ ตรงประเด็น 1-2 ประโยค |
| **Grammar** | Active voice, ประโยคสั้น |
| **Punctuation** | ใช้ ... สำหรับ loading, ! ไม่เกิน 1/หน้า |
| **Capitalization** | Sentence case (EN) |

ถ้าผู้ใช้มี brand voice → ให้สร้าง Voice Chart ครบ 6 dimensions ก่อนเขียน copy

### 2.3 Tone ตามสถานการณ์

| สถานการณ์ | Tone | ตัวอย่าง (ไทย) | ตัวอย่าง (EN) |
|-----------|------|----------------|---------------|
| สำเร็จ / ยินดี | อบอุ่น, ยินดีด้วย | "สมัครสมาชิกเรียบร้อยแล้ว" | "You're all set!" |
| ข้อผิดพลาด | สงบ, ช่วยเหลือ | "กรอกอีเมลไม่ถูกรูปแบบ ลองตรวจอีกครั้ง" | "That email doesn't look right." |
| คำเตือน | จริงจัง, ชัดเจน | "ลบแล้วจะกู้คืนไม่ได้" | "This can't be undone." |
| รอ / โหลด | ผ่อนคลาย | "กำลังเตรียมข้อมูลให้..." | "Getting things ready..." |
| ว่างเปล่า | ให้กำลังใจ | "ยังไม่มีรายการ เริ่มเพิ่มตัวแรกกันเลย" | "Nothing here yet." |
| Onboarding | ตื่นเต้น | "มาเริ่มกันเลย!" | "Let's get you started!" |
| ขออนุญาต | เปิดเผย | "เราต้องใช้ตำแหน่งเพื่อแสดงร้านค้าใกล้เคียง" | "We need your location." |

### 2.4 Custom Tone
ถ้าผู้ใช้กำหนด brand voice/tone → สร้าง Voice Chart 6 dimensions ก่อน จดไว้และใช้ตลอด session ปรับตาม tone matrix แต่คง brand voice

---

## Step 3: Write — เขียน Copy ตาม 11 Text Patterns

ใช้ 11 UX Text Patterns (รายละเอียดเต็มดู `references/ux-writing-patterns.md`):

### 3.1 Quick Reference — 11 Patterns

| # | Pattern | ความยาว | สูตร/กฎหลัก |
|---|---------|---------|-------------|
| 1 | **Titles** | 1-5 คำ | Noun/verb phrase บอกว่าอยู่ที่ไหน |
| 2 | **Buttons** | 1-2 คำ (best) | Verb-first, match กับ title, ห้าม "ตกลง/OK" |
| 3 | **Descriptions** | <40 chars, ≤3 lines | ตอบ "ทำไมต้องสนใจ?" |
| 4 | **Empty States** | 1-2 ประโยค | "หากต้องการ [ผลลัพธ์] ให้ [ทำ action]" |
| 5 | **Labels** | 1-3 คำ | Noun, ไม่ลงท้ายด้วย : |
| 6 | **Controls** | phrase | อ่านเป็นประโยคได้เมื่อรวมกับ control |
| 7 | **Text Inputs** | 4 ส่วน | Label + Placeholder (ตัวอย่างจริง) + Helper + Error |
| 8 | **Transitional** | สั้น + ... | บอก "กำลังทำอะไร" ไม่ใช่ "กำลังโหลด" |
| 9 | **Confirmations** | 1-2 ประโยค | [Action สำเร็จ] + [ข้อมูลสำคัญ] + [ขั้นตอนถัดไป] |
| 10 | **Notifications** | 1 บรรทัด | [Source]: [Content] + [Action hint] |
| 11 | **Errors** | 1-2 ประโยค | สอนวิธีทำให้ถูก ไม่บอกว่าทำผิด |

### 3.2 Button Best Practices (สำคัญ)

- **1-2 คำ perform ดีที่สุด** — ตัด filler words
- **Match button text กับ title**: Title "ลบบัญชี" → Button "ลบบัญชี" ไม่ใช่ "ตกลง"
- **Destructive pairs**: Primary = action ตรง ("ลบ"), Secondary = "ยกเลิก"

| Pattern | ไทย | EN |
|---------|-----|-----|
| Verb-only | บันทึก | Save |
| Verb + Object | บันทึกที่อยู่ | Save address |
| Verb + Benefit | เริ่มทดลองฟรี | Start free trial |

### 3.3 Error Writing Rules (สำคัญ)

**หลักการ**: "สอนวิธีทำให้ถูก อย่าบอกว่าทำผิด"
**ห้ามใช้**: "invalid", "failed", "disabled", "ไม่ถูกต้อง", "ผิดพลาด"

| Type | ตำแหน่ง | สูตร |
|------|---------|------|
| **Inline** | ใต้ input | ข้ามปัญหา → บอกวิธีแก้เลย: "ใช้ตัวอักษรอย่างน้อย 8 ตัว" |
| **Detour** | Banner/Toast | [ปัญหา] + [วิธีแก้]: "อีเมลนี้มีบัญชีแล้ว — เข้าสู่ระบบ" |
| **Blocking** | Full-screen | [ปัญหา] + [วิธีแก้] + [CTA]: "ไม่สามารถเชื่อมต่อ ลองอีกครั้ง" |

### 3.4 Confirmation Dialogs (Destructive)
**สูตร: [ผลที่จะเกิดขึ้น] + [ย้อนกลับได้ไหม]**
- Button = action ตรง ("ลบบัญชี") ไม่ใช่ "ตกลง"

### 3.5 Onboarding
- Step title + subtitle อธิบาย value (ไม่ใช่ feature)
- CTA + Skip option เสมอ

### 3.2 ภาษาไทย — หลักการเฉพาะ

- ไม่ใช้ราชาศัพท์ ใช้ภาษาปกติ
- ไม่ห้วนเกินไป ใส่คำนุ่มนวลเล็กน้อย
- ครับ/ค่ะ ใช้ใน chatbot ได้ แต่ UI ปกติไม่จำเป็น
- ใช้คำไทยถ้ามี แต่ทับศัพท์ได้ถ้าคุ้นเคยกว่า
- สะกดทับศัพท์ตามราชบัณฑิต
- ไม่ใช้ "ของคุณ" ทุกที่ ไม่ขึ้นต้นด้วย "กรุณา" ทุกครั้ง

### 3.3 ภาษาอังกฤษ — หลักการเฉพาะ

- Sentence case, Use contractions, Avoid "please"
- Use "you/your" sparingly, Active voice
- Front-load keywords, No jargon, Oxford comma

---

## Step 4: Edit — 4-Phase Editing Process

ตรวจ copy ทุกครั้งผ่าน 4 เฟส (จาก "Nicely Said"):

### 4.0 Four Phases

| Phase | คำถามหลัก | ทำอะไร |
|-------|----------|--------|
| **1. Purposeful** | ข้อความนี้ช่วย user ทำอะไร? | ตัดข้อความที่ไม่ advance user's goal |
| **2. Concise** | ตัดคำไหนออกได้? | "ทำการบันทึก" → "บันทึก", "คุณสามารถ...ได้" → ตัด |
| **3. Conversational** | อ่านออกเสียงแล้วเป็นธรรมชาติไหม? | ถ้าพูดกับเพื่อนจะพูดแบบนี้ไหม? |
| **4. Clear** | อ่านครั้งเดียวเข้าใจไหม? | คนที่ไม่รู้ context จะเข้าใจไหม? |

### 4.1 UX Writing Checklist (หลังผ่าน 4 Phases)

| # | Check | คำถาม |
|---|-------|-------|
| 1 | **ชัดเจน** | อ่านครั้งเดียวเข้าใจไหม? (Phase 4) |
| 2 | **กระชับ** | ตัดคำไม่จำเป็นออกแล้ว? (Phase 2) |
| 3 | **มีจุดประสงค์** | ข้อความนี้ช่วย user ทำอะไร? (Phase 1) |
| 4 | **เป็นธรรมชาติ** | อ่านออกเสียงแล้วเหมือนคนพูดไหม? (Phase 3) |
| 5 | **เหมาะกับ Tone** | Tone ตรงกับสถานการณ์ + Voice Chart? |
| 6 | **ไม่โทษผู้ใช้** | ภาษาเชิงบวก/กลางๆ? ไม่ใช้ "invalid/failed"? |
| 7 | **เข้าถึงได้** | หลีกเลี่ยงศัพท์เทคนิค? inclusive? |
| 8 | **สม่ำเสมอ** | ใช้คำเดียวกันเรียกสิ่งเดียวกัน? (ดู Terminology Table) |
| 9 | **ครบทุก state** | มี copy สำหรับ success, error, empty, loading? |
| 10 | **Button ตรง context** | Button text match กับ title? ไม่ใช่ "ตกลง"? |
| 11 | **Error สอนวิธีแก้** | สอนวิธีทำให้ถูก ไม่บอกว่าทำผิด? |
| 12 | **Localization-ready** | ใช้พื้นที่ EN 50-67%? ไม่ concat strings? |
| 13 | **สะกดถูก** | ตรวจ typo, ทับศัพท์? (ดู Section 4.2) |

### 4.2 Spell & Grammar Check

ตรวจคำผิดทุกข้อความ — ทั้งสะกดผิด, ไวยากรณ์ผิด, ทับศัพท์ผิด, เว้นวรรคผิด

**วิธีใช้**: สแกนข้อความ → ตรวจทีละประโยค → แก้ไข → สร้าง Correction Log

**ตารางคำผิด + ไวยากรณ์ + Correction Log format**: ดู `references/ux-writing-spellcheck.md`

#### เมื่อตรวจจาก Figma

```
1. scan_text_nodes(nodeId)                → ดึง text ทั้งหมด
2. ตรวจทุก text node ด้วยหลักการจาก references/ux-writing-spellcheck.md
3. สร้าง Correction Log
4. (Optional) แก้ text: set_multiple_text_contents(parentId, [...])
5. (Optional) ใส่ annotation: set_multiple_annotations({...})
```

### 4.3 Terminology Consistency Table

สร้างตาราง terminology เพื่อให้ทั้ง app ใช้คำเดียวกัน:

```markdown
| Concept | ไทย | English | ห้ามใช้ |
|---------|-----|---------|---------|
| Sign in | เข้าสู่ระบบ | Sign in | ล็อกอิน, Login |
| Sign up | สมัครสมาชิก | Create account | ลงทะเบียน, Register |
| Sign out | ออกจากระบบ | Sign out | ล็อกเอาท์, Logout |
| Password | รหัสผ่าน | Password | พาสเวิร์ด |
| Delete | ลบ | Delete | เอาออก, Remove |
| Save | บันทึก | Save | เซฟ |
| Cancel | ยกเลิก | Cancel | — |
| Settings | การตั้งค่า | Settings | — |
| Search | ค้นหา | Search | เสิร์ช, หา |
```

### 4.4 Character Count

ดูตาราง max character count ต่อ element ที่ `references/ux-writing-spellcheck.md` > Character Count Guidelines

---

## Step 5: Score — UX Content Heuristics Scorecard

ให้คะแนน copy ตาม 2 มิติ (รายละเอียดเต็มดู `references/ux-writing-patterns.md`):

### Usability (น้ำหนัก 2/3)

| # | Heuristic | คะแนน (1-5) |
|---|-----------|-------------|
| 1 | **Accessible** — ผู้พิการใช้ได้ไหม? | — |
| 2 | **Findable** — หาข้อความเจอง่ายไหม? | — |
| 3 | **Clear** — อ่านครั้งเดียวเข้าใจไหม? | — |
| 4 | **Useful** — ช่วย user ทำสิ่งที่ต้องการได้จริง? | — |
| 5 | **Appropriate** — เหมาะกับ context? | — |
| 6 | **Translatable** — แปลเป็นภาษาอื่นได้ง่าย? | — |

### Voice (น้ำหนัก 1/3)

| # | Heuristic | คะแนน (1-5) |
|---|-----------|-------------|
| 1 | **Concepts** — ตรง brand voice? | — |
| 2 | **Vocabulary** — ใช้คำศัพท์เหมาะสม? | — |
| 3 | **Verbosity** — ความยาวเหมาะสม? | — |
| 4 | **Grammar** — โครงสร้างประโยคดี? | — |
| 5 | **Punctuation** — เครื่องหมายถูกต้อง? | — |
| 6 | **Capitalization** — ตัวพิมพ์เหมาะสม? | — |

### Rating

| คะแนน | ระดับ | Action |
|-------|-------|--------|
| 4.5-5.0 | ดีเยี่ยม | Ship ได้เลย |
| 3.5-4.4 | ดี | ปรับเล็กน้อย |
| 2.5-3.4 | ปานกลาง | ต้อง revise |
| 1.0-2.4 | ต้องปรับปรุง | เขียนใหม่ |

---

## Step 6: Apply — ใส่ Text เข้า Design (Optional)

### Option A: Apply ลง HTML Preview File
- ใช้ Read tool อ่านไฟล์ `.html`
- ใช้ Edit tool แก้ text content โดยตรง
- User refresh browser เห็นผลทันที

### Option B: Apply ลง Figma
```
scan_text_nodes(nodeId)                        → ดู text ทั้งหมด
set_multiple_text_contents(parentId, [...])    → แก้หลาย nodes พร้อมกัน
set_multiple_annotations({...})                → ใส่ annotation อธิบาย copy decisions
```

---

---

## Output Formats

### Copy Deck Table (Output หลัก)

```markdown
## Copy Deck: [Screen Name]

### Voice & Tone
- Voice: [Standard / Custom]
- Tone: [ตาม situation]

### Copy
| # | Element | Location | ไทย | English | Tone | Max Length | Notes |
|---|---------|----------|-----|---------|------|-----------|-------|

### Terminology
| Concept | ไทย | English |
|---------|-----|---------|
```

### Content Audit Table (เมื่อ review copy ที่มีอยู่)

```markdown
## Content Audit: [Screen Name]
| # | Element | Current Copy | Issue | Recommended | Principle |
|---|---------|-------------|-------|-------------|-----------|
```

---

## หลักการสำคัญ

1. **ชัดเจนเหนือสิ่งอื่นใด**: ถ้าต้องเลือกระหว่างสวยกับชัด เลือกชัด
2. **อ่านครั้งเดียวเข้าใจ**: ผู้ใช้ไม่ควรต้องอ่านซ้ำ
3. **ทุกข้อความมีหน้าที่**: ถ้าตัดออกแล้วไม่เสียอะไร ให้ตัด (Phase 1: Purposeful)
4. **สอนวิธีทำให้ถูก อย่าบอกว่าทำผิด**: Error messages = instructive, ไม่ใช้ "invalid/failed"
5. **Button 1-2 คำ match title**: "ลบบัญชี" ไม่ใช่ "ตกลง" — ตรงกับ context
6. **ภาษาของผู้ใช้ ไม่ใช่ภาษาของระบบ**: "บันทึกแล้ว" ไม่ใช่ "Data saved successfully"
7. **Bilingual Consistency**: ไทยและอังกฤษสื่อความหมายเดียวกัน ไม่ต้องแปลตรงตัว
8. **ครบทุก State**: default, success, error, empty, loading
9. **Terminology เดียวกันทั้ง App**: ใช้ terminology table ตลอด
10. **Test ด้วยการอ่านออกเสียง**: ถ้าพูดแล้วเข้าใจ เขียนก็เข้าใจ (Phase 3: Conversational)
11. **Localization-ready**: EN ใช้พื้นที่ 50-67% / ไม่ concatenate strings / ไม่ใช้ idiom
12. **Inclusive**: ไม่สมมติเพศ/อายุ/ความสามารถ ใช้ people-first language

---
name: jira-req-analysis
description: "วิเคราะห์ Requirements จาก Jira Card ของ BA เพื่อเตรียม UI Design Scope ดึงข้อมูลจาก Jira MCP หรือรับ text จากผู้ใช้ แยกวิเคราะห์เป็น User Stories, Acceptance Criteria, Edge Cases, Screen List ใช้ skill นี้เมื่อผู้ใช้ต้องการ: วิเคราะห์ requirement, อ่าน Jira card, BA analysis, หรือเมื่อพิมพ์ 'jira', 'analyse req', 'วิเคราะห์ requirement', 'card analysis', 'BA req', 'jira card'"
---

# Jira Requirement Analysis Skill

วิเคราะห์ Requirements จาก Jira Card ของ BA เพื่อเตรียม UI Design Scope

---

## Step 1: รับ Jira Card

### ถ้ามี Jira MCP (ตรวจจาก tools ที่ available)

ถาม issue key แล้วดึงข้อมูล:

```
jira_get(
  path: "/rest/api/3/issue/{issueKey}",
  jq: "{key: key, summary: fields.summary, description: fields.description, status: fields.status.name, priority: fields.priority.name, labels: fields.labels, issueType: fields.issuetype.name}"
)
```

ดึง comments ด้วย:
```
jira_get(
  path: "/rest/api/3/issue/{issueKey}/comment",
  jq: "comments[*].{author: author.displayName, body: body, created: created}",
  queryParams: { maxResults: "10" }
)
```

ถ้ามี subtasks:
```
jira_get(
  path: "/rest/api/3/search/jql",
  queryParams: { jql: "parent={issueKey}", maxResults: "20" },
  jq: "issues[*].{key: key, summary: fields.summary, status: fields.status.name}"
)
```

### ถ้าไม่มี Jira MCP

ถามผู้ใช้:
> "กรุณา paste เนื้อหา requirement จาก Jira card มาเลยครับ (summary, description, acceptance criteria)"

---

## Step 2: วิเคราะห์ Requirements

จาก Jira card ให้แยกวิเคราะห์เป็น:

### 2.1 User Stories

แยก requirement ออกเป็น User Stories format:
```
As a [user type], I want to [action], so that [benefit]
```

### 2.2 Acceptance Criteria

ดึง acceptance criteria (AC) ออกมาเป็น checklist:
- AC ที่เขียนไว้ใน card
- AC ที่ implied จาก description
- AC ที่ขาดหายไป (แนะนำเพิ่ม)

### 2.3 Business Rules

สรุปกฎเฉพาะ:
- Validation rules (format, length, required fields)
- Permission/role ที่เกี่ยวข้อง
- Limits/quotas
- Dependencies กับระบบอื่น

### 2.4 Edge Cases

ระบุ edge cases ที่ต้องออกแบบ:
| Case | Description | ต้องมี UI สำหรับ? |
|------|-------------|-------------------|
| Empty State | ยังไม่มีข้อมูล | ใช่ |
| Error State | API fail, validation error | ใช่ |
| Loading State | กำลังโหลดข้อมูล | ใช่ |
| Success State | ทำสำเร็จแล้ว | ใช่ |
| Permission Denied | ไม่มีสิทธิ์ | ตรวจสอบ |
| Offline | ไม่มี internet | ตรวจสอบ |
| Long Text | ข้อความยาวเกิน | ใช่ |
| Max Items | ข้อมูลเยอะมาก | ตรวจสอบ |
| First Time User | ใช้ครั้งแรก | ตรวจสอบ |

### 2.5 Dependencies

- Feature/screen อื่นที่เกี่ยวข้อง
- API endpoints ที่ต้องใช้
- Data models

---

## Step 3: สรุป UI Scope

Output เป็น structured summary:

### Screen List

| # | Screen Name | Description | Priority |
|---|-------------|-------------|----------|
| 1 | ... | ... | Must have |
| 2 | ... | ... | Must have |
| 3 | ... | ... | Nice to have |

### State Matrix

| Screen | Default | Filled | Error | Loading | Success | Empty |
|--------|---------|--------|-------|---------|---------|-------|
| Screen 1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Screen 2 | ✅ | ✅ | ✅ | - | ✅ | - |

### Component List

รายการ component ที่ต้องออกแบบ:
- Navigation: tabs, back button, etc.
- Forms: input fields, dropdowns, etc.
- Actions: buttons, links, etc.
- Feedback: toast, alerts, etc.
- Content: cards, lists, etc.

### User Flow Summary

**Happy Path**:
1. User เข้า screen → ...
2. User กรอกข้อมูล → ...
3. User กดยืนยัน → ...
4. แสดง success → ...

**Error Paths**:
- Validation error → แสดง inline error
- API error → แสดง error dialog
- ...

---

## Step 4: แนะนำ Design Approach

### Platform Pattern

อ้างอิง platform guidelines:
- **iOS**: อ่าน `references/hig.md` — navigation, modals, forms
- **Android**: อ่าน `references/material-design.md` — components, layout
- **Web**: อ่านทั้งสอง + responsive patterns

### UX Principles ที่เกี่ยวข้อง

อ่าน `references/ux-principles.md` แล้วแนะนำ:
- **H1 (Visibility)**: ผู้ใช้ต้องเห็น status ตลอด
- **H3 (User Control)**: มี undo/back ทุกจุด
- **H5 (Error Prevention)**: validate ก่อน submit
- **H9 (Error Recovery)**: error message ชัดเจน + วิธีแก้
- **Hick's Law**: ลด choices ต่อ screen
- **Miller's Law**: จัดกลุ่มข้อมูล 5-9 items
- (แนะนำตาม context ของ requirement)

### Design Tokens ที่เกี่ยวข้อง

อ่าน `references/design-tokens.md` แล้วระบุ:
- Color tokens ที่ใช้ (primary, error, success, etc.)
- Typography ที่เหมาะสม (heading, label, caption)
- Spacing pattern
- Component patterns

### Similar App/Pattern References

แนะนำ app ที่มี pattern คล้ายกัน เพื่อเป็น reference

---

## Step 5: ส่งต่อไป IA + User Flow

> **Pipeline**: `Jira BA` → **IA + User Flow** → `UI Design` → `QA Gate` → ส่งมอบ

เมื่อ user review สรุปแล้ว ถาม:

> "พร้อมลาก IA และ User Flow ไหมครับ? ผมจะวาง Information Architecture และออกแบบ flow ก่อนเริ่มทำหน้าจอ"

เมื่อ user ตอบพร้อม:
- ใช้ข้อมูลจาก Step 1-4 เป็น input สำหรับ **figma-user-flow** skill
- ส่ง: Screen list, User stories, User flow summary, Edge cases, Dependencies ไปเป็น requirements
- **figma-user-flow** จะสร้าง IA, Screen Map, Navigation Matrix, User Flow diagrams
- เมื่อ flow เสร็จ → ส่งต่อไป **figma-ui-design-spec** → สร้าง HTML preview
- เมื่อ HTML เสร็จ → ส่งต่อไป **html-qa-gate** → ตรวจคุณภาพก่อนส่งมอบ

---

## Output Format

### UI Requirements Summary

```markdown
# UI Requirements Summary

## Source
- Jira: {ISSUE_KEY} — {Summary}
- Status: {Status}
- Priority: {Priority}

## User Stories
1. As a {user}, I want to {action}, so that {benefit}
2. ...

## Screens to Design
| # | Screen | States | Components |
|---|--------|--------|------------|
| 1 | ... | default, filled, error, loading, success | ... |
| 2 | ... | ... | ... |

## User Flow
{Happy path + error paths}

## Edge Cases
{Edge case list}

## Design Approach
- Platform: {iOS/Android/Web}
- Key UX Principles: {H1, H5, H9, ...}
- Design Tokens: {primary, error, ...}
- References: {similar apps}

## Acceptance Criteria Checklist
- [ ] AC 1
- [ ] AC 2
- ...
```

---
name: html-presentation-slide
description: "สร้าง HTML Presentation Slide (16:9) แบบ self-contained พร้อม Navigation ครบชุด ใช้สำหรับ Weekly Update, Sprint Review, Project Demo หรือ Presentation ใดๆ ใช้ skill นี้เมื่อผู้ใช้ต้องการ: สร้าง slide, ทำ presentation, weekly update slide, sprint review deck, สร้าง deck, project presentation, หรือเมื่อพิมพ์ 'slide', 'presentation', 'deck', 'weekly update', 'sprint review', 'present'"
---

# HTML Presentation Slide Skill

สร้างไฟล์ `.html` self-contained เปิดใน browser ได้ทันที เป็น Presentation Slide 16:9 พร้อม Navigation ครบชุด

---

## Overall Flow

```
1. Requirements → 2. Read Design Tokens → 3. สร้าง HTML Slide → 4. Iterate → 5. Push to GitHub
```

1. **Requirements**: ถามเนื้อหา, จำนวนหน้า, theme
2. **Design Tokens**: อ่าน references/design-tokens.md สำหรับ color/typography
3. **สร้าง HTML**: สร้างไฟล์ .html ที่เปิดได้ใน browser ทันที
4. **Iterate**: User เปิดดู → บอก Claude แก้ → refresh
5. **Push**: commit และ push ขึ้น GitHub

---

## Step 1: รวบรวม Requirements

ถามข้อมูลเหล่านี้ (ถ้ายังไม่ระบุ):

- **หัวข้อ Presentation**: เช่น Weekly Update — Week 1
- **จำนวน Slide โดยประมาณ**: ปกติ 10-20 หน้า
- **เนื้อหาแต่ละหน้า**: Agenda, Planning, Outcome, Demo, Nextstep ฯลฯ
- **รูปภาพ**: มี path ของรูปที่ต้องใส่ไหม?
- **Theme**: ใช้ Design Token ของโปรเจกต์ หรือ custom?
- **Project Logo**: มี SVG logo ไหม?

---

## Step 2: อ่าน Design Tokens

```
references/design-tokens.md → อ่านเสมอ สำหรับ color, typography, spacing, radius
```

---

## Step 3: สร้าง HTML Slide

### Architecture: Single HTML File

ไฟล์ `.html` เดียว self-contained ทั้ง CSS + JS ไม่ต้องพึ่ง external library ใดๆ (ยกเว้น Google Fonts)

### CSS/HTML/JS Templates

ดูรายละเอียด templates ทั้งหมดที่ `references/slide-templates.md`:

- **Design Tokens (CSS Variables)** — `:root` variables สำหรับ color, spacing, radius, shadow, motion
- **Slide Viewport (16:9)** — Container หลักรักษา aspect ratio
- **Slide Structure** — `<div class="slide" data-slide="N">` format
- **Slide Transition CSS** — Smooth slide-left/slide-right animation
- **Background Gradient Presets** — สลับ gradient แต่ละ slide
- **Decorative Elements** — Circle blur + dot pattern
- **Content Layouts** — Header bar, content area, layout variants
- **Typography** — `clamp()` responsive font sizes

---

## Step 4: Navigation Components

ดูรายละเอียด CSS/HTML ที่ `references/slide-templates.md` > Navigation Components

### ต้องมีทั้ง 3 ส่วน:

1. **Top Bar** (absolute top-right ใน viewport):
   - **Present Button** — แสดงเฉพาะ Cover Slide เมื่อไม่ได้ fullscreen
   - **Pages Dropdown** — แสดงทุกหน้ายกเว้น Cover (ยกเว้น fullscreen แสดงทุกหน้า)

2. **Bottom Nav Bar** (absolute bottom ใน viewport):
   - Home button (ไปหน้าแรก)
   - Prev/Next buttons
   - Counter (1/16)

3. **Present Hint Text** — เฉพาะ Cover Slide: "กดปุ่ม F เพื่อเข้าโหมด Present"

---

## Step 5: JavaScript (Navigation Engine)

ดูรายละเอียด JS code ที่ `references/slide-templates.md` > JavaScript (Navigation Engine)

**ต้องมีเสมอ** — ใส่ก่อน `</body>`:

- **goToSlide(index)** — transition animation
- **nextSlide() / prevSlide()** — increment/decrement
- **updateNavBar()** — update counter, dark mode, dropdown visibility
- **Keyboard**: ArrowRight/Left/Up/Down, Space, Home, End, F
- **Touch**: swipe left/right (threshold 50px)
- **Fullscreen**: enterPresent() toggle
- **Pages Dropdown**: buildDropdownMenu(), togglePageDropdown()
- **slideTitles[]** array — ชื่อ slide ทั้งหมด

---

## Visibility Rules Summary

| Component | Cover (ไม่ fullscreen) | Cover (fullscreen) | หน้าอื่นๆ |
|-----------|-----|-----|-----|
| Present Button | แสดง | ซ่อน | ซ่อน |
| Pages Dropdown | ซ่อน | แสดง | แสดง |
| Nav Bar (Home + Prev/Next) | แสดง | แสดง | แสดง |
| Present Hint Text | แสดง (ใน cover) | แสดง | ไม่มี |

---

## Slide Type Templates

### Cover Slide
- gradient background + decorative circles
- โลโก้โปรเจกต์ (SVG)
- วันที่ + ชื่อ Presentation + subtitle
- tags (project name, topic)
- character image (ถ้ามี)
- present hint text

### Content Slide (Two Column)
- slide-header (logo + section label)
- `.slide-content.two-col` → `.col-text` + `.col-visual`

### Content Slide (Full Width)
- slide-header
- `.slide-content` → เนื้อหา full width (timeline, calendar, grid, etc.)

### Image Gallery Slide
- slide-header
- grid ของรูปภาพ (CSS Grid)

### Thank You Slide
- gradient background + decorative circles
- "Thank you!" title + "Questions & Discussion"

---

## Checklist ก่อนส่งมอบ

- [ ] ทุก slide มี `data-slide` attribute เรียงลำดับ 0, 1, 2, ...
- [ ] Slide แรกมี class `active`
- [ ] `slideTitles` array ตรงกับจำนวนและลำดับ slide
- [ ] Background gradient สลับกันทุก slide (ไม่ซ้ำติดกัน)
- [ ] Dark slide มี class `dark-slide` เพื่อ toggle nav theme
- [ ] Navigation ครบ: Home btn, Prev/Next, Counter, Pages dropdown, Present btn
- [ ] Keyboard shortcuts ทำงาน: Arrow keys, Space, Home, End, F
- [ ] Touch swipe ทำงาน
- [ ] Fullscreen mode ทำงาน + nav ยังแสดง
- [ ] Typography ใช้ `clamp()` ทั้งหมด
- [ ] รูปภาพมี `object-fit: contain` หรือ `cover` ตามเหมาะสม

---

## Troubleshooting

### Slide transition กระตุก
**Cause**: CSS transition conflict หรือ reflow ไม่ trigger
**Solution**: ตรวจว่ามี `newSlide.offsetHeight;` ก่อน remove enter-from class

### Nav bar ไม่เปลี่ยนเป็น dark mode
**Cause**: slide ไม่มี class `dark-slide`
**Solution**: เพิ่ม `dark-slide` class ให้ slide ที่ background เข้ม

### Fullscreen ไม่ทำงาน
**Cause**: Browser block fullscreen ถ้าไม่ได้เกิดจาก user gesture
**Solution**: enterPresent() ต้องเรียกจาก onclick/onkeydown เท่านั้น

### Pages Dropdown แสดงผิดจำนวน
**Cause**: slideTitles array ไม่ตรงกับจำนวน slide
**Solution**: นับ `data-slide` attributes ให้ตรงกับ slideTitles.length

---
name: html-qa-gate
description: "ตรวจคุณภาพ HTML file อัตโนมัติก่อนส่งมอบ (Pre-Dev Design Review) ครอบคลุม Functional Intent, Component & Visual Readiness, Handoff Check พร้อม auto-fix และวนตรวจซ้ำ (max 3 รอบ) ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ตรวจ HTML, QA check, ตรวจงาน, เช็คคุณภาพ, validate HTML, ตรวจก่อนส่ง, design review, handoff check, หรือเมื่อพิมพ์ 'QA', 'qa gate', 'ตรวจงาน', 'check html', 'validate', 'ตรวจคุณภาพ', 'quality check', 'เช็คงาน', 'handoff', 'pre-dev'"
---

# HTML QA Gate Skill

Pre-Dev Design Review — ตรวจคุณภาพ HTML file ก่อนส่งมอบ 3 Part / 10 จุดตรวจ
แก้ไขอัตโนมัติ แล้ววนตรวจใหม่จนผ่าน (สูงสุด 3 รอบ)

## Pipeline Position

```
Jira BA → IA + User Flow → UI Design → [QA Gate] → ส่งมอบ
                                          ▲ อยู่ตรงนี้ (ด่านสุดท้ายก่อนส่งมอบ)
```

Skill นี้เป็น **ด่านสุดท้าย** ก่อนที่ HTML จะถึงมือ user — ตรวจทุก HTML file ที่ผ่านมาจาก:
- **figma-ui-design-spec** → HTML preview ของหน้าจอ app/web
- **html-presentation-slide** → HTML presentation slides
- **file อื่นๆ** → HTML file ใดๆ ที่ต้องการ QA

## เป้าหมาย

```
Dev เปิด Figma แล้ว "เข้าใจทันที"
ไม่มีคำถามซ้ำเรื่อง spacing / state / behavior
ลด loop แก้งานระหว่าง Design <> Dev
```

นี่ไม่ใช่ QA สำหรับ production — แต่คือ **Design Thinking QA** ลด friction ระหว่าง Design <> Dev

---

## Overall Flow

```
1. Receive → 2. Read References → 3. Audit (3 Parts / 10 Points) → 4. Report → 5. Auto-fix → 6. Re-audit (loop max 3) → 7. Final Report
```

```
[รับ HTML file] → [ตรวจ 10 จุด] → ผ่านทั้งหมด? ── YES ──→ [PASS Report → ส่งให้ user]
                                        │ NO
                              [Auto-fix] → [ตรวจใหม่] → (วน max 3 รอบ) → [Final Report]
```

---

## Step 1: Receive HTML File

1. **ระบุ path โดยตรง**: ผู้ใช้บอก path ของ HTML file
2. **ต่อเนื่องจาก skill อื่น**: หลังจาก `figma-ui-design-spec` หรือ `html-presentation-slide` สร้าง HTML เสร็จ
3. **Glob search**: ค้นหา `**/*.html` เลือกไฟล์ที่ modified ล่าสุด ถามยืนยันก่อนตรวจ

อ่าน HTML file ด้วย **Read tool** แล้ว Parse แยก: `<style>`, `<body>`, `<script>`

---

## Step 2: อ่าน References

```
references/design-tokens.md           → สำหรับตรวจ color tokens, spacing tokens (อ่านเสมอ)
references/ux-principles.md           → สำหรับตรวจ usability, heuristics (อ่านเสมอ)
references/qa-gate-criteria.md        → รายละเอียดการตรวจแต่ละจุด (อ่านเสมอ)
references/ui-preview-quality-rules.md → กฎ Visual Design จาก Refactoring UI, Practical UI, Laws of UX (อ่านเสมอ)
```

---

## Step 3: Audit — 3 Part / 10 จุด

### State Management

```
round = 1, maxRounds = 3, issues = [], fixes = []
```

### PART 1: Functional Intent — ดีไซน์สื่อพฤติกรรมได้ครบ

| # | Point | สิ่งที่ตรวจ |
|---|-------|-----------|
| 1 | **User Flow Clarity** | หน้ามี purpose ชัด, primary CTA โดดเด่น, visual hierarchy ถูกต้อง |
| 2 | **State Coverage** | มีอย่างน้อย 4 states: Default, Loading, Empty, Error |
| 3 | **Interaction Intent** | Interactive elements มี cursor/hover/active, disabled ดู disabled |
| 4 | **Form Logic** | Required fields มองออก, error position ใกล้ input, overflow handling |

### PART 2: Component & Visual Readiness — ไฟล์สะอาด ใช้งานต่อได้

| # | Point | สิ่งที่ตรวจ |
|---|-------|-----------|
| 5 | **Component Hygiene** | ปุ่ม/input/card ใช้ style consistent, ไม่มี duplicate hex |
| 6 | **Naming & Structure** | Class names สื่อความหมาย, semantic HTML, heading hierarchy |
| 7 | **Layout & Spacing** | ใช้ 4px/8px grid, sibling spacing consistent, alignment ตรง |
| 8 | **Typography** | Text style system, heading/body แยกชัด, line-height สัมพันธ์กับ size, line length 60-80 chars, ห้ามลด contrast เพื่อ de-emphasize |
| 9 | **Color & Token** | ใช้ CSS variables, สีสถานะถูก, WCAG contrast ผ่าน, near-black/near-white (ไม่ใช่ pure #000/#FFF), 60-30-10 ratio, neutral มี hue shift |
| 10 | **Visual Design Quality** | Shadow blur=2x distance, outer padding >= inner, button padding h=2x v, nested radius=outer-gap, ไม่มี adjacent hard divides, empty state มี content |
| 11 | **Responsive Intent** | Desktop layout + mobile intent, slide viewport 16:9 (ถ้าเป็น slide) |

### PART 3: Ready to Handoff

| # | Check | PASS Criteria |
|---|-------|---------------|
| H1 | ไม่มี element "คิดเอาเอง" | ไม่มี element ที่หลุดจาก token system |
| H2 | ไม่มี style เฉพาะจุดที่ไม่อธิบาย | Inline styles ไม่เกิน 20% |
| H3 | Component ใช้ตรงกัน | ทุก component type = 1 base style |
| H4 | ไม่มี placeholder มั่ว | ไม่มี "Lorem", "test", "xxx", "TBD", "TODO" |
| H5 | Dev ไม่ต้องเดา behavior | ผ่าน Point 1-4 (Functional Intent) |

**รายละเอียดการตรวจแต่ละจุด**: ดู `references/qa-gate-criteria.md`

---

## Step 4: Report

### Report Template

```markdown
# QA Gate Report: [filename.html]

## Summary
- **Round**: [N/3]
- **Status**: PASS / FAIL
- **Result**: [X/10] points passed

## Score Board

### PART 1: Functional Intent
| # | Point | Status | Issues | Auto-fixed | Remaining |
|---|-------|--------|--------|------------|-----------|
| 1 | User Flow Clarity | PASS/FAIL | N | N | N |
| 2 | State Coverage | PASS/FAIL | N | N | N |
| 3 | Interaction Intent | PASS/FAIL | N | N | N |
| 4 | Form Logic | PASS/FAIL | N | N | N |

### PART 2: Component & Visual Readiness
| # | Point | Status | Issues | Auto-fixed | Remaining |
|---|-------|--------|--------|------------|-----------|
| 5 | Component Hygiene | PASS/FAIL | N | N | N |
| 6 | Naming & Structure | PASS/FAIL | N | N | N |
| 7 | Layout & Spacing | PASS/FAIL | N | N | N |
| 8 | Typography | PASS/FAIL | N | N | N |
| 9 | Color & Token | PASS/FAIL | N | N | N |
| 10 | Responsive Intent | PASS/FAIL | N | N | N |

### PART 3: Ready to Handoff
| # | Check | Status |
|---|-------|--------|
| H1-H5 | [check names] | PASS/FAIL |

## Contrast Audit
| Element | Foreground | Background | Ratio | Size | AA |
|---------|-----------|------------|-------|------|----|

## Issues Detail
### [Point Name]
| # | Severity | Issue | Location | Fix Applied |
|---|----------|-------|----------|-------------|

## Changes Made (Auto-fix Log)
| # | Location | Before | After | Reason |
|---|----------|--------|-------|--------|
```

### Severity Levels
- **Critical**: ใช้งานไม่ได้, contrast FAIL, navigation broken, missing states → ต้องแก้
- **Major**: inconsistent, ไม่ตรง token, naming ไม่ดี → ควรแก้
- **Minor**: best practice, optimization → แก้ได้ก็ดี

### PASS/FAIL Logic
- **Point PASS**: ไม่มี Critical issues เหลือในจุดนั้น
- **Overall PASS**: ทุก 10 points + 5 handoff checks = PASS

---

## Step 5: Auto-fix Loop

### Loop Logic

```
สำหรับแต่ละรอบ (round 1-3):
1. ตรวจ HTML file ตาม 10 points + 5 handoff checks
2. ถ้าไม่มี Critical issues → PASS → Final Report
3. ถ้ามี Critical issues:
   a. Auto-fix ทุก issue ที่แก้ได้
   b. บันทึก changes ใน fix log
   c. เขียน HTML file กลับ (overwrite)
   d. round + 1 → ตรวจใหม่ (ถ้า round <= 3)
   e. ถ้า round > 3 → FAIL → Final Report
```

### Auto-fix Priority
1. Contrast failures → 2. Missing states → 3. Placeholder text → 4. Component inconsistency → 5. Interaction hints → 6. Naming & structure → 7. Spacing → 8. Typography → 9. Responsive → 10. Form logic

### Auto-fix Method
ใช้ **Edit tool** แก้ไข HTML file โดยตรง:
- ระบุ `old_string` → `new_string`
- แก้ทีละจุด ไม่ rewrite ทั้งไฟล์
- บันทึกทุกการแก้ไขใน fix log

---

## Step 6: Final Report

**PASS**: แสดง report → "HTML file ผ่าน QA — Dev เปิดเข้าใจทันที พร้อมส่งมอบ"

**FAIL** (หลัง 3 รอบ): แสดง report + remaining issues + recommendation → ถาม user:
1. ส่งมอบ HTML ตามที่แก้ได้ (พร้อม known issues)
2. ให้ลองแก้ manual ตาม recommendation

---

## Important Rules

1. **ตรวจทุกจุดทุกรอบ**: การแก้อาจทำให้จุดอื่นพัง
2. **ไม่ทำลาย functionality**: auto-fix ต้องไม่ทำให้ feature เดิมพัง
3. **บันทึกทุก change**: ทุก auto-fix ต้องอยู่ใน fix log
4. **Severity เป็นตัวตัดสิน**: PASS/FAIL ดูจาก Critical เท่านั้น
5. **Conservative fixes**: ถ้าไม่แน่ใจ → manual recommendation
6. **Respect design intent**: ไม่เปลี่ยนโทนสี/สไตล์
7. **Dev-first mindset**: ทุกอย่างที่ตรวจ ถามว่า "Dev เห็นแล้วเข้าใจไหม?"

---

## Troubleshooting

### Auto-fix ทำให้ feature พัง
**Cause**: แก้ CSS/JS ที่มี dependency กับส่วนอื่น
**Solution**: revert change ด้วย Edit tool แล้วรายงานเป็น manual fix

### Contrast check ให้ผลผิด
**Cause**: สีมาจาก gradient หรือ rgba overlay
**Solution**: ใช้สี dominant ของ gradient มาคำนวณ ถ้าไม่แน่ใจ → skip + report

### ตรวจ state coverage ไม่เจอ states ที่มีอยู่
**Cause**: states อาจใช้ class toggle แทน data-state
**Solution**: ตรวจทั้ง data-state attributes และ CSS class patterns (.loading, .empty, .error)

---
name: interaction-design-spec
description: "สร้าง Interaction Design Specification — ครอบคลุม micro-interactions, animations, transitions, gestures, state changes, feedback patterns ตาม 5 Dimensions of Interaction Design (Words, Visuals, Space, Time, Behavior) ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ออกแบบ interaction, กำหนด animation, micro-interaction, transition spec, gesture design, motion design, ระบุ behavior ของ UI, หรือเมื่อพิมพ์ 'interaction', 'animation', 'transition', 'micro-interaction', 'gesture', 'motion', 'behavior', 'ออกแบบ interaction', 'กำหนด animation', 'motion spec'"
---

# Interaction Design Specification Skill

สร้าง Interaction Design Spec อย่างเป็นระบบ — กำหนดว่า UI ตอบสนองอย่างไรเมื่อผู้ใช้ interact ครอบคลุม animations, transitions, gestures, micro-interactions, feedback patterns

---

## Pipeline Position

```
Jira BA → IA/Flow → UI Design → ★ Interaction Spec ★ → QA Gate → Handoff
```

---

## Overall Flow

```
1. รับ Design ──▶ 2. อ่าน Principles ──▶ 3. วิเคราะห์ 5 Dimensions ──▶ 4. สร้าง Spec ──▶ 5. Output
```

---

## Step 1: รับ Design

ถามผู้ใช้ (ถ้ายังไม่ได้ระบุ):

- **Source**: Figma URL, HTML preview, หรือจะเลือกใน Figma?
- **Scope**: ทั้งหน้า หรือเฉพาะบาง component/flow?
- **Platform**: Mobile (iOS/Android), Web, Desktop?
- **Context**: หน้าจอนี้ใช้ทำอะไร? มี flow ต่อเนื่องไหม?

### วิธีอ่าน Design:

**จาก Figma URL (Remote MCP):**
- get_screenshot → ดู visual
- get_design_context → อ่าน design details
- get_metadata → ดู structure + component list

**จาก Figma Selection (TalkToFigma MCP):**
- read_my_design → อ่าน design ที่เลือก
- scan_nodes_by_types → scan interactive elements

**จาก HTML Preview:**
- อ่านไฟล์ .html ด้วย Read tool
- ดู interactive elements, transitions, states

---

## Step 2: อ่าน Design Principles

อ่าน reference files:

- `references/ux-principles.md` → Fitts's Law, Hick's Law, Doherty Threshold **(อ่านเสมอ)**
- `references/ui-preview-quality-rules.md` → Animation rules, Loading states, Component patterns **(อ่านเสมอ)**
- `references/hig.md` → ถ้า iOS — Motion, Gestures, Haptics
- `references/material-design.md` → ถ้า Android/Web — Motion, Transitions
- `references/visual-design-principles.md` → Visual feedback, animation principles

---

## Step 3: วิเคราะห์ 5 Dimensions of Interaction Design

### Dimension 1: Words (1D) — ข้อความที่สื่อสาร interaction

- Button labels ใช้ verb ที่ชัดเจนไหม? (เช่น "บันทึก" ไม่ใช่ "ตกลง")
- Placeholder text บอก format ที่คาดหวังไหม?
- Loading text บอก status ไหม? ("กำลังบันทึก..." ไม่ใช่แค่ spinner)
- Error messages บอกปัญหา + วิธีแก้ไหม?
- Confirmation dialogs ชัดเจนไหม? (ระบุ action ที่จะเกิดขึ้น)
- Empty state text กระตุ้น action ไหม?

### Dimension 2: Visual Representations (2D) — สิ่งที่ผู้ใช้เห็น

- Interactive elements มี visual affordance ชัดเจนไหม?
- Active/selected states แตกต่างจาก default ชัดเจนไหม?
- Disabled states สื่อว่า "ใช้ไม่ได้" ไหม?
- Focus indicators เห็นชัดไหม? (contrast >= 3:1)
- Progress indicators แสดง status ไหม? (determinate vs indeterminate)
- Visual feedback ตอบสนองทันทีเมื่อ interact ไหม?

### Dimension 3: Physical Objects / Space (3D) — พื้นที่ interaction

- Touch targets >= 44pt (iOS) / 48dp (Android)?
- Thumb zone awareness — ปุ่มสำคัญอยู่ล่าง (reachable zone)?
- Gesture areas ไม่ conflict กันไหม? (swipe vs scroll)
- Modal/sheet ใช้พื้นที่เหมาะสมไหม?
- Content ต้อง scroll ไหม? ถ้าต้อง — มี scroll indicator?

### Dimension 4: Time (4D) — เวลาและจังหวะ

**Animation Duration:**
| Type | Duration | Easing | ใช้เมื่อ |
|------|----------|--------|---------|
| Micro-feedback | 100-150ms | ease-out | Button press, toggle, checkbox |
| Simple transition | 200-300ms | ease-in-out | Page transition, expand/collapse |
| Complex animation | 300-500ms | custom bezier | Modal open, slide-in panel |
| Emphasis/Attention | 500-1000ms | ease-in-out | Onboarding spotlight, celebration |

**Timing Rules:**
- Response < 100ms = feels instant (Doherty Threshold)
- Feedback < 400ms = feels connected
- Animation > 500ms = feels slow — ใช้เท่าที่จำเป็น
- Loading > 1s = ต้องมี progress indicator
- Loading > 3s = ต้องมี skeleton / text explanation

**Easing Functions:**
| Easing | CSS | ใช้เมื่อ |
|--------|-----|---------|
| ease-out | cubic-bezier(0, 0, 0.2, 1) | Element entering (appear, slide-in) |
| ease-in | cubic-bezier(0.4, 0, 1, 1) | Element leaving (disappear, slide-out) |
| ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) | Element moving within view |
| spring | custom | Bounce, pull-to-refresh, snap |

### Dimension 5: Behavior (5D) — พฤติกรรมที่เกิดขึ้น

**Micro-interaction Framework:**
ทุก interaction ต้องมี 4 ส่วน:

```
Trigger → Rules → Feedback → Loops & Modes
```

1. **Trigger**: อะไรเริ่มต้น interaction? (tap, swipe, scroll, timer, system event)
2. **Rules**: กฎคืออะไร? (validation, conditions, boundaries)
3. **Feedback**: ผู้ใช้เห็น/รู้สึกอะไร? (visual, haptic, audio)
4. **Loops & Modes**: ทำซ้ำไหม? มี mode เปลี่ยนไหม?

---

## Step 4: สร้าง Interaction Spec

### 4.1 Interaction Inventory

สำรวจทุก interactive element แล้วจัดกลุ่ม:

| # | Element | Type | Trigger | States | Animation | Duration |
|---|---------|------|---------|--------|-----------|----------|
| 1 | CTA Button | Button | Tap | default→pressed→loading→success | scale(0.95)→spinner→checkmark | 150ms→∞→300ms |
| 2 | Card | Tappable | Tap | default→pressed→navigate | scale(0.98)→page transition | 100ms→300ms |
| 3 | Pull to refresh | Gesture | Pull down | idle→pulling→refreshing→done | translate-y→spinner→fade | gesture→∞→200ms |

### 4.2 State Transitions

สำหรับแต่ละ component กำหนด state machine:

```
                    ┌──── tap ────┐
                    ▼             │
    Default ──▶ Pressed ──▶ Loading ──▶ Success
       ▲                       │          │
       │                       ▼          │
       │                     Error ───────┘
       │                       │     (retry)
       └───────────────────────┘
              (dismiss)
```

### 4.3 Gesture Spec (Mobile)

| Gesture | Action | Element | Behavior | Fallback |
|---------|--------|---------|----------|----------|
| Tap | Select | Card, Button, List item | Highlight → navigate/toggle | — |
| Long press | Context menu | Card, Message | Haptic → show menu | Tap → open |
| Swipe left | Delete / Archive | List item | Reveal action → snap | Tap menu |
| Swipe down | Dismiss / Refresh | Sheet, List | Rubber band → dismiss/refresh | Close button |
| Pinch | Zoom | Image, Map | Scale with gesture | Zoom controls |
| Double tap | Quick action | Image, Text | Zoom / Like | Tap → zoom |

### 4.4 Transition Spec (Between Screens)

| From | To | Transition | Duration | Easing | Direction |
|------|----|-----------|----------|--------|-----------|
| Home | Detail | Push right | 300ms | ease-in-out | → |
| List | Detail | Shared element | 300ms | ease-out | expand |
| Any | Modal | Slide up + dim | 300ms | ease-out | ↑ |
| Modal | Dismiss | Slide down + fade | 250ms | ease-in | ↓ |
| Any | Alert | Fade + scale | 200ms | ease-out | center |

### 4.5 Feedback Pattern Spec

| Event | Visual | Haptic (Mobile) | Audio | Duration |
|-------|--------|-----------------|-------|----------|
| Button tap | Ripple / scale | Light impact | — | 150ms |
| Toggle on | Slide + color change | Light impact | — | 200ms |
| Success | Checkmark animation | Success pattern | Optional ding | 500ms |
| Error | Shake + red flash | Error pattern | — | 300ms |
| Pull to refresh | Spinner appear | — | — | gesture |
| Swipe action | Reveal background | Medium impact | — | gesture |

### 4.6 Loading States

| Scenario | Pattern | When to use | Duration hint |
|----------|---------|------------|---------------|
| Skeleton | Gray placeholder shapes | Content loading < 5s | Pulse animation |
| Spinner | Circular indicator | Action processing < 3s | Indeterminate |
| Progress bar | Linear fill | Upload/download, known % | Determinate |
| Shimmer | Gradient sweep | Image/card loading | Pulse 1.5s loop |
| Inline text | "กำลังบันทึก..." | Button/form submission | Replace button text |

### 4.7 Reduced Motion Alternative

ทุก animation ต้องมี alternative เมื่อ `prefers-reduced-motion: reduce`:

| Normal | Reduced Motion |
|--------|---------------|
| Slide transition | Instant cut / cross-fade |
| Bounce animation | Simple scale |
| Parallax scroll | Static position |
| Auto-play animation | Static frame + play button |
| Loading spinner | Text "กำลังโหลด..." |

---

## Step 5: Output

### Output Format: HTML Interaction Spec (Preferred)

สร้างไฟล์ `interaction-spec.html` ที่แสดง:

1. **Interaction Inventory Table** — รายการทุก interaction
2. **State Machine Diagrams** — แต่ละ component (ใช้ CSS/SVG diagram)
3. **Animation Preview** — ตัวอย่าง animation จริง (ใช้ CSS @keyframes)
4. **Gesture Guide** — gesture ที่ใช้พร้อมภาพประกอบ
5. **Transition Map** — screen-to-screen transitions
6. **Timing Table** — duration + easing ทุก animation
7. **Reduced Motion Table** — alternative ทุก animation

### Styling Guidelines
- ใช้ Design Tokens ของระบบเป็น CSS variables
- แต่ละ interaction มี **live preview** (CSS animation ที่เล่นได้)
- ใช้สีตาม severity: ต้องมี = สีแดง, แนะนำ = สีเหลือง, nice-to-have = สีม่วง

---

## หลักการสำคัญ

1. **Purpose-Driven**: ทุก animation ต้องมีเหตุผล — guide attention, show connection, provide feedback
2. **Performance First**: animation ไม่ควรทำให้ UI ช้า (ใช้ transform/opacity เท่านั้น)
3. **Consistent Timing**: ใช้ duration/easing system ที่สม่ำเสมอทั้ง app
4. **Accessible**: ทุก animation ต้องมี reduced-motion alternative
5. **Natural Feel**: easing ต้องรู้สึกธรรมชาติ ไม่ linear (ยกเว้น progress bar)
6. **Micro > Macro**: micro-interaction feedback สำคัญกว่า flashy animation
7. **Doherty Threshold**: response < 400ms = ผู้ใช้รู้สึก "connected"

---
name: mobile-ux-audit
description: "ตรวจสอบ Mobile UX อย่างเจาะลึก — ครอบคลุม thumb zones, gestures, bottom navigation, card patterns, pull-to-refresh, push notifications, mobile forms, one-handed use, performance perception เฉพาะ mobile ที่ responsive audit ไม่ครอบคลุม ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ตรวจ mobile UX, audit mobile app, ตรวจ thumb zone, เช็ค gesture, mobile usability, ตรวจแอป, หรือเมื่อพิมพ์ 'mobile ux', 'mobile audit', 'thumb zone', 'mobile usability', 'ตรวจ mobile', 'mobile patterns', 'app ux', 'ตรวจแอป'"
---

# Mobile UX Audit Skill

ตรวจ Mobile UX เชิงลึก — เน้นสิ่งที่เฉพาะ mobile เท่านั้น: thumb zones, gestures, native patterns, performance perception, one-handed use ที่ responsive design skill ไม่ได้ครอบคลุม

---

## Pipeline Position

```
UI Design → Responsive → ★ Mobile UX Audit ★ → Accessibility Audit → QA Gate
```

---

## Overall Flow

```
1. รับ Design ──▶ 2. อ่าน Guidelines ──▶ 3. Audit 8 หมวด ──▶ 4. Score ──▶ 5. Report
```

---

## Step 1: รับ Design

ถามผู้ใช้ (ถ้ายังไม่ได้ระบุ):

- **Source**: Figma URL, HTML preview, screenshot?
- **Platform**: iOS หรือ Android? (guidelines ต่างกัน)
- **App Type**: Native, Hybrid, PWA?
- **Target Device**: iPhone 15 (393px), Android (360px), Tablet?
- **Context**: flow นี้ทำอะไร? user ใช้ตอนไหน? (เดินอยู่, นั่งอยู่, มือเดียว?)

### วิธีอ่าน Design:

**จาก Figma (Remote/Local MCP)** — เหมือน skills อื่น
**จาก HTML Preview** — อ่านไฟล์ + ตรวจ viewport, touch targets, mobile patterns

---

## Step 2: อ่าน Guidelines

```
references/ux-principles.md              → Fitts's Law, Hick's Law, Thumb Zone (อ่านเสมอ)
references/ui-preview-quality-rules.md   → Form rules, Button rules, Component patterns (อ่านเสมอ)
references/hig.md                        → iOS-specific (ถ้า iOS)
references/material-design.md            → Android-specific (ถ้า Android)
references/visual-design-principles.md   → Mobile visual patterns
```

---

## Step 3: Audit 8 หมวด

### Category 1: Thumb Zone & Reachability (20%)

**Thumb Zone Map (iPhone 15 / 393x852):**
```
┌─────────────────────────┐
│     HARD TO REACH       │  ← Status bar, top nav
│   ┌─────────────────┐   │
│   │                 │   │
│   │  MODERATE       │   │  ← Content area
│   │                 │   │
│   │  ┌───────────┐  │   │
│   │  │           │  │   │
│   │  │  EASY     │  │   │  ← Bottom half
│   │  │  REACH    │  │   │
│   │  │           │  │   │
│   │  └───────────┘  │   │
│   └─────────────────┘   │
│     NATURAL THUMB ARC   │  ← Bottom nav, FAB
└─────────────────────────┘
```

**ตรวจ:**
| Check | Criteria | Weight |
|-------|----------|--------|
| Primary CTA position | อยู่ใน easy reach zone (ล่าง)? | Critical |
| Navigation | Bottom nav / tab bar (ไม่ใช่ hamburger menu ด้านบน)? | Critical |
| Frequent actions | อยู่ล่างหรือกลาง? | Major |
| Destructive actions | อยู่ห่างจาก easy reach (ป้องกัน accidental tap)? | Major |
| Search | เข้าถึงง่ายไหม? (bottom bar หรือ pull-down) | Minor |

### Category 2: Touch Interaction (15%)

**Touch Target Rules:**
| Platform | Minimum | Recommended | Spacing |
|----------|---------|-------------|---------|
| iOS | 44 x 44pt | 56pt (primary CTA) | >= 8pt |
| Android | 48 x 48dp | 56dp (primary CTA) | >= 8dp |

**ตรวจ:**
| Check | Criteria |
|-------|----------|
| All tappable elements | >= minimum size? |
| Icon-only buttons | มี adequate tap area (padding around icon)? |
| Close/dismiss buttons | ไม่เล็กเกินไป? (X button ต้อง >= 44pt) |
| Adjacent tap targets | มี spacing >= 8pt? ไม่ overlap? |
| List item tap area | Full-width row ไม่ใช่แค่ text? |
| Swipe areas | ไม่ conflict กับ system gestures? (edge swipe = back) |

### Category 3: Mobile Navigation Patterns (15%)

**ตรวจตาม Platform:**

**iOS (HIG):**
| Pattern | ถูกต้อง | ผิด |
|---------|---------|-----|
| Tab Bar | ล่าง, 5 items max, icon + label | Hamburger ด้านบน |
| Back | Edge swipe + back button ซ้ายบน | Custom back position |
| Modal | Sheet from bottom | Full-screen unnecessary modal |
| Search | Pull down หรือ search bar | Hidden search |

**Android (Material):**
| Pattern | ถูกต้อง | ผิด |
|---------|---------|-----|
| Navigation | Bottom nav / Nav drawer | Top-only nav |
| Back | System back gesture + app back | No back affordance |
| FAB | Bottom right, single primary action | Multiple FABs |
| Snackbar | Bottom, auto-dismiss, one action | Sticky toast blocking content |

**ตรวจ:**
| Check | Criteria |
|-------|----------|
| Primary nav | ใช้ bottom navigation? |
| Depth indicator | ผู้ใช้รู้ว่าอยู่ตรงไหนของ app ไหม? |
| Back behavior | กด back แล้วไปถูกหน้าไหม? |
| Navigation consistency | Nav bar consistent ทุกหน้า? |
| Deep link support | เข้าจาก notification/link แล้ว navigate ต่อได้ไหม? |

### Category 4: Mobile Form Design (15%)

**ตรวจ:**
| Check | Criteria |
|-------|----------|
| Keyboard type | ตรงกับ input type? (email → @, phone → numpad, URL → .com) |
| Auto-complete | ใช้ autocomplete attributes? (name, email, address, cc-number) |
| Input positioning | Input ไม่ถูก keyboard บังไหม? (scroll into view) |
| Label visibility | Label ยังเห็นเมื่อ focused? (floating label recommended) |
| Error display | Inline error ใกล้ input? ไม่ใช่ top-of-page alert? |
| Multi-step form | มี progress indicator? ไม่ยาวเกิน 1 scroll? |
| Required fields | ระบุชัดเจน? (* หรือ "required" badge) |
| Submit button | ใกล้ keyboard? หรือ sticky bottom? |
| Paste support | ยอมให้ paste ได้? (OTP, password) |
| Biometric | รองรับ Face ID / fingerprint สำหรับ login? |

### Category 5: Content Patterns (10%)

**Mobile Card Design:**
| Check | Criteria |
|-------|----------|
| Card size | เห็นอย่างน้อย 1.5 cards ใน viewport? (hint ว่า scroll ได้) |
| Card tap area | ทั้ง card tappable? หรือแค่บาง element? |
| Image loading | มี placeholder/skeleton ก่อน image load? |
| Text truncation | Long text ตัดเหมาะสม? (ellipsis, "Read more") |
| Card actions | Actions ไม่ conflict กับ card tap? |

**Mobile List Design:**
| Check | Criteria |
|-------|----------|
| Row height | >= 44pt (iOS) / 48dp (Android)? |
| Swipe actions | มี swipe-to-action? (delete, archive, favorite) |
| Pull to refresh | รองรับ pull-to-refresh? |
| Infinite scroll | มี loading indicator ที่ bottom? |
| Empty state | แสดง illustration + CTA เมื่อ list ว่าง? |

### Category 6: Performance Perception (10%)

ไม่ได้ตรวจ actual performance แต่ตรวจว่า design รองรับ perceived performance:

| Check | Criteria |
|-------|----------|
| Skeleton screens | มี skeleton UI ก่อน content load? |
| Optimistic updates | UI update ทันทีก่อน server confirm? (เช่น like) |
| Progressive loading | Critical content load ก่อน? |
| Splash screen | ไม่นานเกิน 2 วินาที? transition เข้า app smooth? |
| Image loading | Progressive JPEG / blur-up / placeholder? |
| Offline state | แสดง cached content + offline indicator? |
| Background task | แจ้ง status ใน notification / app badge? |

### Category 7: Push Notification Design (5%)

| Check | Criteria |
|-------|----------|
| Permission timing | ขอหลังจาก user เห็นคุณค่าแล้ว? (ไม่ใช่ first launch) |
| Permission explanation | อธิบายว่าจะส่งอะไร ก่อนขอ permission? |
| Notification content | actionable + specific? (ไม่ใช่แค่ "มีข้อความใหม่") |
| Deep link | กดแล้วไปถูกหน้าในแอป? |
| Grouping | จัดกลุ่ม notification ที่เกี่ยวข้อง? |
| Frequency | ไม่ส่งถี่เกินไป? (ไม่เกิน 3-5 ต่อวัน) |

### Category 8: Platform Conventions (10%)

**ตรวจว่า design ตรงกับ platform expectations:**

**iOS-specific:**
| Check | iOS Convention |
|-------|---------------|
| Navigation bar | Title centered, back button ซ้าย |
| Tab bar | Icons + labels, max 5 tabs |
| Segmented control | ไม่ใช่ toggle ที่ดูเหมือน Android |
| Action sheets | Bottom sheet for destructive actions |
| Alert style | iOS-style alert dialog |
| Swipe back | Edge swipe to go back |

**Android-specific:**
| Check | Android Convention |
|-------|-------------------|
| Material components | ใช้ Material Design components? |
| System bars | Transparent/translucent status bar? |
| Back gesture | Predictive back animation? |
| Share sheet | ใช้ system share sheet? |
| FAB placement | Bottom right, not blocking content? |
| Bottom sheet | Rounded top corners, drag handle? |

---

## Step 4: Score

### Scoring Matrix

| Category | Weight | Score (1-10) | Critical Issues | Notes |
|----------|--------|-------------|-----------------|-------|
| Thumb Zone & Reachability | 20% | — | — | — |
| Touch Interaction | 15% | — | — | — |
| Mobile Navigation | 15% | — | — | — |
| Mobile Form Design | 15% | — | — | — |
| Content Patterns | 10% | — | — | — |
| Performance Perception | 10% | — | — | — |
| Push Notification | 5% | — | — | — |
| Platform Conventions | 10% | — | — | — |
| **Weighted Total** | **100%** | **—/10** | — | — |

### Rating Scale
- **9-10**: Native-quality UX — รู้สึกเหมือนแอป first-party
- **7-8**: ดี — มี minor adjustments
- **5-6**: ใช้ได้ — แต่รู้สึก "web-like" บน mobile
- **3-4**: ต้องปรับหนัก — ไม่ตรง platform conventions
- **1-2**: ต้อง rethink — ไม่ได้ออกแบบสำหรับ mobile

---

## Step 5: Report

### Output Format: HTML Mobile UX Report

สร้างไฟล์ `mobile-ux-report.html` ที่แสดง:

1. **Score Overview** — คะแนนรวม + breakdown ทุกหมวด
2. **Thumb Zone Heat Map** — overlay บนรูปจริง แสดง reachability zones
3. **Issue Cards** — ทุก issue แยกตาม severity (Critical/Major/Minor)
   - WHERE: จุดบนรูปจริง
   - WHAT: ปัญหาคืออะไร
   - WHY: ทำไมถึงเป็นปัญหา (อ้าง principle)
   - FIX: วิธีแก้สำหรับ Designer
4. **Platform Compliance** — เทียบกับ iOS/Android guidelines
5. **Checklist** — สรุปทุก issue เรียงตาม priority

### โทน Designer-Friendly:
- ใช้โทน "แนะนำ" ไม่ใช่ "ตรวจจับ"
- ให้ภาพเปรียบเทียบ (ก่อน/หลัง) ทุก issue
- อ้าง platform guidelines เสมอ

---

## หลักการสำคัญ

1. **Platform-Native Feel**: Design ต้อง "รู้สึกถูกที่" บน platform นั้น
2. **One-Handed Use**: 75% ของ mobile users ใช้มือเดียว — ออกแบบสำหรับนิ้วโป้ง
3. **Context-Aware**: Mobile ใช้ระหว่างเดิน, ข้างนอก, แสงจ้า — content ต้องชัด
4. **Gesture-First**: Native gestures (swipe, pull) รู้สึกดีกว่า button taps
5. **Forgiveness**: Mobile = typo + accidental tap — ต้องมี undo/redo ง่าย
6. **Performance = UX**: Perceived speed สำคัญเท่า actual speed
7. **Offline-Ready**: ผู้ใช้ mobile อาจหลุด connection — design สำหรับ graceful degradation

---
name: conversion-ux-review
description: "ตรวจ UX เพื่อ Conversion — วิเคราะห์ checkout flow, form optimization, CTA effectiveness, trust signals, cart abandonment prevention, landing page, onboarding funnel ตาม CRO best practices จากหนังสือ 16 เล่มด้าน Marketing & Conversion + 33 Design Crimes ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ตรวจ conversion, เพิ่ม conversion rate, วิเคราะห์ funnel, ตรวจ checkout, ตรวจ form, landing page review, CTA review, หรือเมื่อพิมพ์ 'conversion', 'CRO', 'checkout', 'funnel', 'landing page', 'cart abandonment', 'form optimization', 'ตรวจ conversion', 'เพิ่ม conversion'"
---

# Conversion UX Review Skill

วิเคราะห์ UX ด้าน Business Conversion — ตรวจว่า design กระตุ้นให้ user ทำ action ที่ต้องการไหม (สมัคร, ซื้อ, กรอกฟอร์ม) โดยอิงจาก CRO best practices

---

## Pipeline Position

```
UI Design → Design Critique → ★ Conversion UX Review ★ → QA Gate → Handoff
```

---

## Overall Flow

```
1. รับ Design ──▶ 2. ระบุ Conversion Goal ──▶ 3. Audit 7 มิติ ──▶ 4. Score ──▶ 5. Report
```

---

## Step 1: รับ Design

ถามผู้ใช้ (ถ้ายังไม่ได้ระบุ):

- **Source**: Figma URL, HTML preview, screenshot?
- **Page Type**: Landing page, Checkout, Registration, Onboarding, Product page?
- **Platform**: Web, Mobile web, Native app?
- **Target Audience**: ใครคือ user? (อายุ, tech-savviness, ใช้ free หรือจ่ายเงิน?)

### อ่าน References ก่อน Audit:
```
references/ux-principles.md              → Laws of UX (Hick's, Fitts's, Von Restorff) (อ่านเสมอ)
references/ui-preview-quality-rules.md   → CTA rules, Form rules, Visual hierarchy (อ่านเสมอ)
```

### วิธีอ่าน Design:
เหมือน skills อื่น — Figma MCP หรืออ่าน HTML

---

## Step 2: ระบุ Conversion Goal

ก่อนวิเคราะห์ ต้องระบุ goal ให้ชัด:

| Page Type | Primary Conversion | Secondary Conversion |
|-----------|-------------------|---------------------|
| Landing page | Sign up / CTA click | Scroll to learn more |
| Registration | Complete sign up | Social login |
| Onboarding | Complete onboarding | Skip to app |
| Product page | Add to cart | Save to wishlist |
| Checkout | Complete purchase | Apply coupon |
| Pricing page | Select plan | Start free trial |
| Login | Successful login | Forgot password recovery |

ถามผู้ใช้:
> "Conversion goal หลักคืออะไรครับ? ต้องการให้ user ทำอะไร?"

---

## Step 3: Audit 7 มิติ

### Dimension 1: CTA (Call-to-Action) Effectiveness (20%)

**Primary CTA Checklist:**
| Check | Criteria | Why |
|-------|----------|-----|
| Visibility | CTA เห็นทันทีใน viewport แรก (above the fold)? | 80% ของ clicks เกิดที่ above the fold |
| Visual prominence | CTA เป็นสิ่งที่โดดเด่นที่สุดบนหน้า? | Von Restorff Effect — สิ่งที่ต่างจะถูกจำ |
| Color contrast | CTA สีต่างจาก background + surrounding elements? | ต้อง pop ออกมาจาก page |
| Button text | ใช้ action verb ที่เฉพาะเจาะจง? | "เริ่มทดลองฟรี" ดีกว่า "ส่ง" |
| Size | ใหญ่พอที่จะ tap ได้ง่าย (>= 48px height)? | Fitts's Law |
| Whitespace | มี whitespace รอบ CTA เพียงพอ? | ป้องกัน visual clutter |
| Position | อยู่ใน natural reading flow? (F/Z pattern) | Eye tracking research |
| Sticky CTA | มี sticky CTA เมื่อ scroll ลงยาว? | ให้ user convert ได้ทุกจุด |
| Single CTA | มี CTA เดียวที่โดดเด่นที่สุด ต่อ section? | Hick's Law — ลด choice paralysis |

**CTA Text Analysis:**
| Bad | Better | Best |
|-----|--------|------|
| ส่ง | สมัคร | เริ่มทดลองฟรี 14 วัน |
| ตกลง | ยืนยัน | ยืนยันการสั่งซื้อ |
| Click here | ดูเพิ่มเติม | ดูแพ็กเกจทั้งหมด |
| OK | บันทึก | บันทึกที่อยู่จัดส่ง |

### Dimension 2: Form Optimization (20%)

**Form Friction Checklist:**
| Check | Criteria | Impact |
|-------|----------|--------|
| Field count | น้อยที่สุดเท่าที่จำเป็น? (ทุก field ที่เพิ่ม = -7% conversion) | Critical |
| Required only | ขอเฉพาะข้อมูลที่จำเป็นจริงๆ? | Critical |
| Smart defaults | มี default values ที่เหมาะสม? (ประเทศ, เมือง auto) | Major |
| Auto-fill | รองรับ browser autofill? (name, email, address) | Major |
| Input types | ใช้ keyboard type ถูกต้อง? (email, tel, number) | Major |
| Real-time validation | validate ทันที ไม่ใช่รอกด submit? | Major |
| Inline errors | error แสดงใกล้ field ที่ผิด? | Major |
| Password rules | แสดง requirements ก่อนกรอก? (ไม่ใช่หลัง submit) | Major |
| Progress indicator | form หลาย step มี progress bar? | Minor |
| Social login | มีทางลัด (Google, Apple, LINE)? | Minor |
| Guest checkout | ซื้อได้โดยไม่ต้องสมัคร? | Critical (e-commerce) |

**Form Layout Best Practices:**
- Single column layout (ไม่ใช่ multi-column)
- Label above input (ไม่ใช่ข้าง — saves vertical space บน mobile)
- Group related fields (ชื่อ-นามสกุล, ที่อยู่)
- CTA ท้ายฟอร์ม ไม่ใช่ต้น form
- "ย้อนกลับ" link — ไม่ใช่ button (ลด visual weight)

### Dimension 3: Trust & Credibility (15%)

| Check | Criteria | Where |
|-------|----------|-------|
| Social proof | มี reviews, ratings, testimonials? | Near CTA / product info |
| Numbers | แสดงจำนวนผู้ใช้, downloads, reviews? | Hero section / near CTA |
| Security badges | มี SSL, payment badges, guarantees? | Checkout / payment form |
| Brand trust | มี logo ที่จำได้ + consistent branding? | Header / throughout |
| Contact info | มีช่องทางติดต่อ (chat, phone, email)? | Footer / help section |
| Privacy policy | มี link ไป privacy policy ใกล้ form? | Registration / checkout |
| Money-back guarantee | มีการรับประกัน? | Pricing / checkout |
| Real photos | ใช้รูปจริง ไม่ใช่ stock photos? | Throughout |
| Third-party logos | มี "trusted by" / partner logos? | Below hero / social proof |

### Dimension 4: Visual Hierarchy for Conversion (15%)

| Check | Criteria |
|-------|----------|
| Value proposition | เห็นทันทีใน 5 วินาที ว่าหน้านี้ offer อะไร? |
| F-pattern / Z-pattern | Content เรียงตาม reading pattern? |
| Eye flow to CTA | สายตาถูก guide ไปยัง CTA อย่างธรรมชาติ? |
| Distraction-free | ไม่มี element ที่แย่ง attention จาก CTA? |
| Above the fold | ข้อมูลสำคัญที่สุดอยู่ใน viewport แรก? |
| Content priority | Important content อยู่บน, details อยู่ล่าง? |
| Negative space | ใช้ white space guide attention ไป CTA? |
| One clear message | แต่ละ section มี message เดียว? |

### Dimension 5: Friction & Abandonment Prevention (15%)

**Friction Points Checklist:**
| Check | Impact | Fix |
|-------|--------|-----|
| Surprise costs | ราคาเปลี่ยนที่ checkout? | แสดงราคาสุดท้ายก่อน checkout |
| Account required | ต้องสมัครก่อนซื้อ/ใช้? | Guest checkout / lazy registration |
| Too many steps | Checkout > 3 steps? | ลดเหลือ 1-3 steps |
| Unclear next step | ไม่รู้ต้องทำอะไรต่อ? | CTA ชัดเจน + progress indicator |
| External redirect | ออกจาก site ไปจ่ายเงิน? | Inline payment / embedded form |
| Slow loading | > 3 วินาที load time? | Skeleton + lazy loading |
| Captcha | ต้องไขปริศนา? | Invisible captcha / hCaptcha |
| Forced registration | popup สมัครก่อนเห็น content? | ให้เห็น value ก่อน |

**Exit Intent Recovery:**
| Trigger | Recovery Pattern |
|---------|-----------------|
| Mouse to close tab (web) | Exit-intent popup + offer |
| Back button (mobile) | Confirmation dialog "ยังไม่ได้บันทึก" |
| Cart abandonment | Email / notification reminder |
| Form abandonment | Auto-save draft + "ดำเนินการต่อ" |
| Long idle time | "ยังอยู่ไหม?" prompt |

### Dimension 6: Onboarding & First Experience (10%)

| Check | Criteria |
|-------|----------|
| Time to value | User เห็น core value ใน < 60 วินาที? |
| Progressive disclosure | ไม่ show ทุก feature ทีเดียว? |
| Skip option | สามารถ skip onboarding ได้? |
| Contextual guidance | สอนตอนใช้จริง ไม่ใช่ tutorial ก่อนเริ่ม? |
| Minimal setup | ขอข้อมูลน้อยที่สุดก่อนเริ่มใช้? |
| Welcome state | หน้าแรกหลัง onboarding มี guidance ไหม? |
| Empty state as CTA | Empty state กระตุ้น action แรก? |
| Achievement feeling | มี micro-celebration เมื่อทำสำเร็จ? |

### Dimension 7: Pricing & Value Communication (5%)

| Check | Criteria |
|-------|----------|
| Price anchoring | แสดง plan ที่แพงที่สุดก่อน? (anchor effect) |
| Recommended plan | Highlight plan ที่ต้องการขาย? (visual prominence) |
| Feature comparison | เปรียบเทียบ features ชัดเจน? |
| Free trial | มี risk-free option? |
| Annual discount | แสดง savings ของ annual plan? |
| Currency/tax | แสดง currency + inclusive/exclusive tax? |
| Refund policy | แสดงชัดเจน? |

---

## Step 4: Score

### Scoring Matrix

| Dimension | Weight | Score (1-10) | Revenue Impact | Notes |
|-----------|--------|-------------|----------------|-------|
| CTA Effectiveness | 20% | — | — | — |
| Form Optimization | 20% | — | — | — |
| Trust & Credibility | 15% | — | — | — |
| Visual Hierarchy | 15% | — | — | — |
| Friction Prevention | 15% | — | — | — |
| Onboarding | 10% | — | — | — |
| Pricing Communication | 5% | — | — | — |
| **Weighted Total** | **100%** | **—/10** | — | — |

### Rating Scale
- **9-10**: Conversion machine — UX ไม่มี friction
- **7-8**: ดี — มี minor optimizations
- **5-6**: Average — conversion rate ต่ำกว่าที่ควร
- **3-4**: Leaky funnel — สูญเสีย user หลายจุด
- **1-2**: Broken — user ไม่สามารถ/ไม่อยาก convert

---

## Step 5: Report

### Output Format: HTML Conversion UX Report

สร้างไฟล์ `conversion-ux-report.html` ที่แสดง:

1. **Score Overview** — คะแนนรวม + conversion funnel diagram
2. **Funnel Analysis** — แต่ละ step ของ funnel + predicted drop-off points
3. **Issue Cards** แยกตาม severity:
   - WHAT: ปัญหาคืออะไร
   - WHY: ทำไมกระทบ conversion (อ้าง research/principle)
   - IMPACT: estimated impact (high/medium/low)
   - FIX: วิธีแก้ + before/after mockup
4. **CTA Audit** — วิเคราะห์ CTA ทุกตัว (text, color, position, size)
5. **Form Audit** — วิเคราะห์ form fields ทุกตัว
6. **Trust Signal Map** — แสดงว่า trust signals อยู่ตรงไหน (หรือขาดตรงไหน)
7. **Quick Wins** — 3-5 สิ่งที่แก้ง่ายแต่ impact สูง
8. **Checklist** — สรุปทุก issue เรียงตาม priority

### โทน Designer-Friendly:
- ใช้ "เพิ่ม conversion ได้ด้วย..." แทน "ปัญหาคือ..."
- ให้ before/after comparison ทุก issue
- อ้าง research data เมื่อมี (เช่น "ลด 1 field = +7% conversion")

---

## หลักการสำคัญ (33 Design Crimes to Avoid)

จาก "33 Website Design Crimes to Avoid":

1. **No clear value proposition** — user ไม่รู้ว่าจะได้อะไร
2. **Too many CTAs** — ไม่รู้จะกดอะไร (Hick's Law)
3. **Weak CTA text** — "Submit" ไม่บอกว่า submit อะไร
4. **No social proof** — ทำไมต้องเชื่อ?
5. **Hidden pricing** — ราคาเท่าไหร่?
6. **Surprise costs** — ทำไมราคาเปลี่ยน?
7. **Forced registration** — ต้องสมัครก่อน?
8. **Long forms** — กรอกเยอะจัง
9. **No error prevention** — กดผิดแล้วเริ่มใหม่
10. **Slow performance** — รอนาน ไม่รอแล้ว
11. **No mobile optimization** — ใช้ mobile ไม่ได้
12. **Confusing navigation** — หาไม่เจอ
13. **Auto-play video/audio** — น่ารำคาญ
14. **Popup overload** — popup ทับ popup
15. **No search** — หาสิ่งที่ต้องการไม่ได้

---
name: usability-testing-plan
description: "สร้างแผน Usability Testing อย่างเป็นระบบ — ครอบคลุม test objectives, participant recruitment, task scenarios, test script, metrics, analysis framework รองรับทั้ง moderated/unmoderated, remote/in-person ใช้ skill นี้เมื่อผู้ใช้ต้องการ: วางแผน usability test, สร้าง test plan, เขียน task scenario, ทดสอบ usability, user testing, UX research, หรือเมื่อพิมพ์ 'usability test', 'user test', 'test plan', 'ux research', 'ทดสอบ', 'สร้าง test plan', 'test scenario', 'ux testing'"
---

# Usability Testing Plan Skill

สร้างแผน Usability Testing ที่พร้อมใช้งาน — ตั้งแต่กำหนด objectives ถึง analysis framework

---

## Pipeline Position

```
UI Design → Prototype → ★ Usability Testing Plan ★ → Conduct Test → Iterate → QA Gate
```

---

## Overall Flow

```
1. รับ Context ──▶ 2. เลือกวิธี ──▶ 3. สร้าง Plan ──▶ 4. เขียน Script ──▶ 5. กำหนด Metrics ──▶ 6. Output
```

---

## Step 1: รับ Context

ถามผู้ใช้:

- **Product**: ทดสอบอะไร? (app, website, feature, prototype)
- **Stage**: อยู่ขั้นไหน? (concept, wireframe, prototype, live product)
- **Goal**: ต้องการรู้อะไร? (usability, learnability, findability, preference)
- **Scope**: ทดสอบทั้ง app หรือเฉพาะ flow?
- **Budget**: มีงบเท่าไหร่? มีเวลากี่วัน?
- **Existing Data**: มี analytics, support tickets, หรือ feedback อยู่แล้วไหม?

---

## Step 2: เลือกวิธีทดสอบ

### Testing Method Matrix

| Method | Cost | Speed | Depth | Best for |
|--------|------|-------|-------|----------|
| **Moderated Remote** | Medium | Fast | Deep | Complex flows, think-aloud, follow-up questions |
| **Unmoderated Remote** | Low | Very fast | Medium | Large sample, simple tasks, quantitative data |
| **Moderated In-Person** | High | Slow | Very deep | Physical products, sensitive topics, observation |
| **Guerrilla Testing** | Very low | Very fast | Low | Quick validation, public spaces, informal |
| **A/B Testing** | Low | Varies | Specific | Design decisions, CTA comparison, layout |
| **Card Sorting** | Low | Fast | Medium | IA, navigation, categorization |
| **First Click Testing** | Low | Fast | Medium | Navigation, findability, layout |
| **5-Second Test** | Very low | Very fast | Low | First impression, clarity, value proposition |

### แนะนำตาม Stage:

| Stage | Recommended Method | Participants |
|-------|-------------------|--------------|
| Concept / Wireframe | Moderated (remote/in-person), 5-Second test | 5-8 |
| Lo-fi Prototype | Moderated remote, Card sorting | 5-8 |
| Hi-fi Prototype | Moderated remote, Unmoderated remote | 5-15 |
| Live Product | Unmoderated remote, A/B testing, Analytics | 10-50+ |
| Quick Validation | Guerrilla, 5-Second test, First Click | 5-10 |

---

## Step 3: สร้าง Test Plan

### 3.1 Test Objectives

เขียน 3-5 objectives ที่ measurable:

```
Format: "ตรวจสอบว่าผู้ใช้สามารถ [action] โดย [criteria] ได้หรือไม่"
```

ตัวอย่าง:
1. "ตรวจสอบว่าผู้ใช้ใหม่สามารถลงทะเบียนสำเร็จใน < 2 นาทีได้หรือไม่"
2. "ตรวจสอบว่าผู้ใช้หา feature X ได้ใน < 3 clicks หรือไม่"
3. "ตรวจสอบว่าผู้ใช้เข้าใจ value proposition ภายใน 5 วินาทีหรือไม่"

### 3.2 Participant Profile

| Criteria | Specification |
|----------|--------------|
| จำนวน | 5-8 คน (หา 85% ของปัญหา — Nielsen's 5-user rule) |
| Demographics | อายุ, เพศ, อาชีพ, ที่ตั้ง |
| Tech proficiency | Novice / Intermediate / Expert |
| Domain knowledge | คุ้นเคยกับ domain ไหม? |
| Product experience | เคยใช้ product นี้ไหม? (new vs returning) |
| Device | iPhone / Android / Desktop / Tablet |
| Exclusion criteria | ใครที่ห้ามเข้าร่วม? (เช่น designer, developer) |

### Recruitment Screener Questions

สร้าง 5-7 คำถาม screening:

```markdown
1. คุณใช้สมาร์ทโฟนยี่ห้ออะไร?
   □ iPhone  □ Android  □ อื่นๆ → [DISQUALIFY if not target platform]

2. คุณเคยใช้แอป [category] หรือไม่?
   □ ใช่ → ถามต่อ  □ ไม่เคย → [QUALIFY/DISQUALIFY depending on goal]

3. คุณใช้แอป [category] บ่อยแค่ไหน?
   □ ทุกวัน  □ สัปดาห์ละ  □ เดือนละ  □ ไม่เคย

4. อาชีพของคุณคืออะไร?
   [Open text] → [DISQUALIFY if UX/UI designer or developer]

5. คุณสะดวกเข้าร่วมทดสอบ [date/time] ไหม?
   □ สะดวก  □ ไม่สะดวก
```

### 3.3 Task Scenarios

**Task Writing Rules:**
- ใช้ **scenario-based** ไม่ใช่ **instruction-based**
- เขียนเป็น "เรื่องเล่า" ไม่ใช่ขั้นตอน
- ห้ามใช้คำที่อยู่บน UI (clue words)
- ให้ realistic context

**Bad vs Good Tasks:**

| Bad (Instruction) | Good (Scenario) |
|-------------------|-----------------|
| "กดปุ่ม Register" | "คุณเพิ่งรู้จักแอปนี้จากเพื่อน อยากลองใช้ดู ลองเริ่มต้นใช้งาน" |
| "หาหน้า Settings" | "คุณอยากเปลี่ยนรูปโปรไฟล์ ลองทำดู" |
| "กรอกฟอร์มที่อยู่" | "คุณสั่งของออนไลน์ ต้องกรอกที่อยู่สำหรับจัดส่ง ลองดำเนินการ" |
| "ค้นหาร้านอาหาร" | "คุณหิวข้าว อยากหาร้านอาหารไทยใกล้ๆ ลองหาดู" |

**Task Template:**

```markdown
### Task [N]: [Task Name]

**Scenario:**
[Realistic context — 2-3 sentences]

**Starting Point:**
[Where the user starts — specific screen]

**Success Criteria:**
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]

**Expected Path:**
[Screen A] → [Screen B] → [Screen C] → [Success]

**Data Points to Collect:**
- Task completion: Yes/No
- Time on task: ___
- Number of errors: ___
- Number of clicks/taps: ___
- Satisfaction (1-5): ___
```

สร้าง 5-8 tasks ต่อ session (ไม่เกิน 60 นาที total)

### 3.4 Test Environment

| Setting | Specification |
|---------|--------------|
| Location | Remote (Zoom/Teams) / In-person / Unmoderated (UserTesting) |
| Device | Participant's own device / Provided device |
| Prototype | Figma prototype URL / Live product URL |
| Recording | Screen + face + audio (ต้องขอ consent) |
| Tools | Screen sharing, think-aloud, eye-tracking (optional) |
| Duration | 30-60 min per session |
| Compensation | [Amount] per participant |

---

## Step 4: เขียน Test Script

### Moderator Script Template:

```markdown
## ก่อนเริ่ม (5 min)

### แนะนำตัว
"สวัสดีครับ/ค่ะ ขอบคุณที่มาช่วยทดสอบวันนี้
ผม/ดิฉัน [ชื่อ] จาก [ทีม]
วันนี้เราจะลองทดสอบ [product] กัน ใช้เวลาประมาณ [X] นาที"

### อธิบาย Process
"ขอเล่าให้ฟังก่อนนะครับ:
- เราทดสอบ **product** ไม่ใช่ทดสอบคุณ
- ไม่มีคำตอบถูกหรือผิด
- ถ้าอะไรยากหรือสับสน นั่นคือปัญหาของ design ไม่ใช่ของคุณ
- อยากให้ **คิดออกเสียง** — พูดสิ่งที่คิดขณะใช้งาน
- คุณสามารถหยุดได้ทุกเมื่อ
- ผมจะบันทึกหน้าจอและเสียง เพื่อนำไปปรับปรุง — ยินยอมไหมครับ?"

### Warm-up Questions
"ก่อนเริ่ม ขอถามสั้นๆ:
- ปกติใช้แอปแบบนี้บ้างไหม? ใช้อะไรบ้าง?
- ใช้บ่อยแค่ไหน?
- ชอบ/ไม่ชอบอะไรเกี่ยวกับแอปพวกนั้น?"

---

## ช่วงทดสอบ (40-50 min)

### Task 1: [Task Name]
"ลองจินตนาการว่า... [scenario]"

*เงียบ รอให้ user ทำเอง*

**ถ้า user ติด (> 30 วินาทีไม่มี action):**
- ระดับ 1: "ตอนนี้คิดอะไรอยู่ครับ?"
- ระดับ 2: "ปกติจะทำยังไง?"
- ระดับ 3: "ลองดูตรง [area] สิครับ" (เฉพาะกรณีจำเป็นมาก)

**Note:**
- เวลาเริ่ม: ___
- เวลาจบ: ___
- สำเร็จ: □ Yes □ No □ Partial
- จำนวน errors: ___
- สังเกต: ___

### [Tasks 2-N ตาม pattern เดียวกัน]

---

## ช่วงสรุป (5-10 min)

### Post-Task Questions
"ขอบคุณมากครับ ขอถามอีกนิดหน่อย:

1. โดยรวมรู้สึกยังไงบ้างกับการใช้ [product]?
2. มีจุดไหนที่ยากหรือสับสนเป็นพิเศษไหม?
3. มีอะไรที่ชอบเป็นพิเศษไหม?
4. ถ้าเปลี่ยนได้ 1 อย่าง จะเปลี่ยนอะไร?
5. คะแนน 1-10 ความง่ายในการใช้งานให้เท่าไหร่?"

### SUS Questionnaire (Optional)
System Usability Scale — 10 questions, 1-5 scale

### ปิด
"ขอบคุณมากครับ สิ่งที่คุณแชร์จะเป็นประโยชน์มากในการปรับปรุง"
```

---

## Step 5: กำหนด Metrics

### Quantitative Metrics

| Metric | Formula | Benchmark |
|--------|---------|-----------|
| Task completion rate | สำเร็จ / ทั้งหมด × 100% | >= 78% (industry avg) |
| Time on task | เวลาเฉลี่ย per task | เทียบกับ expected time |
| Error rate | จำนวน errors / ทั้งหมด | < 10% |
| Click/tap count | จำนวน clicks vs optimal path | <= optimal + 2 |
| SUS Score | System Usability Scale | >= 68 (above avg) |
| NPS | Promoters - Detractors | >= 30 (good) |

### Qualitative Metrics

| Metric | How to capture |
|--------|---------------|
| Pain points | สิ่งที่ user พูดว่ายาก/สับสน |
| Mental model mismatch | สิ่งที่ user คาดหวังแต่ไม่ตรง |
| Delight moments | สิ่งที่ user ชอบ/ประทับใจ |
| Workarounds | วิธีที่ user แก้ปัญหาเอง |
| Quotes | คำพูดสำคัญจาก user (verbatim) |

### Analysis Framework

**Severity Rating:**
| Rating | Label | Description | Action |
|--------|-------|-------------|--------|
| 4 | Catastrophic | User ไม่สามารถทำ task สำเร็จ | แก้ทันที |
| 3 | Major | User ทำสำเร็จแต่ยากมาก / ใช้เวลานาน | แก้ใน sprint นี้ |
| 2 | Minor | User สับสนเล็กน้อยแต่แก้ได้เอง | แก้ใน sprint ถัดไป |
| 1 | Cosmetic | สังเกตได้แต่ไม่กระทบ task | backlog |

**Finding Template:**
```markdown
### Finding [N]: [Title]

**Severity:** [4/3/2/1]
**Task:** [Which task]
**Frequency:** [X out of Y participants]
**Description:** [What happened]
**User Quote:** "[exact words]"
**Root Cause:** [Why — UX principle violated]
**Recommendation:** [How to fix]
**Evidence:** [Screenshot / recording timestamp]
```

---

## Step 6: Output

### Output Format: HTML Usability Test Plan

สร้างไฟล์ `usability-test-plan.html` ที่แสดง:

1. **Test Overview** — goals, method, timeline, participants
2. **Participant Profile** — demographics + screener questions
3. **Task Scenarios** — ทุก task พร้อม scenario + success criteria
4. **Moderator Script** — script ที่พิมพ์ได้
5. **Data Collection Sheet** — ตาราง record data per participant
6. **Analysis Framework** — severity scale + finding template
7. **Timeline** — recruitment → testing → analysis → report
8. **Printable Consent Form** — form ขอ consent บันทึก

### Alternative Output: Markdown
ถ้าผู้ใช้ต้องการ ส่งเป็น markdown สำหรับ Notion/Confluence

---

## หลักการสำคัญ

1. **5 Users Enough**: 5 คนหาปัญหาได้ 85% (Nielsen)
2. **Test Early, Test Often**: ทดสอบ lo-fi ดีกว่าไม่ทดสอบเลย
3. **Observe, Don't Lead**: ห้ามบอกใบ้ ห้ามช่วย (ยกเว้นจำเป็นจริงๆ)
4. **Think Aloud**: ให้ user พูดสิ่งที่คิด — data ที่ดีที่สุด
5. **Behavior > Opinion**: สังเกตสิ่งที่ user ทำ สำคัญกว่าสิ่งที่ user พูด
6. **No Bias**: ห้ามถาม leading questions ("คุณชอบปุ่มนี้ไหม?")
7. **Iterate Fast**: test → find → fix → test again ก่อน launch

---
name: design-handoff-spec
description: "สร้าง Developer Handoff Documentation อย่างครบถ้วน — ครอบคลุม design specs, component inventory, interaction annotations, responsive behavior, edge cases, asset list, API mapping เพื่อให้ dev implement ได้ตรงตาม design โดยไม่ต้องถาม ใช้ skill นี้เมื่อผู้ใช้ต้องการ: ส่งงานให้ dev, สร้าง handoff doc, spec sheet, design spec, component spec, ส่งมอบ design, หรือเมื่อพิมพ์ 'handoff', 'ส่งงาน', 'dev handoff', 'design spec', 'spec sheet', 'ส่งมอบ', 'handoff doc', 'component spec', 'dev spec'"
---

# Design Handoff Specification Skill

สร้าง Developer Handoff Document ที่ครบถ้วน — ให้ dev implement ได้ตรง design โดยไม่ต้องถามซ้ำ

---

## Pipeline Position

```
UI Design → QA Gate (pass) → ★ Design Handoff ★ → Developer
```

---

## Overall Flow

```
1. รับ Design ──▶ 2. วิเคราะห์ ──▶ 3. สร้าง Spec ──▶ 4. สร้าง Handoff Doc ──▶ 5. Output
```

---

## Step 1: รับ Design

ถามผู้ใช้:

- **Source**: Figma URL, HTML preview?
- **Scope**: ทั้ง feature หรือเฉพาะบาง screen?
- **Tech Stack**: dev ใช้อะไร? (React Native, Flutter, SwiftUI, Web?)
- **Design System**: มี shared component library ไหม?
- **Previous Handoff**: เคยส่ง handoff ก่อนหน้าไหม? มี pattern ที่ dev คุ้นเคย?

### วิธีอ่าน Design:

**จาก Figma:**
- get_design_context → อ่าน design details (สี, font, spacing, components)
- get_metadata → ดู structure + layer naming
- get_screenshot → ดู visual
- get_variable_defs → ดู design tokens

**จาก HTML Preview:**
- อ่านไฟล์ .html ด้วย Read tool
- Extract styles, colors, fonts, spacing จาก source

### อ่าน References:
```
references/design-tokens.md              → Token mapping (อ่านเสมอ)
references/ui-preview-quality-rules.md   → Visual design rules สำหรับ spec ให้ dev (อ่านเสมอ)
```

---

## Step 2: วิเคราะห์ Design

### 2.1 Screen Inventory

สำรวจทุก screen + states:

| # | Screen | States | Components | Notes |
|---|--------|--------|------------|-------|
| 1 | Login | default, filled, error, loading | Input×2, Button, Link | Social login options |
| 2 | Home | default, loading, empty, error | Header, Card×N, TabBar | Infinite scroll |

### 2.2 Component Inventory

สำรวจทุก component ที่ใช้:

| Component | Variants | States | Props |
|-----------|----------|--------|-------|
| Button | Primary, Secondary, Tertiary | Default, Pressed, Disabled, Loading | label, icon?, size, isLoading |
| Input | Text, Password, Email, Search | Default, Focused, Filled, Error, Disabled | label, placeholder, helper, error, type |
| Card | Default, Compact, Featured | Default, Pressed | title, subtitle, image?, badge? |

### 2.3 Token Mapping

จับคู่ design values กับ tokens:

| Property | Design Value | Token Name | CSS Variable |
|----------|-------------|------------|-------------|
| Primary color | #EC599D | primary/bg/mid | --color-primary |
| Body text | #1B1D22 | gray-neutral/fg/high | --color-text-primary |
| Card padding | 16px | spacing-4 | --spacing-4 |
| Card radius | 12px | radius-lg | --radius-lg |
| Body font | 16px/24px Regular | caption-3 | --font-body |

---

## Step 3: สร้าง Spec แต่ละ Component

### 3.1 Visual Spec

สำหรับแต่ละ component/screen ระบุ:

```
┌─────────────────────────────────────────────┐
│  Component Name: [PrimaryButton]            │
│                                             │
│  ┌─────────────────────────────┐            │
│  │                             │            │
│  │  ┌───────────────────────┐  │  height: 48px
│  │  │     Label Text        │  │  font: Label.3 (16/24 Bold)
│  │  │     #FFFFFF            │  │  color: white
│  │  └───────────────────────┘  │
│  │                             │  padding: 12px 24px
│  │  bg: #EC599D (primary)      │  radius: 8px (radius-md)
│  │  min-width: 120px           │
│  └─────────────────────────────┘            │
│                                             │
│  States:                                    │
│  ├── Default:  bg #EC599D                   │
│  ├── Pressed:  bg #D14A8A (darken 10%)     │
│  ├── Disabled: bg #EBECEF, text #9A9DAD    │
│  └── Loading:  bg #EC599D + spinner        │
│                                             │
│  Animation:                                 │
│  ├── Press: scale(0.97) 100ms ease-out     │
│  └── Loading: spinner rotate 1s linear     │
└─────────────────────────────────────────────┘
```

### 3.2 Spacing Spec

แต่ละ screen ระบุ spacing:

```
┌─ Screen: Login ─────────────────────────────┐
│                                             │
│  ┌─ Header ──────────────────────┐ pt: 48px │
│  │  Logo (40x40)                 │          │
│  └───────────────────────────────┘          │
│                                    gap: 32px │
│  ┌─ Form ────────────────────────┐          │
│  │  Email Input                  │          │
│  │                      gap: 16px│          │
│  │  Password Input               │          │
│  │                      gap: 8px │          │
│  │  Forgot Password Link         │          │
│  │                      gap: 24px│          │
│  │  Login Button                 │          │
│  │                      gap: 16px│          │
│  │  "or continue with"           │          │
│  │                      gap: 16px│          │
│  │  Social Login Row             │          │
│  └───────────────────────────────┘          │
│                                    gap: 24px │
│  ┌─ Footer ──────────────────────┐          │
│  │  "Don't have account?" Link   │          │
│  └───────────────────────────────┘ pb: 34px │
│                                             │
│  margin-x: 24px                             │
└─────────────────────────────────────────────┘
```

### 3.3 Interaction Spec (Per Component)

| Element | Trigger | Action | Animation | Duration |
|---------|---------|--------|-----------|----------|
| Login Button | Tap | Validate → API call → Navigate | Press scale → Loading → Success | 100ms → ∞ → 300ms |
| Email Input | Focus | Show keyboard, scroll into view | Border color change | 200ms |
| Password Eye | Tap | Toggle visibility | Icon swap | instant |
| Forgot PW | Tap | Navigate to reset flow | Push right | 300ms |
| Social Login | Tap | Open OAuth webview | Scale press → slide up | 100ms → 300ms |

### 3.4 Responsive Behavior

| Breakpoint | Layout Change | Notes |
|------------|--------------|-------|
| Mobile (< 640px) | Single column, full-width buttons | Default design |
| Tablet (768px) | Center content, max-width 400px | Card-like container |
| Desktop (1024px+) | Split layout: illustration left, form right | 50/50 split |

### 3.5 Edge Cases & Error States

| Case | UI Behavior | Copy | Design |
|------|------------|------|--------|
| Empty email | Inline error below input | "กรุณากรอกอีเมล" | Red border + error text |
| Invalid email format | Inline error | "รูปแบบอีเมลไม่ถูกต้อง" | Red border |
| Wrong password | Inline error + shake | "รหัสผ่านไม่ถูกต้อง" | Shake animation 300ms |
| Network error | Toast notification | "ไม่สามารถเชื่อมต่อได้ ลองอีกครั้ง" | Error toast bottom |
| Server 500 | Full-screen error | "เกิดข้อผิดพลาด" + retry button | Error illustration |
| Account locked | Alert dialog | "บัญชีถูกล็อค" + support link | Warning dialog |
| Long email (overflow) | Text ellipsis | — | Truncate with ... |

---

## Step 4: สร้าง Handoff Document

### Handoff Document Structure

```
handoff-doc.html
├── OVERVIEW
│   ├── Feature summary (1-2 sentences)
│   ├── Screen list + state matrix
│   └── Tech requirements (platform, dependencies)
│
├── DESIGN TOKENS
│   ├── Colors used (with CSS variables)
│   ├── Typography used (with token names)
│   ├── Spacing values (with token names)
│   └── Other tokens (radius, shadow, etc.)
│
├── SCREEN SPECS (per screen)
│   ├── Full screenshot + annotated measurements
│   ├── Component breakdown (which components used)
│   ├── Spacing diagram (all margins, paddings, gaps)
│   ├── Responsive behavior table
│   └── Edge cases + error states
│
├── COMPONENT SPECS (per component)
│   ├── Visual spec (size, colors, typography)
│   ├── All states (default, hover, pressed, disabled, error, loading)
│   ├── Props / variants table
│   └── Interaction spec (triggers, animations, durations)
│
├── INTERACTION SPEC
│   ├── Screen transition map
│   ├── Gesture spec (if mobile)
│   ├── Loading states spec
│   └── Animation timing table
│
├── ASSET LIST
│   ├── Icons needed (with size + format)
│   ├── Images needed (with dimensions + format)
│   ├── Illustrations (with source)
│   └── Fonts (with weights + source)
│
├── API MAPPING (if known)
│   ├── Screen → API endpoint mapping
│   ├── Form field → API field mapping
│   └── Error code → UI state mapping
│
└── CHECKLIST
    ├── Implementation checklist (per screen)
    ├── Accessibility requirements
    └── Testing scenarios
```

### Asset Export Spec

| Asset | Format | Sizes | Naming |
|-------|--------|-------|--------|
| App icon | PNG | 1024×1024, @1x @2x @3x | app-icon |
| Tab icons | SVG or PNG | 24×24 @1x, @2x, @3x | icon-{name} |
| Illustrations | SVG or PNG | Original + @2x | illust-{name} |
| Photos | JPEG/WebP | Multiple sizes | photo-{name}-{size} |
| Logos | SVG | Original | logo-{variant} |

### Implementation Notes

สิ่งที่ dev ต้องรู้แต่ design ไม่เห็น:

```markdown
## Notes for Developers

### Behavior Notes
- [Form] Auto-save draft ทุก 30 วินาที
- [List] Infinite scroll — load 20 items per page
- [Image] Lazy load images outside viewport
- [Input] Debounce search input 300ms
- [Button] Disable after tap until API responds (prevent double-submit)

### Accessibility Notes
- All interactive elements: min 44×44pt touch target
- All images: require alt text
- Form errors: announce via screen reader (aria-live="assertive")
- Color is not the only indicator: use icons + text alongside colors
- Support Dynamic Type / font scaling

### Performance Notes
- Use skeleton screens during API calls
- Cache API responses where appropriate
- Optimize images (WebP, lazy load, srcset)
- Preload critical fonts
```

---

## Step 5: Output

### Output Format: HTML Handoff Document

สร้างไฟล์ `handoff-[feature-name].html` ที่แสดง:

1. **Overview** — feature summary + screen list
2. **Token Table** — ทุก token ที่ใช้ พร้อม CSS variable + preview สี
3. **Screen Specs** — annotated screenshots + spacing diagrams
4. **Component Specs** — visual spec + states + props
5. **Interaction Specs** — transitions + animations + gestures
6. **Asset List** — ทุก asset ที่ต้อง export
7. **Edge Cases** — ทุก error/empty/loading state
8. **Implementation Checklist** — dev ใช้ check เมื่อ implement เสร็จ

### Styling Guidelines
- ใช้ Design Tokens ของระบบ
- Component specs ใช้ real design values (px, hex, token names)
- ทุก measurement ต้องชัดเจน — ไม่มี "ประมาณ"
- ใช้ visual diagrams ไม่ใช่แค่ text descriptions

---

## หลักการสำคัญ

1. **No Ambiguity**: ทุก value ต้องระบุ exact (px, hex, token name) — ห้าม "ประมาณ"
2. **All States Covered**: ทุก component ต้องมีทุก state (default, hover, pressed, disabled, error, loading)
3. **Edge Cases First**: Edge cases สำคัญกว่า happy path — dev ต้องรู้ว่า design เมื่อ error/empty/offline
4. **Token-Based**: ทุก value ต้อง map กับ design token — ไม่ใช่ hardcode
5. **Visual > Text**: ใช้ annotated screenshots + diagrams ดีกว่าอธิบาย
6. **Dev Language**: เขียนด้วยภาษาที่ dev เข้าใจ (px, rem, CSS properties)
7. **Single Source of Truth**: Handoff doc คือ "ความจริง" — ถ้า Figma กับ doc ต่างกัน ให้ยึด doc
8. **Checklist-Driven**: dev ต้อง check ทุก item ก่อนส่ง review