- 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
12 KiB
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→ ต้อง bumpVERSIONและ<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 หยุด — อย่าด่วนสรุปว่าโค้ดพัง ให้ยกแท็บขึ้นหน้าก่อนวัด