คู่มือการปรับปรุงสไตล์

คู่มือนี้จัดทำเอกสารสำหรับ design system token และ component class ที่ใช้งานใน styles/custom.css โดยทำหน้าที่เป็นเอกสารอ้างอิงสำหรับ token ของ border, surface, shadow, radius, button, gradient, transition, focus และ typography ที่ใช้ทั่วทั้งธีม

สถานะ: design token และ component class ทั้งหมดที่อธิบายไว้ด้านล่างได้รับการนำไปใช้งานแล้วและพร้อมให้ใช้งาน

วิธีอ่านคู่มือนี้

แต่ละส่วนจะจัดทำเอกสารสำหรับประเภท token:

1. คำจำกัดความของ token — CSS custom properties พร้อมค่าสำหรับโหมดสว่าง/มืด
2. การแมป component — component ของธีมที่ใช้แต่ละ token
3. หมายเหตุการนำไปใช้ — คำแนะนำการใช้งานและข้อควรพิจารณาด้านการเข้าถึง

ตาราง token จะแยกตาม โหมดสว่าง และ โหมดมืด ในกรณีที่ค่าแตกต่างกัน

---

1. ระบบสี

Border แบบ Alpha-Transparent

ธีมใช้ border แบบ alpha-transparent แทนสีเทาทึบ ซึ่งช่วยให้ border ปรับตัวได้อย่างเป็นธรรมชาติกับพื้นหลังทุกประเภท

/* รูปแบบ border แบบ alpha-transparent */
border: 1px solid var(--f5-border-default);  /* neutral ที่ alpha 20% */

Border Token

/* โหมดสว่าง */
:root[data-theme='light'] {
  --f5-border-faint: #3434341a;    /* --f5-black-3 ที่ 10% */
  --f5-border-default: #34343433;  /* --f5-black-3 ที่ 20% */
  --f5-border-strong: #22222266;   /* --f5-black-4 ที่ 40% */
}

/* โหมดมืด */
:root {
  --f5-border-faint: #f5f5f51a;    /* --f5-white-2 ที่ 10% */
  --f5-border-default: #f5f5f533;  /* --f5-white-2 ที่ 20% */
  --f5-border-strong: #cccccc66;   /* --f5-white-4 ที่ 40% */
}

กรณีการใช้งาน Border

Token	ความทึบแสง	กรณีการใช้งาน
--f5-border-faint	10%	ตัวแบ่งที่ละเอียด, แถวตาราง
--f5-border-default	20%	border ค่าเริ่มต้น, กรอบ card
--f5-border-strong	40%	border ที่เน้นชัดเจน, สถานะ active

สถานะ: เสร็จสมบูรณ์ — นำไปใช้งานแล้วใน styles/custom.css

สี Surface แบบ Interactive

Semantic surface token สำหรับสถานะ hover และ active

Surface โหมดสว่าง

Token	ค่า	วัตถุประสงค์
--f5-white	#ffffff	พื้นหลังหลัก
--f5-white-1	#faf9f7	Sidebar, พื้นที่ที่ละเอียด
--f5-white-2	#f5f5f5	Surface ที่ยกสูง
--f5-surface-hover	var(--f5-white-2)	การเติมสีเมื่อ hover
--f5-surface-active	var(--f5-white-3)	การเติมสีเมื่อกด/active

Surface โหมดมืด

Token	ค่า	วัตถุประสงค์
--f5-black	#000000	พื้นหลังหลัก
--f5-black-4	#222222	Sidebar, พื้นที่ที่ละเอียด
--f5-surface-hover	var(--f5-black-3)	การเติมสีเมื่อ hover
--f5-surface-active	var(--f5-black-2)	การเติมสีเมื่อกด/active

คำจำกัดความของ Surface Token

:root[data-theme='light'] {
  --f5-surface-hover: var(--f5-white-2);     /* #f5f5f5 */
  --f5-surface-active: var(--f5-white-3);    /* #e6e6e6 */
}

:root {
  --f5-surface-hover: var(--f5-black-3);     /* #343434 */
  --f5-surface-active: var(--f5-black-2);    /* #666666 */
}

สถานะ: เสร็จสมบูรณ์ — นำไปใช้งานแล้วใน styles/custom.css

---

2. ระบบ Elevation และ Shadow

ระดับ Shadow

