Component cốt lõi: Input & Hành độngCore Components: Inputs & Actions

Thuộc bộ kiến thức Design System Roadmap.

Tổng quan

Mọi design system đều có một nhóm nhỏ component xuất hiện ở gần như mọi màn hình: Button, text Input, Checkbox, Radio, Switch, Select. Đây chính là các component cốt lõi (core components), và chúng xứng đáng với cái tên đó không phải vì đẹp mắt, mà vì tần suất tái sử dụng cực cao. Một trang marketing có thể chỉ dùng component “hero banner” một lần trên mỗi trang; trong khi đó, Button có thể được khởi tạo hàng chục lần chỉ riêng trong một luồng checkout. Sự bất đối xứng này kéo theo hệ quả trực tiếp về lượng công sức thiết kế và kỹ thuật nên đầu tư: một lỗi nhỏ ở component ít dùng thì tốn kém không đáng kể, nhưng một lỗi nhỏ ở Button — thiếu focus state, thang size không nhất quán, prop disabled âm thầm không có tác dụng trên button được render bằng <a> — sẽ bị nhân lên trên toàn bộ sản phẩm và trở nên cực kỳ tốn kém để sửa về sau, khi đã có hàng trăm nơi phụ thuộc vào hành vi lỗi đó.

Bài này bao quát hai nhóm component cốt lõi tạo nên phần lớn UI tương tác:

• Hành động (Actions) — các component có nhiệm vụ kích hoạt một hành động nào đó: Button và các biến thể.
• Input — các component thu thập giá trị từ người dùng: text Input, Textarea, Checkbox, Radio, Switch, Select, và Dropdown tùy chỉnh.

Bài cũng bao quát cách các “nguyên liệu” (primitives) này kết hợp thành form, cũng như các nguyên tắc thiết kế API component (đặt tên prop, controlled vs. uncontrolled) giúp bộ component library nhất quán khi lớn dần lên. Các nền tảng thị giác mà những component này sử dụng — màu sắc, khoảng cách, thang typography — được trình bày trong Design Token & Nền tảng thị giác. Các component hiển thị thông tin thay vì thu thập thông tin (alert, toast, tooltip, badge) được trình bày trong Component cốt lõi — Nội dung & Feedback. Hành vi bàn phím và trình đọc màn hình cho từng component được nói ở đây sẽ được mở rộng trong Accessibility & Thiết kế bao trùm.

Vì sao component “cốt lõi” xứng đáng được đầu tư nhiều hơn

Ba đặc điểm phân biệt một component cốt lõi với một component thông thường:

1. Tần suất tái sử dụng. Nó xuất hiện ở gần như mọi tính năng, thường nhiều lần trên cùng một màn hình.
2. Vai trò nền tảng. Các component phức tạp hơn (action ở mỗi hàng của data table, nút confirm trong modal, mỗi field trong form) đều được xây trên nó. Một lỗi ở đây sẽ lan ra khắp nơi.
3. Khả năng chịu đựng thay đổi API thấp. Vì quá nhiều nơi phụ thuộc vào nó, việc thay đổi hình dạng prop về sau là một breaking change có phạm vi ảnh hưởng rất lớn. Làm đúng API ngay từ đầu rẻ hơn nhiều so với sửa sau này.

Đây là lý do các đội xây design system thường xây Button và text Input trước tiên, đầu tư nhiều nhất vào tài liệu và test cho chúng, và coi mỗi lần thêm prop mới cho chúng là một buổi review thiết kế thu nhỏ chứ không phải một PR thông thường.

Kiến thức nền tảng

Button

Button kích hoạt một hành động — submit form, mở dialog, điều hướng, xóa một bản ghi. Nó được định nghĩa theo ba trục độc lập: variant (thứ bậc thị giác / ý định), size (mật độ), và state (phản hồi tương tác).

Variant

Variant	Ý định	Cách dùng điển hình	Trọng lượng thị giác
primary	Hành động quan trọng nhất trên màn hình	”Save”, “Submit”, “Continue”	Cao nhất — nền đặc, màu thương hiệu
secondary	Hành động thay thế hoặc hỗ trợ đi kèm với primary	”Cancel” đứng cạnh “Save”	Trung bình — viền ngoài (outline) hoặc nền nhạt
tertiary	Hành động ít nhấn mạnh, thường nằm trong dòng text hoặc UI dày đặc	”Learn more”, nút phân trang	Thấp — không viền, giống text
ghost	Hành động tối giản, hòa vào nền cho đến khi được tương tác	Icon button trong toolbar, action trong card	Thấp nhất — trong suốt cho đến khi hover/focus
danger	Hành động phá hủy hoặc không thể hoàn tác	”Delete account”, “Remove member”	Màu riêng biệt (đỏ/cam), bất kể pairing với primary/secondary

