Files
Bkk1234 cdfd77ffff theme: dark mode + theme tokens (parity with web-at-transit)
- ui/theme.css: token set copied value-for-value from the Next app
  (--c-surface/-ink/-border/-brand/-tint/-glass + radius), light and dark blocks
- ui/theme.js: 3-mode switch (light / dark / auto=prefers-color-scheme) with a
  header dropdown, aria-haspopup/menu, Esc/outside close, live matchMedia listener
- index.html: pre-paint theme script (no flash), theme.css link before _shared.css
- remapped ~290 literal colours in _shared.css/index.html/partials to var(--c-*)
  so both projects render from the same tokens; dark patch block covers the
  remaining decorative gradients
- DESIGN.md: new section 3.2 (theme tokens + where to add colours)
- VERSION 2026.09.27.114
2026-11-04 01:29:37 +07:00

24 KiB
Raw Permalink Blame History

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. โทเคนสี (ใช้ค่าที่กำหนดเท่านั้น — ห้ามคิดเลขใหม่เอง)

: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')
  • <html 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) ← ค่าเริ่มต้น
  • ตั้งค่า: <html data-theme="light|dark"> + data-theme-mode="light|dark|auto" · เก็บที่ localStorage.at_theme
  • ปุ่มใน header = dropdown (ไอคอนเปลี่ยนตามโหมด) · สคริปต์ก่อน paint อยู่ใน index.html (กันจอขาววูบ)
  • ห้ามใส่ hex ใหม่ในไฟล์ CSS/partial — ถ้าจำเป็นให้เพิ่มเป็นโทเคนคู่ light/dark ที่นี่ก่อน (ยกเว้นสีที่ต้องคงที่ทุกธีม เช่น #fff บนพื้นแบรนด์ และไล่เฉดภาพประดับ)

4. ตัวพิมพ์ (Typography)

--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-<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 — แบ่งองค์ประกอบ ไม่ใช้เงา

ไฟล์นี้มีผลบังคับใช้กับทุกงานออกแบบในโปรเจกต์ — ถ้าอยากเปลี่ยนทิศทางศิลป์ ต้องแก้ไฟล์นี้ก่อน แล้วค่อยเขียนโค้ด


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)