ธีมใช้ shadow แบบ alpha ที่มีสีกลาง พร้อมค่าสองชั้นเพื่อความลึกที่เป็นธรรมชาติ โหมดสว่างใช้ --f5-black-3 (#343434) เป็นฐานสี ส่วนโหมดมืดใช้ #cccccc

Shadow โหมดสว่าง

:root[data-theme='light'] {
  --f5-shadow-inset: inset 0px 1px 2px 1px #3434341a;
  --f5-shadow-low:
    0px 1px 1px 0px #3434340d,
    0px 2px 2px 0px #3434340d;
  --f5-shadow-mid:
    0px 2px 3px 0px #3434341a,
    0px 8px 16px -10px #34343433;
  --f5-shadow-high:
    0px 2px 3px 0px #34343426,
    0px 16px 16px -10px #34343433;
  --f5-shadow-higher:
    0px 2px 3px 0px #3434341a,
    0px 12px 28px 0px #34343440;
}

Shadow โหมดมืด

:root {
  --f5-shadow-inset: inset 0px 1px 2px 1px #cccccc0d;
  --f5-shadow-low:
    0px 1px 1px 0px #cccccc0a,
    0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid:
    0px 2px 3px 0px #cccccc0d,
    0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high:
    0px 2px 3px 0px #cccccc1a,
    0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher:
    0px 2px 3px 0px #cccccc0d,
    0px 12px 28px 0px #cccccc26;
}

การแมป Shadow ของ Component

Component	ระดับ Shadow
.swatch, .icon-card	--f5-shadow-low (ขณะพัก)
.starlight-aside	--f5-shadow-low
.expressive-code .frame	--f5-shadow-mid
.mermaid-container	--f5-shadow-mid
Card เมื่อ hover	--f5-shadow-mid
Dropdown, popover	--f5-shadow-high
Modal	--f5-shadow-higher

สถานะ: เสร็จสมบูรณ์ — ระดับ shadow ทั้งหมด (inset, low, mid, high, higher) นำไปใช้งานแล้วใน styles/custom.css

---

3. ระดับ Border Radius

Radius Token

:root {
  --f5-radius-xs: 0.1875rem;   /* 3px — badge, tag */
  --f5-radius-sm: 0.3125rem;   /* 5px — รายการ nav, control ขนาดเล็ก */
  --f5-radius-md: 0.375rem;    /* 6px — card, code block */
  --f5-radius-lg: 0.5rem;      /* 8px — modal, container ขนาดใหญ่ */
  --f5-radius-full: 999px;     /* pill, มนเต็มรูปแบบ */
}

การแมป Radius ของ Component

Component	Radius Token
.swatch	--f5-radius-md (6px)
.icon-card	--f5-radius-md (6px)
.starlight-aside	--f5-radius-md (6px)
.expressive-code .frame	--f5-radius-md (6px)
.mermaid-container	--f5-radius-lg (8px)
.edit-link	--f5-radius-full (pill)
รายการ nav ของ Sidebar	--f5-radius-sm (5px)
Badge	--f5-radius-xs (3px)

สถานะ: เสร็จสมบูรณ์ — ระดับ radius (xs, sm, md, lg, full) นำไปใช้งานแล้วใน styles/custom.css

---

4. การจัดสไตล์การนำทาง Sidebar

สไตล์รายการ Sidebar

/* รายการนำทางของ Sidebar */
nav.sidebar a {
  border-radius: var(--f5-radius-sm);    /* 5px */
  padding: 0.25rem 0.5rem;               /* 4px 8px */
  min-height: 2.25rem;                    /* 36px */
  display: flex;
  align-items: center;
  transition: background-color 0.15s ease, color 0.15s ease;
}

/* hover โหมดสว่าง */
:root[data-theme='light'] nav.sidebar a:hover {
  background-color: var(--f5-white-2);   /* #f5f5f5 */
}

/* hover โหมดมืด */
:root nav.sidebar a:hover {
  background-color: var(--f5-black-3);   /* #343434 */
}

/* ตัวบ่งชี้หน้าที่ active */
nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-white-3);   /* #e6e6e6 สำหรับโหมดสว่าง */
  font-weight: 600;
}

:root:not([data-theme='light']) nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-black-2);   /* #666666 → ปรับเพื่อความสามารถในการอ่าน */
}

ตัวบ่งชี้ accent ด้านซ้าย