Một màn hình chỉ nên có tối đa một nút primary trong mỗi nhóm hành động logic — đó chính là điều tạo nên ý nghĩa “bước tiếp theo được đề xuất”. Một màn hình đầy nút primary thì không còn thứ bậc nào cả, làm mất đi mục đích của việc có variant.

Size

Size	Chiều cao điển hình	Trường hợp dùng
sm	28–32px	UI dày đặc, action trong hàng của table, toolbar
md	36–40px	Mặc định cho phần lớn form và dialog
lg	44–48px	Trang marketing, CTA chính, UI ưu tiên chạm (touch-first) trên mobile

Các size nên ánh xạ vào cùng bộ token spacing/typography dùng ở nơi khác trong hệ thống (xem Design Token & Nền tảng thị giác) thay vì các giá trị pixel tùy tiện, để Button size="md" và Input size="md" thẳng hàng về mặt thị giác khi đặt cạnh nhau trong một form.

State

State	Kích hoạt bởi	Thay đổi gì
Default	Ở trạng thái nghỉ	Style cơ bản
Hover	Con trỏ đặt trên phần tử	Thay đổi nhẹ nền/viền — chỉ áp dụng với chuột, không áp dụng trên touch
Focus	Focus bằng bàn phím (:focus-visible)	Vòng focus rõ ràng, phải đạt yêu cầu về độ tương phản
Active	Đang nhấn / :active	Hơi tối hơn/lún xuống, tạo cảm giác phản hồi xúc giác
Disabled	Prop disabled	Giảm opacity, pointer-events: none, bị loại khỏi tab order, dùng aria-disabled hoặc disabled native
Loading	Prop loading	Spinner thay thế hoặc đi kèm label, nút không còn tương tác được, label thường được giữ lại để tránh lệch chiều rộng

Trạng thái loading cần được chăm chút riêng: thay label bằng spinner mà không cố định chiều rộng sẽ gây layout shift; một pattern phổ biến là giữ nguyên kích thước nút, hoặc chồng spinner lên trên label đã ẩn, hoặc đặt spinner cạnh label và vô hiệu hóa tương tác khi loading là true. disabled và loading không nên bị gộp chung trong API — một nút loading thường vẫn muốn truyền tải “hành động này đang được xử lý”, trong khi disabled truyền tải “hành động này hiện không hợp lệ”, và trình đọc màn hình nên thông báo chúng khác nhau (aria-busy cho loading, aria-disabled cho disabled).

Ví dụ API component

// Cách dùng cơ bản
<Button variant="primary" size="md">
  Save changes
</Button>

// Hành động phụ đi kèm
<Button variant="secondary" size="md">
  Cancel
</Button>

// Hành động phá hủy
<Button variant="danger" size="sm" onClick={handleDelete}>
  Delete account
</Button>

// Trạng thái loading — nút vẫn disabled trong lúc xử lý
<Button variant="primary" size="md" loading disabled={isSubmitting}>
  Submit
</Button>

// Icon-only button — bắt buộc phải có accessible name vì không có label hiển thị
<Button variant="ghost" size="sm" iconOnly aria-label="Close dialog">
  <CloseIcon />
</Button>

// Icon + label — icon mang tính trang trí, label mang ý nghĩa
<Button variant="secondary" size="md" icon={<DownloadIcon />}>
  Download report
</Button>

Hình dạng prop TypeScript tiêu biểu cho Button:

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  iconOnly?: boolean;
  icon?: React.ReactNode;
  type?: 'button' | 'submit' | 'reset';
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  'aria-label'?: string; // bắt buộc theo lint rule khi iconOnly là true
  children?: React.ReactNode;
}

Icon-only vs. icon + label

Mặc định nên dùng icon + label — rõ ràng, dễ quét mắt hơn với người dùng mới, và không phụ thuộc vào việc người dùng nhận ra ý nghĩa của icon khi tách khỏi ngữ cảnh. Chỉ dùng nút icon-only khi:

