Mở đầu — vì sao bài này quan trọng
Có một câu nói kinh điển trong giới xây dựng design system: "Tên gọi chính là API của bạn." Nghe hơi kỹ thuật, nhưng bạn hãy thử hình dùng thế này. Trong một product team ở Việt Nam, một designer mới vào tên là Linh cần tìm component nút bấm dạng phụ để làm nút "Huỷ" trong một dialog. Bạn đoán xem Linh gõ gì vào ô tìm kiếm của Figma? "Button". Nhưng thư viện của công ty lại đặt tên nó là "Btn / Ghost / MD". Linh không tìm ra, cô hỏi trong Slack, người trả lời cô đang họp, ba mươi phút trôi qua. Cuối cùng Linh tự copy một nút cũ từ file khác về sửa. Thế là design system vừa sinh ra một biến thể lệch chuẩn.
Câu chuyện đó lặp lại hàng ngày ở mọi tổ chức không có quy ước đặt tên rõ ràng. Naming — đặt tên — nghe có vẻ là chuyện nhỏ, chuyện "gu cá nhân", nhưng thực chất nó là hạ tầng vô hình quyết định cả team có tìm thấy nhau hay không. Một hệ thống tên tốt giúp designer tìm component trong vài giây, giúp developer ánh xạ đúng tên trong code, giúp người mới onboard mà không cần hỏi, và giúp bản thân design system mở rộng được mà không sụp đổ. Một hệ thống tên tệ thì ngược lại: nó là thứ thuế ngầm bạn trả mỗi ngày, mỗi lần tìm kiếm, mỗi lần review.
Bài này tập trung hoàn toàn vào một câu hỏi: đặt tên như thế nào cho có hệ thống. Chúng ta không bàn về cách build component (Bài 12), không bàn về design tokens ở tầng giá trị (Bài 14), cũng không bàn documentation (Bài 36). Chúng ta chỉ bàn về ngôn ngữ — cách bạn gọi tên mọi thứ trong design system sao cho cả người và máy đều hiểu.
Khái niệm cốt lõi
Tên là một hợp đồng, không phải nhãn dán
Điều đầu tiên cần thay đổi trong đầu bạn: tên không phải thứ bạn "dán" lên component sau khi làm xong cho có. Tên là một lời hứa về việc component đó là gì, làm gì và tìm nó ở đâu. Khi bạn đặt tên Button/Primary/Large, bạn đang hứa rằng có một họ Button, trong đó có biến thể Primary, và có kích cỡ Large. Designer khác đọc tên đó là hiểu ngay cấu trúc mà không cần mở component ra xem.
Vì là hợp đồng, tên phải có tính dự đoán được (predictable). Nếu ai đó biết bạn có Button/Primary/Large, họ phải đoán được rằng chắc chắn tồn tại Button/Primary/Small và Button/Secondary/Large. Tính dự đoán này chính là thứ giảm thời gian tìm kiếm xuống gần bằng không.
Ba trục của một cái tên component
Trong Figma, dấu gạch chéo / không chỉ là ký tự — nó tạo ra cấu trúc phân cấp trong panel Assets và gom biến thể (variants) lại. Một quy ước phổ biến và bền vững là đặt tên theo mô hình phân cấp từ tổng quát đến cụ thể:
Category / Component / Variant / State
Ví dụ: Input / TextField / Filled / Error. Đọc từ trái sang phải, bạn đi từ nhóm rộng (Input) đến cụ thể (một text field, kiểu filled, đang ở trạng thái lỗi). Ba đến bốn cấp là đủ; nhiều hơn thường là dấu hiệu bạn đang nhồi nhét metadata vào tên thay vì dùng properties.
Một lưu ý quan trọng của Figma hiện đại: với component variants, bạn nên tách phần thuộc tính ra thành properties thay vì nhét hết vào slash. Nghĩa là component set tên Button, còn Type, Size, State là các property riêng. Nhưng ngay cả khi dùng properties, bạn vẫn cần đặt tên property và giá trị property nhất quán — size với các giá trị sm / md / lg, chứ không phải chỗ thì Large chỗ thì L chỗ thì big.
Đặt tên token: tầng ngữ nghĩa
Với design tokens, quy ước phổ biến nhất hiện nay là cấu trúc phân tầng theo mô hình ba lớp mà cộng đồng hay gọi là primitive → semantic → component:
- Primitive (global / core):
color-blue-500,space-4,radius-2. Đây là giá trị thô, không mang ý nghĩa sử dụng. - Semantic (alias):
color-text-primary,color-bg-danger,space-inset-md. Đây là token nói về mục đích, không nói về giá trị. Đây là tầng designer và dev nên dùng hàng ngày. - Component-level:
button-primary-bg,card-padding. Token gắn với một component cụ thể.
category-property-variant-state. Ví dụ color-action-primary-hover. Bạn đọc được ngay: đây là màu (color), cho hành động (action), loại chính (primary), khi hover. Cấu trúc này quan trọng vì token là thứ được đồng bộ trực tiếp sang code (chúng ta sẽ nói kỹ ở Bài 35 về Tokens Studio), nên tên token gần như trở thành tên biến CSS --color-action-primary-hover.Semantic vs literal — cuộc chiến kinh điển
Đây là điểm nhiều team sai. color-blue-500 là tên literal (mô tả cái nó là). color-primary là tên semantic (mô tả cái nó dùng để làm gì). Nếu bạn đặt nút chính bằng token color-blue-500, đến ngày công ty rebrand từ xanh sang tím, bạn phải sửa tay khắp nơi. Nếu bạn dùng color-primary trỏ tới xanh, khi rebrand bạn chỉ đổi một chỗ. Nguyên tắc: primitive dùng tên literal, còn tầng người dùng cuối chạm vào phải là tên semantic.
Quy ước hình thức: casing và ký tự
Chuyện tưởng nhỏ nhưng gây tranh cãi bất tận: viết hoa hay thường, dùng gì để nối chữ. Không có đáp án "đúng" tuyệt đối, chỉ có "nhất quán". Một số quy ước phổ biến:
- kebab-case (
color-text-primary) — chuẩn CSS, rất phổ biến cho token. - PascalCase cho tên component (
TextField,NavBar) — khớp với cách đặt tên component trong React. - Tránh khoảng trắng thừa, tránh ký tự đặc biệt, tránh tiếng Việt có dấu trong tên kỹ thuật (dấu tiếng Việt sẽ vỡ khi export sang code).
Tình huống thực tế
Tình huống 1: Fintech Việt và cái giá của "Btn2 final"
Một công ty fintech ở TP.HCM (gọi là VietPay cho dễ) có đội design 6 người. Ban đầu chỉ có một designer, mọi thứ trong đầu anh nên tên gì cũng được: button, button blue, btn small, Btn2 final. Đến khi scale lên 6 designer và 4 frontend dev, thư viện Figma có 340 component với đủ kiểu tên loạn xạ.
Hậu quả cụ thể: một cuộc audit nội bộ phát hiện họ có 7 biến thể khác nhau của cùng một nút primary, vì mỗi designer không tìm thấy nút cũ nên tự tạo nút mới. Frontend dev thì phàn nàn rằng khi nhận file, họ mất trung bình gần 40 phút mỗi màn hình chỉ để tra xem "cái nút này là component nào, dùng token màu nào".
Giải pháp họ áp dụng: chuẩn hoá về Category/Component/Variant/State, gộp 7 nút thành 1 component set với property type và size, và đặt tên token màu theo semantic. Sau ba tuần dọn dẹp, thời gian handoff mỗi màn hình giảm còn khoảng 10 phút. Bài học: naming loạn không giết bạn ngày một ngày hai — nó âm thầm nhân đôi khối lượng công việc cho đến khi đội đủ lớn để bạn cảm nhận được.
Tình huống 2: Cú rebrand cứu bởi tên semantic
Một startup thương mại điện tử ở Singapore đổi màu thương hiệu chủ đạo từ cam sang xanh lá sau vòng gọi vốn Series A, khi có nhà đầu tư chiến lược mới. Team design lo sốt vó vì app có hàng trăm màn hình.
Nhưng vì trước đó họ đã kỷ luật đặt token theo semantic — mọi nút, link, badge quan trọng đều trỏ tới color-brand-primary chứ không phải color-orange-500 — nên việc rebrand chỉ là đổi giá trị của một token gốc. Chưa tới một buổi chiều, cả hệ thống đổi màu, và vì token được đồng bộ sang code, frontend chỉ cần pull bản token mới. Bài học: tên semantic không phải để cho đẹp — nó là bảo hiểm cho những thay đổi lớn trong tương lai mà hôm nay bạn chưa lường được.
Tình huống 3: Khi tên không khớp giữa design và code
Một agency ở Hà Nội làm design system cho khách hàng ngân hàng. Designer đặt tên component là Ô nhập liệu, Nút chính, bằng tiếng Việt cho "thân thiện". Đến lúc handoff, developer đặt tên trong code là TextInput, PrimaryButton. Kết quả: không ai map được component nào với code nào, mỗi cuộc họp review đều mất thời gian dịch qua dịch lại, và Figma Dev Mode (Bài 42) trở nên vô dụng vì tên hiển thị không khớp gì với codebase.
Họ phải làm lại: thống nhất một shared vocabulary — một bảng từ vựng chung mà cả designer và dev đồng ý, đặt tên kỹ thuật bằng tiếng Anh (TextField, Button), còn phần mô tả tiếng Việt để trong documentation. Bài học: tên trong design system là ngôn ngữ chung của hai nghề khác nhau. Nó phải khớp được với code, nên tiếng Việt có dấu tuy dễ đọc nhưng gây vỡ ở khâu kỹ thuật; hãy để tiếng Việt cho mô tả, giữ tên kỹ thuật bằng tiếng Anh không dấu.
Hướng dẫn từng bước
Đây là quy trình thực tế để thiết lập naming convention cho một design system, dù bạn bắt đầu từ con số 0 hay đang dọn dẹp mớ hỗn độn.
Bước 1 — Chọn cấu trúc phân cấp cho component. Quyết định mô hình của bạn, ví dụ Category / Component / Variant. Viết nó ra thành một dòng nguyên tắc ai cũng đọc được. Đừng để nó trong đầu một người.
Bước 2 — Lập một shared vocabulary với dev. Ngồi cùng frontend lead, liệt kê các component nền tảng và thống nhất tên tiếng Anh cho từng cái: nút là Button hay Btn? Ô nhập là Input, TextField hay TextInput? Chốt một lần, ghi vào tài liệu. Nguyên tắc vàng: nếu code gọi nó là X, thì Figma cũng nên gọi nó là X.
Bước 3 — Thiết lập ba tầng token. Tạo primitive (tên literal), semantic (tên theo mục đích), và component token nếu cần. Với tầng semantic, luôn tự hỏi "token này dùng để làm gì", không phải "nó màu gì".
Bước 4 — Chốt quy ước hình thức. Casing nào cho token (kebab-case), casing nào cho component (PascalCase), thứ tự các thành phần trong tên (category trước, state sau). Viết vài ví dụ mẫu.
Bước 5 — Chuyển metadata sang properties. Với component variants, đừng nhồi mọi thứ vào slash. Tách Size, State, Type thành component properties có tên và giá trị nhất quán.
Bước 6 — Viết ra một trang "Naming Guidelines". Một trang thôi, kèm ví dụ đúng/sai. Đây là tài liệu bạn đưa cho người mới trong ngày đầu.
Bước 7 — Audit định kỳ. Mỗi quý, rà lại thư viện tìm tên lệch chuẩn, component trùng lặp. Naming là kỷ luật liên tục, không phải việc làm một lần.
Lỗi thường gặp & mẹo
Lỗi 1 — Đặt tên theo hình thức thay vì chức năng. RedButton, BigCard. Đến khi màu đỏ đổi thành cam thì tên thành nói dối. Hãy đặt theo vai trò: DangerButton, hoặc dùng property variant=danger.
Lỗi 2 — Tên "final", "v2", "copy", "new". Button final final 2. Những từ này là dấu hiệu bạn dùng tên để quản lý version, việc đó nên để cho version history hoặc branching của Figma (Bài 37) lo.
Lỗi 3 — Viết tắt tuỳ hứng. Btn, Bg, Txt, Ctn. Người viết hiểu, người mới thì phải đoán. Nếu bắt buộc viết tắt, hãy chuẩn hoá danh sách viết tắt và ghi vào guideline.
Lỗi 4 — Trộn nhiều ngôn ngữ và casing. Chỗ Primary, chỗ chính, chỗ PRIMARY. Máy tìm kiếm và con người đều loạn.
Lỗi 5 — Đặt tên literal ở tầng người dùng chạm vào. Dùng color-blue-500 trực tiếp trên component thay vì color-action-primary. Sẽ trả giá khi rebrand.
Mẹo — Kiểm tra "test dự đoán": đưa cho một đồng nghiệp một tên bạn đặt, rồi nhờ họ đoán các tên anh em của nó. Nếu họ đoán đúng, hệ thống tên của bạn tốt. Nếu họ ngập ngừng, tên đang thiếu tính dự đoán.
Mẹo — Tên nên đọc được to lên tự nhiên: một cái tên tốt là cái tên bạn đọc lên nghe như một câu mô tả: "color, action, primary, hover". Nếu đọc lên mà líu lưỡi, thứ tự các thành phần có lẽ sai.
Bài tập thực hành
- Audit nhanh: Mở một file Figma bất kỳ bạn từng làm (hoặc một UI Kit miễn phí). Liệt kê 10 tên component đầu tiên bạn thấy. Đánh dấu tên nào vi phạm 5 lỗi ở trên. Bạn sẽ bất ngờ vì số lượng.
- Thiết kế cấu trúc: Cho các component sau — nút, ô nhập, thẻ card, nhãn badge, hộp thoại — hãy viết ra cấu trúc tên đầy đủ của bạn theo mô hình
Category/Component/Variant/State, kèm ít nhất 3 variant cho mỗi cái.
- Ba tầng token: Viết tên cho một hệ màu action gồm: màu nền nút primary lúc bình thường, lúc hover, lúc disabled; và màu văn bản danger. Yêu cầu: có đủ tầng primitive và semantic, và giải thích tại sao component nên dùng tầng semantic.
- Test dự đoán: Đưa cho một người bạn (designer hoặc dev) đúng một cái tên bạn vừa đặt, ví dụ
Button/Secondary/Large. Nhờ họ viết ra 3 tên anh em mà họ đoán là tồn tại. So sánh với hệ thống thực của bạn. Ghi lại độ khớp.
Tóm tắt
Naming convention không phải chuyện thẩm mỹ hay sở thích cá nhân — nó là API của design system, là ngôn ngữ chung giữa designer và developer, và là hạ tầng quyết định tốc độ tìm kiếm cũng như khả năng mở rộng của cả hệ thống. Hãy nhớ mấy trụ cột chính: đặt tên component theo phân cấp từ tổng quát đến cụ thể (Category/Component/Variant/State); đặt token theo ba tầng primitive → semantic → component, và cho người dùng cuối chạm vào tầng semantic; ưu tiên tên theo chức năng hơn hình thức để sống sót qua các đợt rebrand; thống nhất một shared vocabulary khớp với code và giữ tên kỹ thuật bằng tiếng Anh không dấu; và cuối cùng, tính nhất quán quan trọng hơn sự "đúng" — một quy ước không hoàn hảo nhưng được tuân thủ tuyệt đối vẫn tốt hơn một quy ước hoàn hảo mà mỗi người làm một kiểu. Đặt tên tốt là món quà bạn tặng cho chính mình và cả team ở tương lai, mỗi lần họ gõ vào ô tìm kiếm và thấy đúng thứ mình cần trong hai giây.