Files
hobbypj-contents/DESIGN.md
T
Bkk1234 db7724b237 feat(home): link the homepage of every local project in the workspace
- server: GET /api/local-projects scans sibling folders for index.html
  (title from <title>/<h1>, generic titles fall back to the folder name,
  sorted by newest edit) and GET /projects/<folder>/ serves that folder
- both endpoints are loopback-only; node_modules/.git/.hermes blocked and
  path traversal rejected; WORKSPACE_DIR=none disables the feature
- home: new 'โปรเจคในเครื่อง' list (2 columns >=700px) that hides itself when
  the API is absent, so the live static site never shows fake rows
- SW skips /projects/* so other projects' files are never cached; version 2026.11.19.5
- docs: README/AGENTS/DESIGN cover the endpoints, the loopback rule and the layout
2026-11-20 14:26:54 +07:00

105 lines
12 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 — กติกาการออกแบบ (ใช้กับทุกหน้าในโปรเจคนี้)
เอกสารนี้คือ “รัฐธรรมนูญ” ของหน้าตา เว็บนี้ ถ้าจะเปลี่ยนสี ระยะ หรือส่วนประกอบ ต้องแก้ไฟล์นี้ก่อนแล้วจึงแก้โค้ด
## 1. แนวคิด
- เว็บรวมโปรเจคอดิเรกส่วนตัว: **เรียบ อบอุ่น อ่านง่าย** ไม่ใช่เว็บขายของ
- โครงหน้าและจังหวะการวางอ้างอิง **fastwork.com** (ฮีโร่ + ช่องค้นหา + การ์ดเป็นตาราง + ฟุตเตอร์บรรทัดเดียว)
- ธีมสี: **น้ำตาล + ขาว** เลือกเฉดน้ำตาลที่ “สดและสว่าง” (โมก้า-คาราเมล) หลีกเลี่ยงน้ำตาลเข้มแบบซีเปีย/วินเทจที่สื่อถึงความเก่า
- ภาษาไทยทั้งหน้า ไม่มีคำอังกฤษลอยเป็นป้าย/หัวข้อ (ชื่อโดเมนและคำเทคนิคเท่านั้นที่คงอังกฤษ)
## 2. โทเคนสี (ตรวจคอนทราสต์บนพื้นขาวแล้ว)
| โทเคน | ค่า | คอนทราสต์บน #FFFFFF | ใช้กับ |
|---|---|---|---|
| `--brand-50` | `#FDF7F2` | — | พื้นอ่อน, พื้นไอคอน |
| `--brand-100` | `#FAEADF` | — | ป้ายนับจำนวน, พื้น chip ที่เลือก |
| `--brand-200` | `#F3D5C1` | — | เส้นขอบอ่อน |
| `--brand-300` | `#E8B695` | — | เส้นขอบ hover |
| `--brand-400` | `#D99368` | 2.52:1 | **กราฟิกเท่านั้น ห้ามใช้เป็นตัวอักษร** |
| `--brand-500` | `#C4703C` | 3.66:1 | ไอคอน/เส้นตกแต่ง (ไม่ใช่เนื้อหา) |
| `--brand-600` | `#A85A2C` | 5.04:1 | ตัวอักษรเน้น, โฟกัสริง |
| `--brand-700` | `#8A4722` | 6.99:1 | ปุ่มหลัก, ลิงก์ |
| `--brand-800` | `#6B3620` | 9.66:1 | หัวข้อย่อย, ตัวอักษรเน้นเข้ม |
| `--brand-900` | `#3D241A` | 14.33:1 | หัวข้อหลัก |
| `--foreground` | `#241A15` | 17.02:1 | เนื้อความ |
| `--muted-foreground` | `#6F6159` | 5.95:1 | คำอธิบาย, ข้อความรอง |
| `--border` | `#EADFD6` | — | เส้นขอบการ์ด |
| `--border-strong` | `#DCCABA` | — | ขอบช่องกรอก/เส้นแบ่งที่ต้องเห็นชัด |
| `--surface-2` | `#FBF6F1` | — | พื้นพาเนล/ฟุตเตอร์ |
กติกา: ตัวอักษรทุกตัวต้อง ≥ 4.5:1 บนพื้นของตัวเอง · ปุ่มหลักใช้พื้น `--brand-700` + ตัวอักษรขาว (6.99:1)
## 3. ตัวอักษร
- ฟอนต์: **K2D** (ฝังใน `fonts/`, 3 น้ำหนัก: 400 / 500 / 700) — ไทยมีหัว อ่านง่ายบนจอเล็ก
- ฐาน: `16px`, `line-height 1.6`; หัวข้อ `line-height 1.25` และ `letter-spacing` ติดลบเล็กน้อย
- หัวเรื่องฮีโร่: `clamp(1.6rem, 1.15rem + 2.05vw, 2.5rem)` กว้างสุด `24ch` (ข้อความต้อนรับยาว จึงต้องคุมความกว้าง)
- ห้ามใช้ตัวอักษรเล็กกว่า 12px ในเนื้อหา
## 4. ระยะ / มุม / เงา
- สเกลระยะ: 4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 64 · 80 px
- มุมโค้ง: `8 / 12 / 16 / 22 / pill` — การ์ดใช้ 16, ช่องกรอกใช้ 12, ปุ่มใช้ pill
- เงา: ใช้เฉพาะตอนยกการ์ดขึ้น (hover) และปุ่มหลัก — ไม่ใส่เงาซ้อนหลายชั้น
## 5. ส่วนประกอบ
- **Header**: สูง 64px (มือถือ) / 72px (≥900px), sticky, พื้นขาว 92% + blur, ขอบล่าง 1px
- **ปุ่ม**: สูงขั้นต่ำ 44px (44×44 ตาม WCAG 2.5.8) · `primary` (น้ำตาลเข้ม+ขาว) · `ghost` (ขาว+ขอบ) · `quiet` · `danger`
- **ช่องค้นหา**: pill, เงา, ไอคอนซ้าย, ปุ่มล้างคำค้นหา 32×32 (มี label ให้ screen reader)
- **การ์ดโปรเจค**: ไอคอน 46×46 (พื้น `--brand-50`), ชื่อเป็นลิงก์ที่ขยายพื้นที่คลิกเต็มใบด้วย `::after`, คำอธิบาย 3 บรรทัดตัดด้วย `-webkit-line-clamp`, ท้ายการ์ดมี host + “เปิดเว็บไซต์”
- **คำว่า `hobbyproject` ในฮีโร่**: แบ่งสีตามตัวอักษร — `hobbyp` + `j` ใช้ `--brand-900` (#3D241A, 12.21:1) และ `ro` + `ect` ใช้ `--brand-500` (#C4703C, 3.12:1 บนพื้นฮีโร่เข้มสุด) จึงต้องมีขนาด ≥24px ตัวหนาขึ้นไป (ตอนนี้ clamp 24–32px) ถ้าลดต่ำกว่านั้นต้องเปลี่ยนไปใช้ `--brand-600` (#A85A2C, 4.30:1) เพื่อให้ผ่าน 4.5:1 ของตัวอักษรปกติ
- **ฮีโร่**: พื้นไล่เฉดอุ่นอ่อน + การ์ดลอย 3 ใบ **สุ่มจากโปรเจคทั้งหมดใหม่ทุกครั้งที่โหลดหน้า** (Fisher–Yates, ไม่ซ้ำ) แสดงเฉพาะ ≥1080px, `aria-hidden`
- **หลังบ้าน**: พาเนล + การ์ดรายการ, ปุ่มเลื่อนขึ้น/ลง/ลบ, แถบบันทึกแบบ sticky ด้านล่าง, `<dialog>` ยืนยันการลบ/ทิ้งการแก้ไข
- **โปรเจคในเครื่อง (localhost)**: รายการ 2 คอลัมน์ (≥700px) / 1 คอลัมน์ (มือถือ) — ไอคอนโฟลเดอร์ 34px, ชื่อโปรเจค 15px ตัวกลาง, บรรทัดล่างเป็น `<folder> · index.html · แก้ล่าสุด <วันที่ไทย>` (12.5px, โมโนสเปซเฉพาะชื่อโฟลเดอร์), ปุ่มขวา “เปิดหน้าแรก →” (ซ่อนข้อความเมื่อ <560px เหลือลูกศร) · แสดงเฉพาะเมื่อเปิดผ่านเซิร์ฟเวอร์ในเครื่อง
## 6. สิ่งที่ห้าม
- ห้ามใช้อิโมจิเป็นไอคอน (ใช้ SVG เส้น 1.7px ใน `ui/ui.js`)
- ห้ามใช้สีน้ำตาลเข้ม `#3E2A20`-ลงไปเป็นพื้นปุ่มใหญ่ (ดูแก่) — ใช้ได้แค่ตัวอักษร
- ห้ามใส่คำอังกฤษลอยเป็นหัวข้อ/ป้ายบนหน้าไทย
- ห้ามลบ focus ring; ทุกองค์ประกอบที่โฟกัสได้ต้องเห็น ring น้ำตาล
- ห้ามใช้ `transform`/animation กับการเปลี่ยน layout; ต้องเคารพ `prefers-reduced-motion`
## 7. Responsive
- มือถือก่อน: การ์ด 1 คอลัมน์ (<700px) → 2 (≥700px) → 3 (≥1000px)
- การ์ดลอยในฮีโร่แสดงเฉพาะ ≥1080px
- ตรวจที่ 375 / 768 / 1024 / 1440 px และต้องไม่มี horizontal scroll
## 8. PWA
- `manifest.json`: `display: standalone`, `start_url: ./`, `theme_color: #8A4722`
- ไอคอน PNG จริง 192 / 512 / 512-maskable / 180 (สร้างจาก `make_icons` ด้วย PIL ไม่ใช้ตัวอักษร)
- `sw.js`: network-first สำหรับ HTML/CSS/JS/JSON, cache-first สำหรับรูป/ฟอนต์, ข้าม `/api/`
- แก้ `sw.js` หรือรายการ `PRECACHE` → ต้อง bump `VERSION` และ `<meta name="app-version">` พร้อมกัน
## 9. Motion (ลูกเล่นภาพเคลื่อนไหว)
ไฟล์: `assets/css/motion.css` + `ui/motion.js`
**สัญญาความปลอดภัยของเนื้อหา** — ห้ามซ่อนเนื้อหาใน CSS หลัก:
- inline script ใน `<head>` ใส่ `.fx-motion` ที่ `<html>` ก่อนวาดเฟรมแรก เว้นแต่ผู้ใช้ตั้ง `prefers-reduced-motion: reduce`
- CSS ซ่อนเฉพาะ `html.fx-motion [data-reveal]`; เมื่อ JS ปิด/ถูกบล็อก/ลดการเคลื่อนไหว → เนื้อหาเห็นครบ ไม่มีช่วงจอว่าง
- ทุก keyframe มีคู่หูใน `@media (prefers-reduced-motion: reduce)` ที่สั่ง `animation: none; opacity: 1; transform: none`
**อนิเมตได้เฉพาะ `transform` / `opacity` / `filter`** — ห้ามอนิเมต `width` / `height` / `top`
| องค์ประกอบ | ท่า | เวลา |
|---|---|---|
| ชื่อเรื่องฮีโร่ | แยกเป็นคำ (`splitWordsHtml` ตัดด้วยช่องว่างเท่านั้น ปลอดภัยกับสระ/วรรณยุกต์ไทย) ยกขึ้น + คลายเบลอ | 760ms · เริ่ม 140ms · เว้น 85ms/คำ |
| ป้ายเหนือหัวเรื่อง / คำโปรย / ช่องค้นหา / แถบข้อมูล | drop / rise / pop / fade ตามลำดับ | 520–760ms |
| การ์ดลอยในฮีโร่ | สุ่ม 3 ใบใหม่ทุก refresh แล้วสไลด์จากซ้ายทีละใบ | 700ms · 320/440/560ms |
| การ์ดโปรเจค | `data-reveal="pop"` ตอนเลื่อนถึง (IntersectionObserver, `rootMargin: 2000px 0px -6% 0px`) | 660ms · หน่วง 95ms × คอลัมน์ |
| หัวข้อ section | เส้นใต้กวาดจากซ้าย (`scaleX`) | 760ms |
| แถบความคืบหน้า | `scaleX` ตาม scroll ผ่าน rAF | — |
**กับดักที่ต้องจำ**
- การ์ดที่สร้างใหม่ (กรองคำค้นหา) ต้องเรียก `initReveal(gridEl)` ซ้ำ ไม่งั้นค้างที่ `opacity: 0`
- `mount()` ของหน้า admin ถูกเรียกซ้ำ (กด “ทิ้งการแก้ไข”) → ต้องเรียก `initReveal(root)` ทุกครั้ง
- hover ยกการ์ดใช้พร็อพเพอร์ตี `translate` (ไม่ใช่ `transform`) เพราะ `animation-fill-mode: both` ของ reveal จะทับ `transform`
- แท็บที่อยู่เบื้องหลัง: IntersectionObserver ไม่ยิงและ rAF หยุด — อย่าด่วนสรุปว่าโค้ดพัง ให้ยกแท็บขึ้นหน้าก่อนวัด