• UI cực kỳ dày đặc, nơi phần chữ label sẽ phá vỡ layout (toolbar, action trong hàng của table).
• Icon có ý nghĩa được hiểu phổ biến trong ngữ cảnh đó (dấu ”×” để đóng, biểu tượng thùng rác cạnh một hàng đơn lẻ, chevron để mở rộng/thu gọn).
• Cùng một hành động lặp lại nhiều lần trong danh sách, nơi label ở mỗi hàng sẽ gây rối mắt.

Mọi nút icon-only bắt buộc phải có accessible name qua aria-label (hoặc aria-labelledby) — bản thân icon không truyền tải gì cho trình đọc màn hình, và chỉ dựa vào tooltip title là không đủ vì tooltip không được công nghệ hỗ trợ (assistive technology) hiển thị một cách đáng tin cậy, và cũng không hoạt động tốt trên thiết bị cảm ứng.

Text Input & Textarea

Input và Textarea thu thập giá trị dạng văn bản tự do. Mô hình state của chúng tương tự Button nhưng có thêm các state liên quan đến validation:

State	Kích hoạt bởi	Thay đổi gì
Default	Nghỉ, chưa được chạm vào	Viền/nền cơ bản
Focus	:focus	Vòng focus, thay đổi màu viền
Error	Validation thất bại	Viền đỏ, icon lỗi, thông báo lỗi hiển thị bên dưới
Disabled	Prop disabled	Giảm opacity, không focus được, giá trị không được gửi kèm form
Read-only	Prop readOnly	Giá trị vẫn hiển thị và có thể chọn/copy, nhưng không sửa được; vẫn focus được và vẫn được submit

Disabled và read-only thường bị nhầm lẫn: disabled loại field khỏi tab order và khỏi việc submit form hoàn toàn (hữu ích cho field “chưa áp dụng được”); readOnly giữ field có thể focus, chọn, và vẫn nằm trong dữ liệu submit, nhưng ngăn chỉnh sửa (hữu ích cho giá trị được tính toán hoặc điền sẵn mà người dùng nên copy được nhưng không được thay đổi).

Cấu trúc (anatomy)

Một text input hiếm khi chỉ là mỗi phần tử <input> — cấu trúc đầy đủ mà một design system thường chuẩn hóa là:

1. 1
   Labeltùy chọn
2. 2
   [prefix] value [suffix]bản thân field
3. 3
   Helper text hoặc thông báo lỗi

• Label — luôn có mặt trừ các ô tìm kiếm đơn giản nhất; được liên kết qua <label for> / htmlFor, không bao giờ chỉ dựa vào placeholder.
• Field — ô có viền; có thể chứa icon prefix/suffix hoặc đơn vị ($, .com, icon tìm kiếm).
• Helper text — hướng dẫn thường trực bên dưới field (“Phải có ít nhất 8 ký tự”).
• Error message — thay thế hoặc xuất hiện cùng helper text khi validation thất bại, và phải được liên kết theo chương trình với field qua aria-describedby để trình đọc màn hình đọc lên.

Ví dụ API component

<FormField
  label="Email address"
  helperText="We'll never share your email."
  error={errors.email}
  required
>
  <Input
    type="email"
    name="email"
    value={email}
    onChange={(e) => setEmail(e.target.value)}
    placeholder="you@example.com"
    disabled={isSubmitting}
  />
</FormField>

Khi được compose lại, nó sẽ render ra đại khái:

<div class="form-field">
  <label for="email">Email address <span aria-hidden="true">*</span></label>
  <input
    id="email"
    type="email"
    name="email"
    aria-required="true"
    aria-invalid="true"
    aria-describedby="email-error email-helper"
  />
  <p id="email-helper" class="helper-text">We'll never share your email.</p>
  <p id="email-error" class="error-text" role="alert">Enter a valid email address.</p>
</div>

Lưu ý aria-describedby có thể tham chiếu nhiều ID cùng lúc (cả helper text lẫn error message), và aria-invalid="true" được đặt bất cứ khi nào error khác rỗng, độc lập với viền đỏ hiển thị — tín hiệu thị giác và tín hiệu lập trình luôn phải đi cùng nhau, nếu không người dùng bình thường sẽ thấy lỗi trong khi người dùng trình đọc màn hình không hề được thông báo.