nav.sidebar a[aria-current="page"] {
  border-left: 3px solid var(--sl-color-accent);
  padding-left: calc(0.5rem - 3px);  /* ชดเชยสำหรับ border */
}

สถานะ: เสร็จสมบูรณ์ — hover, active และตัวบ่งชี้ accent ของ sidebar นำไปใช้งานแล้วใน styles/custom.css

---

5. ระบบ Button

ตัวแปรของ Button

/* Primary — ใช้ F5 Red เป็น brand action */
.btn-primary {
  background: var(--f5-red);
  color: var(--f5-white);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, box-shadow 0.15s ease;
}
.btn-primary:hover {
  background: var(--f5-red-3);
  box-shadow: var(--f5-shadow-low);
}

/* Secondary — สไตล์ outline */
.btn-secondary {
  background: transparent;
  color: var(--sl-color-gray-2);
  border: 1px solid var(--f5-border-default);
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, border-color 0.15s ease;
}
.btn-secondary:hover {
  background: var(--f5-surface-hover);
  border-color: var(--f5-border-strong);
}

/* Tertiary — ghost/text เท่านั้น */
.btn-tertiary {
  background: transparent;
  color: var(--sl-color-accent);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease;
}
.btn-tertiary:hover {
  background: var(--f5-surface-hover);
}

ระดับขนาด Button

ขนาด	Padding	ขนาดฟอนต์	ความสูงต่ำสุด
เล็ก	0.375rem 0.75rem	0.8125rem (13px)	32px
กลาง (ค่าเริ่มต้น)	0.625rem 1rem	0.875rem (14px)	40px
ใหญ่	0.75rem 1.5rem	1rem (16px)	48px

สถานะ: เสร็จสมบูรณ์ — ตัวแปร button ทั้งหมด (primary, secondary, tertiary, critical) และระดับขนาด (sm, ค่าเริ่มต้น, lg) นำไปใช้งานแล้วใน styles/custom.css

---

6. พื้นหลัง Hero และ Header

Gradient ของ Hero

ใช้จานสี F5 brand:

/* gradient hero หลัก — River blue */
.hero-gradient-primary {
  background: linear-gradient(135deg, var(--f5-river-2) 0%, var(--f5-river) 100%);
  /* #6e8dcc → #0e41aa */
}

/* การล้างหน้าแบบจาง — โทนอบอุ่นที่ละเอียด */
:root[data-theme='light'] .hero-gradient-faint {
  background: linear-gradient(180deg, #faf9f7 0%, #f5f5f5 100%);
}
:root .hero-gradient-faint {
  background: linear-gradient(180deg, #222222 0%, #000000 100%);
}

/* ตัวแปร eggplant สำหรับหน้า feature */
.hero-gradient-eggplant {
  background: linear-gradient(135deg, var(--f5-eggplant-2) 0%, var(--f5-eggplant) 100%);
  /* #9c59c9 → #62228b */
}

/* ตัวแปร brand red สำหรับประกาศ */
.hero-gradient-red {
  background: linear-gradient(135deg, var(--f5-red-2) 0%, var(--f5-red) 100%);
  /* #f06680 → #e4002b */
}

เทคนิค Gradient Overlay

/* vignette แบบ radial เพื่อความลึก */
.hero-vignette::after {
  content: '';
  position: absolute;
  inset: 0;
  background: radial-gradient(ellipse at center, transparent 40%, rgba(0, 0, 0, 0.15) 100%);
  pointer-events: none;
}

/* การจางลงสู่พื้นหลังของหน้าที่ด้านล่าง */
.hero-fade::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  height: 30%;
  background: linear-gradient(to bottom, transparent, var(--sl-color-black));
  pointer-events: none;
}

สถานะ: เสร็จสมบูรณ์ — hero gradient (primary, eggplant, red, faint) และ overlay (hero-fade, hero-vignette) นำไปใช้งานแล้วใน styles/custom.css

---

7. เอฟเฟกต์ Hover และ Transition

Transition Token

:root {
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);
}

