Design Tokens — ตั้งชื่อสีและระยะไว้ที่เดียว ใช้ทั้งแอป

next         16.3.5
react        19.2.8
tailwindcss  4.3.3
typescript   5.9.3
node         v24.14.0
# โปรเจกต์ create-next-app + npx shadcn init -d (preset base-nova)
# + shadcn add button card badge skeleton

ก่อนเขียนโค้ด — สไลด์ให้ AI ช่วยออกแบบก่อน (หน้า 18–24)

สไลด์ขึ้นหัวข้อ “Build your design” (หน้า 18) แล้วโชว์เครื่องมือออกแบบที่ใช้ AI ช่วย (หน้า 19): Claude · Open Design · v0 · Figma · bolt · Lovable · Stitch
อาจารย์เลือกใช้ Claude Design (หน้า 20) ซึ่งสไลด์อธิบายว่าเป็นเครื่องมือของ Anthropic Labs ที่สร้างและแก้ prototype แบบกดเล่นได้

ขั้นตอนที่สไลด์โชว์มีสามจังหวะ:

1. เขียน prompt วางแผนก่อน (หน้า 21) — ให้ AI รับบทเป็น senior UX/UI designer แล้วบอกบริบทของโปรเจกต์ “Wongnok”: เป็นแพลตฟอร์มแชร์สูตรอาหาร · ผู้ใช้ทั่วไปมีหน้า Landing, หน้ารวมสูตร (ค้นด้วยชื่อ กรองวันที่ กรองระดับความยาก), หน้ารายละเอียด, ให้ดาว, กดชอบ (ต้อง sign-in ก่อน), login ด้วย Keycloak, แก้โปรไฟล์ · ส่วนคนแชร์สูตรมีฟอร์มเพิ่มสูตร และแก้/ลบสูตรของตัวเองได้
2. ให้ AI สร้างหน้าจอ (หน้า 22–23) — ภาพในสไลด์เป็นหน้า Landing กับหน้า All Recipes ที่ใช้สีม่วงเป็นสีหลัก · สังเกตว่าในแถบซ้ายของภาพ prompt ขอให้ออกแบบสถานะครบสี่แบบ (LOADING · EMPTY · ERROR · DEFAULT) และระบุชื่อ component ของ shadcn ที่จะใช้ด้วย (Card, Input, Select, Badge, Pagination, Skeleton, Sonner toast)
3. สรุปธีมออกมาเป็น token (หน้า 24–27) — ซึ่งคือเนื้อหาหลักของบทนี้

Design token คืออะไร

ดูภาพหน้า 22 อีกที ปุ่ม “Browse Recipes” เป็นสีม่วง ป้าย “Home cooks welcome” ก็ม่วงอ่อน ลิงก์เมนูที่เลือกอยู่ก็ม่วง
ถ้าเขียนแบบตรง ๆ คุณจะพิมพ์ #A80689 ซ้ำไว้ในไฟล์เป็นสิบที่ · วันหนึ่งฝ่ายการตลาดขอเปลี่ยนเฉดม่วง คุณต้องไล่หาทั้งโปรเจกต์ แล้วก็จะพลาดสักที่

Design token คือการตั้งชื่อให้การตัดสินใจเรื่องหน้าตา แล้วเก็บไว้ที่เดียว
แทนที่จะพิมพ์ #A80689 เราตั้งชื่อว่า --primary แล้วทุกที่ใช้ชื่อนี้ · อยากเปลี่ยนสีก็แก้บรรทัดเดียว
สไลด์หน้า 25 นิยามไว้สั้น ๆ ว่าเป็นตัวแปรที่มีชื่อ ใช้เก็บการตัดสินใจเรื่อง สี · ฟอนต์ · ระยะห่าง และหน้า Wongnok UI ในภาพก็เขียนหลักไว้ว่า ใช้ --primary ไม่ใช่ใช้เลข hex เพื่อให้เปลี่ยนธีมได้โดยไม่ต้องแก้ component

ตัวอย่าง token ฝั่งสีแบรนด์จากสไลด์หน้า 25:

สังเกตว่าชื่อบอกหน้าที่ ไม่ได้บอกสี — ไม่มี token ชื่อ --purple เพราะถ้าวันหนึ่งแบรนด์เปลี่ยนเป็นสีเขียว ชื่อ --purple จะกลายเป็นคำโกหกทั้งโปรเจกต์ แต่ --primary ยังถูกอยู่

เปิด globals.css ของจริง — token มีสองชั้น