Textarea dùng chung cấu trúc và mô hình state với Input, chỉ thêm mối quan tâm về rows / autoResize cho kích thước — nó vẫn nên nhận label, helperText, error, và disabled qua cùng một wrapper FormField để mọi component nhập text trong hệ thống trông và hoạt động nhất quán.

Khái niệm chính

Checkbox, Radio, và Switch — chọn đúng control

Ba control này đều toggle một trạng thái kiểu boolean, đó chính là lý do chúng dễ bị nhầm lẫn với nhau. Sự khác biệt nằm ở hình dạng của lựa chọn, chứ không chỉ ở style thị giác.

Khía cạnh	Checkbox	Radio	Switch
Mô hình lựa chọn	Độc lập, chọn từ không đến nhiều; hoặc một boolean đơn lẻ	Loại trừ lẫn nhau, chọn đúng một trong tập hiển thị	Độc lập, bật/tắt ngay lập tức
Kích thước nhóm điển hình	0 hoặc nhiều từ một danh sách	2+ lựa chọn, tất cả hiển thị cùng lúc	Đứng riêng lẻ, mỗi setting một cái
Khi nào thay đổi có hiệu lực	Thường khi submit form	Thường khi submit form	Ngay lập tức, không cần bước submit
Ví dụ	Danh sách “chọn tất cả các mục phù hợp”, một checkbox “Tôi đồng ý với điều khoản"	"Tốc độ giao hàng: Standard / Express / Overnight"	"Bật dark mode”, “Wi-Fi”
Khi KHÔNG nên dùng	Không dùng cho một mục đơn lẻ mà trạng thái có hiệu lực ngay (dùng Switch)	Không dùng khi chỉ có một lựa chọn, hoặc khi lựa chọn cần thay đổi ngay lập tức (dùng Switch hoặc Select nếu danh sách dài)	Không dùng khi hành động cần xác nhận, có tác dụng phụ mang tính phá hủy, hoặc là một phần của form được submit theo lô (dùng Checkbox + Submit)

Quy tắc chung: checkbox = “đánh dấu không hoặc nhiều mục trong số này” hoặc “xác nhận một sự thật/thỏa thuận đơn lẻ”; radio = “chọn đúng một, và tôi muốn thấy tất cả lựa chọn trước khi chọn”; switch = “bật/tắt một setting ngay bây giờ, không cần hành động gì thêm.”

Sai lầm phổ biến: switch cho việc cần bước xác nhận

Một lỗi sai thường gặp là đặt Switch cho một hành động thực chất có hệ quả lớn, có thể không thể hoàn tác — “Bật xác thực hai yếu tố”, “Đưa repository này thành public”, “Tự động gia hạn subscription”. Switch truyền tải “tức thì, ít rủi ro, có thể hoàn tác” hoàn toàn qua mô hình tương tác của nó (gạt nó, xong ngay, gạt lại nếu đổi ý). Nếu hành động thực tế không phải như vậy — nếu nó cần một dialog tiếp theo, gửi email, hoặc không thể dễ dàng hoàn tác — thì việc dùng Switch sẽ tạo kỳ vọng sai, và người dùng sẽ bật/tắt nó mà không nhận ra hệ quả vừa xảy ra. Trong những trường hợp này, nên ưu tiên Checkbox bên trong một form có nút Save/Confirm rõ ràng, hoặc một Switch mở ngay dialog xác nhận trước khi thực sự áp dụng thay đổi (và tự trả lại trạng thái thị giác nếu người dùng hủy).

// Ổn: tức thì, có thể hoàn tác, không có tác dụng phụ ngoài preference UI
<Switch
  checked={darkMode}
  onChange={setDarkMode}
  label="Dark mode"
/>

// Rủi ro nếu để switch trần — có hệ quả lớn và khó hoàn tác
<Switch
  checked={isPublic}
  onChange={handleTogglePublic} // kích hoạt ngay lập tức, không có xác nhận
  label="Make repository public"
/>

// Tốt hơn: switch mở bước xác nhận trước khi thực sự áp dụng
<Switch
  checked={isPublic}
  onChange={(next) => next ? openConfirmDialog() : handleTogglePublic(false)}
  label="Make repository public"
/>

Ví dụ API cho Checkbox và Radio

// Nhóm Checkbox — chọn từ không đến nhiều
<CheckboxGroup label="Notify me about" name="notifications">
  <Checkbox value="comments" label="New comments" />
  <Checkbox value="mentions" label="Mentions" defaultChecked />
  <Checkbox value="digest" label="Weekly digest" />