Token	ระยะเวลา	Easing	กรณีการใช้งาน
--f5-transition-fast	0.15s	ease	สถานะ hover ส่วนใหญ่, การเปลี่ยนสี
--f5-transition-base	0.2s	ease	การเติมพื้นหลัง, การเปลี่ยน border
--f5-transition-bounce	0.2s	cubic-bezier(0.68, -0.2, 0.265, 1.15)	Switch, toggle
--f5-transition-decelerate	0.6s	cubic-bezier(0.5, 1, 0.89, 1)	ตัวบ่งชี้ tab, แผงเลื่อน
--f5-transition-spring	0.2s	cubic-bezier(0.54, 1.5, 0.38, 1.11)	Tooltip, การเข้า popover

สิ่งที่ควร Animate

Property	ปลอดภัยสำหรับ Animate	หมายเหตุ
background-color	ใช่	มาตรฐานสำหรับการเติมสีเมื่อ hover
color	ใช่	การเปลี่ยนสีข้อความ
border-color	ใช่	การเน้น border เมื่อ hover
box-shadow	ใช่	การเปลี่ยน elevation (ใช้ will-change หากกระตุก)
transform	ใช่	Scale, translate เพื่อ feedback
opacity	ใช่	Fade in/out
width, height	หลีกเลี่ยง	ทำให้เกิด layout reflow
padding, margin	หลีกเลี่ยง	ทำให้เกิด layout reflow

การแมป Transition ของ Component

/* รายการ nav ของ Sidebar */
nav.sidebar a {
  transition: background-color var(--f5-transition-fast),
              color var(--f5-transition-fast);
}

/* Card — shadow ยกสูงเมื่อ hover */
.swatch, .icon-card {
  transition: box-shadow var(--f5-transition-base),
              transform var(--f5-transition-base);
}
.swatch:hover, .icon-card:hover {
  box-shadow: var(--f5-shadow-mid);
  transform: translateY(-1px);
}

/* Button */
.btn-primary, .btn-secondary, .btn-tertiary {
  transition: background-color var(--f5-transition-fast),
              border-color var(--f5-transition-fast),
              box-shadow var(--f5-transition-fast);
}

/* ลิงก์ */
a {
  transition: color var(--f5-transition-fast);
}

สถานะ: เสร็จสมบูรณ์ — transition token ทั้งห้า (fast, base, bounce, decelerate, spring) และ transition ของ component นำไปใช้งานแล้วใน styles/custom.css

---

8. ระบบ Focus Ring

Focus Ring Token

ธีมใช้รูปแบบ double-ring พร้อม inner ring แบบ inset และ outer glow:

/* Action focus — ใช้ F5 River blue */
:root {
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  /* inset 0 0 0 1px #0e41aa, 0 0 0 3px #6e8dcc */

  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);
  /* inset 0 0 0 1px #a70020, 0 0 0 3px #f06680 */
}

/* ใช้กับ element แบบ interactive */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: none;
  box-shadow: var(--f5-focus-action);
}

/* ตัวแปร critical สำหรับปุ่มที่ทำลายข้อมูล */
.btn-critical:focus-visible {
  box-shadow: var(--f5-focus-critical);
}

หมายเหตุด้านการเข้าถึง

• รูปแบบ double-ring ตรงตามข้อกำหนด WCAG 2.2 Focus Appearance (outline ที่มีความคมชัดขั้นต่ำ 2px)
• การใช้ box-shadow แทน outline ช่วยให้ border-radius ถูกนำมาพิจารณา
• :focus-visible ทำให้ ring ปรากฏเฉพาะสำหรับการนำทางด้วยแป้นพิมพ์ ไม่ใช่การคลิกเมาส์

สถานะ: เสร็จสมบูรณ์ — รูปแบบ focus double-ring (action, critical) และสไตล์ :focus-visible นำไปใช้งานแล้วใน styles/custom.css

---

9. Typography

Font Stack

:root {
  --sl-font: "proximaNova", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-font-heading: "neusaNextProWide", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-line-height-headings: 1.1;
}

ระดับ Type

ระดับ	ขนาด	ความสูงบรรทัด	การใช้งาน
Display 500	1.875rem (30px)	1.267	--sl-text-h1
Display 400	1.5rem (24px)	1.333	--sl-text-h2
Display 300	1.125rem (18px)	1.333	--sl-text-h3
Display 200	1rem (16px)	1.5	--sl-text-h4
Display 100	0.8125rem (13px)	1.385	Overline text
Body 300	1rem (16px)	1.5	เนื้อหาหลัก
Body 200	0.875rem (14px)	1.429	ข้อความ Sidebar, คำอธิบายภาพ
Body 100	0.8125rem (13px)	1.385	ตัวพิมพ์เล็ก