สไลด์หน้า 26 บอกให้ “ใส่ธีมลงใน globals.css ตาม design token” และภาพ VS Code ในหน้านั้นเห็นบรรทัดหน้าตาแบบ --color-primary: var(--primary); เรียงกันยาว
ผมเปิดไฟล์ที่ shadcn init สร้างให้จริง ๆ มาดู (ตัดเหลือเฉพาะส่วนที่เกี่ยวกับ primary):

/* app/globals.css — ที่ shadcn init สร้างให้ (ตัดบางส่วน) */
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";

@custom-variant dark (&:is(.dark *));

@theme inline {                                   /* ชั้นที่ 2: บอก Tailwind ให้สร้าง class */
  --color-primary-foreground: var(--primary-foreground);
  --color-primary: var(--primary);
  /* … อีกราว 40 บรรทัด … */
}

:root {                                           /* ชั้นที่ 1: ค่าจริงของธีมสว่าง */
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  /* … */
}

.dark {                                           /* ชั้นที่ 1 อีกชุด: ค่าจริงของธีมมืด */
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  /* … */
}

อ่านจากล่างขึ้นบนจะเข้าใจง่ายกว่า:

• ชั้นที่ 1 · :root และ .dark — เก็บค่าจริง เป็น CSS variable ธรรมดา · browser อ่านตรงนี้ · Tailwind ไม่ได้สร้าง class อะไรจากชั้นนี้เลย
• ชั้นที่ 2 · @theme inline — เป็นคำสั่งของ Tailwind v4 ว่า “ให้มีสีชื่อ primary นะ ค่าของมันคือ var(--primary)” · ชื่อที่ขึ้นต้นด้วย --color- คือสัญญาณให้ Tailwind สร้าง class สีทุกตระกูล (bg- · text- · border- · ring- …)

บรรทัดสุดท้ายในแผนภาพไม่ได้เดา — ก็อปมาจากไฟล์ CSS ที่ build ออกมาจริง (components/ui/button.tsx ใช้ bg-primary อยู่ Tailwind จึงสร้าง rule นี้ให้)

กับดักหลักของบท — เพิ่ม token แค่ชั้นเดียว

สไลด์หน้า 27 มี --primary-hover: #8a0570; อยู่ใน :root (ภาพตัดส่วน @theme inline ไม่ได้โชว์) · สมมติคุณก็อปมาแค่บรรทัดนั้น แล้วเขียนปุ่มแบบนี้:

/* app/globals.css — เพิ่มบรรทัดเดียวใน :root */
:root {
  --primary-foreground: oklch(0.985 0 0);
  --primary-hover: #8a0570;          /* ← เพิ่ม */
}
/* @theme inline ไม่ได้แตะ */

// app/t81/page.tsx
export default function Page() {
  return (
    <button className="bg-primary-hover px-3 text-primary-foreground">
      Browse Recipes
    </button>
  );
}

✓ Compiled successfully in 907ms
└ ○ /t81

$ grep -o '\.bg-primary-hover{[^}]*}' .next/static/chunks/*.css; echo "rc=$?"
rc=1

$ grep -o '\-\-primary-hover:[^;]*' .next/static/chunks/*.css
--primary-hover:#8a0570

วิธีแก้คือเพิ่มบรรทัดเดียวในชั้นที่ 2:

@theme inline {
  --color-primary: var(--primary);
  --color-primary-hover: var(--primary-hover);   /* ← เพิ่ม */
}

build ใหม่แล้ว grep คำสั่งเดิม:

$ grep -o '\.bg-primary-hover{[^}]*}' .next/static/chunks/*.css; echo "rc=$?"
.bg-primary-hover{background-color:var(--primary-hover)}
rc=0

ตอนนี้ rule มาแล้ว และไม่ใช่แค่ bg- — ผมลองใส่ hover:bg-primary-hover ในอีกหน้าหนึ่ง ก็ได้ .hover\:bg-primary-hover:hover{background-color:var(--primary-hover)} ออกมาด้วย เพราะชื่อที่ลงทะเบียนใน @theme ใช้กับ variant ทุกตัวของ Tailwind ได้ทันที

dark mode — ทำไมต้องเป็น @theme inline

shadcn ทำ dark mode ด้วยการประกาศ token ชื่อเดิมซ้ำในบล็อก .dark ด้วยค่าใหม่ · component ไม่ต้องรู้เรื่องธีมเลย มันใช้ bg-primary เหมือนเดิมทุกครั้ง ส่วน element ไหนอยู่ใต้ class dark ค่า --primary ตรงนั้นก็เปลี่ยนเอง

.dark {
  --primary-hover: #e879c9;   /* ค่าสมมติสำหรับทดลอง — สไลด์หน้า 25 มีแต่ธีมสว่าง */
}