</CheckboxGroup>

// Checkbox đơn lẻ — một sự đồng ý dạng boolean
<Checkbox
  checked={agreed}
  onChange={(e) => setAgreed(e.target.checked)}
  label="I agree to the Terms of Service"
  required
/>

// Nhóm Radio — chọn đúng một trong tập hiển thị
<RadioGroup
  label="Shipping speed"
  name="shipping"
  value={shipping}
  onChange={setShipping}
>
  <Radio value="standard" label="Standard (5–7 days)" />
  <Radio value="express" label="Express (2–3 days)" />
  <Radio value="overnight" label="Overnight" />
</RadioGroup>

Lưu ý sự bất đối xứng trong API: CheckboxGroup chỉ là một wrapper tiện lợi cho layout và chia sẻ label/name, nhưng trạng thái checked của từng Checkbox là độc lập — bỏ chọn một cái không ảnh hưởng đến những cái khác. Ngược lại, RadioGroup sở hữu duy nhất một value/onChange cho cả nhóm, vì các lựa chọn loại trừ lẫn nhau theo định nghĩa — một Radio riêng lẻ không có trạng thái checked độc lập nào có ý nghĩa bên ngoài nhóm của nó.

Select & Dropdown

Cả hai đều cho phép người dùng chọn một giá trị (hoặc nhiều giá trị) từ một danh sách, nhưng chúng giải quyết vấn đề theo cách rất khác nhau, và lựa chọn giữa chúng là một trong những quyết định về accessibility có hệ quả lớn nhất mà một design system phải đưa ra.

<select> native:

<label for="country">Country</label>
<select id="country" name="country">
  <option value="">Select a country</option>
  <option value="vn">Vietnam</option>
  <option value="us">United States</option>
  <option value="jp">Japan</option>
</select>

Component Dropdown tùy chỉnh:

<Dropdown
  label="Country"
  value={country}
  onChange={setCountry}
  options={[
    { value: 'vn', label: 'Vietnam', icon: <FlagVN /> },
    { value: 'us', label: 'United States', icon: <FlagUS /> },
    { value: 'jp', label: 'Japan', icon: <FlagJP /> },
  ]}
  placeholder="Select a country"
  searchable
/>

Khía cạnh	<select> native	Dropdown tùy chỉnh
Accessibility	Miễn phí — điều hướng bàn phím, thông báo cho trình đọc màn hình, type-ahead đều có sẵn trong trình duyệt/hệ điều hành	Phải tự cài đặt lại bằng tay: phím mũi tên, Home/End, type-ahead, aria-expanded, aria-activedescendant hoặc roving tabindex, focus trapping
Hành vi trên mobile	Mở picker wheel/sheet native của hệ điều hành — nhanh, quen thuộc, thân thiện với ngón tay cái	Render một overlay tùy chỉnh phải tự tinh chỉnh cho touch, viewport clipping, và safe-area insets
Kiểm soát thị giác	Rất hạn chế — khó hiển thị icon, option nhiều dòng, hoặc định dạng phong phú bên trong option	Toàn quyền kiểm soát — icon, avatar, mô tả, tiêu đề nhóm, layout option tùy chỉnh
Tính năng bổ sung	Không có sẵn — không search/filter, không multi-select nếu không có mẹo markup thêm	Có thể thêm search-to-filter, multi-select với tag, option tải bất đồng bộ, gom nhóm
Chi phí triển khai	Gần như bằng không	Đáng kể — một custom dropdown đúng đắn, accessible là một trong những component khó xây dựng nhất từ đầu
Phù hợp nhất cho	Danh sách đơn giản, ngắn đến trung bình, không cần hiển thị đặc biệt (quốc gia, tiểu bang, giá trị enum thuần)	Danh sách dài cần search, option cần hiển thị phong phú, hoặc multi-select với tag hiển thị

Lựa chọn thực dụng mặc định là ưu tiên <select> native trước, và chỉ xây Dropdown tùy chỉnh khi có yêu cầu thực sự đòi hỏi (search, icon, multi-select) — và khi đó, component phải cài đặt lại đúng đắn pattern ARIA combobox/listbox, bao gồm cả hỗ trợ bàn phím, thay vì chỉ là một <div> được style đẹp mà chỉ hoạt động được với chuột.

Form như một sự kết hợp (composition)

