medesign 0.0.0-stage → 1.2.0

package/references/proactive-motion.md

@@ -0,0 +1,167 @@
+## 5. CONTEXT-AWARE PROACTIVITY
+
+These are tools, not defaults. Use them when the design read calls for them. **None of these fire automatically.**
+
+* **Liquid Glass / Glassmorphism:** Appropriate for premium consumer, Apple-adjacent, luxury brand, or media-overlay vibes. Inappropriate for dashboards, public-sector, or "boring B2B." When used, go beyond `backdrop-blur`: add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) for physical edge refraction. Provide a solid-fill fallback under `prefers-reduced-transparency`.
+* **Magnetic Micro-physics:** Use when `MOTION_INTENSITY > 5` AND the brief reads premium / playful / agency. Implement EXCLUSIVELY with Motion's `useMotionValue` / `useTransform` outside the React render cycle. Never `useState`. See Section 3.B.
+* **Perpetual Micro-Interactions** (Pulse, Typewriter, Float, Shimmer, Carousel): Use when `MOTION_INTENSITY > 5` AND the section actively benefits from motion (status indicators, live feeds, AI-feel). **Not every card needs an infinite loop.** If a section is informational, leave it still. Apply Spring Physics (`type: "spring", stiffness: 100, damping: 20`) - no linear easing.
+* **"Motion claimed, motion shown."** If `MOTION_INTENSITY > 4`, the page must actually move: entry transitions on hero, scroll-reveal on key sections, hover physics on CTAs, at minimum. A static page that claims `MOTION_INTENSITY: 7` is broken. Conversely, if you cannot ship working motion in the available scope, drop the dial to 3 and ship a clean static page. Never half-build motion that breaks (cut-off ScrollTriggers, jumpy enters, missing cleanups).
+* **MOTION MUST BE MOTIVATED (mandatory).** Before adding any animation, ask: "what does this animation communicate?" Valid answers: hierarchy (drawing attention to the right thing), storytelling (revealing content in sequence that matches a narrative), feedback (acknowledging a user action), state transition (showing something changed). Invalid answer: "it looked cool". GSAP everywhere because GSAP is available is amateur. Each ScrollTrigger, each marquee, each pinned section needs a reason. If you cannot articulate the reason in one sentence, drop the animation.
+* **MARQUEE MAX-ONE-PER-PAGE (mandatory).** Horizontal scrolling text marquees ("logos endlessly scrolling", "manifesto scrolling sideways", "kinetic word strip") are appropriate at most ONCE per page. Two or more marquees on the same page reads as lazy filler. Pick the one section where the marquee actually serves the content; the others get a different layout.
+* **GSAP Sticky-Stack Pattern (when scroll-stack is used).** A "card stack on scroll" must be a REAL sticky-stack, not a sequential reveal list. See Section 5.A below for the canonical code skeleton. Common failure: trigger fires halfway through scroll instead of pinning at viewport top. Fix: `start: "top top"` not `start: "top center"` or `"top 80%"`.
+* **GSAP Horizontal-Pan Pattern (when horizontal scroll-hijack is used).** See Section 5.B below for the canonical skeleton. Common failure: animation starts before the section is pinned, so the user sees half a slide. Same fix: `start: "top top"`, pin the wrapper, scrub the inner track.
+
+### 5.A Sticky-Stack - Canonical Skeleton
+
+```tsx
+"use client";
+import { useRef, useEffect } from "react";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { useReducedMotion } from "motion/react";
+
+gsap.registerPlugin(ScrollTrigger);
+
+export function StickyStack({ cards }: { cards: React.ReactNode[] }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const reduce = useReducedMotion();
+
+  useEffect(() => {
+    if (reduce || !ref.current) return;
+    const ctx = gsap.context(() => {
+      const cardEls = gsap.utils.toArray<HTMLElement>(".stack-card");
+      cardEls.forEach((card, i) => {
+        if (i === cardEls.length - 1) return;
+        ScrollTrigger.create({
+          trigger: card,
+          start: "top top",                              // pin at viewport top
+          endTrigger: cardEls[cardEls.length - 1],
+          end: "top top",
+          pin: true,
+          pinSpacing: false,
+        });
+        gsap.to(card, {
+          scale: 0.92,
+          opacity: 0.55,
+          ease: "none",
+          scrollTrigger: {
+            trigger: cardEls[i + 1],
+            start: "top bottom",
+            end: "top top",
+            scrub: true,
+          },
+        });
+      });
+    }, ref);
+    return () => ctx.revert();
+  }, [reduce]);
+
+  return (
+    <div ref={ref} className="relative">
+      {cards.map((card, i) => (
+        <div
+          key={i}
+          className="stack-card sticky top-0 min-h-[100dvh] flex items-center justify-center"
+        >
+          {card}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+Critical points: `start: "top top"`, `pin: true`, every card except the last is pinned, the scale/opacity transform is driven by the NEXT card's scroll trigger (so previous card shrinks as next one arrives).
+
+### 5.B Horizontal-Pan - Canonical Skeleton
+
+```tsx
+"use client";
+import { useRef, useEffect } from "react";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { useReducedMotion } from "motion/react";
+
+gsap.registerPlugin(ScrollTrigger);
+
+export function HorizontalPan({ children }: { children: React.ReactNode }) {
+  const wrap = useRef<HTMLDivElement>(null);
+  const track = useRef<HTMLDivElement>(null);
+  const reduce = useReducedMotion();
+
+  useEffect(() => {
+    if (reduce || !wrap.current || !track.current) return;
+    const ctx = gsap.context(() => {
+      const distance = track.current!.scrollWidth - window.innerWidth;
+      gsap.to(track.current, {
+        x: -distance,
+        ease: "none",
+        scrollTrigger: {
+          trigger: wrap.current,
+          start: "top top",                              // pin starts when section top hits viewport top
+          end: () => `+=${distance}`,                    // scroll distance = track width minus viewport
+          pin: true,
+          scrub: 1,
+          invalidateOnRefresh: true,
+        },
+      });
+    }, wrap);
+    return () => ctx.revert();
+  }, [reduce]);
+
+  return (
+    <section ref={wrap} className="relative overflow-hidden">
+      <div ref={track} className="flex h-[100dvh] items-center">
+        {children}
+      </div>
+    </section>
+  );
+}
+```
+
+Critical points: `start: "top top"`, `pin: true`, `end: "+=${distance}"` (scroll length = horizontal travel needed), `scrub: 1`. The wrapper is pinned, the inner track slides horizontally as the user scrolls vertically.
+
+### 5.C Scroll-Reveal Stagger - Canonical Skeleton (lighter alternative)
+
+For simple "items appear as they enter viewport" (no pinning), prefer Motion's `whileInView` over GSAP - lighter, no ScrollTrigger needed:
+
+```tsx
+"use client";
+import { motion, useReducedMotion } from "motion/react";
+
+export function RevealStagger({ items }: { items: string[] }) {
+  const reduce = useReducedMotion();
+  return (
+    <ul className="grid gap-6">
+      {items.map((item, i) => (
+        <motion.li
+          key={item}
+          initial={reduce ? false : { opacity: 0, y: 24 }}
+          whileInView={{ opacity: 1, y: 0 }}
+          viewport={{ once: true, amount: 0.3 }}
+          transition={{
+            duration: 0.6,
+            delay: i * 0.06,
+            ease: [0.16, 1, 0.3, 1],
+          }}
+        >
+          {item}
+        </motion.li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Use this for: feature lists, testimonial grids, logo walls, anything that just needs "enter on scroll." Save GSAP for actual pin/scrub work.
+
+### 5.D Forbidden Animation Patterns
+
+* **`window.addEventListener("scroll", ...)`** is banned. It runs on every scroll frame, jank-prone, no batching. Use Motion's `useScroll()`, GSAP's `ScrollTrigger`, IntersectionObserver, or CSS `scroll-driven animations` (`animation-timeline: view()`).
+* **Custom scroll progress calculations using `window.scrollY`** in React state. Same reason. Re-renders on every frame.
+* **`requestAnimationFrame` loops that touch React state.** Use motion values (`useMotionValue` + `useTransform`) instead.
+* **Layout Transitions:** Use Motion's `layout` and `layoutId` props for visible state changes (re-ordering lists, expanding modals, shared elements between routes). Do not wrap static content in `layout` props "for safety" - it costs measurement work.
+* **Staggered Orchestration:** Use `staggerChildren` (Motion) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) for reveal moments where sequence matters. For `staggerChildren`, parent (`variants`) and children MUST share the same Client Component tree.
+
+---
+

package/references/quality-gate.md

@@ -0,0 +1,147 @@
+## 9. Multi-Skill Design Optimization Engine (11-Skill Unified Synthesis)
+
+เมื่อเรียกใช้ `/medesign` (ทั้งในโหมดสร้างหน้าใหม่, โหมดรีดีไซน์, และโหมด Auto-Blueprint `FINAL-01..04`) ระบบจะบังคับใช้ **กฎวิศวกรรมดีไซน์และเกณฑ์ตรวจสอบคุณภาพจาก 11 สกิลหลัก** โดยอัตโนมัติ:
+
+### 9.1 🎛️ Design Dials & Spatial Topology (`taste-skill`)
+- **3-Axis Design Dials (Locked Calibration):**
+  - `DESIGN_VARIANCE = 8–9/10` (Asymmetric Grids: `3:6:3` Newspaper Command, `8:4` Bento Split, `45:55` Master-Detail, หรือ Expandable Executive Stream — **ห้ามใช้ 3-Card Equal Generic Row ติดกันโดยไม่มีจังหวะลำดับขั้น**)
+  - `MOTION_INTENSITY = 6/10` (Spring Physics `cubic-bezier(0.22, 1, 0.36, 1)` สำหรับ Hover/Drawer + 0ms Instant State Sync สำหรับการสลับเหรียญ/กรองตาราง + เคารพ `@media (prefers-reduced-motion: reduce)`)
+  - `VISUAL_DENSITY = 7–8/10` (High-Craft Telemetry Density: ใช้ `font-variant-numeric: tabular-nums` ทุกตัวเลขราคา/พิกัด/เวลา, ช่องว่างภายในสัมพันธ์กับรัศมีขอบ)
+- **Gapless Bento & Viewport Budget:**
+  - กริดแบบ Bento ต้องใส่ `grid-auto-flow: dense;` เสมอเพื่อไม่ให้เกิดหลุมว่าง (No orphan grid holes)
+  - ใช้ `min-height: 100dvh;` แทน `100vh` และล็อก `overflow-x: hidden;` บน `body`
+  - **Viewport Budget:** ใน 1 หน้าจอแรก (Above the Fold) ห้ามมีกลุ่มองค์ประกอบแยกกันเกิน 3 โซนหลัก และต้องมีพื้นที่ว่าง (Whitespace / Surface Canvas) อย่างน้อย 25%
+
+### 9.2 📐 Concentric Surface Physics & Tactile Telemetry (`soft-skill` + `minimalist-skill` + `brutalist-skill`)
+- **Safe Concentric Border Radius Formula:**
+  - บังคับใช้: `border-radius: max(0px, calc(var(--r-outer) - var(--border-w, 0px) - var(--pad)));` เพื่อป้องกันค่าติดลบจน Browser ทิ้งคำสั่ง และชดเชยความหนาของ Border อย่างถูกต้อง
+  - สำหรับปุ่มหรือแคปซูลที่มีการ Animate ขยาย/ยุบรูปทรง (Morphing) ให้ใช้ `calc(infinity * 1px)` หรือ `calc(var(--el-height) / 2)` แทน `9999px` เพื่อไม่ให้มุมโค้งกระตุกค้างช่วงท้าย
+- **Doppelrand & Tactile Framing:**
+  - ผสมผสานความละมุนของ `soft-skill` (`box-shadow: inset 0 1px 0 rgba(255,255,255,0.06)` Doppelrand inner highlight) เข้ากับความคมชัดของ `minimalist-skill` & `brutalist-skill` (`1px solid` structural hairline + `3px solid` top category accent bar + `border-dashed` ticket perforation + `<kbd>` shortcut tags เช่น `T`)
+- **Custom Browser Surfaces:**
+  - ต้องกำหนดสี `::selection` ให้เข้ากับธีม, แต่ง `::-webkit-scrollbar` ให้บางคม (`6px`), ล็อก `scrollbar-gutter: stable;`, และกำหนด `color-scheme: light dark;` บน `:root` เสมอ
+
+### 9.3 🪙 2.5-Tier Semantic Token Contract & Polarity Discipline (`stitch-skill` + `ui-styling` + `redesign-skill`)
+- **2.5-Tier Token Architecture (Zero Cascade Waterfall):**
+  - *Tier 1 (Primitive) & Tier 2 (Semantic):* กำหนดที่ `:root` ผ่านฟังก์ชัน `light-dark()` เพื่อให้ไฟล์ CSS กระชับและสลับธีมได้ทันที
+  - *Tier 3 (Component):* ห้ามประกาศเป็น Global Tokens เด็ดขาด ให้ใช้เฉพาะ **Private Scoped Aliases** ที่ขึ้นต้นด้วย Underscore (`--_bg`, `--_border`, `--_text`) ภายใน Class ของ Component นั้นๆ เพื่อป้องกัน Style Recalculation ซ้ำซ้อนบนตารางหมื่นเซลล์
+- **Contrast-Safe CTA Foreground (`--accent-on-primary`):**
+  - **กฎเหล็กป้องกันบั๊กสีกลืนในโหมดมืด:** ห้ามเขียน `color: #ffffff` ตายตัวบนปุ่มที่ใช้พื้นหลัง `var(--accent-primary)` เด็ดขาด เพราะเมื่อสลับเป็นโหมดมืด (`velvet-obsidian` ที่ใช้สีเขียวสว่าง `#34d399`) ตัวหนังสือสีขาวจะมี Contrast เพียง `1.92:1` (อ่านไม่ออก/ตกเกณฑ์ WCAG)
+  - ต้องใช้ `color: var(--accent-on-primary)` เสมอ โดยในโหมดสว่าง (`editorial-paper` พื้นเขียวเข้ม `#0f6b32`) กำหนด `--accent-on-primary: #ffffff` (`6.66:1` AA/AAA) และในโหมดมืด (`velvet-obsidian` พื้นเขียวมิ้นต์ `#34d399`) กำหนด `--accent-on-primary: #042f1e` (`10.8:1` AAA)
+- **Non-Text SVG Contrast:**
+  - เส้นกราฟหลักและวงแหวนเกจวัด (SVG `stroke`) ห้ามฮาร์ดโค้ดสีสว่างที่จมบนพื้นขาว ต้องผูกกับ `stroke="var(--accent-primary)"` เพื่อให้ผ่านเกณฑ์ WCAG Non-Text Contrast (`> 3:1`) ทั้งในโหมดกระดาษครีมและโหมดมืด
+
+### 9.4 🛡️ 4-Tier Quality Governance & Pre-Flight Gate
+
+เปลี่ยนผ่านจากการเป็นเพียง CSS Style Enforcer สู่ **Design Decision Engine** ด้วยการแบ่งระดับการตรวจสอบออกเป็น 4 ชั้นชัดเจน:
+
+| ระดับการตรวจสอบ | เกณฑ์ประเมิน | ตัวอย่างข้อกำหนด | กลไกการตรวจรับ (Gate) |
+|---|---|---|---|
+| **Tier 1: Hard Invariants** | ไม่มีการประนีประนอม (Pass/Fail) | WCAG Dual-Theme Contrast, Keyboard Focus Visible, 44px Touch Targets, Reduced-Motion Compliance, Semantic State Contract | Automated Unit & Contrast Test |
+| **Tier 2: Soft Heuristics** | ปรับตามบริบทและขนาดหน้าจอ | Safe Concentric Radius, Motion Timing, Accent Budget ($\le 15\%$), Whitespace Budget ($\ge 25\%$) | Design Review & Optical Comparison |
+| **Tier 3: Progressive Enhancements** | เสริมความลื่นไหลเมื่อเบราว์เซอร์รองรับ | CSS Anchor Positioning, Scroll-Driven Animations, View Transitions L2, `@starting-style` | Feature Detection (`@supports` / JS Fallback) |
+| **Tier 4: Domain Rules** | สอดคล้องกับงานเฉพาะทางของผู้ใช้ | High-Density Telemetry, Map Canvas 100dvh, 0W Idle WebGL `frameloop="demand"` | Domain User Workflow Audit |
+
+#### 1. Complete Semantic State Contract (Hard Invariant):
+ทุก Interactive Component ต้องผ่านการออกแบบและมี CSS ครบทั้ง 6 สถานะ:
+$$\text{default} \longrightarrow \text{hover} \longrightarrow \text{pressed} \longrightarrow \text{focus-visible} \longrightarrow \text{disabled / loading} \longrightarrow \text{success / error}$$
+- **Focus Rings:** ทุกปุ่ม/ลิงก์/อินพุตต้องมี `:focus-visible` ชัดเจน (`outline: 2px solid var(--border-focus); outline-offset: 2px;`)
+- **Press Displacement:** ปุ่มยุบตัวทางสายตาด้วย Area-Proportional Scaling โดยไม่ลดขนาดกล่อง Hit Target
+- **Reduced Motion:** หากผู้ใช้เปิด `prefers-reduced-motion: reduce` ต้องตัด Transition เหลือ `0ms` ทันที
+
+#### 2. Dual-Theme Contrast & Polarity Discipline (Hard Invariant):
+- ข้อความหลัก (`--text-1`) $> 12:1$ (AAA)
+- ข้อความรอง (`--text-2`) $> 7:1$ (AAA)
+- ข้อความกำกับ/หน่วย (`--text-3`) $> 4.5:1$ (AA)
+- ปุ่มหลัก (`--accent-on-primary` บน `--accent-primary`) $> 4.5:1$ ทั้ง Light (`editorial-paper`) และ Dark (`velvet-obsidian`)
+- เส้นกราฟ/ไอคอน (Non-text) $> 3:1$ เทียบกับพื้นผิว
+
+#### 3. Information Architecture & Anti-Slop Heuristics (Soft Heuristic):
+- **Layout Follows Information Relationships:** บังคับให้ AI ระบุ Primary Task, Primary Data, Supporting Context, และ Secondary Actions ก่อนสร้าง Layout
+- **ห้าม Generic Card Uniformity:** ห้ามเปลี่ยนตารางข้อมูลหรือฟังก์ชันที่มีความสำคัญต่างกันให้กลายเป็นการ์ดเรียง 3 ใบที่มีขนาดและ Effect เท่ากันหมด
+- **Surface Effect Budget:** ทุก Drop-shadow, Blur, และ Glow ต้องมีหน้าที่ชัดเจน (แยกชั้นความลึก หรือบอกสถานะ) ไม่ใส่ฟุ้งกระจายจนขาดลำดับขั้น
+
+#### 4. Interactive Self-Audit Score:
+ในหน้า Prototype สามารถแสดงแถบ **`🛡️ 4-Tier Audit Score`** เพื่อแสดงผลตรวจ Contrast, Focus Visibility, และ State Contract สดบนหน้าเว็บได้ทันที
+
+### 9.5 🎨 Perceptual Color, Motion Profiles & Micro-Craft Standards
+
+- **Perceptual Intent Color Engine:**
+  - เลือกใช้ `in oklch shorter hue` เมื่อต้องการรักษาความสดฉ่ำของ Hue ข้ามช่วง
+  - เลือกใช้ `in oklab` เมื่อต้องการเกลี่ยความสว่างนุ่มนวลหรือไล่สีเข้าหา Neutral/White/Black เพื่อขจัดรอยตัดขอบ
+  - ตรวจสอบ Midpoint ที่ตำแหน่ง 25%, 50%, 75% เพื่อป้องกันแถบสีหม่น
+  - สร้างสถานะด้วย `color-mix(in oklch, var(--surface-base) 88%, white)` แทนการฮาร์ดโค้ด Hex
+- **Dark Mode Functional Tokens:**
+  - บริหารผ่าน `--surface-canvas` (OLED Pure Black `#000000` + Chroma $C \in [0.004, 0.012]$), `--surface-raised`, `--surface-inset`, `--border-subtle`, `--border-focus`
+- **4 Motion Profiles & Timing Math:**
+  - สัดส่วนเวลาปิดต่อเวลาเปิด: $T_{\text{exit}} = 0.65 \times T_{\text{entry}}$ (280ms เข้า / 180ms ออก)
+  - กำหนด Motion ตามลักษณะงาน: `precision` (0-100ms no overshoot สำหรับงานข้อมูล/แผนที่), `soft-settle` (240-280ms สำหรับ Popover), `spring-settle` (สำหรับ Morphing ข้ามรูปทรง), และ `instant` (0ms)
+- **Typography & Script Calibration:**
+  - UI Chrome: `line-height: 1.25` (EN) / `1.38` (TH) + สำรอง Headroom สำหรับสระบน/วรรณยุกต์ไทย 2-4px
+  - Reading Prose: `line-height: 1.60` (EN) / `1.70-1.75` (TH)
+  - ปรับจูน Fallback Font ด้วย `size-adjust` ภายใน `@font-face` เพื่อป้องกัน Layout Shift (CLS = 0)
+- **Spatial 3D & WebGL Resource Gating:**
+  - สถาปัตยกรรม **`frameloop="demand"`**: ตัด Render Loop ทันทีเมื่อความเร็ว $\lvert v \rvert < 0.0001$ (GPU 0W idle)
+  - VRAM Footprint $\le 32\text{MB}$ ผ่าน Meshopt Compression และ KTX2 Basis Universal Textures
+
+---
+
+### 9.6 👁️ Task-Driven Attention Models & Information Saliency
+
+ห้ามบังคับใช้ F-Pattern กับทุก Archetype ให้เลือก **Attention Model** ให้ตรงกับภารกิจหลัก:
+
+| Attention Model | เหมาะสำหรับ | เกณฑ์การจัดวางและการวัดผล |
+|---|---|---|
+| **F-Pattern** | บทความ, Documentation, คู่มือการใช้งาน | ลำดับการอ่านหัวข้อ และตำแหน่งเริ่มต้นอ่านแนวนอนสู่แนวตั้ง |
+| **Z-Pattern** | Marketing Landing Page ความหนาแน่นต่ำ | เส้นทางสายตาจาก Brand สู่ Value Proposition และ Primary CTA |
+| **Task-First** | Dashboard, ซอฟต์แวร์วิศวกรรม, CAD | ผู้ใช้พบปุ่ม Action หลักหรือสถานะปัจจุบันของระบบได้เร็วที่สุด |
+| **Spatial Attention** | GIS, แผนที่, CAD Workbench, 3D Canvas | Canvas คือจุดโฟกัสหลัก โดยมีแผงเครื่องมือและข้อมูลแวดล้อมเกาะขอบ |
+| **Alert-First** | Mission Control HMI, Telemetry Console | ค่าผิดปกติ (Critical Alarm) ต้องถูกแยกออกจากสถานะปกติอย่างเด็ดขาด |
+| **Reading Hierarchy** | ตารางสแกนข้อมูล, รายงานการคำนวณ | สแกนค่าตามแถว คอลัมน์สรุปผล และค่าพิกัดความคลาดเคลื่อนได้อย่างแม่นยำ |
+
+#### Gestalt Proximity & Saliency Formulation:
+- **Gestalt Proximity:** องค์ประกอบที่เกี่ยวข้องกันทางตรรกะ ต้องอยู่ใกล้กันทางสายตา:
+  $$d_{ij} = \frac{\sqrt{(x_i - x_j)^2 + (y_i - y_j)^2}}{\sqrt{W^2 + H^2}}, \quad P_{ij} = \exp\left(-\frac{d_{ij}^2}{2\sigma^2}\right)$$
+- **Information Saliency Score ($S_i$):**
+  $$S_i = 0.30 R_i + 0.18 C_i + 0.16 T_i + 0.12 A_i + 0.10 P_i + 0.08 I_i + 0.06 E_i$$
+  โดย $R$ (Task Relevance), $C$ (Contrast), $T$ (Typography Saliency), $A$ (Area), $P$ (Position), $I$ (Isolation), $E$ (Enclosure)
+
+---
+
+### 9.7 🍱 Bento Allocation & CLS Near-Zero Invariants
+
+1. **Task-Weighted Area Allocation:**
+   คำนวณขนาดของ Module ตามน้ำหนักภารกิจ ไม่ใช่ความชอบส่วนตัวของนักออกแบบ:
+   $$w_i = 0.35 T_i + 0.25 F_i + 0.20 D_i + 0.20 K_i$$
+   ($T$: ความสำคัญต่อภารกิจ, $F$: ความถี่ในการคลิก/ควบคุม, $D$: ความหนาแน่นของข้อมูล, $K$: ความวิกฤตเมื่อเกิดข้อผิดพลาด)
+2. **Aspect Ratio Starting Constraints:**
+   - **GIS Map Canvas:** ประมาณ 16:10 ถึง 4:3 (หรือ 100dvh full-bleed)
+   - **Telemetry Timeline:** 2.2:1 ถึง 3:1 (แนวนอนกว้างเพื่อให้เห็นแนวโน้มกาลเวลา)
+   - **Data Table:** Flexible height พร้อม Internal Scrolling (`overflow-y: auto`)
+   - **Inspector / Controls:** Flexible height พร้อมล็อก `min-width: 20rem` (320px) ป้องกันข้อมูลถูกบีบ
+3. **Grid Dense Warning:**
+   - บังคับใช้ `grid-auto-flow: row` ควบคู่กับ **Named Grid Areas** (`grid-template-areas`) เป็นค่าเริ่มต้นเสมอ
+   - ห้ามใช้ `grid-auto-flow: dense` กับ Dashboard ข้อมูล เพราะจะทำให้ลำดับ DOM และ Tab Order ของคีย์บอร์ดสลับตำแหน่ง
+4. **CLS Near-Zero Invariants:**
+   - **Reserved Geometry:** จองพื้นที่ว่างและ Aspect Ratio ให้กับ Map Canvas, กราฟ และภาพก่อนโหลดข้อมูลเสมอ
+   - **Stable Data Regions:** การอัปเดตข้อมูลต้องเกิดขึ้นภายใน Scroll Container ที่กำหนดขอบเขตไว้ ไม่ดันโครงสร้างหลักขยับ
+   - **Overlay for Transient Feedback:** แจ้งเตือน Toast และ Popover ต้องอยู่บน Top Layer ไม่แทรกเข้าไปใน DOM Flow
+
+---
+
+### 9.8 📊 Automated Heuristic Scoring Pipeline & Release Gate
+
+ประเมินคุณภาพของโค้ด UI ผ่านสมการคะแนนรวม:
+$$Q = 0.30 H + 0.25 I + 0.20 G + 0.15 R + 0.10 V$$
+- $H$ (Hierarchy & Task Saliency)
+- $I$ (Information Architecture & State Completeness)
+- $G$ (Geometry, Concentric Radii & Touch Targets)
+- $R$ (Responsive Stability & CLS = 0)
+- $V$ (Visual Craft, OKLCH Gamut & Anti-Slop)
+
+#### Zero-Compromise Gating Policy:
+- **90–100:** PASS — พร้อมส่งมอบระดับ Production
+- **75–89:** REVIEW REQUIRED — ใช้งานเป็น Candidate ได้แต่ต้องตรวจสอบคำเตือน
+- **< 75:** REJECT — สถาปัตยกรรมข้อมูลไม่ผ่านเกณฑ์ ต้องปรับแก้ก่อนเรนเดอร์
+- **Hard Invariant Violation:** REJECT ทันที (หากตกเกณฑ์ Contrast AA/AAA, ขาด Focus Ring, หรือไม่มี Reduced-Motion Gate แม้คะแนนรวมจะได้ 95 ก็ถือว่าตกเกณฑ์)
+

package/references/redesign-audit.md

@@ -0,0 +1,38 @@
+# Anti-AI Design & Redesign Audit Protocol
+
+เกณฑ์การตรวจสอบและยกระดับหน้าเว็บเดิมให้สวยงาม พรีเมียม และกำจัดร่องรอย "AI Generated Look" (AI Tells) โดยไม่กระทบฟังก์ชันการทำงานเดิมของระบบ
+
+---
+
+## 1. ลำดับขั้นตอนการรีดีไซน์ (3-Step Redesign Sequence)
+
+1. **Scan (สำรวจสแต็กเดิม):** อ่านโครงสร้างโปรเจกต์เดิม ตรวจสอบ Framework (Next.js, Vite, React, Astro, Vue), วิธีจัดการสไตล์ (Tailwind CSS, Vanilla CSS, CSS Modules) และ Icon Library ที่ใช้อยู่
+2. **Diagnose (วินิจฉัยจุดบกพร่อง):** เทียบโค้ดปัจจุบันกับ Checklist ข้อห้ามด้านล่าง คัดแยกรูปแบบที่ดูเชย หรือดูโหลแบบ AI
+3. **Targeted Upgrade (ยกระดับเฉพาะจุด):** ปรับปรุงโค้ดบนสแต็กเดิมทันทีโดยไม่ต้องรื้อระบบใหม่ทั้งหมด (Incremental Polish)
+
+---
+
+## 2. หมวดการตรวจสอบเชิงลึก (Audit Checklist)
+
+### ก. การจัดพิมพ์และตัวหนังสือ (Typography)
+- [ ] **แทนที่ฟอนต์โหล (Inter/System Font):** ใช้ฟอนต์ที่มีบุคลิกชัดเจน เช่น `Geist`, `Cabinet Grotesk`, `Outfit`, `Plus Jakarta Sans` หรือคู่ฟอนต์สไตล์ Editorial (Serif สำหรับ Header + Sans สำหรับ Body)
+- [ ] **น้ำหนักหัวข้อ (Headline Presence):** หัวข้อขนาดใหญ่ต้องปรับ Tracking ให้แน่นเสมอ (`letter-spacing: -0.025em` ถึง `-0.03em`) และลด `line-height` เหลือ `1.05 - 1.15`
+- [ ] **ความกว้างบรรทัดข้อความ:** จำกัดความกว้างของย่อหน้าเนื้อหาให้อยู่ที่ `60 - 75ch` (`max-w-prose` หรือ `max-w-xl`) เพื่อให้อ่านสบายตา
+- [ ] **ลำดับน้ำหนักฟอนต์:** เลิกใช้แค่ Regular (400) คู่กับ Bold (700) ให้เสริม Medium (500) และ SemiBold (600) เพื่อความต่อเนื่อง
+- [ ] **ตัวเลขและตารางข้อมูล:** ใช้ฟอนต์ Monospace (`Geist Mono`, `JetBrains Mono`) หรือเปิดใช้งาน `font-variant-numeric: tabular-nums` เสมอ
+- [ ] **ป้องกันคำโดด (Orphaned Words):** ใช้ `text-wrap: balance` สำหรับ Heading และ `text-wrap: pretty` สำหรับ Body Text
+
+### ข. พื้นผิว สี และมิติ (Color, Surfaces & Depth)
+- [ ] **ห้ามใช้ Pure Black (`#000000`):** ใน Dark Theme ให้ใช้ Off-Black เช่น `#09090b`, `#0d0d11`, หรือ `#121216` เพื่อความสบายตา
+- [ ] **กำจัด AI Purple Gradient:** เลิกใช้สีเหลือบม่วง-ฟ้าแบบ AI เจนทั่วไป ให้ใช้พื้นสีกลางสะอาดคู่กับ Accent Color เพียง 1 สีที่ผ่านการคัดสรร
+- [ ] **ควบคุมความสดของสี Accent:** คุมค่า Saturation ให้อยู่ต่ำกว่า 85% เพื่อความกลมกลืนระดับพรีเมียม
+- [ ] **มิติเงาที่มีอุณหภูมิ (Tinted Shadows):** หลีกเลี่ยงเงาดำทื่อๆ ให้ผสมโทนสีของพื้นหลังลงในเงา (เช่น เงาสีกรมท่าเข้มบนพื้นหลัง Dark Navy)
+- [ ] **ขอบและแสงตกกระทบ (Border Rim Light):** ใช้ขอบบาง `1px solid rgba(255, 255, 255, 0.08)` และ Top Rim Light (`linear-gradient(90deg, transparent, rgba(255,255,255,0.6), transparent)`) เพื่อสร้างความคมชัด
+- [ ] **ความสม่ำเสมอของโหมดแสง:** หลีกเลี่ยงการแทรกกล่องสีดำสนิทลงในหน้า Light Mode อย่างไม่มีเหตุผล ให้คุมโทนพื้นหลังให้เป็นหนึ่งเดียว
+
+### ค. โครงสร้างและการจัดวาง (Layout & Spacing)
+- [ ] **กำจัด 3-Card Column Cliché:** เลิกวางการ์ดขนาดเท่ากัน 3 ช่องทื่อๆ เปลี่ยนเป็น Bento Grid แบบอสมมาตร, Horizontal Scroll, หรือ Two-Column Asymmetric Grid
+- [ ] **ความสูงหน้าจออุปกรณ์:** ใช้ `min-height: 100dvh` แทน `100vh` เพื่อป้องกันปัญหา Layout กระตุกบนเบราว์เซอร์มือถือ (iOS Safari URL bar bug)
+- [ ] **ขอบเขตความกว้างหน้าจอ:** กำหนด `max-w-[1200px]` ถึง `max-w-[1440px]` พร้อม `mx-auto` เสมอ ป้องกันเนื้อหายืดแผ่ขอบจอ
+- [ ] **การจัดตำแหน่งปุ่ม CTA ในการ์ด:** ใช้ `mt-auto` ใน Flexbox Card เพื่อให้ปุ่ม Action ด้านล่างอยู่ระนาบเดียวกันเสมอ ไม่กระโดดตามความยาวเนื้อหา
+- [ ] **ระยะหายใจ (Whitespace):** เพิ่ม Padding และ Gap ให้กว้างขึ้น ให้หน้าเว็บโปร่ง โล่ง และมีจุดโฟกัสสายตาที่ชัดเจน

package/references/redesign.md

@@ -0,0 +1,52 @@
+## 11. REDESIGN PROTOCOL
+
+This skill handles **greenfield builds AND redesigns**. Misclassifying the mode is the single biggest source of bad redesign output.
+
+### 11.A Detect the Mode (first action)
+* **Greenfield** - no existing site, or full overhaul approved. Dial baseline from Section 1.
+* **Redesign - Preserve** - modernise without breaking the brand. Audit first, extract brand tokens, evolve gradually.
+* **Redesign - Overhaul** - new visual language on top of existing content. Treat as greenfield for visuals; preserve content and IA.
+
+If ambiguous, ask **once**: *"Should this redesign preserve the existing brand, or are we starting visually from scratch?"*
+
+### 11.B Audit Before Touching
+Document the current state before proposing changes:
+* **Brand tokens** - primary / accent colors, type stack, logo treatment, radii.
+* **Information architecture** - page tree, primary nav, key conversion paths.
+* **Content blocks** - what exists, what's doing work, what's filler.
+* **Patterns to preserve** - signature interactions, recognisable hero, copy voice.
+* **Patterns to retire** - AI-slop tells, broken layouts, dead links, generic stock imagery, perf traps.
+* **Dial reading of the existing site** - infer current `DESIGN_VARIANCE` / `MOTION_INTENSITY` / `VISUAL_DENSITY`. That's your starting point, not the baseline.
+* **SEO baseline** - current ranking pages, meta titles, structured data, OG cards. **SEO migration is the #1 redesign risk.**
+
+### 11.C Preservation Rules
+* **Do not change information architecture** unless asked. Keep page slugs, anchor IDs, primary nav labels stable for SEO and muscle memory.
+* **Extract brand colors before applying Section 4.2.** A brand that is already purple stays purple - apply the LILA RULE's override.
+* **Preserve copy voice** unless asked for a rewrite. Visual modernisation ≠ content rewrite.
+* **Honor existing accessibility wins.** Do not regress focus states, alt text, keyboard nav, contrast.
+* **Respect existing analytics events.** Do not rename buttons, form fields, section IDs that downstream tracking depends on.
+
+### 11.D Modernisation Levers (priority order)
+Apply in order - stop when the brief is satisfied:
+1. **Typography refresh** - biggest visual lift per unit of risk.
+2. **Spacing & rhythm** - increase section padding, fix vertical rhythm.
+3. **Color recalibration** - desaturate, unify neutrals, keep brand accent.
+4. **Motion layer** - add `MOTION_INTENSITY`-appropriate micro-interactions to existing components.
+5. **Hero & key-section recomposition** - restructure top-of-funnel using Section 10 vocabulary.
+6. **Full block replacement** - only when the existing block is unsalvageable.
+
+### 11.E Decision Tree: Targeted Evolution vs Full Redesign
+* IA, content, and SEO sound → **targeted evolution** (Levers 1-4). ~70% of value at ~40% of risk.
+* Visual debt is structural (broken IA, no design system, broken mobile) → **full redesign** with strict content preservation.
+* Brand itself is changing → **greenfield**.
+
+### 11.F What Never Changes Silently
+Never modify without explicit user approval:
+* URL structure / route slugs.
+* Primary nav labels.
+* Form field names or order (breaks analytics + autofill).
+* Brand logo or wordmark.
+* Existing legal / consent / cookie copy.
+
+---
+

package/references/slides-copywriting-formulas.md

@@ -0,0 +1,84 @@
+# Copywriting Formulas
+
+25 formulas for persuasive slide copy.
+
+## Core Formulas
+
+### PAS (Problem-Agitate-Solution)
+**Use:** Problem slides, pain points
+**Components:** Problem → Agitate → Solution
+**Template:** "[Pain point]? Every [time frame], [consequence]. [Solution] fixes this."
+
+### AIDA (Attention-Interest-Desire-Action)
+**Use:** CTAs, closing slides
+**Components:** Attention → Interest → Desire → Action
+**Template:** "[Bold statement]. [Benefit detail]. [Social proof]. [CTA]."
+
+### FAB (Features-Advantages-Benefits)
+**Use:** Feature slides, product showcases
+**Components:** Feature → Advantage → Benefit
+**Template:** "[Feature] lets you [advantage], so you can [benefit]."
+
+### Cost of Inaction
+**Use:** Agitation slides, urgency
+**Components:** Status Quo → Loss → Time Decay
+**Template:** "Without [solution], you're losing [amount] every [timeframe]."
+
+### Before-After-Bridge
+**Use:** Transformation slides, case studies
+**Components:** Before → After → Bridge
+**Template:** "[Pain point before]. [Desired state after]. [Your solution] is the bridge."
+
+## Formula-to-Slide Mapping
+
+| Slide Type | Primary Formula | Emotion |
+|------------|-----------------|---------|
+| Title/Hook | AIDA, Hook | curiosity |
+| Problem | PAS, Agitate | frustration |
+| Cost/Risk | Cost of Inaction | fear |
+| Solution | FAB, BAB | hope |
+| Features | FAB | confidence |
+| Traction | Proof Stack | trust |
+| Social Proof | Testimonial | trust |
+| Pricing | Value Stack | confidence |
+| CTA | AIDA, Urgency | urgency |
+
+## Headline Patterns
+
+### Power Words
+- "Stop [bad thing]"
+- "Get [desired result] in [timeframe]"
+- "The [adjective] way to [action]"
+- "Why [audience] choose [product]"
+- "[Number] ways to [achieve goal]"
+
+### Contrast Patterns
+- "[Old way] is dead. Meet [new way]."
+- "Don't [bad action]. Instead, [good action]."
+- "From [pain point] to [benefit]."
+
+### Social Proof Patterns
+- "[Number]+ [users/companies] trust [product]"
+- "Join [notable company] and [notable company]"
+- "As seen in [publication]"
+
+## Search Commands
+
+```bash
+# Find formula for slide type
+python ../design-system/scripts/search-slides.py "problem agitation" -d copy
+
+# Get emotion-appropriate formula
+python ../design-system/scripts/search-slides.py "urgency cta" -d copy
+```
+
+## Quick Reference
+
+| Need | Use Formula |
+|------|------------|
+| Create urgency | Cost of Inaction, Scarcity |
+| Build trust | Social Proof, Testimonial |
+| Show value | FAB, Value Stack |
+| Drive action | AIDA, CTA |
+| Tell story | BAB, Story Arc |
+| Present data | Proof Stack |

package/references/slides-create.md

@@ -0,0 +1,4 @@
+Invoke `slides` skill to create persuasive HTML slides using design tokens, Chart.js, and the slide knowledge database.
+
+## Task
+<task>$ARGUMENTS</task>