# DESIGN.md — เอกลักษณ์งานออกแบบ Atroute > ไฟล์นี้คือ "รัฐธรรมนูญ" ของงานออกแบบ — **AI agent ต้องอ่านก่อนแก้ UI ทุกครั้ง** > และต้องปฏิบัติตามกฎ "ห้ามทำ" อย่างเคร่งครัด ไม่งั้นงานจะกลายเป็นเว็บ AI slop > ที่เห็นกันเต็มอินเทอร์เน็ต (gradient ม่วงสุ่ม ๆ + การ์ดแก้ว + blob + emoji + เงาหว่าน) --- ## 1. เอกลักษณ์ (Design Signature) **Concept: "ขาวไล่ม่วง" (White-to-Purple)** — พื้นขาวสะอาด มีม่วงเฉดเดียวเป็นตัวชูโรง หัวใจคือ **ม่วงหนึ่งเฉด + ความนิ่งของตัวพิมพ์** ไม่ใช่การไล่สีรุ้งแบบ template: ม่วง `#7a4cc0` ถูกใช้อย่างตั้งใจ (ปุ่ม / CTA / รหัสป้าย / แอคเซนต์) บนพื้นขาวที่ไล่ ไปม่วงจาง ๆ แทบไม่เห็น เพื่อให้ข้อมูลอ่านง่ายและไม่แย่งความสนใจ สามเสาหลัก: 1. **ข้อมูลต้องอ่านได้ชัดเจน** — ตัวเลข/รหัสใช้ฟอนต์ mono + tabular-nums เรียงตรงกัน 2. **ม่วงหนึ่งเฉด มีเหตุผล** — ม่วง = แบรนด์/แอคเซนต์, ไม่ใช่สีสุ่ม 5 เฉดไร้ความหมาย 3. **สี = ภาษาสถานะ** — เขียว = มีรอบ, แดง = ออกแล้ว, เทา = ไม่มีข้อมูล ไม่ใช่ของตกแต่ง --- ## 2. กฎ "ห้ามทำ" (ฉีกสไตล์ AI slop) รายการนี้คือลายเซ็นของเว็บ AI ยุค 2024–2025 — **ห้าม** ใช้เด็ดขาด: | # | ห้าม | เพราะ | |---|---|---| | 1 | ❌ **Aurora gradient หลายสี** (ม่วง→ชมพู→ฟ้า→เขียว ผสมกันแนวทแยง) | ลายเซ็น AI อันดับหนึ่ง | | 2 | ❌ **ม่วงสุ่ม 5+ เฉด** ไม่มีความหมาย (ม่วง 50/100/200/…/900 หว่านเต็มหน้า) | ยึดม่วงเฉดเดียว `#7a4cc0` + อ่อน `#b07ce0` | | 3 | ❌ Glassmorphism (`backdrop-filter: blur`) | ใช้เฉพาะแถบนำทางที่จำเป็นจริง ๆ | | 4 | ❌ **Emoji เป็น icon** (🚏🕒📍🛣️🧭) | ใช้ SVG icon หรือ glyph ตัวพิมพ์ | | 5 | ❌ Blob / รูปทรงออร์แกนิกลอย ๆ เป็นพื้นหลัง | ใช้เส้นขอบ/ตาราง/ลวดลายเรขาคณิต | | 6 | ❌ การ์ดมน ๆ พื้นสีพาสเทล รัศมี 16–22px | ใช้เส้นขอบ 1px + `radius: 8px` ไม่ใช่สีพื้น+เงา | | 7 | ❌ Badge "✨ ยินดีต้อนรับ", sparkle, star | ไร้สาระ ไม่ได้ให้ข้อมูล | | 8 | ❌ Drop shadow ทั่วหน้า | แบ่งองค์ประกอบด้วย border + whitespace | | 9 | ❌ ฟอนต์แฟนซี/display เกินจำเป็น | ใช้ระบบฟอนต์เดียวตลอด (ดูหัวข้อ 4) | | 10 | ❌ คำว่า "template / mockup / demo" ใน UI | โปรเจกต์จริง ไม่ใช่ template | | 11 | ❌ ตัวหนังสือ gradient (text-clip) บนพื้นอ่อน | ตัวหนังสือสีทึบ ตรง ไม่มี gradient | > ตรวจงานก่อนส่งทุกครั้ง: ถ้าเห็นรายการข้างต้นในโค้ด/ดีไซน์ = แก้ก่อน merge --- ## 3. โทเคนสี (ใช้ค่าที่กำหนดเท่านั้น — ห้ามคิดเลขใหม่เอง) ```css :root { /* ม่วง — สีหลักเฉดเดียวของแบรนด์ */ --purple-700: #6d28d9; /* ม่วงเข้ม — hover / เน้น */ --purple: #7a4cc0; /* ม่วงหลัก — ปุ่ม / CTA / แอคเซนต์ */ --purple-300: #b07ce0; /* ม่วงอ่อน — ปลาย gradient / ขอบโฟกัส */ --purple-50: #f3ecff; /* พื้นม่วงอ่อน — badge / ชิป */ --purple-25: #faf7ff; /* พื้นไล่ม่วงจางสุด — hover / hero */ /* พื้นฐาน */ --paper: #ffffff; /* พื้นขาวหลัก */ --ink: #1f2a44; /* ตัวอักษรหลัก (น้ำเงินเข้ม) */ --muted: #6f7b95; /* ตัวอักษรรอง */ --line: #e7e0f6; /* เส้นขอบม่วงอ่อน */ /* หมวดเส้นทาง (route_group ใน routes.json) — ใช้กับ "เลขสาย" (chip) เท่านั้น */ --group-bangkok: #1f5fbf; /* เข้ากรุงเทพฯ — น้ำเงิน */ --group-interprovincial: #7a4cc0; /* ระหว่างจังหวัด — ม่วง (ม่วงแบรนด์) */ --group-in-province: #d6388f; /* ภายในจังหวัด — ชมพู */ --group-municipal: #6b7268; /* ภายในเทศบาล — เทา (สำรอง ยังไม่มีสายใช้) */ /* สถานะ */ --green-500: #1f8765; /* มีรอบ / เปิดให้บริการ */ --green-50: #e4efe4; --amber: #c47b1d; /* เตือน / หมายเหตุ (ไม่ใช่สีหลัก) */ --amber-50: #fff6e8; --red: #c93a3a; /* ออกรถแล้ว / ยกเลิก */ --red-50: #fbe4e4; /* โครงสร้าง */ --radius: 8px; /* มุมโค้งเล็ก เท่านั้น */ --radius-sm: 4px; --shadow: none; /* ห้ามใช้ shadow เป็นเครื่องมือแบ่งองค์ประกอบ */ --line-w: 1px; /* gradient ที่อนุญาต (ใช้ซ้ำได้) */ --grad-brand: linear-gradient(135deg, #7a4cc0, #b07ce0); /* ปุ่ม/ชิป/CTA */ --grad-bg: linear-gradient(180deg, #ffffff, #faf7ff, #f4f0fd); /* พื้นหลังหน้า */ } ``` ### กติกาสีต่อสถานะ | องค์ประกอบ | สี | |---|---| | แอคเซนต์ / ปุ่ม / CTA / รหัสป้าย | `--grad-brand` (ม่วงหลัก) | | พื้นหลังหน้า | `--grad-bg` (ขาว→ม่วงจาง) | | ป้ายสถานะ "มีรอบ/เปิดให้บริการ" | `--green-500` | | ป้ายสถานะ "ออกรถแล้ว/ปิด" | `--red` | | ข้อมูลว่าง / ไม่มีพิกัด | `--muted` | | หมายเหตุ / เตือน | `--amber` (ใช้ sparingly) | --- ## 3.1 ระบบภาษา (i18n) คำแปลแยกเป็น **ไฟล์ต่อภาษา** — `ui/locales/<รหัสภาษา>.json` (แบน: `"key": "ข้อความ"`) - **ภาษาที่รองรับ** ประกาศที่ `ui/i18n.js → SUPPORTED` (ปัจจุบัน `th`, `en`) · ภาษาตั้งต้น `th` ใช้เป็น fallback เมื่อคีย์ขาดในภาษาปัจจุบัน - **เพิ่มภาษาใหม่** = วางไฟล์ `ui/locales/<รหัส>.json` + เพิ่มรหัสใน `SUPPORTED` + เพิ่ม `./locales/<รหัส>.json` ใน PRECACHE ของ `ui/sw.js` (ไม่ต้องแก้โค้ดอื่น) - **โหลดแบบ lazy** เฉพาะภาษาที่ใช้ (+ ภาษาตั้งต้น) — ไม่ดึงทุกภาษามาทั้งหน้า - **ข้อความใน HTML คือ fallback** — ถ้าโหลดไฟล์ภาษาไม่สำเร็จ ระบบจะ **ไม่เขียนทับ** (คงข้อความเดิมไว้) - **สลับภาษา** → `I18N.setLang()` โหลดไฟล์ภาษาให้เสร็จก่อน แล้วประกาศ event `langchange` ให้หน้าวาดใหม่ (กันข้อความที่ JS สร้างค้างเป็นภาษาเก่า) · จำค่าไว้ใน `localStorage('at_lang')` - `` ถูกอัปเดตตามภาษาที่เลือกอัตโนมัติ (a11y · การตัดคำ · เลือกฟอนต์) - **ชื่อเฉพาะไม่แปล** — ชื่อสถานี จังหวัด สายรถ (ภาษาไทยเสมอ) - **ตรวจก่อน commit:** `python resource/tools/check-i18n.py` ## 3.2 ธีม (light / dark / ตามอุปกรณ์) — `ui/theme.css` - **โทเคนสีทุกตัวอยู่ใน `ui/theme.css`** (`--c-*`) — ค่าเดียวกับ `web-at-transit/frontend/src/styles/theme.css` (GUI สองโปรเจกต์ต้องตรงกัน ห้ามแก้ค่าข้างเดียว) - โหมด: `light` · `dark` · `auto` = **ตามธีมอุปกรณ์** (`prefers-color-scheme`) ← ค่าเริ่มต้น - ตั้งค่า: `` + `data-theme-mode="light|dark|auto"` · เก็บที่ `localStorage.at_theme` - ปุ่มใน header = dropdown (ไอคอนเปลี่ยนตามโหมด) · สคริปต์ก่อน paint อยู่ใน `index.html` (กันจอขาววูบ) - **ห้ามใส่ hex ใหม่ในไฟล์ CSS/partial** — ถ้าจำเป็นให้เพิ่มเป็นโทเคนคู่ light/dark ที่นี่ก่อน (ยกเว้นสีที่ต้องคงที่ทุกธีม เช่น `#fff` บนพื้นแบรนด์ และไล่เฉดภาพประดับ) ## 4. ตัวพิมพ์ (Typography) ```css --font-display: "K2D", "Prompt", "Noto Sans Thai", sans-serif; /* หัวเรื่อง — หนัก 600–800 (มีหัวแบบไทย) */ --font-body: "K2D", "Noto Sans Thai", "Sarabun", sans-serif; /* เนื้อหา — อ่านง่ายบนจอเล็ก */ --font-mono: "IBM Plex Mono", ui-monospace, monospace; /* เวลา + เลขสาย + ตัวเลข */ ``` **ทำไม K2D:** ฟอนต์ไทย **มีหัว (Loop)** หัวเหลี่ยมโมเดิร์น ไม่เชย · น้ำหนักครบ 300–800 · ตัวเลขสวย (เข้าคู่กับ `IBM Plex Mono` ที่ใช้กับเวลา/เลขสาย) · ใบอนุญาต SIL OFL **ฝังไว้ในโปรเจกต์ (ไม่พึ่ง CDN):** ไฟล์อยู่ที่ `ui/vendor/fonts/` — `k2d.css` (@font-face 18 กฎ · 6 น้ำหนัก × subset thai/latin/latin-ext · ~218 KB) + ไฟล์ `.woff2` 18 ไฟล์ · precache ใน `sw.js` → **ทำงานออฟไลน์ได้จริง** · อัปเดตฟอนต์ = โหลดชุดใหม่ทับ แล้ว bump `VERSION` ใน `sw.js` · `Prompt` / `Noto Sans Thai` ยังโหลดจาก Google Fonts เป็นตัวสำรองใน Fallback chain (ออฟไลน์จะถอยไป `system-ui`) | ระดับ | ฟอนต์ | ขนาด | ลักษณะ | |---|---|---|---| | H1 (hero) | display 800 | clamp(2.2rem, 6vw, 3.4rem) | ตัวตรง ไม่มี gradient | | H2 (section) | display 700 | 1.35rem | + เส้นใต้สั้น 24px สี `--purple` | | เลขสาย/รหัสป้าย/เวลา | mono 700 | 1.1–1.6rem | `font-variant-numeric: tabular-nums` | | ป้าย micro-label | body 600 | 0.72rem | ภาษาอังกฤษ ตัวพิมพ์ใหญ่ `letter-spacing: 0.14em`, สี muted | **กฎ:** ตัวเลข/รหัส/เวลาทุกตำแหน่งต้อง mono + tabular-nums — ตัวเลขต้องเรียงตรงกัน --- ## 5. องค์ประกอบ (Component Spec) ### การ์ดเส้นทาง / ป้าย (route card / stop tile) - พื้น `--paper`, ขอบ `1px solid --line`, `radius: 8px` - หัวการ์ด / รหัสป้าย: ตัวเลข mono ใหญ่บนพื้น `--grad-brand` ตัวอักษรขาว - ชื่อ: body 700 ขนาด 1rem - ข้อมูลรอง: muted 0.85rem - hover: ขอบเปลี่ยนเป็น `--purple-300` + `translateY(-1px)` — **ห้ามใส่ shadow** ### ชิปรหัส / เวลา (code chip / departure chip) - รหัสป้าย/เลขสาย: พื้น `--grad-brand` ตัวอักษรขาว mono 700 - กลุ่มเวลาวางเป็น grid เรียงจากน้อยไปมาก ### เลขสายหน้า `#/routes/:id` — พื้นหลังตามหมวดเส้นทาง เลขสาย (`.mu-route-chip`) เปลี่ยนสีพื้นหลังตาม **หมวดเส้นทาง** ที่ประกาศใน `resource/data/routes.json → route_group` (นิยามหมวดอยู่ที่ `route_groups.json`) เพื่อให้อ่านปราดเดียวรู้ว่าสายนั้นเป็นสายประเภทใด | หมวด (`route_group`) | สี | โทเคน | คลาส CSS | |---|---|---|---| | `bangkok` — เข้ากรุงเทพฯ | น้ำเงิน | `--group-bangkok` | `.grp-bangkok` | | `interprovincial` — ระหว่างจังหวัด | ม่วง | `--group-interprovincial` | `.grp-interprovincial` | | `in_province` — ภายในจังหวัด | ชมพู | `--group-in-province` | `.grp-in_province` | | `municipal` — ภายในเทศบาล | เทา (สำรอง) | `--group-municipal` | `.grp-municipal` | | ไม่ระบุ / ไม่รู้จัก | ม่วงแบรนด์ (ค่าเริ่มต้น) | `--grad-brand` | *(ไม่มีคลาส)* | - ใช้เฉพาะ **การ์ดหัวเรื่องหน้ารายละเอียดสาย** (`#/routes/:id`) — chip เล็กในหน้า `#/stops` ยังใช้ม่วงแบรนด์ - **เพิ่มหมวดใหม่** = เพิ่ม `route_group` ใน `route_groups.json` + โทเคนสีใน §3 + กฎ `.grp-` ใน `busDetail.html` - สีของหมวด **ไม่ใช่** สีสถานะ — ห้ามนำไปใช้กับ badge สถานะ (§5 ป้ายสถานะ) ### ป้ายสถานะ (status badge) - พื้นสีอ่อน (`--green-50` / `--red-50` / `--amber-50`) + ตัวอักษรสีเข้มของเฉดนั้น - ใช้เฉพาะบอกสถานะจริง ไม่ใช่แค่ตกแต่ง ### หัวโซน (zone head) — ป้ายหัวข้อ + บรรทัดข้อมูล ใช้กับทุกโซนที่มีป้ายกำกับ (`.mu-zone-head`) เช่น `#/check` (`ตารางเวลาเดินรถทุกจุดจอด`) และ `#/routes/:id` (แผนที่) - ป้ายหัวข้อ (`.mu-zone-tag`) — แคปซูลสีอ่อนตามโทนของโซน (tag-purple / tag-sky / tag-pink / tag-yellow) - **บรรทัดข้อมูลต้องแยกเป็น "ชิ้น" (`.mu-zone-seg`)** ไม่ใช่สตริงยาว ๆ ที่ต่อด้วย `·` เอง - เหตุผล: ภาษาไทยไม่มีเว้นวรรค → ถ้าเป็นสตริงเดียว เบราว์เซอร์จะ **ตัดกลางชื่อสถานี** - แต่ละชิ้นเป็น flex item → ตัดบรรทัดเป็นหน่วย · ตัวคั่น `·` วาดด้วย `::after` (ท้ายชิ้น ไม่ขึ้นต้นบรรทัด) - ชิ้นที่เล็กลง (เช่น ชื่อสถานีในวงเล็บ `.mu-zone-at`) ช่วยให้บรรทัดจัดเรียงสวยขึ้น - **มือถือ (<768px)** — ป้ายหัวข้อบรรทัดบน · บรรทัดข้อมูลเต็มความกว้าง เรียงลงมา (flex + wrap) - **จอใหญ่ (≥768px)** — เปลี่ยนเป็น **grid 2 คอลัมน์**: ป้ายหัวข้อซ้าย · บรรทัดข้อมูลคอลัมน์ขวา · จำกัดความยาวบรรทัด `max-width: 82ch` (กันบรรทัดยาวเกินอ่านยาก) - ห้ามใช้ `flex` โดยไม่ใส่ `flex-wrap` ร่วมกับลูกที่เป็น `flex-basis:100%` (จะถูกบีบรวมแถวเดียว) ### แถบนำทาง (topbar) - พื้น `--paper` (ขาว) ตัวอักษร `--ink` ขอบล่าง `1px solid --line` - active menu = เส้นใต้ `--purple` - CTA "เช็กเวลาเดินรถ" = พื้น `--grad-brand` ตัวอักษรขาวหนา ### ฟอร์มค้นหา - พื้น `--paper` ขอบ `--line`, โฟกัส = ขอบ `--purple-300` — ไม่มี glow - ช่องกรอกแบบแบ่งกล่อง (รหัสป้าย) ใช้ mono + กล่องละ 1 หลัก --- ## 6. วิธีเขียนงานออกแบบใหม่ (สำหรับ AI) เมื่อได้รับงาน "ออกแบบ/ปรับ UI" ให้ทำตามลำดับ: 1. **ห้ามเริ่มเขียนโค้ดทันที** — เขียน mockup spec 1 ย่อหน้า: concept นี้คืออะไร, ใช้สี/ฟอนต์/ลวดลายอะไร 2. ใช้โทเคนจากหัวข้อ 3–4 เท่านั้น — ถ้าสี/ขนาดไม่พอ ค่อยเพิ่มในไฟล์นี้ (ไม่ใช่ inline ในโค้ด) 3. ใช้ class เดิม + ปรับ CSS ตาม spec — ห้ามสร้าง class ใหม่ทั้งชุดโดยไม่จำเป็น 4. ตรวจกฎ "ห้ามทำ" (หัวข้อ 2) ก่อนสรุปงาน ## 7. เอกสารอ้างอิงเชิงภาพ (moodboard ภาษา) - พื้นหลังไล่เฉดขาว→ม่วงอ่อน (single-hue fade) — สะอาด ไม่มีสีรุ้ง - ป้าย/CTA ม่วง `#7a4cc0` ตัดกับพื้นขาว — แอคเซนต์เดียว ชัดเจน - ตัวเลขรหัสป้ายแบบ mono + tabular — เรียงตรงกันเหมือนป้ายจริง - เส้นแบ่งบาง ๆ ม่วงอ่อน `#e7e0f6` — แบ่งองค์ประกอบ ไม่ใช้เงา --- *ไฟล์นี้มีผลบังคับใช้กับทุกงานออกแบบในโปรเจกต์ — ถ้าอยากเปลี่ยนทิศทางศิลป์ ต้องแก้ไฟล์นี้ก่อน แล้วค่อยเขียนโค้ด* --- ## 8. การเคลื่อนไหว (Motion) — `ui/motion.js` + ท้าย `_shared.css` **หลักคิด:** อนิเมชันต้องบอก "ของใหม่เข้ามา" ไม่ใช่ของเล่น — ทุกอย่างจบใน ≤ 0.6 วิ และต้องปิดได้ | บทบาท | ค่า | ที่มา | |---|---|---| | เส้นโค้ง | `--mu-ease` = `cubic-bezier(.22,.61,.36,1)` (deceleration) | MD motion | | เข้าหน้า | 420ms · จาง + ขึ้น 10px (`#view.mu-view-in`) | — | | การ์ดโผล่ตอนเลื่อน | 520ms · จาง + ขึ้น 18px (`.mu-reveal` → `.is-in`) | — | | เหลื่อมต่อชิ้น | 45ms/ชิ้น (สูงสุด 4 ชิ้น = 180ms) | MD stagger 30–50ms | | แถบโหลด | 3px บนสุด · โผล่/จาง 180–260ms (ออกเร็วกว่าเข้า) | MD exit-faster | **กฎ** 1. แตะเฉพาะ `opacity` + `transform` — **ห้ามอนิเมต width/height/top/left** (ทำให้เกิด layout shift) 2. **ห้ามใส่ `.mu-reveal` ให้ของที่ครอบแผนที่** (`SKIP_INSIDE` ใน motion.js — Leaflet คำนวณพิกัดจากกล่องแม่) 3. ของที่เห็นบนจออยู่แล้วตอนโหลด **ไม่ต้องอนิเมต** (กันกะพริบ) — JS เลือกให้เอง 4. เคลียร์ class/transform ทิ้งหลังจบ → hover lift เดิมของแต่ละหน้าไม่ถูกทับ 5. `prefers-reduced-motion: reduce` = ปิดทั้งชุด (ไม่แตะ DOM, ไม่มีแถบโหลด) 6. เพิ่มหน้าใหม่ไม่ต้องแก้อะไร — router เรียก `Motion.enter()` ให้ และ MutationObserver สแกนการ์ดที่ JS สร้างทีหลัง --- ## 9. รูปภาพ (Asset cache) รูปทุกตัวเติม `?v=<เวอร์ชันแอป>` อัตโนมัติผ่าน `ui/imageurl.js` — เปลี่ยนรูปทับชื่อเดิมแล้ว ต้องรัน `python resource/tools/bump-version.py` เพื่อให้ทุกเครื่องเห็นของใหม่ (รายละเอียดใน AGENTS.md)