Một form không hẳn là một component tự thân mà đúng hơn là một bài toán về layout và điều phối (orchestration) được xây trên các primitive ở trên. Hai quyết định lặp lại ở gần như mọi form:

Vị trí đặt label

Pattern	Ưu điểm	Nhược điểm	Trường hợp dùng điển hình
Label phía trên field	Dễ quét mắt, hoạt động tốt ở mọi chiều rộng field, thứ tự đọc mặc định thân thiện với accessibility nhất	Tốn nhiều không gian theo chiều dọc	Lựa chọn mặc định cho hầu hết form
Label bên cạnh field (căn trái)	Gọn theo chiều dọc, quen thuộc trong UI admin dày đặc	Cần căn chỉnh cẩn thận khi độ dài label khác nhau; khó vừa với viewport hẹp/mobile	Trang settings, panel admin dày đặc dữ liệu
Label nổi / inline	Rất gọn, hợp xu hướng	Mơ hồ khi đã điền xong, khó xử lý với giá trị điền sẵn hoặc dài, chuyển động thêm có thể ảnh hưởng người dùng nhạy cảm tiền đình	Form marketing, UI hạn chế về không gian (nên dùng dè dặt)

Trình bày lỗi: summary vs. inline

• Lỗi inline (mỗi FormField hiển thị prop error riêng ngay bên dưới field) phù hợp nhất cho form ngắn và tạo sự gần gũi tức thì giữa thông báo và field.
• Error summary ở đầu form (danh sách tất cả field lỗi kèm link nhảy đến và focus vào từng field) phù hợp nhất cho form dài, được một số hướng dẫn accessibility yêu cầu như một bổ sung (không phải thay thế) cho lỗi inline, và cho người dùng trình đọc màn hình một cái nhìn tổng quan được thông báo ngay lập tức, thay vì phải tab qua toàn bộ form để phát hiện lỗi ở đâu.

Hầu hết hệ thống trưởng thành làm cả hai: một error summary ở đầu khi submit (được thông báo qua role="alert" hoặc chuyển focus vào một vùng aria-live), cộng với lỗi inline ở mỗi field bị ảnh hưởng để cung cấp ngữ cảnh khi người dùng đến đó.

Thời điểm validation

Thời điểm	Hành vi	Đánh đổi
Chỉ khi submit	Lỗi chỉ xuất hiện sau khi người dùng cố submit	Ít gây khó chịu nhất khi đang gõ, nhưng có thể khiến người dùng bất ngờ với một loạt lỗi ở cuối
Khi blur	Field được validate khi người dùng rời khỏi nó	Điểm cân bằng tốt — phản hồi theo từng field mà không làm gián đoạn việc gõ
Live / khi thay đổi	Field được validate ở mỗi lần gõ phím	Tốt nhất cho phản hồi tức thì như độ mạnh mật khẩu hay kiểm tra username còn trống, nhưng có thể gây khó chịu nếu hiển thị “lỗi” trước khi người dùng gõ xong (ví dụ báo email không hợp lệ trước khi họ kịp gõ dấu @)

Một cách dung hòa phổ biến và đã được kiểm chứng: validate khi blur cho lần đầu tiên (để field không bị gắn cờ lỗi khi người dùng vẫn đang gõ dở), sau đó chuyển sang validate live cho field cụ thể đó một khi nó đã từng hiện lỗi — để người dùng nhận được xác nhận tức thì rằng việc sửa của họ đã đúng, mà không bị làm phiền trước khi lần thử đầu tiên kịp hoàn thành.

Best Practices

Đặt tên prop nhất quán giữa các component

Khoản đầu tư có đòn bẩy cao nhất trong API của một component library là đặt tên cùng một khái niệm theo cùng một cách ở mọi component. Nếu Button dùng size="sm" | "md" | "lg", Input cũng nên dùng đúng bộ giá trị đó — chứ không phải small/medium/large ở component này và sm/md/lg ở component khác. Tương tự với:

