Mở đầu — vì sao bài này quan trọng
Hãy tưởng tượng bạn vừa hoàn thành một màn hình đẹp long lanh trong Figma: bố cục cân đối, màu sắc chuẩn design token, spacing đều tăm tắp. Bạn tự tin bàn giao cho anh dev, rồi hai ngày sau nhận về một sản phẩm... đúng nhưng sai. Đúng về mặt hình ảnh — mọi thứ trông y hệt file thiết kế. Nhưng sai về mặt hành vi: khi người dùng nhập sai email thì lỗi không hiện ra, khi danh sách rỗng thì màn hình trắng bóc, khi bấm nút hai lần thì đơn hàng bị tạo trùng. Anh dev không làm sai — anh ấy chỉ code đúng những gì nhìn thấy. Vấn đề là những gì quan trọng nhất lại không nằm trong hình.
Đây chính là khoảng trống mà annotation (chú thích thiết kế) sinh ra để lấp đầy. Một file Figma tĩnh chỉ kể được câu chuyện "trạng thái lý tưởng" — sản phẩm trông thế nào khi mọi thứ diễn ra hoàn hảo. Nhưng phần mềm thực tế sống trong sự hỗn loạn: mạng chậm, dữ liệu thiếu, người dùng bấm loạn xạ, tài khoản hết hạn. Annotation là nơi bạn — nhà thiết kế — giải thích cho kỹ sư biết sản phẩm phải cư xử ra sao trong những tình huống mà hình ảnh không thể diễn tả.
Trong Bài 42 bạn đã làm quen với Dev Mode như một môi trường bàn giao. Bài này đi sâu vào một kỹ năng cụ thể và cực kỳ đáng tiền: viết annotation tốt để dev hiểu "cách làm và lý do", chứ không chỉ "trông ra sao". Đây là kỹ năng phân biệt một designer junior chỉ vẽ đẹp với một product designer thực thụ có thể ship sản phẩm ra thị trường mà không cần trăm câu hỏi qua lại.
Khái niệm cốt lõi
Design thể hiện "what", Annotation diễn giải "how + why"
Có một câu nói tôi luôn nhắc học viên: bản thiết kế trả lời câu hỏi "cái gì", annotation trả lời câu hỏi "như thế nào" và "tại sao". Một khung hình cho thấy có một nút "Đặt hàng" màu cam ở góc dưới. Nhưng chỉ annotation mới nói được: nút này bị disable cho tới khi người dùng chọn phương thức thanh toán; khi bấm sẽ hiện loading spinner và chặn double-click; nếu API trả lỗi 402 thì hiện toast "Số dư không đủ"; và lý do nút phải nằm sticky ở đáy màn hình là vì dữ liệu người dùng cho thấy 70% khách hàng cuộn qua nó trên mobile.
Annotation tốt thường tập trung vào bốn nhóm thông tin mà hình ảnh không thể tự nói:
1. Interaction logic (logic tương tác)
Đây là những gì xảy ra khi người dùng chạm vào giao diện. Bấm nút này dẫn tới đâu? Vuốt sang trái làm gì? Nhập vào ô này thì hệ thống validate lúc nào — khi đang gõ, khi rời khỏi ô, hay khi bấm submit? Ví dụ: "Ô tìm kiếm debounce 300ms rồi mới gọi API" là một annotation interaction cực kỳ giá trị, vì không có cách nào một hình ảnh tĩnh truyền tải được con số 300ms đó.
2. State transitions (chuyển đổi trạng thái)
Một component hiếm khi chỉ có một hình dạng. Nút có các trạng thái default, hover, pressed, loading, disabled, success. Một ô input có empty, focused, filled, error, disabled. Annotation cần chỉ rõ cái gì kích hoạt chuyển trạng thái và trạng thái đó kéo dài bao lâu. Bạn có thể vẽ đủ 6 trạng thái của nút, nhưng nếu không chú thích "sau khi success hiển thị 2 giây rồi tự quay về default", dev sẽ phải đoán — và thường đoán sai.
3. Edge cases (trường hợp biên)
Đây là phần bị bỏ quên nhiều nhất và cũng gây bug nhiều nhất. Tên người dùng dài 80 ký tự thì hiển thị ra sao — cắt bằng dấu ba chấm hay xuống dòng? Danh sách có 0 phần tử thì màn hình ra sao? Giá tiền lên tới hàng tỷ đồng thì con số có bị tràn khỏi khung không? Ảnh đại diện lỗi không load được thì thay bằng gì? Mỗi edge case bạn không chú thích là một quyết định bạn vô tình giao cho dev — và dev sẽ quyết định theo hướng dễ code nhất, không phải hướng tốt nhất cho người dùng.
4. Business rules (quy tắc nghiệp vụ)
Đây là tầng logic sâu nhất, thứ mà thậm chí dev không thể suy ra từ giao diện. "Chỉ tài khoản đã xác thực KYC mới thấy nút Rút tiền." "Mã giảm giá không áp dụng cho đơn dưới 200.000đ." "Người dùng ở khu vực chưa hỗ trợ giao hàng sẽ thấy thông báo thay vì nút mua." Những quy tắc này thường đến từ phòng kinh doanh hoặc pháp lý, và nếu không được chú thích rõ ràng ngay trên thiết kế, chúng dễ dàng thất lạc giữa hàng chục cuộc họp.
Annotation ở đâu và bằng công cụ gì
Trong Figma hiện đại, bạn có nhiều lớp để đặt annotation. Ở mức đơn giản nhất là các note dạng text hoặc sticky note đặt cạnh khung hình. Cao cấp hơn, Dev Mode có tính năng Annotations gắn trực tiếp vào từng layer, tự động hiển thị thuộc tính như spacing, typography, color kèm ghi chú của bạn — và quan trọng là dev có thể bật/tắt để không làm rối canvas. Với các luồng phức tạp, người ta dùng flow diagram (mũi tên nối các màn hình) kèm chú thích điều kiện rẽ nhánh. Nguyên tắc chung: annotation phải nằm gần nơi nó mô tả và không lẫn vào chính thiết kế để tránh dev nhầm chú thích thành nội dung UI.
Tình huống thực tế
Ví dụ 1: Sàn thương mại điện tử và nút "Mua ngay" bị bấm hai lần
Một startup thương mại điện tử tại TP.HCM (gọi là ShopViet) ra mắt tính năng flash sale. Designer bàn giao màn hình sản phẩm với nút "Mua ngay" rực rỡ, kèm đủ trạng thái hover và pressed. Trong đợt sale đầu tiên, tổng đài nhận hơn 40 cuộc gọi phàn nàn trong một buổi sáng: khách bị tạo trùng đơn hàng, có người bị tính tiền hai lần vì mạng lúc sale bị chậm nên họ bấm nút liên tục.
Nguyên nhân gốc: file thiết kế chỉ có trạng thái loading nhưng không chú thích rằng nút phải bị disable ngay lập tức sau cú bấm đầu tiên và chỉ mở lại khi server phản hồi. Dev thấy có spinner nên chỉ thêm spinner, còn nút vẫn nhận được cú bấm tiếp theo. Sau sự cố, designer bổ sung một annotation ngắn ngay cạnh nút: "Khi bấm: disable nút + hiện spinner NGAY (optimistic). Chỉ enable lại khi có response. Nếu lỗi mạng > 10s, hiện toast 'Kết nối chậm, vui lòng thử lại' và enable nút."
Bài học: một dòng annotation về interaction logic đã ngăn được một lỗi tiền bạc nghiêm trọng. Trạng thái loading trong hình là chưa đủ — điều dev cần là thời điểm và điều kiện chuyển trạng thái.
Ví dụ 2: Ứng dụng ví điện tử và quy tắc nghiệp vụ ẩn
Một nhóm phát triển ví điện tử ở Đông Nam Á thiết kế màn hình "Rút tiền". Thiết kế đẹp, rõ ràng, có ô nhập số tiền và nút xác nhận. Dev code đúng răm rắp. Nhưng khi vào kiểm thử, phòng tuân thủ (compliance) hoảng hốt: người dùng chưa hoàn tất KYC vẫn rút được tiền, và không có giới hạn hạn mức 20 triệu đồng/ngày theo quy định.
Vấn đề là những quy tắc này tồn tại trong đầu của product manager và trong một tài liệu Word nào đó, chứ không nằm trên thiết kế. Designer sau đó thêm một khối annotation "Business rules" cạnh màn hình: "(1) Nút Rút chỉ hiện nếu kyc_status = verified, ngược lại thay bằng banner 'Xác thực danh tính để rút tiền'. (2) Tổng rút trong ngày ≤ 20.000.000đ; nếu vượt, hiện lỗi inline dưới ô số tiền. (3) Phí rút hiển thị real-time khi người dùng nhập, công thức lấy từ endpoint /fees."
Bài học: business rules là loại thông tin dev không thể tự suy ra. Chúng phải được ghi rõ ràng, có điều kiện cụ thể, và tốt nhất là dùng đúng tên biến/trạng thái mà backend sử dụng để tránh hiểu lầm.
Ví dụ 3: Màn hình danh sách đơn hàng và những edge case bị bỏ quên
Một sản phẩm SaaS quản lý bán hàng cho các cửa hàng nhỏ tại Việt Nam thiết kế màn hình "Danh sách đơn hàng". File Figma trình bày một danh sách đẹp với 8 đơn hàng mẫu, mỗi đơn có tên khách, số tiền, trạng thái. Khi lên production, hàng loạt vấn đề nảy sinh: khách hàng mới chưa có đơn nào thì thấy màn hình trắng trơn (thiếu empty state); có đơn tên khách là "Nguyễn Thị Hoàng Yến Nhi Phương Thảo" thì tràn layout; đơn giá trị 1.250.000.000đ thì con số đè lên cột trạng thái.
Sau buổi retro, đội thống nhất mọi màn hình danh sách phải kèm annotation edge case bắt buộc. Designer cập nhật: "Tên khách: giới hạn 1 dòng, tràn thì cắt bằng '...'. Số tiền: định dạng phân cách nghìn, tối đa hiển thị đủ 12 chữ số. Empty state: xem frame 'Đơn hàng - rỗng' bên phải. Loading: skeleton 5 dòng. Lỗi tải: xem frame 'Đơn hàng - lỗi'."
Bài học: dữ liệu mẫu trong Figma luôn "đẹp" một cách phi thực tế. Nhiệm vụ của annotation edge case là kéo thiết kế về với thực tế xấu xí — dữ liệu dài, thiếu, tràn, hoặc không có.
Hướng dẫn từng bước
Đây là quy trình tôi khuyên bạn áp dụng mỗi khi chuẩn bị bàn giao một màn hình.
Bước 1 — Rà soát toàn bộ trạng thái của mỗi component. Đi qua từng phần tử tương tác và tự hỏi: nó có bao nhiêu trạng thái? Cái gì kích hoạt mỗi trạng thái? Với mỗi trạng thái chưa vẽ ra thành hình, hãy chú thích bằng chữ.
Bước 2 — Đánh dấu mọi tương tác. Với mỗi thứ có thể bấm, gõ, vuốt, kéo, hãy viết một dòng: hành động này → kết quả gì. Ghi rõ cả các con số quan trọng như thời gian debounce, thời gian hiển thị toast, ngưỡng timeout.
Bước 3 — Liệt kê edge case theo checklist. Với mỗi vùng hiển thị dữ liệu, chạy qua bộ câu hỏi: rỗng thì sao? Đang tải thì sao? Lỗi thì sao? Dữ liệu quá dài thì sao? Quá nhiều phần tử thì sao? Số quá lớn thì sao? Chú thích câu trả lời hoặc link sang frame tương ứng.
Bước 4 — Ghi rõ business rules kèm điều kiện. Với mỗi phần tử hiển thị/ẩn theo điều kiện, viết công thức logic rõ ràng: "hiện X nếu điều kiện Y". Dùng đúng tên trạng thái, tên biến mà đội backend dùng nếu có thể.
Bước 5 — Dùng Annotations trong Dev Mode để gắn vào layer. Thay vì rải text tự do khắp canvas, gắn annotation trực tiếp vào layer liên quan để dev thấy chú thích đúng ngữ cảnh, và có thể ẩn đi khi cần nhìn thiết kế sạch.
Bước 6 — Tách bạch chú thích khỏi UI. Đảm bảo annotation có màu, kiểu, vị trí khác hẳn nội dung thật (thường đặt ngoài khung hình, dùng màu tương phản như tím/hồng) để dev không bao giờ nhầm chú thích thành text cần code.
Bước 7 — Đi bộ qua thiết kế cùng dev. Annotation tốt nhất vẫn nên được "walkthrough" trực tiếp một lần. Buổi nói chuyện 15 phút giúp phát hiện những chỗ bạn tưởng đã rõ nhưng dev vẫn thắc mắc.
Lỗi thường gặp & mẹo
Lỗi 1 — Annotation quá nhiều biến canvas thành mớ hỗn độn. Người mới thường sợ thiếu nên chú thích mọi thứ, kể cả những điều hiển nhiên như "đây là nút". Kết quả là dev bị ngợp và bỏ qua luôn cả những chú thích quan trọng. Mẹo: chỉ chú thích những gì hình ảnh không tự nói được. Nếu spacing đã có trong Dev Mode, đừng chú thích lại spacing.
Lỗi 2 — Chú thích cái "trông rõ ràng", bỏ qua cái "vô hình". Nhiều bạn chăm chú ghi màu, font (những thứ dev tự thấy được) nhưng lại quên interaction và business rules (những thứ dev không thể thấy). Mẹo: dành 80% công sức annotation cho hành vi và logic, không phải cho thuộc tính hình ảnh.
Lỗi 3 — Dùng ngôn ngữ mơ hồ. "Nút hơi mờ khi không dùng được" là vô nghĩa với dev. Bao nhiêu phần trăm opacity? Mẹo: luôn cụ thể và định lượng — "disabled: opacity 40%, không nhận sự kiện bấm".
Lỗi 4 — Annotation không được cập nhật khi thiết kế thay đổi. Chú thích lỗi thời còn nguy hiểm hơn không có chú thích, vì nó gây hiểu lầm có chủ đích. Mẹo: coi annotation là một phần của thiết kế, sửa hình thì sửa luôn chú thích.
Lỗi 5 — Bỏ quên hành vi responsive và trạng thái rỗng. Đây là hai vùng edge case bị quên nhiều nhất. Mẹo: biến câu hỏi "màn hình này khi rỗng thì sao?" thành phản xạ bắt buộc.
Mẹo vàng: hãy viết annotation như thể bạn đang viết cho một dev thông minh nhưng chưa từng dự bất kỳ cuộc họp nào của dự án. Nếu người đó vẫn code đúng, annotation của bạn đã đạt chuẩn.
Bài tập thực hành
Chọn một màn hình có tính tương tác trong một dự án của bạn — ví dụ màn hình đăng nhập, hoặc màn hình danh sách sản phẩm.
- Liệt kê trạng thái: với mỗi phần tử tương tác, viết ra tất cả trạng thái có thể có và điều kiện kích hoạt từng cái. Đặt mục tiêu tìm được ít nhất 5 trạng thái mà thiết kế gốc chưa vẽ ra.
- Chạy checklist edge case: với mỗi vùng dữ liệu, trả lời đủ 6 câu hỏi (rỗng, loading, lỗi, dữ liệu dài, quá nhiều phần tử, số quá lớn). Ghi câu trả lời thành annotation.
- Săn business rule: viết ra ít nhất 3 quy tắc nghiệp vụ ẩn có thể tồn tại (ví dụ: điều kiện hiển thị nút, giới hạn hạn mức, quyền truy cập). Nếu chưa biết chắc, biến chúng thành câu hỏi gửi PM.
- Gắn annotation trong Dev Mode: dùng tính năng Annotations của Figma để gắn ít nhất 3 chú thích vào đúng layer, thay vì đặt text tự do.
- Kiểm định: đưa file cho một người không thuộc dự án (bạn học chẳng hạn) và hỏi họ có thể mô tả lại hành vi màn hình chỉ dựa trên thiết kế và annotation không. Mỗi chỗ họ đoán sai là một annotation bạn còn thiếu.
Tóm tắt
Annotation là cầu nối giữa "hình ảnh tĩnh" và "phần mềm sống động". Thiết kế cho dev thấy sản phẩm trông như thế nào; annotation cho dev biết sản phẩm phải cư xử ra sao và tại sao lại thế. Bốn trụ cột cần chú thích là: interaction logic (điều gì xảy ra khi tương tác), state transitions (cái gì kích hoạt và giữ mỗi trạng thái bao lâu), edge cases (dữ liệu rỗng, thiếu, tràn, quá lớn), và business rules (quy tắc nghiệp vụ dev không thể tự suy ra).
Ba câu chuyện thực tế — nút "Mua ngay" bị bấm trùng ở ShopViet, quy tắc KYC bị bỏ sót trong ví điện tử, và danh sách đơn hàng vỡ layout — đều có chung một bài học: bug đắt giá nhất không đến từ pixel sai, mà từ hành vi không được diễn giải. Hãy chú thích những gì vô hình, viết thật cụ thể và định lượng, tách bạch chú thích khỏi UI, giữ annotation luôn cập nhật, và luôn dành một buổi walkthrough ngắn với dev. Làm được vậy, bạn không chỉ bàn giao một file đẹp — bạn bàn giao một sản phẩm sẵn sàng để ship.