ทีนี้ลองเทียบสองแบบ: สีที่ลงทะเบียนผ่าน @theme inline (แบบ shadcn) กับสีที่ลงทะเบียนผ่าน @theme ธรรมดา ชี้ไปที่ token ตัวเดียวกัน

@theme inline { --color-primary-hover: var(--primary-hover); }
@theme        { --color-brand-noinline: var(--primary-hover); }

// วางทั้งสองกล่องไว้ใต้ .dark
<div className="dark">
  <div id="in-inline"   className="bg-primary-hover">inline ใน .dark</div>
  <div id="in-noinline" className="bg-brand-noinline">no inline ใน .dark</div>
</div>

// ใน .dark ค่า --primary-hover คือ #e879c9 (ชมพูอ่อน)
// ส่วนนอก .dark คือ #8a0570 (ม่วงเข้ม)
getComputedStyle(#in-inline).backgroundColor    // ?
getComputedStyle(#in-noinline).backgroundColor  // ?

{
  "inline":   "rgb(232, 121, 201)",   // = #e879c9 เปลี่ยนตาม .dark ✅
  "noinline": "rgb(138, 5, 112)"      // = #8a0570 ยังเป็นค่าของธีมสว่าง ❌
}

.bg-primary-hover{background-color:var(--primary-hover)}
.bg-brand-noinline{background-color:var(--color-brand-noinline)}
/* และแบบไม่ inline ถูกประกาศไว้ที่ :root */
:root,:host{ … --color-brand-noinline:var(--primary-hover)}

typography แบบ wongnok-text-h2 — ต้องใช้ @utility

prompt ในสไลด์หน้า 27 สั่ง AI ว่าให้ทำ typography เป็น class ที่ขึ้นต้นด้วย wongnok เช่น wongnok-text-h1 · และสั่งด้วยว่า อะไรที่ Tailwind มี class อยู่แล้ว ไม่ต้องเขียนเพิ่มใน globals.css
prompt เดียวกันยังสั่งอีกสองข้อ: ให้ใส่ token เรื่องเงา (shadow) ตามธีมด้วย · และไม่ต้องทำ token ส่วน Motion เพราะจะใช้ไลบรารี animation แยก — ที่น่าสังเกตคือในภาพ prompt มีไฟล์แนบชื่อ “Wongnok Design Tokens…” กับ support.js ไปด้วย และสั่งให้ทำตาม “Wongnok Design Token” — คือส่งของที่ออกแบบไว้ให้ AI อ่าน ไม่ได้ปล่อยให้เดาสีเอง
ทำไมต้องมี class แบบนี้? เพราะหัวข้อหนึ่งตัวต้องกำหนด 3–4 ค่าพร้อมกัน (ขนาด · ความสูงบรรทัด · ความหนา · ระยะตัวอักษร) ถ้าพิมพ์ text-3xl leading-9 font-bold tracking-tight ซ้ำทุกหัวข้อ วันที่ต้องปรับจะไล่แก้ไม่หมด

ใน Tailwind v4 วิธีที่ถูกคือ @utility:

/* app/globals.css */
@utility wongnok-text-h2 {
  font-size: 1.875rem;
  line-height: 2.25rem;
  font-weight: 700;
  letter-spacing: -0.01em;
}

ถ้าเขียนเป็น class CSS ธรรมดาก็ใช้ได้เหมือนกันในกรณีปกติ — แต่ลองดูว่าเกิดอะไรขึ้นเมื่อใส่ variant อย่าง md: (ผมใส่ทั้งสองแบบลงหน้าเดียวกันแล้ว build จริง):

@layer components {
  .wongnok-plain-h2 {
    font-size: 1.875rem;
    font-weight: 700;
  }
}

@utility wongnok-text-h2 {
  font-size: 1.875rem;
  /* … */
}

CSS ที่ build ออกมาจริงของฝั่ง @utility:

.wongnok-text-h2{letter-spacing:-.01em;font-size:1.875rem;font-weight:700;line-height:2.25rem}
/* … และในบล็อก @media (min-width:48rem){ … } ของ md: */
.md\:wongnok-text-h2{letter-spacing:-.01em;font-size:1.875rem;font-weight:700;line-height:2.25rem}

@utility ทำให้ class ของเราเป็นพลเมืองชั้นหนึ่งของ Tailwind — ใช้กับ md: · hover: · dark: ได้ และถ้าไม่มีใครใช้ class นี้เลย Tailwind ก็ไม่ใส่ลงไฟล์ CSS ให้เปลืองที่

ภารกิจ — ใส่ token สีอำพันกับหัวข้อ h1 ของ Wongnok

@@ -29,6 +29,8 @@
   --color-destructive: var(--destructive);
   --color-accent-foreground: var(--accent-foreground);
   --color-accent: var(--accent);
+  --color-accent-subtle: var(--accent-subtle);
+  --color-accent-strong: var(--accent-strong);
   --color-muted-foreground: var(--muted-foreground);
@@ -63,6 +65,8 @@
   --accent: oklch(0.97 0 0);
   --accent-foreground: oklch(0.205 0 0);
+  --accent-subtle: #fff1dc;
+  --accent-strong: #b36a00;
   --destructive: oklch(0.577 0.245 27.325);
@@ -117,6 +121,12 @@
   --sidebar-ring: oklch(0.556 0 0);
 }

+@utility wongnok-text-h1 {
+  font-size: 2.25rem;
+  line-height: 2.5rem;
+  font-weight: 700;
+}
+
 @layer base {

// app/recipes-demo/page.tsx
export default function RecipesDemo() {
  return (
    <main className="p-8">
      <h1 className="wongnok-text-h1">All Recipes</h1>
      <span className="rounded-md bg-accent-subtle px-2 py-0.5 text-accent-strong">Easy</span>
    </main>
  );
}

$ npx next build
✓ Compiled successfully in 450ms
└ ○ /recipes-demo

$ npx tsc --noEmit; echo "tsc rc=$?"
tsc rc=0
$ npx eslint app/recipes-demo; echo "eslint rc=$?"
eslint rc=0

$ grep -oE '\.(bg-accent-subtle|text-accent-strong|wongnok-text-h1)\{[^}]*\}' .next/static/chunks/*.css
.bg-accent-subtle{background-color:var(--accent-subtle)}
.wongnok-text-h1{font-size:2.25rem;font-weight:700;line-height:2.5rem}
.text-accent-strong{color:var(--accent-strong)}

$ grep -oE -- '--accent-(subtle|strong):[^;]*' .next/static/chunks/*.css
--accent-subtle:#fff1dc
--accent-strong:#b36a00

ลองตอบดู

ถามกลับได้เลย

ถ้าคุณเพิ่ม token แล้ว class ไม่ทำงาน ให้เอาของสามอย่างนี้มาคุย: บรรทัดที่เพิ่มใน :root · บรรทัดที่เพิ่มใน @theme inline · และผลของ grep ชื่อ class ในไฟล์ .next/static/chunks/*.css
สามอย่างนี้บอกได้เกือบทุกครั้งว่าพังที่ชั้นไหน
หรือถ้าอยากรู้ว่า token ฝั่ง spacing · radius · shadow ในสไลด์หน้า 25 (เมนูซ้าย) ควรลงทะเบียนในตระกูลไหนของ @theme ก็ถามได้

อ้างอิง

• Tailwind CSS — Theme variables — อ่านตาราง Theme variable namespaces เพื่อดูว่าตระกูล --color- · --font- · --radius- สร้าง class อะไรบ้าง · และหัวข้อ Referencing other variables ที่อธิบายว่าทำไมต้องใช้ inline เวลาตัวแปรใน theme อ้างตัวแปรอื่น (ตรงกับผลทดลอง dark mode ในบทนี้)
• Tailwind CSS — Adding custom styles — อ่านหัวข้อ Adding custom utilities ที่สอน @utility และบอกว่า class ที่สร้างแบบนี้ใช้กับ variant ได้
• shadcn/ui — Theming — อ่านหัวข้อ Adding New Tokens ซึ่งเพิ่ม token --warning ด้วยขั้นตอนเดียวกับบทนี้ (ใส่ใน :root/.dark แล้ว map ใน @theme inline) · และดูหลักการตั้งชื่อคู่ background/foreground
• Tailwind CSS — Dark mode — อ่านหัวข้อ Toggling dark mode manually ที่ใช้ @custom-variant dark ผูก dark: เข้ากับ class (ในเอกสารเขียน &:where(.dark, .dark *) ส่วน shadcn เขียน &:is(.dark *) — หลักการเดียวกัน)
• MDN — Using CSS custom properties — อ่านหัวข้อ Inheritance of custom properties เพื่อเข้าใจว่าทำไมค่าที่ถูกคำนวณที่ :root แล้วส่งลงมา จึงไม่เปลี่ยนตาม .dark ที่อยู่ข้างล่าง