Prop	Ý nghĩa ở mọi nơi nó xuất hiện	Anti-pattern cần tránh
size	Cùng một thang (sm/md/lg, hoặc thang số) ở mọi component có thể đổi kích thước	Button dùng size, Input dùng inputSize
variant	Trục style thị giác/ngữ nghĩa	Trộn lẫn variant và type cho cùng một khái niệm giữa các component
disabled	Component không thể tương tác, bị loại khỏi tab order	Một component dùng isDisabled trong khi các component khác dùng disabled
error	Validation thất bại, thường nhận chính thông báo lỗi hoặc một boolean	Một component nhận string, component khác chỉ nhận boolean mà không có cách hiển thị nội dung thông báo
label	Đoạn text hiển thị, được liên kết với control	Một số component yêu cầu aria-label riêng mà không có prop label hiển thị nào cả
onChange	Kích hoạt với giá trị mới (hoặc event) mỗi khi giá trị thay đổi	Một số component chỉ kích hoạt onChange khi blur, số khác ở mỗi lần gõ phím, mà không có cách nào biết được từ API

Một bảng ngắn gọn, được xuất bản như thế này — đôi khi được gọi thẳng là “prop glossary” — nên nằm trong tài liệu của design system (xem Guideline Component & Mẫu tài liệu nếu có trong bộ kiến thức này) để mọi người đóng góp khi xây component mới sẽ tái sử dụng từ vựng sẵn có thay vì tự sáng tạo ra một bộ mới.

Controlled vs. uncontrolled component

Mọi component kiểu input trong một design system cần có một lập trường rõ ràng về việc ai sở hữu state:

• Controlled: component cha sở hữu giá trị qua value + onChange; bản thân component không giữ state nội bộ cho giá trị. Điều này cho consumer toàn quyền kiểm soát (validation, định dạng, đồng bộ với các field khác) nhưng buộc họ phải tự nối dây state cho mọi field.
• Uncontrolled: component tự quản lý state nội bộ của mình, có thể được khởi tạo bằng defaultValue, và component cha đọc giá trị khi cần (qua ref, hoặc chỉ tại thời điểm submit qua dữ liệu form). Cách này ít code hơn cho form đơn giản nhưng khó đồng bộ hơn với UI khác đang phản ứng theo cùng giá trị đó theo thời gian thực.

// Controlled — component cha điều khiển giá trị
<Input value={email} onChange={(e) => setEmail(e.target.value)} />

// Uncontrolled — component tự sở hữu state, cha đọc khi submit
<Input defaultValue="" name="email" ref={emailRef} />
// sau này: emailRef.current.value, hoặc qua FormData(formEl) khi submit

Hầu hết design system hỗ trợ cả hai để linh hoạt, phản ánh đúng cách các phần tử form HTML native hoạt động (<input value={x} onChange={...}> so với <input defaultValue={x}>), và coi một component là “controlled” hoàn toàn dựa trên việc value có được truyền vào hay không — chính là quy ước mà bản thân React sử dụng. Điều một design system cần tránh là một component controlled khi đọc (nhận value) nhưng lại âm thầm bỏ qua các cập nhật đến nó (không gọi onChange, hoặc không re-render khi value thay đổi từ bên ngoài) — đây là lỗi controlled-component phổ biến nhất và khiến component không thể dự đoán được hành vi.

Các hướng dẫn thực tế khác

• Đừng để một phần tử disabled là cách duy nhất để giải thích vì sao nó bị disabled. Kết hợp với tooltip, helper text, hoặc đoạn text đi kèm — một nút disabled không có giải thích là ngõ cụt với người dùng.
• Giữ vòng focus bật mặc định cho người dùng bàn phím ngay cả khi thiết kế chỉ có :hover trông gọn hơn với người dùng chuột; dùng :focus-visible thay vì loại bỏ outline hoàn toàn.
• Đừng suy ra ý nghĩa chỉ từ màu sắc — trạng thái lỗi không bao giờ nên chỉ dựa vào viền đỏ; kết hợp với icon và text để không thất bại với người dùng mù màu.
• Làm cho trạng thái loading an toàn trước gián đoạn — một nút loading không nên cho phép submit lần hai trong khi lần đầu đang xử lý (bảo vệ cả về thị giác lẫn bằng cách thực sự vô hiệu hóa click handler).
• Version một cách có chủ đích — vì các component này có phạm vi ảnh hưởng rộng nhất trong hệ thống, việc đổi tên prop hay thay đổi hành vi nên đi qua cùng kỷ luật deprecation/versioning được nói tới ở Versioning & Quản lý Release, thay vì thay đổi trực tiếp tại chỗ.

Tài liệu tham khảo

