Files
web-at-transit/DESIGN.md
T
itmeadmin 138a3d15d8 พอร์ต UI จาก web-at-transit-mock เข้า Next.js + data sync เข้า Postgres/SeaweedFS
- 8 หน้า (home/stops/routes/stop/check/blog/about/credits) แปลง partials → React component ตรง mock
- ตรรกะพอร์ตเป็น src/lib/ui/*.ts (mount()) + runtime/PageRuntime
- CSS: base + pages/*.css import ต่อ route (คงลำดับ cascade ของ mock)
- asset/content: public/{image,resource/data,content,locales,vendor}
- แก้ path รูปไทล์พาร์ทเนอร์ (.image → /image) + fallback absolute
- ลบ UI เดิมที่ไม่ตรง mock (expanded/stops details/old components/globals.css)
- script/sync_data_to_postgres.mjs + sync_images_to_storage.mjs (dry-run/--apply, backup)
- docs/UI-PORT.md + DESIGN.md + README
2026-10-23 15:50:00 +07:00

229 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# DESIGN.md — เอกลักษณ์งานออกแบบ Atroute
> **ขอบเขต:** ใช้กับ UI ใน `frontend/` (Next.js App Router) ซึ่งพอร์ตมาจาก mock
> (`D:\Git\workspace\web-at-transit-mock`) แบบ 1:1 — mock คือแหล่งความจริงของดีไซน์
> AI agent ต้องอ่านไฟล์นี้ก่อนแก้ UI ทุกครั้ง และห้ามฝ่าฝืนกฎ "ห้ามทำ"
---
## 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)
คำแปลแยกเป็น **ไฟล์ต่อภาษา** — `frontend/locales/<รหัสภาษา>.json` (แบน: `"key": "ข้อความ"`)
- **ภาษาที่รองรับ** ประกาศที่ `frontend/i18n.js → SUPPORTED` (ปัจจุบัน `th`, `en`) · ภาษาตั้งต้น `th`
ใช้เป็น fallback เมื่อคีย์ขาดในภาษาปัจจุบัน
- **เพิ่มภาษาใหม่** = วางไฟล์ `frontend/locales/<รหัส>.json` + เพิ่มรหัสใน `SUPPORTED`
+ เพิ่ม `./locales/<รหัส>.json` ใน PRECACHE ของ `frontend/sw.js` (ไม่ต้องแก้โค้ดอื่น)
- **โหลดแบบ lazy** เฉพาะภาษาที่ใช้ (+ ภาษาตั้งต้น) — ไม่ดึงทุกภาษามาทั้งหน้า
- **ข้อความใน HTML คือ fallback** — ถ้าโหลดไฟล์ภาษาไม่สำเร็จ ระบบจะ **ไม่เขียนทับ** (คงข้อความเดิมไว้)
- **สลับภาษา** → `I18N.setLang()` โหลดไฟล์ภาษาให้เสร็จก่อน แล้วประกาศ event `langchange` ให้หน้าวาดใหม่
(กันข้อความที่ JS สร้างค้างเป็นภาษาเก่า) · จำค่าไว้ใน `localStorage('at_lang')`
- `<html lang>` ถูกอัปเดตตามภาษาที่เลือกอัตโนมัติ (a11y · การตัดคำ · เลือกฟอนต์)
- **ชื่อเฉพาะไม่แปล** — ชื่อสถานี จังหวัด สายรถ (ภาษาไทยเสมอ)
- **ตรวจก่อน commit:** `python resource/tools/check-i18n.py`
## 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):** ไฟล์อยู่ที่ `frontend/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`) เปลี่ยนสีพื้นหลังตาม **หมวดเส้นทาง** ที่ประกาศใน
`frontend/public/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-<key>` ใน `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` — แบ่งองค์ประกอบ ไม่ใช้เงา
---
*ไฟล์นี้มีผลบังคับใช้กับทุกงานออกแบบในโปรเจกต์ — ถ้าอยากเปลี่ยนทิศทางศิลป์ ต้องแก้ไฟล์นี้ก่อน แล้วค่อยเขียนโค้ด*
---
## 9. รูปภาพ (Asset cache)
รูปทุกตัวเติม `?v=<เวอร์ชันแอป>` อัตโนมัติผ่าน `frontend/imageurl.js` — เปลี่ยนรูปทับชื่อเดิมแล้ว
ต้องรัน `python resource/tools/bump-version.py` เพื่อให้ทุกเครื่องเห็นของใหม่ (รายละเอียดใน AGENTS.md)