medesign 0.0.0-stage → 1.2.0

package/references/modern-craft-invariants.md

@@ -0,0 +1,332 @@
+# Modern Craft Invariants & Apple Design Award Standards (v2.0 Manifesto)
+
+คู่มือวิศวกรรมดีไซน์ขั้นสูง สังเคราะห์จากบททดสอบ Red-Team Audit และการถอดรหัสของ Gemini 4.0 Argon สำหรับใช้งานใน `/medesign` ครอบคลุมกฎเหล็ก 10 ประการ, สถาปัตยกรรม CSS Engine ปี 2026, คณิตศาสตร์ทางสายตา (Visual Optics), และการบริหารทรัพยากร GPU/Display
+
+---
+
+## 1. 🏆 10 กฎเหล็กระดับ Apple Design Award (The 10 Golden Invariants)
+
+### กฎข้อที่ 1: Area-Proportional Press Scaling (กฎการยุบตัวแปรผันผกผันกับขนาดพื้นที่)
+- **ปัญหา:** การใช้ `active:scale-95` (`0.95`) กับทุกขนาดทำให้การ์ดขนาดใหญ่ (เช่น 600×400px) ขอบกระชากเข้ามาถึง 30px ซึ่งรุนแรงเกินไป
+- **สูตรคำนวณและระยะขอบเขต (Optical Displacement):**
+  ระยะยุบตัวทางสายตารวม ($\Delta P$) ต้องคงที่ที่ประมาณ **2px ถึง 3px** (เฉลี่ยขอบเคลื่อนเข้า $\approx 1.25\text{px}$ ต่อด้าน) พร้อมล็อก `clamp()` เพื่อป้องกันการเสียรูป:
+  $$\text{Scale}_{\text{active}} = \text{clamp}\left(0.96, \; 1 - \frac{2.5}{\max(\text{Width}, \text{Height})}, \; 0.995\right)$$
+- **กฎเหล็ก Hit-Target Isolation:** **ห้าม Scale กล่อง Interactive Container ที่รับสัมผัส/การคลิกโดยตรง** เพราะจะทำให้พื้นที่ Hit Test หดตัวลงตาม ให้แยกกล่อง Hit Target ออกจาก Visual Surface เสมอ:
+```css
+/* Interactive Container: รักษาระยะสัมผัส 44px HIG เต็มพื้นที่ */
+.btn-control {
+  position: relative;
+  min-height: 44px;
+  display: inline-flex;
+  align-items: center;
+}
+/* Visual Surface: รับหน้าที่ยุบตัวทางสายตาเท่านั้น */
+.btn-control:active .visual-surface {
+  transform: scale(var(--press-scale, 0.975));
+  transition: transform 80ms cubic-bezier(0.2, 0, 0, 1);
+}
+```
+- **ค่ามาตรฐานประจำ Scale:**
+  - ปุ่มเล็ก ($32\times 32\text{px}$): `transform: scale(0.96);`
+  - ปุ่มกลาง ($48\times 48\text{px}$): `transform: scale(0.98);`
+  - การ์ด/คอนเทนเนอร์ใหญ่ ($400\text{px}+$): `transform: scale(0.994);`
+
+### กฎข้อที่ 2: Asymmetric Entry / Exit Timing & The 4 Motion Profiles
+- **หลักการ:** สมองมนุษย์ต้องการเห็นทิศทางที่มาเมื่อวัตถุปรากฏตัว (Entry) แต่ต้องการให้วัตถุที่สั่งปิดหายไปเร็วที่สุดเพื่อทำงานต่อ (Exit)
+- **สูตรคำนวณเวลาที่สอดคล้องกัน:**
+  $$T_{\text{exit}} = 0.65 \times T_{\text{entry}} \quad (280\text{ms} \times 0.65 = 182\text{ms} \approx 180\text{ms})$$
+- **แยกแยะ Ease-Out กับ Spring Physics ผ่าน 4 Motion Profiles:**
+  | Motion Profile | พฤติกรรมเป้าหมาย | ตัวอย่างการใช้งานจริง | สเปก CSS / Animation |
+  |---|---|---|---|
+  | **`precision`** | เข้าสถานะทันที ไม่มี Overshoot | CAD/GIS Crosshair, ตารางสแกน, สลับข้อมูล | `duration: 0–100ms`, linear/ease-out |
+  | **`soft-settle`** | เร่งต้น ชะลอปลาย นุ่มนวล | Popover, Modal, Dropdown, Tooltip | `240–280ms cubic-bezier(0.16, 1, 0.3, 1)` (Exit: `160–180ms`) |
+  | **`spring-settle`** | มีแรงเฉื่อยทางกายภาพ มี Bounce เบาๆ | การ์ด Drag-and-Drop, Morphing ขยายเต็มจอ | CSS `linear()` spring curve หรือ WAAPI |
+  | **`instant`** | ตัดแอนิเมชันทิ้ง (0ms) | สลับเหรียญ/ฟิลเตอร์, `@media (prefers-reduced-motion)` | `transition: none !important; duration: 0ms;` |
+
+### กฎข้อที่ 3: Diagonal Menu Safe-Triangle (Hover Tunneling Invariant)
+- **ปัญหา:** เมื่อเลื่อนเมาส์แนวทแยงจากเมนูหลักไปยังเมนูย่อย (Submenu) เมาส์จะหลุดข้ามเมนูตัวอื่นและทำให้เมนูย่อยปิดตัวเองทันที
+- **สูตรบังคับ:** สร้างชั้นเรขาคณิตล่องหนด้วย SVG หรือ CSS `clip-path` เชื่อมจากตำแหน่งเมาส์ปัจจุบันไปยังมุมบนและมุมล่างของ Submenu หรือหน่วงเวลาปิด `120ms` เมื่อเวกเตอร์ความเร็วเมาส์ ($\vec{v}$) มุ่งหน้าเข้าหาพื้นที่ Submenu
+
+### กฎข้อที่ 4: Dual-Context Typography & Script-Specific Trimming
+- **UI Chrome (ปุ่ม, แท็บ, เมนู, เซลล์ตาราง, Badge):**
+  - ภาษาอังกฤษ: `line-height: 1.25;` + Progressive `text-box: trim-both cap alphabetic;`
+  - ภาษาไทย: `line-height: 1.38;` + `text-box: trim-both text alphabetic;`
+  - **Thai Diacritic Headroom Invariant:** สระบนและวรรณยุกต์ไทย (ปิ๊, ผู้, ที่) ยื่นเลยระดับ Cap Height เสมอ **ห้าม Trim จนเฉือนวรรณยุกต์ขาด** ต้องใส่ `padding-top: 2px–4px` สำรองเป็น Optical Headroom และห่อหุ้มด้วย `@supports`:
+```css
+@supports (text-box: trim-both cap alphabetic) {
+  .ui-label-en { text-box: trim-both cap alphabetic; }
+  .ui-label-th { 
+    text-box: trim-both text alphabetic; 
+    padding-top: 2px; /* สำรองระยะวรรณยุกต์ไทย */
+  }
+}
+```
+- **Reading Prose (บทความ, เอกสารรายงาน, คำอธิบายยาว):**
+  - ภาษาอังกฤษ: `line-height: 1.60;` + ความกว้างบรรทัด `55ch–68ch;`
+  - ภาษาไทย: `line-height: 1.70–1.75;`
+  - **Font Metric Calibration:** คำสั่ง `size-adjust` เป็น **Descriptor ภายใน `@font-face`** สำหรับปรับจูน Fallback font ให้ความสูง x-height เท่ากับ Web Font จริง ไม่ใช่ CSS inline property:
+```css
+@font-face {
+  font-family: "Geist-Fallback";
+  src: local("Arial");
+  size-adjust: 104%; /* เทียบขนาด Glyph จริง ป้องกัน Layout Shift */
+  ascent-override: 96%;
+}
+```
+
+### กฎข้อที่ 5: Touch-Target Invisible Halo (44×44px HIG Compliance)
+- **ปัญหา:** ใน High-Density WebApp ไอคอนมีขนาดเล็กเพียง `24×24px` หรือ `28×28px` ซึ่งเล็กเกินไปสำหรับการสัมผัสบนมือถือ/แท็บเล็ต
+- **สูตรบังคับ:** แยก Visual Box ออกจาก Hit Box โดยใช้ `::after` ขยายพื้นที่รับสัมผัสเฉพาะอุปกรณ์สัมผัส:
+```css
+.icon-btn-compact {
+  position: relative;
+  width: 28px;
+  height: 28px;
+}
+@media (pointer: coarse) {
+  .icon-btn-compact::after {
+    content: "";
+    position: absolute;
+    inset: -8px; /* 28px + 8px + 8px = 44px ตามมาตรฐาน Apple HIG */
+  }
+}
+```
+
+### กฎข้อที่ 6: Mobile 16px Input Zoom Prevention (Scale-Down Trick)
+- **ปัญหา:** บน iOS Safari หาก `<input>` มี `font-size` ต่ำกว่า `16px` (เช่น `13px` หรือ `14px` ในระบบ High-Density UI) Safari จะบังคับซูมหน้าจออัตโนมัติ
+- **สูตรบังคับ:** บน `@media (max-width: 768px)` กำหนด `font-size: 16px` เพื่อหลอก iOS Safari แล้วย่อขนาดด้วย Transform:
+```css
+@media (max-width: 768px) {
+  .input-compact {
+    font-size: 16px;
+    transform: scale(0.875); /* แสดงผลจริงเทียบเท่า 14px */
+    transform-origin: left center;
+    width: 114.2857%; /* 100 / 0.875 ชดเชยความกว้าง */
+  }
+}
+```
+
+### กฎข้อที่ 7: Dark Mode Variable Font Grade Compensation (Optical Halation Thinning)
+- **ปัญหา:** ตัวหนังสือสีสว่างบนพื้นหลังสีมืดจะบวมขึ้นทางสายตาจากแสงฟุ้ง (Halation Effect)
+- **สูตรบังคับ:** ใน Dark Mode ต้องลดน้ำหนักฟอนต์ลงอัตโนมัติ:
+```css
+[data-theme="dark"] {
+  /* ถ้าเป็น Variable Font ที่มีแกน GRAD */
+  font-variation-settings: "GRAD" -25;
+  /* หรือถ้าเป็น Static Weight ให้ลดน้ำหนักลง 25–30 หน่วย */
+  --font-weight-normal: 375;
+  --font-weight-medium: 470;
+}
+```
+
+### กฎข้อที่ 8: Rubber-Band Resistance Logarithm (กฎความหนืดเมื่อลากสุดขอบ)
+- เมื่อผู้ใช้ลาก Drawer, Bottom Sheet หรือ Slider เกินจุดสิ้นสุด (Over-drag) ให้คำนวณระยะการเคลื่อนที่จริง ($d_{\text{rendered}}$) ด้วยสมการลอการิทึมของ iOS:
+  $$d_{\text{rendered}} = L_{\max} \times \left( 1 - \frac{1}{\frac{\Delta x \times c}{L_{\max}} + 1} \right) \quad (c = 0.55)$$
+
+### กฎข้อที่ 9: Subpixel Scrollbar Gutter & Safe-Area Symmetry
+- บังคับใช้ `scrollbar-gutter: stable;` บนคอนเทนเนอร์ที่เลื่อนได้ทุกตัว เพื่อป้องกันหน้าจอกระตุก 15px เมื่อ Scrollbar ปรากฏขึ้น
+- บนอุปกรณ์เคลื่อนที่ ต้องคำนวณระยะขอบล่างด้วย `padding-bottom: max(var(--space-md), env(safe-area-inset-bottom));` เพื่อไม่ให้ปุ่มโดนแถบ Home Indicator บดบัง
+
+### กฎข้อที่ 10: On-Demand WebGL Render Loop & VRAM Budget Gate
+- สำหรับฉาก 3D Background หรือ CAD/GIS Viewer ที่ไม่มีการเคลื่อนไหวตลอดเวลา **ห้ามรัน `requestAnimationFrame` ต่อเนื่อง**
+- ต้องใช้สถาปัตยกรรม **`frameloop="demand"`**: เรนเดอร์เฉพาะเฟรมที่มีการขยับเมาส์ ซูม หรือระหว่างที่สปริงกล้องยังขยับ เมื่อความเร็ว $\lvert v \rvert < 0.0001$ ให้ตัด Loop ทันทีเพื่อให้ GPU ใช้พลังงาน **0 วัตต์**
+- **งบประมาณ VRAM:** ไฟล์โมเดล 3D ต้องใช้ **Meshopt Compression + KTX2 (Basis Universal) Textures** โดยจำกัดหน่วยความจำหลังคลายบีบอัดบน GPU ไม่เกิน **$32\text{MB}$**
+
+---
+
+## 2. ⚡ Modern CSS Engine Primitives (2026 Standards)
+
+การใช้คุณสมบัติ CSS สมัยใหม่ช่วยตัดโค้ด JavaScript ที่ซับซ้อนทิ้งไปได้มากกว่า 70%:
+
+| ฟีเจอร์ CSS 2026 | การแก้ปัญหาเชิงสถาปัตยกรรม | ไวยากรณ์ระดับ Production |
+|---|---|---|
+| **`light-dark(lightVal, darkVal)`** | ลดความซ้ำซ้อนของการเขียน `.dark { --var: ... }` และป้องกันปัญหาลืมอัปเดตคู่ตัวแปร | ประกาศ `color-scheme: light dark;` ที่ `:root` แล้วเขียนคู่สีในบรรทัดเดียว: `--surface: light-dark(oklch(0.99 0.002 260), oklch(0.14 0.008 260));` |
+| **`text-box-trim` & `text-box-edge`** | ตัดช่องว่าง Half-leading ส่วนเกินของฟอนต์ออก ทำให้ปุ่มและ Badge อยู่กึ่งกลางแนวตั้งเป๊ะ | `@supports (text-box: trim-both cap alphabetic) { text-box: trim-both cap alphabetic; }` |
+| **Popover API + `@starting-style`** | ทำ Modal/Dropdown ลอยบน Browser **Top Layer** (เหนือทุก `z-index`) พร้อมทำ Transition เข้า-ออกโดยไม่ต้องพึ่ง JS | `<div popover>` ควบคู่กับ `@starting-style` และ `transition-behavior: allow-discrete;` |
+| **CSS Anchor Positioning** | ผูก Tooltip/Menu ติดกับปุ่ม พร้อมพลิกหลบขอบจออัตโนมัติบน Compositor Thread 120fps โดยไม่ต้องใช้ Floating UI | `position-anchor: --my-btn;` + `position-try-fallbacks: flip-block, flip-inline;` |
+| **Scroll-Driven Animations** | เชื่อมไทม์ไลน์แอนิเมชันเข้ากับการเลื่อน Viewport โดยตรงที่ระดับ Compositor thread | `animation-timeline: view(); animation-range: entry 0% cover 25%;` (ครอบด้วย reduced-motion gate) |
+| **OKLCH `color-mix()`** | สร้างโทนสี Hover, Focus, Selected และ Tinted Surfaces แบบไดนามิกจากแม่สีตัวแปรเดียว | `color-mix(in oklch, var(--surface-base) 88%, white)` |
+| **`interpolate-size: allow-keywords`** | ปลดล็อกการทำ CSS Transition/Spring ไปหา `height: auto` ได้โดยตรงทั้งระบบ | กำหนด `interpolate-size: allow-keywords;` ที่ `:root` |
+
+### 2.A Scroll-Driven Progressive Animations & Reduced-Motion Gate
+```css
+.section-reveal {
+  opacity: 1;
+  transform: none;
+}
+@media (prefers-reduced-motion: no-preference) {
+  @supports (animation-timeline: view()) {
+    .section-reveal[data-reveal] {
+      animation: section-enter linear both;
+      animation-timeline: view();
+      animation-range: entry 0% cover 25%;
+    }
+    @keyframes section-enter {
+      from { opacity: 0.55; transform: translateY(12px); }
+      to   { opacity: 1;    transform: translateY(0); }
+    }
+  }
+}
+```
+
+### 2.B View Transitions Level 2: Semantic Transition Types
+แทนการใช้ Fade/Spinner แบบเดียว ให้ผูก Transition เข้ากับเจตนาทางสถาปัตยกรรม (Intent):
+| Transition Type | พฤติกรรม UX | การนำไปใช้ |
+|---|---|---|
+| `navigation-forward` | เลื่อนสไลด์ไปข้างหน้า (Drill down) | คลิกดูรายละเอียดแปลงที่ดิน / telemetry telemetry |
+| `navigation-back` | ถอยหลังกลับสู่บริบทเดิม | กดย้อนกลับสู่ Dashboard หลัก |
+| `content-update` | ข้อมูลเปลี่ยนแต่โครงสร้างเดิมนิ่งสนิท | สลับคู่เหรียญ / เปลี่ยนหน่วยพิกัด UTM |
+| `selection-change` | มีแค่ Indicator วิ่งไปหาตัวเลือกใหม่ | สลับแท็บ / สลับเครื่องมือสำรวจ |
+| `layout-reflow` | Bento Card ขยาย/ยุบตัวตามสัดส่วน | กางแถวตารางข้อมูลเชิงลึก |
+
+### 2.C Perceptual Intent Color Engine (OKLab vs OKLCH)
+ยกเลิกการใช้กฎมุมองศาแข็งทื่อ ($\Delta H > 60^\circ$) และปรับใช้ **Perceptual Intent Rules**:
+1. **เมื่อต้องการรักษาความสดฉ่ำของคู่สี (Vibrant Chroma Trajectory):** บังคับใช้ `in oklch shorter hue`
+2. **เมื่อต้องการการเปลี่ยนผ่านความสว่างที่นุ่มนวลหรือไล่เข้าหา Neutral/White/Black:** บังคับใช้ `in oklab` เพื่อขจัดรอยตัดขอบที่ไม่สม่ำเสมอ
+3. **Midpoint Inspection Invariant:** ทดสอบความสว่างและความสดที่ตำแหน่ง `25%`, `50%`, และ `75%` ของ Gradient เสมอ เพื่อป้องกันสีหม่นเทาหรือวูบผิดเจตนา
+4. **Dynamic Token Derivation ผ่าน `color-mix()`:**
+```css
+:root {
+  --color-accent: oklch(0.68 0.18 42); /* Terracotta */
+  --surface-base:  oklch(0.14 0.008 260); /* Obsidian Base */
+  
+  /* สร้างพื้นผิวยกระดับและสถานะโดยไม่ต้องฮาร์ดโค้ด Hex */
+  --surface-raised: color-mix(in oklch, var(--surface-base) 88%, white);
+  --surface-hover:  color-mix(in oklch, var(--surface-base) 90%, var(--color-accent));
+  --border-subtle:  color-mix(in oklch, var(--surface-base) 82%, white);
+}
+```
+5. **Functional Dark Mode Neutrals:** กำหนด Token ตามหน้าที่ ไม่พึ่งพาเพียงแค่ค่าตัวเลข Chroma:
+   - `--surface-canvas`: พื้นหลังลึกสุด (`oklch(0.10 0.006 260)`) ควบคู่ OLED Black `#000000`
+   - `--surface-raised`: การ์ดและคอนเทนเนอร์ลอย (`oklch(0.14 0.008 260)`)
+   - `--surface-inset`: พื้นที่กรอกข้อมูล / หน้าจอแผนที่ (`oklch(0.12 0.006 260)`)
+   - `--border-subtle`: เส้นแบ่งความคมชัดต่ำที่ไม่แย่งความสนใจ
+   - `--border-focus`: เส้นโฟกัสความคมชัดสูง (>3:1 ต่อพื้นผิว)
+
+### 2.D Anchor Positioning & Interactive Popover Menu
+```css
+:root {
+  color-scheme: light dark;
+  interpolate-size: allow-keywords;
+
+  --surface-popover: light-dark(oklch(0.99 0.002 260 / 0.90), oklch(0.16 0.008 260 / 0.88));
+  --border-popover:  light-dark(oklch(0.15 0.008 260 / 0.08), oklch(1.00 0.000 0 / 0.10));
+}
+
+.trigger-btn {
+  anchor-name: --menu-anchor;
+}
+
+.popover-menu[popover] {
+  position: fixed;
+  position-anchor: --menu-anchor;
+  top: calc(anchor(bottom) + 6px);
+  left: anchor(left);
+  position-try-fallbacks: flip-block, flip-inline;
+
+  background: var(--surface-popover);
+  backdrop-filter: blur(20px) saturate(180%);
+  border-radius: 10px;
+  box-shadow: 0 0 0 1px var(--border-popover), 0 12px 32px -4px oklch(0 0 0 / 0.28);
+
+  opacity: 0;
+  transform: scale(0.96) translateY(-4px);
+  transition:
+    opacity 160ms ease,
+    transform 200ms cubic-bezier(0.16, 1, 0.3, 1),
+    overlay 200ms allow-discrete,
+    display 200ms allow-discrete;
+}
+
+.popover-menu[popover]:popover-open {
+  opacity: 1;
+  transform: scale(1) translateY(0);
+}
+
+@starting-style {
+  .popover-menu[popover]:popover-open {
+    opacity: 0;
+    transform: scale(0.96) translateY(-4px);
+  }
+}
+```
+
+---
+
+## 3. 📐 Optical Geometry & Spacing Mathematics
+
+### 3.1 Optical Centering ของไอคอนสามเหลี่ยม (Play Button)
+จุดศูนย์ถ่วงมวล (Centroid) ของสามเหลี่ยมด้านเท่าที่มีความกว้าง $W$ อยู่ที่ระยะ $\frac{1}{3}W$ จากฐาน ในขณะที่ Bounding Box กึ่งกลางอยู่ที่ $\frac{1}{2}W$
+- **ระยะชดเชยที่ถูกต้อง:** ต้องเลื่อนไอคอนไปทางขวาตามแนวแกน X:
+  $$\Delta x = \frac{W}{2} - \frac{W}{3} = \frac{W}{6} \approx 0.167 \times W \quad (\text{หรือ } \frac{W}{8} \text{ สำหรับไอคอนขอบมน})$$
+
+### 3.2 Concentric Border Radius & Smooth Morphing Invariant
+- **สูตรคำนวณ Safe Concentric Radius:**
+  $$R_{\text{inner}} = \max\left(0\text{px}, \; R_{\text{outer}} - B_{\text{width}} - \text{Padding}\right)$$
+- ป้องกันค่าติดลบจน Browser ทิ้งคำสั่ง และชดเชยความหนาของขอบ Border จริง
+- **Morphing Invariant (Finite Geometry vs Infinity):**
+  - สำหรับรูปทรงสถิต (Static Pills): อนุญาตให้ใช้ `calc(infinity * 1px)` หรือ `999px`
+  - สำหรับรูปทรงที่มีการ Animate / Morphing ระหว่างสี่เหลี่ยมผืนผ้าไปเป็นวงรี/แคปซูล: **ห้ามใช้ infinity** เพราะจะทำให้การ Interpolate ขอบกระตุก ให้ผูกกับมิติทางเรขาคณิตจริง เช่น `calc(var(--el-height) / 2)` หรือลงทะเบียนผ่าน `@property <length>` เสมอเพื่อความราบรื่นระดับ 120fps:
+```css
+@property --corner-r {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 8px;
+}
+.morphing-surface {
+  border-radius: var(--corner-r);
+  transition: --corner-r 260ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+### 3.3 Doppelrand (Double-Border Specular Catch-Light)
+เทคนิคจำลองขอบ Anodized Aluminum และการ์ดระดับ Linear:
+```css
+.surface-doppelrand {
+  background: oklch(0.16 0.008 260 / 0.85);
+  backdrop-filter: blur(16px) saturate(180%);
+  border-radius: 12px;
+  /* Layer 1: Outer dark hairline (1px)
+     Layer 2: Top edge specular highlight (1px inset)
+     Layer 3: Omnidirectional inner rim (1px inset) */
+  box-shadow:
+    0 0 0 1px oklch(0.08 0.008 260 / 0.90),
+    inset 0 1px 0 0 oklch(1 0 0 / 0.14),
+    inset 0 0 0 1px oklch(1 0 0 / 0.04);
+}
+```
+
+### 3.4 Multi-Layered Exponential Ambient Shadows
+จำลองการกระจายตัวของแสงในธรรมชาติด้วยสมการ Exponential Progression ($y_n = 2^{n-1}, \sigma_n = 2y_n$):
+```css
+:root {
+  --shadow-hue: 260;
+  --elevation-high:
+    0px 1px 1px -0.5px oklch(0.05 0.01 var(--shadow-hue) / 0.36),
+    0px 3px 6px -1.5px oklch(0.05 0.01 var(--shadow-hue) / 0.28),
+    0px 8px 16px -4px oklch(0.05 0.01 var(--shadow-hue) / 0.22),
+    0px 20px 40px -8px oklch(0.05 0.01 var(--shadow-hue) / 0.16),
+    0px 0px 0px 1px oklch(0.05 0.01 var(--shadow-hue) / 0.60);
+}
+```
+
+### 3.5 Fluid Typography & Spacing Math (`clamp()`)
+สมการเส้นตรง $y = mx + b$ สำหรับปรับขนาดฟอนต์ระหว่าง Viewport $375\text{px}$ ถึง $1440\text{px}$ แบบไร้รอยต่อ:
+```css
+:root {
+  --text-xs:   clamp(0.75rem, 0.7148rem + 0.1502vw, 0.85rem);
+  --text-sm:   clamp(0.875rem, 0.8310rem + 0.1878vw, 1.00rem);
+  --text-base: clamp(1.00rem, 0.9472rem + 0.2254vw, 1.15rem);
+  --text-lg:   clamp(1.25rem, 1.1620rem + 0.3756vw, 1.50rem);
+  --text-xl:   clamp(1.625rem, 1.4049rem + 0.9390vw, 2.25rem);
+  --text-2xl:  clamp(2.25rem, 1.6338rem + 2.6291vw, 4.00rem);
+}
+```
+
+---
+
+## 4. 🧬 2.5-Tier Token Architecture & Polarity Discipline
+
+เพื่อป้องกันปัญหา CSS Variable Waterfall Cascade บนตารางข้อมูลขนาดใหญ่ ให้ใช้สถาปัตยกรรม **2.5-Tier**:
+1. **Tier 1 (Primitives) & Tier 2 (Semantics):** กำหนดไว้ที่ `:root` ผ่านฟังก์ชัน `light-dark()`
+2. **Tier 3 (Components):** ห้ามประกาศเป็น Global Tokens เด็ดขาด ให้ใช้เป็น **Private Scoped Aliases** ที่ขึ้นต้นด้วย Underscore (`--_bg`, `--_border`, `--_text`) ภายใน Class ของ Component นั้นๆ เท่านั้น

package/references/motion-tokens.md

@@ -0,0 +1,99 @@
+# Motion Design Tokens (Takayu Studio Framework)
+
+ระบบตัวแปร Motion & Animation ระดับ Production ดัดแปลงจาก Takayu Studio Motion Reference (782 Demos) เพื่อเปลี่ยน Animation เชยๆ แบบสุ่ม (`0.3s ease`) ให้กลายเป็นความรู้สึกสัมผัสที่มีน้ำหนักและประณีต (High-Fidelity Tactile Feel)
+
+---
+
+## 1. The 5 Feel Archetypes (บุคลิกความรู้สึก 5 ระดับ)
+
+| Archetype | Feel & Sensation | Duration (ms) | Cubic-Bezier Curve | Component Mappings |
+| :--- | :--- | :--- | :--- | :--- |
+| **1. Crisp** | เฉียบคม ฉับไว แม่นยำ | `120 - 180ms` | `cubic-bezier(0.2, 0.0, 0.0, 1.0)` | ปุ่มกด (Button active), Toggle, Tooltip, Checkbox, Icon tap |
+| **2. Smooth** | ลื่นไหล เป็นธรรมชาติ มีจังหวะ | `250 - 350ms` | `cubic-bezier(0.4, 0.0, 0.2, 1.0)` | Dropdown menu, Tab switch, Accordion, Modal slide-in |
+| **3. Soft** | นุ่มนวล ละมุนตา ไม่เร่งรีบ | `400 - 500ms` | `cubic-bezier(0.25, 1.0, 0.5, 1.0)` | Backdrop fade, Hero section reveal, Toast entry, Skeleton pulse |
+| **4. Heavy** | หนักแน่น มีมวลแรงโน้มถ่วง | `500 - 700ms` | `cubic-bezier(0.7, 0.0, 0.3, 1.0)` | Drawer slide-up, Fullscreen sheet, Large card expansion |
+| **5. Bouncy** | เด้งดึ๋ง สปริง มีพลัง (Overshoot) | `350 - 500ms` | `cubic-bezier(0.34, 1.56, 0.64, 1.0)` | Notification badge pop, Success checkmark, Like heart, Pin drop |
+
+---
+
+## 2. Standard CSS Variables (`:root`)
+
+คัดลอกชุดตัวแปรนี้ไปวางในไฟล์ CSS หลัก (`globals.css` หรือ `design-tokens.css`):
+
+```css
+:root {
+  /* --- Duration Tokens --- */
+  --motion-duration-instant: 100ms;
+  --motion-duration-crisp: 180ms;
+  --motion-duration-smooth: 300ms;
+  --motion-duration-soft: 450ms;
+  --motion-duration-heavy: 600ms;
+
+  /* --- Easing Curves (Cubic-Bezier) --- */
+  --motion-ease-crisp: cubic-bezier(0.2, 0.0, 0.0, 1.0);
+  --motion-ease-smooth: cubic-bezier(0.4, 0.0, 0.2, 1.0);
+  --motion-ease-soft: cubic-bezier(0.25, 1.0, 0.5, 1.0);
+  --motion-ease-heavy: cubic-bezier(0.7, 0.0, 0.3, 1.0);
+  --motion-ease-bouncy: cubic-bezier(0.34, 1.56, 0.64, 1.0);
+
+  /* --- Composite Transition Tokens --- */
+  --transition-button: transform var(--motion-duration-crisp) var(--motion-ease-crisp),
+                       background-color var(--motion-duration-crisp) var(--motion-ease-crisp);
+  --transition-dropdown: opacity var(--motion-duration-smooth) var(--motion-ease-smooth),
+                         transform var(--motion-duration-smooth) var(--motion-ease-smooth);
+  --transition-modal: opacity var(--motion-duration-smooth) var(--motion-ease-smooth),
+                      transform var(--motion-duration-smooth) var(--motion-ease-smooth);
+  --transition-drawer: transform var(--motion-duration-heavy) var(--motion-ease-heavy);
+  --transition-badge: transform var(--motion-duration-smooth) var(--motion-ease-bouncy);
+}
+```
+
+---
+
+## 3. Tailwind CSS Integration (`tailwind.config.js`)
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      transitionDuration: {
+        'instant': '100ms',
+        'crisp': '180ms',
+        'smooth': '300ms',
+        'soft': '450ms',
+        'heavy': '600ms',
+      },
+      transitionTimingFunction: {
+        'crisp': 'cubic-bezier(0.2, 0.0, 0.0, 1.0)',
+        'smooth': 'cubic-bezier(0.4, 0.0, 0.2, 1.0)',
+        'soft': 'cubic-bezier(0.25, 1.0, 0.5, 1.0)',
+        'heavy': 'cubic-bezier(0.7, 0.0, 0.3, 1.0)',
+        'bouncy': 'cubic-bezier(0.34, 1.56, 0.64, 1.0)',
+      },
+    },
+  },
+}
+```
+
+---
+
+## 4. Framer Motion / Spring Physics Presets
+
+สำหรับ React และ Next.js ที่ใช้ `framer-motion`:
+
+```typescript
+export const motionSpring = {
+  crisp: { type: "spring", stiffness: 500, damping: 30, mass: 0.8 },
+  smooth: { type: "spring", stiffness: 350, damping: 25, mass: 1 },
+  heavy: { type: "spring", stiffness: 220, damping: 28, mass: 1.5 },
+  bouncy: { type: "spring", stiffness: 400, damping: 15, mass: 1 },
+};
+```
+
+---
+
+## 5. Best Practices & Invariants
+
+1. **ห้ามใช้ `transition: all 0.3s ease` มักง่าย:** ให้ระบุ Properties ชัดเจน (`transform`, `opacity`) เสมอเพื่อประสิทธิภาพ GPU Render (60-120fps)
+2. **Reduced Motion Respect:** ต้องรองรับ `@media (prefers-reduced-motion: reduce)` เสมอ สำหรับผู้ใช้ที่เวียนหัวจากภาพเคลื่อนไหว
+3. **Data-Dense UIs (Trading/Survey):** ในตารางข้อมูล แดชบอร์ดคำนวณ ห้ามใส่ Motion นานเกิน $150\text{ms}$ (ใช้เฉพาะ Crisp หรือ Instant เท่านั้น)