• roadmap.sh — Design System
• W3C ARIA Authoring Practices Guide — Button Pattern
• W3C ARIA Authoring Practices Guide — Combobox Pattern
• W3C ARIA Authoring Practices Guide — Checkbox Pattern
• W3C ARIA Authoring Practices Guide — Radio Group Pattern
• Nielsen Norman Group — Toggle-Switch Guidelines
• Nielsen Norman Group — Checkboxes vs. Radio Buttons
• Material Design 3 — Buttons
• Adele — danh sách các design system mã nguồn mở được tuyển chọn để so sánh API Button/Input trong thực tế

// Basic usage
<Button variant="primary" size="md">
  Save changes
</Button>

// Secondary action alongside it
<Button variant="secondary" size="md">
  Cancel
</Button>

// Destructive action
<Button variant="danger" size="sm" onClick={handleDelete}>
  Delete account
</Button>

// Loading state — button stays disabled while in flight
<Button variant="primary" size="md" loading disabled={isSubmitting}>
  Submit
</Button>

// Icon-only button — requires an accessible name since there's no visible label
<Button variant="ghost" size="sm" iconOnly aria-label="Close dialog">
  <CloseIcon />
</Button>

// Icon + label — icon is decorative, label carries the meaning
<Button variant="secondary" size="md" icon={<DownloadIcon />}>
  Download report
</Button>

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  iconOnly?: boolean;
  icon?: React.ReactNode;
  type?: 'button' | 'submit' | 'reset';
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  'aria-label'?: string; // required by lint rule when iconOnly is true
  children?: React.ReactNode;
}

<FormField
  label="Email address"
  helperText="We'll never share your email."
  error={errors.email}
  required
>
  <Input
    type="email"
    name="email"
    value={email}
    onChange={(e) => setEmail(e.target.value)}
    placeholder="you@example.com"
    disabled={isSubmitting}
  />
</FormField>

<div class="form-field">
  <label for="email">Email address <span aria-hidden="true">*</span></label>
  <input
    id="email"
    type="email"
    name="email"
    aria-required="true"
    aria-invalid="true"
    aria-describedby="email-error email-helper"
  />
  <p id="email-helper" class="helper-text">We'll never share your email.</p>
  <p id="email-error" class="error-text" role="alert">Enter a valid email address.</p>
</div>

// Fine: instant, reversible, no side effects beyond a UI preference
<Switch
  checked={darkMode}
  onChange={setDarkMode}
  label="Dark mode"
/>

// Risky as a bare switch — consequential and hard to reverse
<Switch
  checked={isPublic}
  onChange={handleTogglePublic} // fires immediately, no confirmation
  label="Make repository public"
/>

// Better: switch opens a confirmation step before committing
<Switch
  checked={isPublic}
  onChange={(next) => next ? openConfirmDialog() : handleTogglePublic(false)}
  label="Make repository public"
/>

// Checkbox group — zero or more selections
<CheckboxGroup label="Notify me about" name="notifications">
  <Checkbox value="comments" label="New comments" />
  <Checkbox value="mentions" label="Mentions" defaultChecked />
  <Checkbox value="digest" label="Weekly digest" />
</CheckboxGroup>

// Single standalone checkbox — a boolean agreement
<Checkbox
  checked={agreed}
  onChange={(e) => setAgreed(e.target.checked)}
  label="I agree to the Terms of Service"
  required
/>

// Radio group — exactly one of a visible set
<RadioGroup
  label="Shipping speed"
  name="shipping"
  value={shipping}
  onChange={setShipping}
>
  <Radio value="standard" label="Standard (5–7 days)" />
  <Radio value="express" label="Express (2–3 days)" />
  <Radio value="overnight" label="Overnight" />
</RadioGroup>

<label for="country">Country</label>
<select id="country" name="country">
  <option value="">Select a country</option>
  <option value="vn">Vietnam</option>
  <option value="us">United States</option>
  <option value="jp">Japan</option>
</select>

<Dropdown
  label="Country"
  value={country}
  onChange={setCountry}
  options={[
    { value: 'vn', label: 'Vietnam', icon: <FlagVN /> },
    { value: 'us', label: 'United States', icon: <FlagUS /> },
    { value: 'jp', label: 'Japan', icon: <FlagJP /> },
  ]}
  placeholder="Select a country"
  searchable
/>

// Controlled — parent drives the value
<Input value={email} onChange={(e) => setEmail(e.target.value)} />

// Uncontrolled — component owns its own state, parent reads it on submit
<Input defaultValue="" name="email" ref={emailRef} />
// later: emailRef.current.value, or via FormData(formEl) on submit