แนวทางการตั้งชื่อโทเค็น

ชื่อโทเค็นที่ไม่สอดคล้องกันทำให้คาดเดาหน้าที่ของโทเค็นไม่ได้หากไม่อ่านค่าของมัน หลักการตั้งชื่อที่ชัดเจนและคาดเดาได้เป็นพื้นฐานสำคัญของระบบโทเค็นที่ขยายได้

รูปแบบที่พบบ่อยคือ [category]-[property]-[variant] ตัวอย่างเช่น color-text-primary, color-text-secondary และ spacing-inset-sm แต่ละส่วนจะจำกัดความหมายให้เฉพาะเจาะจงขึ้นตามลำดับ

หลีกเลี่ยงการใช้ชื่อจานสีอย่าง blue-500 ในคอมโพเนนต์ ให้ใช้ชื่อเชิงความหมาย เช่น color-action-default และ color-feedback-error ชื่อเชิงความหมายยังคงใช้ได้เมื่อสีแบรนด์เปลี่ยน โดยไม่ต้องอัปเดตคอมโพเนนต์

ต่อท้ายสถานะไว้ด้านท้าย: color-button-bg-default, color-button-bg-hover และ color-button-bg-disabled การใช้คำต่อท้ายสถานะอย่างสม่ำเสมอทำให้ชุดโทเค็นคาดเดาได้และครบถ้วน

ใช้ขนาดเสื้อผ้า (xs, sm, md, lg, xl) หรือสเกลตัวเลข (100, 200...900) ให้สม่ำเสมอ สเกลตัวเลขช่วยให้แทรกค่าตรงกลางได้ ส่วนขนาดเสื้อผ้าอ่านเข้าใจง่ายกว่าสำหรับชุดขนาดเล็ก

สำหรับระบบที่มีหลายแบรนด์หรือหลายผลิตภัณฑ์ ให้เติมโทเค็นด้วยพื้นที่ชื่อ เช่น brand-a-color-primary เทียบกับ brand-b-color-primary พื้นที่ชื่อช่วยป้องกันการชนกันเมื่อนำชุดโทเค็นมารวมกัน

รูปแบบ kebab-case จะเปลี่ยนเป็นพร็อพเพอร์ตีแบบกำหนดเองของ CSS ได้โดยตรง: color-text-primary จะกลายเป็น --color-text-primary โทเค็นแบบ camel-case ต้องผ่านการแปลง ส่วนโทเค็นแบบ kebab-case ไม่ต้องแปลง

ชื่อที่ดีสามารถอธิบายตัวเองได้: spacing-stack-md (ระยะห่างแนวตั้งระหว่างองค์ประกอบที่เรียงซ้อนกัน ขนาดกลาง) สื่อเจตนาได้โดยไม่ต้องมีคอมเมนต์ ส่วนชื่อที่ไม่ดีอย่าง s3 ต้องอาศัยเอกสารภายนอกเพื่อทำความเข้าใจ

เมื่อมีการใช้งานโทเค็นแล้ว การเปลี่ยนชื่อถือเป็นการเปลี่ยนแปลงที่ไม่เข้ากันได้ ให้ใช้นามแฝงเพื่อประกาศเลิกใช้ โดยคงชื่อเดิมไว้แต่ให้ชี้ไปยังโทเค็นใหม่ เปิดช่วงเวลาให้ผู้ใช้งานย้ายข้อมูลก่อนนำโทเค็นที่เลิกใช้ออก

ตรวจสอบชื่อโทเค็นด้วยกฎแบบกำหนดเองใน Style Dictionary หรือสคริปต์ CI ปฏิเสธโทเค็นที่ไม่ตรงกับรูปแบบการตั้งชื่อ การบังคับใช้โดยอัตโนมัติช่วยป้องกันการตั้งชื่อที่ค่อย ๆ แตกต่างกันเมื่อระบบเติบโตขึ้น

เผยแพร่คู่มือการตั้งชื่อพร้อมตัวอย่างชื่อที่ถูกต้องและไม่ถูกต้อง จัดเวิร์กช็อปสั้น ๆ เพื่อให้ทีมออกแบบและทีมวิศวกรรมตกลงใช้หลักการเดียวกันก่อนระบบจะขยายใหญ่ขึ้น ความสอดคล้องต้องอาศัยความเข้าใจร่วมกัน ไม่ใช่แค่เอกสาร

เหตุใดโทเคนของคอมโพเนนต์จึงควรใช้ชื่อเชิงความหมายแทนชื่อชุดสี เช่น "blue-500"

รูปแบบการตั้งชื่อโทเคนที่สอดคล้องกัน โดยใช้โครงสร้างหมวดหมู่-คุณสมบัติ-รูปแบบย่อย ชื่อเชิงความหมาย ส่วนต่อท้ายสถานะ และคำนำหน้าเนมสเปซ ทำให้ระบบโทเคนคาดเดาได้ อธิบายตัวเองได้ และทนต่อการเปลี่ยนแปลงแบรนด์โดยไม่ทำให้โค้ดคอมโพเนนต์เสียหาย