package/references/preflight.md

@@ -0,0 +1,110 @@
+## 6. PERFORMANCE & ACCESSIBILITY GUARDRAILS
+
+### 6.A Hardware Acceleration
+* Animate ONLY `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`.
+* Use `will-change: transform` sparingly - only on elements that will actually animate.
+
+### 6.B Reduced Motion (mandatory)
+* **Any motion above `MOTION_INTENSITY > 3` MUST honor `prefers-reduced-motion`.** This is non-negotiable.
+* In Motion: wrap with `useReducedMotion()` and degrade to static.
+* In CSS: gate animations behind `@media (prefers-reduced-motion: no-preference)` or provide an override block under `@media (prefers-reduced-motion: reduce)` that disables.
+* Infinite loops, parallax, scroll-hijack, and magnetic physics MUST collapse to static / instant under reduced motion.
+
+### 6.C Dark Mode (mandatory for any consumer-facing page)
+* Design for **both modes from the start**. Never ship light-only or dark-only without explicit user instruction.
+* Use Tailwind `dark:` variant OR CSS variables for tokens. Pick one strategy per project.
+* **Do not prescribe specific dark-mode colors here.** The brief decides. Maintain visual hierarchy, brand identity, and WCAG AA contrast (AAA for body) across both modes.
+* Respect `prefers-color-scheme: dark`. Default to system preference unless the brand insists on one mode.
+
+### 6.D Core Web Vitals Targets
+* **LCP** < 2.5s. Hero image must be `next/image priority` or preloaded.
+* **INP** < 200ms. Heavy work off main thread.
+* **CLS** < 0.1. Reserve space for images, fonts, embeds.
+* Run Lighthouse before declaring a page done.
+
+### 6.E DOM Cost
+* Apply grain / noise filters EXCLUSIVELY to fixed, `pointer-events-none` pseudo-elements (e.g., `fixed inset-0 z-[60] pointer-events-none`). NEVER on scrolling containers - continuous GPU repaints destroy mobile FPS.
+* Be aware of bundle size. Motion is not tiny. Three.js is large. Lazy-load anything that's not above-the-fold.
+
+### 6.F Z-Index Restraint
+NEVER spam arbitrary `z-50` or `z-10`. Use z-index strictly for systemic layer contexts (sticky navbars, modals, overlays, grain). Document the z-index scale in a project constants file.
+
+---
+
+## 14. FINAL PRE-FLIGHT CHECK
+
+Run this matrix before outputting code. This is the last filter.
+
+**THIS IS NOT OPTIONAL. Run every box. If any box fails, the output is not done.**
+
+- [ ] **Brief inference** declared (Section 0.B one-liner)?
+- [ ] **Dial values** explicit and reasoned from the brief, not silently using baseline?
+- [ ] **Design system** chosen from Section 2 if applicable, or aesthetic labeled honestly?
+- [ ] **Redesign mode** detected and audit performed (if applicable, Section 11)?
+- [ ] **ZERO em-dashes (`—`) anywhere on the page.** Headlines, eyebrows, pills, body, quotes, attribution, captions, buttons, alt text. Zero. (Section 9.G - non-negotiable.)
+- [ ] **Page Theme Lock**: ONE theme (light, dark, or auto) for the whole page. No section flips to inverted mode mid-page (Section 4.11)?
+- [ ] **Color Consistency Lock**: one accent color used identically across all sections (Section 4.2)?
+- [ ] **Shape Consistency Lock**: one corner-radius system applied consistently (Section 4.4)?
+- [ ] **Button Contrast Check**: every CTA text is readable against its background (no white-on-white, WCAG AA 4.5:1)?
+- [ ] **CTA Button Wrap**: no CTA label wraps to 2+ lines at desktop?
+- [ ] **Form Contrast Check**: form inputs, placeholders, focus rings, labels all pass WCAG AA against the section background?
+- [ ] **Serif discipline**: if a serif is used, it is NOT Fraunces or Instrument_Serif (or it is, with explicit brand justification)? Different serif from your previous project?
+- [ ] **Premium-consumer palette check**: if the brief is premium-consumer (cookware / wellness / artisan / luxury), the palette is NOT the AI-default beige+brass+oxblood+espresso family? Different family from your previous premium-consumer project?
+- [ ] **Italic descender clearance**: every italic word with `y g j p q` has `leading-[1.1]` min + `pb-1` reserve?
+- [ ] **Hero fits the viewport**: headline ≤ 2 lines, subtext ≤ 20 words AND ≤ 4 lines, CTA visible without scroll, font scale planned around image?
+- [ ] **Hero top padding**: max `pt-24` at desktop, hero content does not float halfway down the viewport?
+- [ ] **Hero stack discipline**: max 4 text elements in hero (eyebrow OR brand strip, headline, subtext, CTAs)? No tiny tagline below CTAs, no trust micro-strip in hero?
+- [ ] **EYEBROW COUNT (mechanical)**: count instances of `uppercase tracking` micro-labels above section headlines across all components. Count ≤ ceil(sectionCount / 3)? Hero counts as 1.
+- [ ] **Split-Header Ban**: no "left big headline + right small explainer paragraph" pattern as a section header (vertical stack instead)?
+- [ ] **Zigzag Alternation Cap**: no 3+ consecutive sections with the same image+text-split layout?
+- [ ] **No Duplicate CTA Intent**: no two CTAs with the same intent ("Get in touch" + "Let's talk" both on page = Fail)?
+- [ ] **Logo wall = logo only**: no industry / category labels printed below logos?
+- [ ] **Bento Background Diversity**: at least 2-3 bento cells have real visual variation (image, gradient, pattern), not all white-on-white text cards?
+- [ ] **"Used by / Trusted by" logo wall** lives UNDER the hero, not inside it, uses REAL SVG logos (Simple Icons / devicon) or generated SVG marks, NOT plain text wordmarks?
+- [ ] **Copy Self-Audit**: every visible string re-read, no grammatically-broken or AI-hallucinated phrases ("free on its past" type) shipped?
+- [ ] **Motion motivated**: every animation can be justified in one sentence (hierarchy / storytelling / feedback / state transition), no GSAP-for-show?
+- [ ] **Marquee max-one-per-page**: no two horizontal marquees on the same page?
+- [ ] **Navigation on ONE line** at desktop, height ≤ 80px?
+- [ ] **Section-Layout-Repetition** check: no two sections share the same layout family (at least 4 different families across 8 sections)?
+- [ ] **Bento has rhythm AND exact cell count** (N items → N cells, no empty cells in middle or at end)?
+- [ ] **Long lists use the right UI component** (not default `<ul>` with `divide-y` for > 5 items - see Section 4.9 alternatives)?
+- [ ] **Real images used** (gen-tool first, then Picsum-seed, then explicit placeholder slots) - NO div-based fake screenshots, NO hand-rolled decorative SVGs, NO pure-text minimalism?
+- [ ] **No pills/labels overlaid on images** (no `Plate · Brand`, no `Field notes - journal`)?
+- [ ] **No photo-credit captions as decoration** (`Field study no. 12 · Ines Caetano`)?
+- [ ] **No version footers** (`v1.4.2`, `Build 0048`) on marketing pages?
+- [ ] **No micro-meta-sentences** under eyebrows ("Each of these is a feature we ship today...")?
+- [ ] **No decoration text strip at hero bottom** (`BRAND. MOTION. SPATIAL.`)?
+- [ ] **No floating top-right sub-text** in section headings?
+- [ ] **No scoring/progress bars with filled background tracks** as comparison visuals?
+- [ ] **No locale / city-name / time / weather strips** unless brief is genuinely globally-distributed or place-focused?
+- [ ] **No scroll cues** (`Scroll`, `↓ scroll`, `Scroll to explore`)?
+- [ ] **No version labels in hero** (V0.6, BETA, INVITE-ONLY) unless the brief is a launch?
+- [ ] **No section-numbering eyebrows** (`00 / INDEX`, `001 · Capabilities`, `06 · how it works`)?
+- [ ] **No decorative dots** (zero by default, only for real semantic state)?
+- [ ] **No `border-t` + `border-b` on every row** of long lists / spec tables?
+- [ ] **Content density** sane: no 20-row data tables, no fake-precise specs without justification, ≤ 25-word sub-paragraphs by default?
+- [ ] **Quotes ≤ 3 lines** of body, attribution clean (no em-dash)?
+- [ ] **Motion claimed = motion shown**: if `MOTION_INTENSITY > 4`, page actually animates, not just claimed?
+- [ ] **GSAP sticky-stack / horizontal-pan** implemented per Section 5.A / 5.B canonical skeleton (`start: "top top"`, `pin: true`, correct scrub)?
+- [ ] **No `window.addEventListener('scroll')`** - using Motion `useScroll()` / ScrollTrigger / IntersectionObserver / CSS scroll-driven animations only?
+- [ ] **Reduced motion** wrapped for everything `MOTION_INTENSITY > 3`?
+- [ ] **Dark mode** tokens defined and tested in both modes?
+- [ ] **Mobile collapse** explicit (`w-full`, `px-4`, `max-w-7xl mx-auto`) for high-variance layouts?
+- [ ] **Viewport stability**: `min-h-[100dvh]`, never `h-screen`?
+- [ ] **`useEffect` animations** have strict cleanup functions?
+- [ ] **Empty / loading / error** states provided?
+- [ ] **Cards omitted** in favor of spacing where possible?
+- [ ] **Icons** from an allowed library only (Phosphor / HugeIcons / Radix / Tabler), no hand-rolled SVG paths?
+- [ ] **Motion** isolated in client-leaf components with `'use client'` at the top, memoized?
+- [ ] **No AI Tells** from Section 9 (Inter as default, AI-purple, three-equal cards, Jane Doe, Acme, "Quietly in use at")?
+- [ ] **Core Web Vitals** plausibly hit (LCP < 2.5s, INP < 200ms, CLS < 0.1)?
+- [ ] **One design system** per project (no Material + shadcn mixed)?
+
+If a single checkbox cannot be honestly ticked, the page is not done. Fix it before delivering.
+
+---
+
+# APPENDICES - Real Source-Backed Reference Material
+
+The sections below are vendored reference content. They give the agent real install commands, real canonical doc links, and real working starter snippets for each design system named in Section 2. Use them to ground decisions in production reality, not training-data fiction.
+