ลักษณะสำคัญ

ด้าน	ค่า	หมายเหตุ
ความสูงบรรทัดหัวเรื่อง	1.1	หัวเรื่องแบบแน่นเพื่อผลกระทบ brand; พิจารณา 1.2 เพื่อความสามารถในการอ่าน
ความสูงบรรทัดเนื้อหา	1.5 (ค่าเริ่มต้น Starlight)	เหมาะสำหรับการอ่าน
ฟอนต์	ฟอนต์ brand แบบกำหนดเอง	proximaNova (เนื้อหา), neusaNextProWide (หัวเรื่อง)
น้ำหนักหัวเรื่อง	h1-h2: 700, h3: 500, h4-h6: 700 uppercase	มีความเห็นชัดเจนเพื่อความสอดคล้องของ brand

ลำดับความสำคัญ: ไม่จำเป็นต้องเปลี่ยนแปลง typography ปัจจุบันมีการกำหนดไว้อย่างชัดเจนและเหมาะสมกับ brand การปรับ heading line height เล็กน้อย (1.1 เป็น 1.2) เป็นตัวเลือกที่ไม่บังคับ

---

10. บันทึกการเปลี่ยนแปลงการนำไปใช้งาน

design token ทั้งหมดถูกนำไปใช้งานใน 5 sprint:

Sprint	ขอบเขต	Token ที่เพิ่ม
1. รากฐาน	Shadow + border radius	--f5-shadow-* (5 ระดับ), --f5-radius-* (5 ระดับ)
2. Sidebar + Surface	Navigation + interactive token	--f5-surface-hover, --f5-surface-active, --f5-border-* (3 ระดับ), --f5-transition-fast
3. Button	ระบบ component	.btn-primary, .btn-secondary, .btn-tertiary, .btn-critical, ตัวแปรขนาด
4. Hero Gradient	Background utility	.hero-gradient-primary, -eggplant, -red, -faint, .hero-vignette, .hero-fade
5. Focus + Transition	การเข้าถึง + การขัดเกลา	--f5-focus-action, --f5-focus-critical, --f5-transition-* (5 token), เอฟเฟกต์ hover ของ card

---

อ้างอิงด่วน: สรุป Token

Custom Properties ทั้งหมด

:root {
  /* ระดับ border radius */
  --f5-radius-xs: 0.1875rem;     /* 3px */
  --f5-radius-sm: 0.3125rem;     /* 5px */
  --f5-radius-md: 0.375rem;      /* 6px */
  --f5-radius-lg: 0.5rem;        /* 8px */
  --f5-radius-full: 999px;

  /* ระยะเวลา transition */
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);

  /* Focus ring */
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);

  /* Shadow โหมดมืด (ค่าเริ่มต้น) */
  --f5-shadow-low: 0px 1px 1px 0px #cccccc0a, 0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid: 0px 2px 3px 0px #cccccc0d, 0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high: 0px 2px 3px 0px #cccccc1a, 0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher: 0px 2px 3px 0px #cccccc0d, 0px 12px 28px 0px #cccccc26;

  /* Border โหมดมืด */
  --f5-border-faint: #f5f5f51a;
  --f5-border-default: #f5f5f533;
  --f5-border-strong: #cccccc66;

  /* Surface โหมดมืด */
  --f5-surface-hover: var(--f5-black-3);
  --f5-surface-active: var(--f5-black-2);
}

:root[data-theme='light'] {
  /* Shadow โหมดสว่าง */
  --f5-shadow-low: 0px 1px 1px 0px #3434340d, 0px 2px 2px 0px #3434340d;
  --f5-shadow-mid: 0px 2px 3px 0px #3434341a, 0px 8px 16px -10px #34343433;
  --f5-shadow-high: 0px 2px 3px 0px #34343426, 0px 16px 16px -10px #34343433;
  --f5-shadow-higher: 0px 2px 3px 0px #3434341a, 0px 12px 28px 0px #34343440;

  /* Border โหมดสว่าง */
  --f5-border-faint: #3434341a;
  --f5-border-default: #34343433;
  --f5-border-strong: #22222266;

  /* Surface โหมดสว่าง */
  --f5-surface-hover: var(--f5-white-2);
  --f5-surface-active: var(--f5-white-3);
}