@beehexa/design-rules 0.0.0-stage → 2611.3.2

package/dist/docs/src/content-vi/foundations/styles/color/dark-mode.mdx

@@ -0,0 +1,22 @@
+---
+title: Giao diện tối
+description: Giao diện tối hoạt động thế nào, những gì thay đổi và những điều không bao giờ làm ở giao diện tối.
+order: 5
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Viết mỗi token một lần; giao diện sẽ đổi giá trị.**
+
+<ColorDemo kind="themes" />
+
+## Cách hoạt động
+
+Mỗi token màu có một giá trị sáng và một giá trị tối dưới cùng tên. Giao diện chọn giá trị; code và thiết kế của bạn chỉ gọi tên token một lần. Giá trị tối của mọi bậc trong bảng màu có ở trang [Bảng màu](/vi/foundations/styles/color/palette/), của mọi role token có ở trang [Token](/vi/foundations/styles/color/tokens/).
+
+## Thiết kế cho giao diện tối
+
+- Không tự đặt màu tối riêng, không chọn màu theo giao diện trong code.
+- Bề mặt càng nổi lên càng sáng: nền trang tối nhất, card sáng hơn một bậc.
+- Nút chính chuyển sang màu sáng, và các nền đặc của trạng thái sáng lên với chữ tối bên trên.
+- Kiểm tra mọi màn hình ở cả hai giao diện trước khi phát hành.
+- Logo dùng bản dành cho nền tối (xem [Logo](/vi/foundations/styles/logos/)).

package/dist/docs/src/content-vi/foundations/styles/color/index.mdx

@@ -0,0 +1,65 @@
+---
+title: Màu sắc
+description: Ba màu thương hiệu và một bộ token màu, mỗi token một việc, cho chữ, icon, bề mặt, nền, viền và trạng thái, ở cả giao diện sáng và tối.
+order: 1
+sidebarLabel: Tổng quan
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+Màu trong sản phẩm Beehexa chủ yếu là xám ghi và trắng. Màu vàng đánh dấu thương hiệu, bốn màu chức năng đánh dấu trạng thái. Bạn không bao giờ chọn màu theo mã màu. Bạn chọn token theo việc nó làm, như `color.text` hay `color.background.danger.bold`, và token đó đúng ở cả giao diện sáng lẫn tối.
+
+<ColorDemo kind="balance" />
+
+## Màu thương hiệu
+
+<ColorDemo kind="brand" />
+
+## Bảng màu
+
+Sáu thang màu, mỗi thang mười hai bậc, cho giao diện sáng và tối. Màu xám ghi thương hiệu là bậc graphite 12 ở giao diện sáng. Màu vàng thương hiệu là bậc yellow 7 ở giao diện sáng và yellow 11 ở giao diện tối. Xem mọi giá trị ở trang [Bảng màu](/vi/foundations/styles/color/palette/).
+
+<ColorDemo kind="ramps" />
+
+## Màu hoạt động thế nào
+
+Màu chia làm ba tầng. Bạn chỉ dùng tầng giữa.
+
+| Tầng | Ví dụ | Ai dùng |
+|---|---|---|
+| Bảng màu | `color.graphite.11` | Không ai dùng trực tiếp. Tầng này cấp giá trị cho role token. |
+| Role token | `color.text.subtle` | Mọi sản phẩm và component. |
+| Component token | `color.code.background` | Chỉ khi không có role token nào phù hợp. |
+
+Role token là token đặt tên theo vai trò của màu. Danh sách role token ở trang [Token](/vi/foundations/styles/color/tokens/). Cách chọn token ở trang [Cách dùng](/vi/foundations/styles/color/usage/).
+
+## Nguyên tắc
+
+### Xám ghi làm phần việc chính, vàng là điểm nhấn
+
+Chữ, icon, đường kẻ và nút chính đều màu xám ghi. Màu vàng chỉ dùng cho logo, vạch chỉ trang hiện tại, phần tô nổi bật và ghi chú thương hiệu. Màu vàng không bao giờ dùng cho chữ hay nút: trên nền trắng nó chỉ đạt 1.85:1.
+
+<ColorDemo kind="dodont" item="yellow" />
+
+### Màu phải có nghĩa
+
+Đỏ, cam, xanh lá và xanh dương nghĩa là nguy hiểm, cảnh báo, thành công và thông tin. Không dùng chúng để trang trí hay để gây chú ý.
+
+<ColorDemo kind="dodont" item="meaning" />
+
+### Không chỉ dựa vào màu
+
+Ghi trạng thái bằng chữ và thêm icon. Đánh dấu mục được chọn bằng một dấu hiệu thứ hai ngoài màu. Người mù màu và người dùng trình đọc màn hình không nhận được thông tin từ màu.
+
+<ColorDemo kind="dodont" item="alone" />
+
+### Dùng đúng token cho đúng việc
+
+Chỉ dùng role token. Không dùng mã hex, không dùng một bậc của thang màu như `color.graphite.11`. Nếu không có token phù hợp, hãy đề nghị thêm token mới.
+
+<ColorDemo kind="dodont" item="tokens" />
+
+### Mỗi màn hình một nút chính
+
+Nút chính màu xám ghi. Mọi nút khác là nút mặc định. Không có nút màu vàng.
+
+<ColorDemo kind="dodont" item="primary" />

package/dist/docs/src/content-vi/foundations/styles/color/palette.mdx

@@ -0,0 +1,57 @@
+---
+title: Bảng màu
+description: Mọi màu trong hệ thống, gồm sáu thang màu mười hai bậc ở giao diện sáng và tối, công dụng của từng thang, từng bậc và độ tương phản mỗi bậc bảo đảm.
+order: 3
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Bảng màu cấp giá trị cho role token. Sản phẩm dùng role token, không bao giờ dùng trực tiếp một bậc của bảng màu.**
+
+Sáu thang màu, mỗi thang mười hai bậc. Rê chuột lên một ô màu để xem tên token.
+
+<ColorDemo kind="palette" />
+
+## Công dụng của từng thang
+
+| Thang | Dùng cho | Không dùng cho |
+|---|---|---|
+| Graphite | Mọi thứ không mang nghĩa riêng: chữ, icon, đường kẻ, bề mặt, nút chính | — |
+| Yellow | Thương hiệu: logo, vạch chỉ trang hiện tại, phần tô nổi bật, ghi chú thương hiệu | Chữ, nút, cảnh báo |
+| Blue | Thông tin, link, viền focus | Trang trí |
+| Green | Thành công | Mọi việc khác |
+| Orange | Cảnh báo | Mọi việc khác |
+| Red | Nguy hiểm | Mọi việc khác |
+
+Không có tím, hồng hay xanh ngọc. Biểu đồ chưa có bảng màu riêng: hãy hỏi trước khi tô màu cho biểu đồ.
+
+## Công dụng của từng bậc
+
+**Mỗi bậc có một việc, giống nhau ở mọi thang.**
+
+<ColorDemo kind="steps" />
+
+- **Bậc 1–2:** nền trang và nền bề mặt.
+- **Bậc 3–5:** nền component khi nghỉ, khi hover và khi nhấn hoặc được chọn.
+- **Bậc 6–8:** viền và đường phân cách, từ nhạt tới đậm.
+- **Bậc 9–10:** nền đặc, như nền của nút, và màu hover của chúng.
+- **Bậc 11–12:** chữ và icon. 11 là chữ phụ, 12 là chữ mặc định.
+
+Graphite là màu của chữ trung tính, nên đầu tối của thang có ba mức chữ thay vì hai: 12 mặc định, 11 chữ phụ, 10 chữ mức ba. Bậc 9 là viền của control và bậc 8 là chữ bị vô hiệu hoá.
+
+Yellow là ngoại lệ duy nhất: nền thương hiệu của nó là bậc 7, chính là màu vàng thương hiệu, với chữ graphite bên trên. Sản phẩm không dùng màu vàng cho nền khác hay cho chữ.
+
+## Sáng và tối
+
+**Mỗi bậc có một giá trị sáng và một giá trị tối dưới cùng một tên.**
+
+`color.graphite.12` là màu chữ ở cả hai giao diện. Role token tự đổi theo giao diện, nên màn hình không bao giờ phải tự chọn màu tối. Ở giao diện tối, nền đặc (bậc 9 và 10) sáng hơn ở giao diện sáng, nên chữ trên đó là chữ tối: dùng `text.on-bold`.
+
+## Độ tương phản được bảo đảm
+
+Ở cả hai giao diện:
+
+- Ở blue, green, orange và red, chữ trên nền đặc (bậc 9 và 10) đạt 4.5:1 với `text.on-bold`: trắng ở giao diện sáng, tối ở giao diện tối.
+- Chữ bậc 11 đạt 4.5:1 trên mọi nền nó được ghép cặp.
+- Ở graphite, bậc 10, 11 và 12 đều đạt 4.5:1 khi làm chữ; bậc 9 đạt 3:1 khi làm viền của control.
+
+Xem các cặp màu ở trang [Khả năng tiếp cận](/foundations/styles/color/accessibility/).

package/dist/docs/src/content-vi/foundations/styles/color/tokens.mdx

@@ -0,0 +1,55 @@
+---
+title: Token
+description: Cách đặt tên token màu, mọi role token với giá trị ở giao diện sáng và tối, cách dùng trong code và cách đề nghị thêm token mới.
+order: 4
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Tên mỗi token màu cho biết nó tô cái gì, mang nghĩa gì, đậm nhạt ra sao và đang ở trạng thái nào.**
+
+## Cách đặt tên
+
+`color.{property}.{role}.{emphasis}.{state}`. Phần nào là mặc định thì bỏ đi.
+
+<ColorDemo kind="anatomy" />
+
+| Phần | Giá trị |
+|---|---|
+| Property (thứ được tô) | `text`, `icon`, `link`, `surface`, `background`, `border`, `skeleton` |
+| Role (vai trò) | `neutral` (bỏ đi), `brand`, `danger`, `warning`, `success`, `info`, `inverse`, `disabled`; với surface: `page`, `subtle`, `inverse`, `scrim` |
+| Emphasis (mức nhấn) | Chữ: mặc định, `subtle`, `subtlest`. Nền: `subtle`, mặc định, `bold`. Viền: mặc định, `bold` |
+| State (trạng thái) | `hover`, `pressed`, `selected`, `focus` |
+
+`color.background.danger.bold.hover` là nền đặc màu nguy hiểm khi hover. Có hai tên gọi theo nền nằm dưới chữ thay vì theo vai trò: `text.on-bold` (trên mọi nền đặc của trạng thái) và `text.on-brand` (trên màu vàng thương hiệu).
+
+Trong CSS, viết `--bh-` rồi đến tên token, thay dấu chấm bằng dấu gạch ngang: `color.text.subtle` là `var(--bh-color-text-subtle)`.
+
+Hãy dùng role token. [Bảng màu](/vi/foundations/styles/color/palette/) cấp giá trị cho role token và không bao giờ được dùng trực tiếp (xem [Màu hoạt động thế nào](/vi/foundations/styles/color/#màu-hoạt-động-thế-nào)).
+
+## Chữ và icon
+
+<ColorDemo kind="roles" group="text" />
+
+<ColorDemo kind="roles" group="icon" />
+
+## Bề mặt
+
+<ColorDemo kind="roles" group="surface" />
+
+## Nền
+
+<ColorDemo kind="roles" group="background" />
+
+## Viền
+
+<ColorDemo kind="roles" group="border" />
+
+## Thiếu token
+
+1. Xem bảng [Tìm token](/vi/foundations/styles/color/usage/#tìm-token) và danh sách bên dưới.
+2. Hỏi đội design system. Cho biết bạn cần token ở đâu, và đề xuất một tên ghép từ bốn phần, trỏ tới một bậc có đúng công dụng (nền ở bậc 3, viền ở bậc 7, chữ ở bậc 11).
+3. Đội sẽ kiểm tra độ tương phản ở cả hai giao diện rồi thêm token. Chỉ dùng token sau khi nó được phát hành.
+
+## Mọi token màu
+
+<ColorDemo kind="tokens" />

package/dist/docs/src/content-vi/foundations/styles/color/usage.mdx

@@ -0,0 +1,111 @@
+---
+title: Cách dùng
+description: Dùng token nào cho từng phần của màn hình, cách tô màu trạng thái, mức nhấn và trạng thái tương tác, và những điều không được làm.
+order: 2
+---
+import ColorDemo from '../../../../components/ColorDemo.astro';
+
+**Chọn token theo thứ bạn đang tô và ý nghĩa của nó, không chọn theo vẻ ngoài.**
+
+<ColorDemo kind="example" />
+
+## Tìm token
+
+| Tôi cần | Dùng |
+|---|---|
+| Nền trang | `surface.page` |
+| Card, panel, dialog | `surface`, viền `border` |
+| Sidebar, header của bảng, vùng nền nhạt | `surface.subtle` |
+| Chữ nội dung, tiêu đề, nhãn | `text` |
+| Mô tả, cột phụ của bảng, điều hướng | `text.subtle` |
+| Metadata, mốc thời gian, chữ hướng dẫn, breadcrumb | `text.subtlest` |
+| Placeholder | `text.subtlest` |
+| Link | `link`; khi hover `link.hover` |
+| Icon cạnh chữ | `icon`; icon ít quan trọng hơn `icon.subtle` |
+| Đường phân cách, viền card | `border` |
+| Viền của ô nhập, checkbox hoặc select | `border.bold` |
+| Viền focus khi dùng bàn phím | `border.focus`, dày 2 px, cách 2 px |
+| Nút chính | `background.neutral.bold`, `text.inverse` |
+| Nút mặc định | `surface`, `border`, `text`; khi hover `background.neutral.subtle.hover` |
+| Nút cho hành động xoá, huỷ | `background.danger.bold`, `text.on-bold` |
+| Dòng hoặc mục menu khi hover | `background.neutral.subtle.hover` |
+| Dòng, tab hoặc mục menu được chọn | `background.selected` và một dấu hiệu thứ hai |
+| Trang hiện tại trong thanh điều hướng | Vạch `border.selected`, `background.selected`, `aria-current="page"` |
+| Lỗi dưới một trường nhập | `text.danger`, `icon.danger` |
+| Banner báo trạng thái | `background.{role}.subtle`, `border.{role}.subtle`, `text`, `icon.{role}` |
+| Trạng thái trong một dòng của bảng | Một [nhãn](#nhãn) |
+| Tooltip, toast | `surface.inverse`, `text.inverse` |
+| Lớp phủ sau dialog hoặc drawer | `surface.scrim` |
+| Khung chờ khi đang tải | `skeleton`, vệt sáng `skeleton.subtle` |
+| Khối code | `code.background`, `code.text` |
+| Ghi chú thương hiệu | `background.brand.subtle`, `border.brand.subtle` |
+| Control bị vô hiệu | `background.disabled`, `text.disabled`, `border.disabled` |
+
+Không có trong bảng? Ghép tên từ bốn phần của nó (xem [Token](/vi/foundations/styles/color/tokens/)). Nếu chưa có token, hãy đề nghị thêm. Không chọn màu gần giống.
+
+## Bề mặt và nền
+
+**Bề mặt (surface) là các lớp của màn hình. Nền (background) tô cho những thứ nằm trên đó.**
+
+<ColorDemo kind="surfaces" />
+
+`surface.scrim` chỉ nằm sau dialog và drawer, một lớp duy nhất, với độ mờ riêng của nó.
+
+## Mức nhấn
+
+<ColorDemo kind="emphasis" />
+
+## Trạng thái
+
+**Mỗi trạng thái thuộc một trong năm vai trò. Chọn theo việc người dùng cần làm, và luôn nói rõ bằng chữ.**
+
+### Chọn trạng thái
+
+| Vai trò | Dùng khi | Ví dụ trong HexaSync |
+|---|---|---|
+| Thông tin (info) | Có việc đang diễn ra hoặc đáng biết; không cần làm gì. | Đang đồng bộ, đang chờ, đang nhập |
+| Thành công (success) | Đã chạy tốt. | Đã đồng bộ, đã kết nối, đã xong |
+| Cảnh báo (warning) | Đang chạy nhưng sắp cần xử lý. | Đồng bộ một phần, token hết hạn sau 3 ngày, bị giới hạn tần suất |
+| Nguy hiểm (danger) | Bị lỗi hoặc bị chặn, hoặc hành động sẽ xoá mất dữ liệu. | Lỗi, mất kết nối, xoá |
+| Trung tính (neutral) | Không có gì đang chạy và không có gì sai. | Tạm dừng, nháp, bỏ qua, lưu trữ |
+
+Cảnh báo dùng màu cam, không dùng màu vàng, vì màu vàng là màu thương hiệu. Không có mức thứ sáu; hãy nói rõ khác biệt bằng chữ ("Lỗi 3 lần").
+
+### Màu trạng thái
+
+<ColorDemo kind="status" />
+
+<ColorDemo kind="banners" />
+
+<ColorDemo kind="dodont" item="warning" />
+
+### Nhãn
+
+<ColorDemo kind="labels" />
+
+| | Nhãn | Nhãn trạng thái |
+|---|---|---|
+| Hình thức | Viền theo `border` của vai trò, chữ theo `text` của vai trò | Nền theo `bold` của vai trò, chữ và icon theo `text.on-bold` |
+| Kích thước | Cao 20 px, padding 6 px; cỡ lớn 24 px, 8 px | Cao 32 px, padding 12 px |
+| Dùng | Nhiều nhãn trên một màn hình: dòng trong bảng, tag | Một nhãn trên mỗi trang: trạng thái chính của trang đó |
+
+## Trạng thái tương tác
+
+**Thêm `.hover` hoặc `.pressed` vào token ở trạng thái nghỉ. Không dùng độ mờ (opacity) hay lớp phủ.**
+
+<ColorDemo kind="states" />
+
+| Trạng thái | Dùng |
+|---|---|
+| Hover, nhấn | Token ở trạng thái nghỉ, thêm `.hover` hoặc `.pressed` |
+| Được chọn | `background.selected` và một dấu hiệu thứ hai |
+| Focus | Viền `border.focus` dày 2 px, cách 2 px |
+| Vô hiệu | `background.disabled`, `text.disabled`, `border.disabled` |
+
+Với dòng hoặc mục menu, mỗi trạng thái cách nền thêm một bậc: hover, rồi được chọn, rồi được chọn khi hover. Dòng đang hover luôn nhạt hơn dòng được chọn, nên không bao giờ trông như đang được chọn.
+
+Xem thêm ở trang [Trạng thái tương tác](/vi/foundations/styles/interaction-states/).
+
+## Nút
+
+<ColorDemo kind="actions" />

package/dist/docs/src/content-vi/foundations/styles/data-visualization.mdx

@@ -0,0 +1,11 @@
+---
+title: "Biểu đồ dữ liệu"
+description: "Màu, chữ và quy tắc cho biểu đồ, ô KPI và các cách hiển thị dữ liệu khác."
+order: 13
+planned:
+  - "Bảng màu cho các chuỗi dữ liệu, đủ tương phản ở light và dark"
+  - "Màu trạng thái trong biểu đồ"
+  - "Các loại biểu đồ và khi nào dùng"
+  - "Trục, chú giải, tooltip và định dạng số"
+  - "Biểu đồ dễ tiếp cận: không chỉ dựa vào màu, có phần mô tả bằng chữ"
+---

package/dist/docs/src/content-vi/foundations/styles/icons/accessibility.mdx

@@ -0,0 +1,72 @@
+---
+title: Khả năng tiếp cận
+description: Icon được đặt tên hoặc giữ im lặng thế nào, vì sao nút chỉ có icon cần tooltip, và mức tương phản cùng vùng bấm icon phải đạt.
+order: 3
+---
+import IconDemo from '../../../../components/IconDemo.astro';
+
+**Icon hoặc là trang trí và bị ẩn, hoặc có tên. Icon bấm được luôn nằm trong một nút hoặc link cỡ ít nhất 24 × 24.**
+
+| Kiểm tra | Quy tắc | WCAG 2.2 |
+|---|---|---|
+| Icon trang trí | Ẩn bằng `aria-hidden="true"` | 1.1.1 |
+| Nút hoặc link chỉ có icon | Có tên (`aria-label`) và tooltip cùng nội dung | 1.1.1, 2.5.3, 4.1.2 |
+| Icon mang nghĩa | Tương phản từ 3:1 trở lên với nền | 1.4.11 |
+| Trạng thái | Viết bằng chữ, không bao giờ chỉ dùng icon hay màu | 1.4.1 |
+| Vùng bấm | Từ 24 × 24 trở lên; nút icon trong sản phẩm là 32 × 32 | 2.5.8 |
+
+## Icon trang trí
+
+**Khi có chữ đứng cạnh, icon chỉ là trang trí.** Ẩn nó đi để trình đọc màn hình chỉ đọc nhãn một lần.
+
+Lucide làm sẵn việc này: icon không có `aria-label`, `aria-labelledby`, `role` hay `title` sẽ được gắn `aria-hidden="true"`. Không thêm nhãn cho icon đã có chữ bên cạnh.
+
+<IconDemo kind="dodont" item="decorative" />
+
+## Nút chỉ có icon
+
+**Đặt tên cho nút, không đặt cho icon.** Gắn tên lên `<button>` hoặc `<a>` bằng `aria-label`. Icon bên trong vẫn ẩn.
+
+- Tên nói điều gì sẽ xảy ra: "Xoá cửa hàng", không phải "Thùng rác" hay "Icon".
+- Thêm tooltip cùng nội dung, hiện khi rê chuột và khi focus bằng bàn phím. Tooltip phải bắt đầu bằng tên của nút, để người dùng điều khiển bằng giọng nói đọc đúng những gì họ thấy (WCAG 2.5.3).
+- Chỉ dùng nút chỉ có icon cho thao tác quen thuộc. Xem [Icon và nhãn](/vi/foundations/styles/icons/usage/#icon-và-nhãn).
+
+```html
+<button type="button" aria-label="Cài đặt">
+  <svg aria-hidden="true">…</svg>
+</button>
+```
+
+<IconDemo kind="dodont" item="tooltip" />
+
+## Icon mang nghĩa đứng riêng
+
+Khi icon là dấu hiệu duy nhất của một điều gì đó, như icon trạng thái trong cột bảng hẹp, hãy đặt tên cho chính icon: `role="img"` và `aria-label="Thất bại"`. Nên ưu tiên viết trạng thái bằng chữ.
+
+## Độ tương phản
+
+**Icon mang nghĩa cần tương phản 3:1 với nền** (WCAG 1.4.11). Mọi token `color.icon.*` đều đạt 3:1 trên các nền đi kèm, ở cả giao diện sáng và tối. Icon trang trí và icon trong control bị vô hiệu không có mức tối thiểu.
+
+Xem mọi cặp màu ở [Màu sắc › Khả năng tiếp cận](/vi/foundations/styles/color/accessibility/).
+
+## Vùng bấm
+
+**Mọi thứ bấm được có cỡ ít nhất 24 × 24** (WCAG 2.5.8). Trong sản phẩm Beehexa, nút icon cỡ 32 × 32 với icon 16 px. Icon không bao giờ là thứ duy nhất để bấm.
+
+<IconDemo kind="target" />
+
+<IconDemo kind="dodont" item="target" />
+
+## Bàn phím và focus
+
+- Nút hoặc link nhận focus, không phải icon. Không thêm `tabindex` cho `<svg>`.
+- Vòng focus bao quanh toàn bộ nút 32 × 32.
+- Tooltip mở khi focus cũng như khi rê chuột, và đóng bằng phím Escape.
+
+## Danh sách kiểm tra
+
+- Mọi icon cạnh chữ đều ẩn khỏi trình đọc màn hình.
+- Mọi nút chỉ có icon đều có tên và tooltip cùng nội dung.
+- Không trạng thái nào chỉ được thể hiện bằng icon hay màu.
+- Icon mang nghĩa đạt 3:1; dùng đúng token là đã đạt.
+- Mọi icon bấm được nằm trong vùng bấm từ 24 × 24 trở lên.

package/dist/docs/src/content-vi/foundations/styles/icons/code.mdx

@@ -0,0 +1,170 @@
+---
+title: Code
+description: Sản phẩm Vue cài đặt, import, đặt cỡ, tô màu và đặt tên icon Lucide thế nào, kèm ghi chú ngắn cho React và Astro.
+order: 4
+---
+
+**Sản phẩm dùng Lucide trực tiếp. Cài gói Lucide cho framework của bạn, cố định phiên bản và import từng icon theo tên.**
+
+## Gói
+
+| Framework | Gói | Phiên bản |
+|---|---|---|
+| Vue, cho sản phẩm Beehexa | `@lucide/vue` | 1.62.0 |
+| React | `lucide-react` | 1.62.0 |
+
+Mọi sản phẩm dùng cùng phiên bản Lucide với trang này, nên icon khớp với [Thư viện](/vi/foundations/styles/icons/library/). Icon được đóng gói vào ứng dụng lúc build. Không có request nào tới CDN.
+
+## Cài đặt
+
+```bash
+npm install @lucide/vue@1.62.0 --save-exact
+```
+
+Cố định đúng phiên bản, không dùng `^` hay `~`. Phiên bản Lucide mới có thể đổi hình hoặc đổi tên icon, nên chỉ nâng phiên bản khi có chủ đích. Xem [Cập nhật Lucide](#cập-nhật-lucide).
+
+## Import
+
+Import từng icon theo tên. Tên là tên trong Thư viện viết kiểu PascalCase: `refresh-cw` thành `RefreshCw`. Chỉ những icon bạn import mới nằm trong bundle.
+
+```vue
+<script setup lang="ts">
+import { RefreshCw } from '@lucide/vue';
+</script>
+
+<template>
+  <button type="button" class="bh-button">
+    <RefreshCw :size="16" />
+    Đồng bộ ngay
+  </button>
+</template>
+```
+
+Không import cả bộ bằng `import * as`. Cách đó đưa mọi icon vào bundle.
+
+## Cỡ mặc định
+
+Lucide vẽ icon ở cỡ 24 px. Sản phẩm Beehexa mặc định dùng 16 px. Đặt một lần ở component gốc:
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { setLucideProps } from '@lucide/vue';
+
+setLucideProps({ size: 16 });
+</script>
+```
+
+Sau đó chỉ đặt `size` cho icon 20, 24 hoặc 32 px.
+
+## Props
+
+| Prop | Mặc định của Lucide | Quy tắc Beehexa |
+|---|---|---|
+| `size` | 24 | Mặc định 16. Chỉ dùng 20, 24 hoặc 32 ở chỗ trang Cách dùng cho phép. Không dùng cỡ khác. |
+| `color` | `currentColor` | Để nguyên. Đặt màu ở phần tử cha bằng token màu icon. |
+| `stroke-width` | 2 | Không đổi. |
+| `non-scaling-stroke` | `false` | Không bật. Cũng không dùng tên cũ của nó là absolute-stroke-width. |
+| `aria-label` | không có | Chỉ cho icon mang nghĩa đứng riêng, đi cùng role img. |
+
+## Cỡ
+
+Dùng prop `size`, hoặc đặt cỡ bằng CSS trên `svg`. Cả hai cách đều giữ nét đúng tỉ lệ.
+
+```vue
+<RefreshCw :size="20" />
+```
+
+## Màu
+
+```css
+.sync-status {
+  color: var(--bh-color-icon-success);
+}
+```
+
+```vue
+<span class="sync-status"><CircleCheck /> Đã đồng bộ</span>
+```
+
+## Khoảng cách
+
+Đặt khoảng cách trên control, theo cỡ của nó: 4 px (`space.050`) với icon 16 px trong control cỡ nhỏ và mặc định, 8 px (`space.100`) với icon 20 hoặc 24 px. Xem [Cách dùng › Khoảng cách](/vi/foundations/styles/icons/usage/#khoảng-cách).
+
+```css
+.bh-button {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--bh-space-050);
+}
+.bh-button.is-large {
+  gap: var(--bh-space-100);
+}
+```
+
+## Khả năng tiếp cận
+
+Lucide ẩn icon khỏi trình đọc màn hình bằng `aria-hidden="true"`, trừ khi bạn truyền prop `aria-*`, `role` hoặc `title`. Đặt tên cho nút chỉ có icon trên chính nút đó, và thêm tooltip cùng nội dung.
+
+```vue
+<a-tooltip title="Cài đặt">
+  <button type="button" class="icon-button" aria-label="Cài đặt">
+    <Settings />
+  </button>
+</a-tooltip>
+```
+
+Icon mang nghĩa đứng riêng được gắn role và nhãn, việc này cũng bỏ `aria-hidden`:
+
+```vue
+<CircleX role="img" aria-label="Thất bại" />
+```
+
+## Trong Ant Design Vue
+
+Đặt icon vào slot `icon` và thêm class `anticon`, để Ant Design Vue căn nó như icon của chính nó.
+
+```vue
+<a-button>
+  <template #icon><Plus class="anticon" /></template>
+  Thêm cửa hàng
+</a-button>
+```
+
+## React
+
+`lucide-react` có cùng icon và props, viết kiểu camelCase. Đặt cỡ mặc định một lần bằng `LucideProvider`.
+
+```tsx
+import { LucideProvider, RefreshCw } from 'lucide-react';
+
+<LucideProvider size={16}>
+  <button type="button">
+    <RefreshCw />
+    Đồng bộ ngay
+  </button>
+</LucideProvider>
+```
+
+## Astro
+
+beehexa.design dùng `@lucide/astro`. Import từng icon từ file riêng của nó để build luôn nhanh:
+
+```astro
+---
+import Search from '@lucide/astro/icons/search';
+---
+<button class="icon-button" type="button" aria-label="Tìm kiếm">
+  <Search size={20} />
+</button>
+```
+
+## Icon tự vẽ
+
+Lucide đáp ứng đủ những gì Beehexa cần hiện nay. Nếu có lúc thiếu icon, hãy vẽ trên lưới 24 px của Lucide với cùng nét và đầu nét, đặt tên kiểu kebab-case với tiền tố `bh-`, và thêm vào thư viện.
+
+## Cập nhật Lucide
+
+1. Đọc ghi chú phát hành của Lucide để biết icon nào bị đổi tên hoặc đổi hình.
+2. Kiểm tra mọi icon trong [Thao tác thường gặp](/vi/foundations/styles/icons/usage/#thao-tác-thường-gặp) vẫn còn.
+3. Nâng phiên bản đã cố định trong sản phẩm, và báo nhóm design system cập nhật Thư viện để hiện đúng các icon đó.

package/dist/docs/src/content-vi/foundations/styles/icons/index.mdx

@@ -0,0 +1,62 @@
+---
+title: Icon
+description: Sản phẩm Beehexa dùng trực tiếp Lucide, một bộ icon nét mở nguồn. Vài quy tắc về cỡ, màu, khoảng cách, nhãn và khả năng tiếp cận.
+order: 11
+sidebarLabel: Tổng quan
+---
+import IconDemo from '../../../../components/IconDemo.astro';
+
+Icon giúp người dùng lướt nhanh màn hình và nhận ra một thao tác. Trong sản phẩm Beehexa, icon không bao giờ thay cho chữ: trạng thái được viết ra, và hầu hết thao tác đều có nhãn.
+
+Beehexa dùng **[Lucide](https://lucide.dev)**: khoảng 1.900 icon nét trên lưới 24 × 24, theo giấy phép ISC. Sản phẩm import Lucide trực tiếp. Không có gói icon riêng của Beehexa. Chúng tôi chỉ thêm quy tắc sử dụng.
+
+<IconDemo kind="sizes" />
+
+## Nguyên tắc
+
+### Chữ trước
+
+Icon hỗ trợ cho nhãn. Chỉ dùng icon đứng riêng cho thao tác ai cũng biết, như đóng, tìm kiếm hoặc thêm, và luôn đặt tên cùng tooltip cho nó.
+
+### Một icon, một nghĩa
+
+Cùng một ý luôn dùng cùng một icon, trong mọi sản phẩm. Đồng bộ luôn là `refresh-cw`. Xem [thao tác thường gặp](/vi/foundations/styles/icons/usage/#thao-tác-thường-gặp).
+
+### Chỉ dùng icon nét
+
+Lucide không có icon tô đặc. Thể hiện mục đang chọn bằng nền "đã chọn" và thanh chỉ báo, không đổi sang icon khác.
+
+### Màu theo chữ
+
+Icon lấy màu của chữ bên cạnh. Chỉ dùng màu trạng thái khi chính icon đó thể hiện trạng thái.
+
+## Tóm tắt quy tắc
+
+| Quy tắc | Giá trị |
+|---|---|
+| Bộ icon | Lucide, chỉ icon nét |
+| Cỡ | 16 (mặc định), 20 (cạnh chữ 16 px, thanh công cụ), 24 (icon đứng riêng), 32 (chỉ cho trạng thái trống) |
+| Nét | Mặc định của Lucide, co giãn theo icon: 1,33 px ở cỡ 16, 1,67 ở cỡ 20, 2 ở cỡ 24 |
+| Lưới | 24 × 24, chừa ít nhất 1 đơn vị, đầu nét và góc nối bo tròn |
+| Màu | `currentColor`, với các token `color.icon.*` |
+| Cạnh chữ | Căn giữa theo dòng đầu tiên. Khoảng cách theo cỡ chữ: 4 px cạnh chữ 14 px trở xuống, 8 px cạnh chữ 16 px trở lên |
+| Nhãn | Mặc định icon đi kèm nhãn; chỉ dùng icon đứng riêng cho thao tác quen thuộc, có tên và tooltip |
+| Icon trang trí | Ẩn khỏi trình đọc màn hình (`aria-hidden="true"`) |
+| Độ tương phản | Từ 3:1 trở lên với icon mang nghĩa (WCAG 1.4.11) |
+| Vùng bấm | Từ 24 × 24 trở lên (WCAG 2.5.8); nút icon trong sản phẩm là 32 × 32 |
+| Tên | Mỗi nghĩa một tên, kebab-case, như `circle-check` |
+| Gói | Lucide cho Vue 1.62.0, cố định phiên bản, import theo tên |
+| Viết từ phải sang trái | Không cần: sản phẩm dùng tiếng Việt và tiếng Anh |
+
+## Trong mục này
+
+| Trang | Nội dung |
+|---|---|
+| [Thư viện](/vi/foundations/styles/icons/library/) | Mọi icon. Tìm, lọc và sao chép tên. |
+| [Cách dùng](/vi/foundations/styles/icons/usage/) | Cỡ, nét, màu, căn với chữ, nhãn, và icon cho từng thao tác thường gặp. |
+| [Khả năng tiếp cận](/vi/foundations/styles/icons/accessibility/) | Tên, icon trang trí, tooltip, độ tương phản và vùng bấm. |
+| [Code](/vi/foundations/styles/icons/code/) | Cài đặt, import, đặt cỡ và đặt tên icon Lucide trong Vue, kèm ghi chú cho React và Astro. |
+
+## Giấy phép
+
+Lucide thuộc © Lucide Contributors và phát hành theo [giấy phép ISC](https://lucide.dev/license). Một phần lấy từ Feather, © Cole Bemis, theo giấy phép MIT. Cả hai đều cho phép dùng thương mại. Giữ lại thông báo giấy phép khi phát hành icon. Gói Lucide đã giữ sẵn cho bạn.

package/dist/docs/src/content-vi/foundations/styles/icons/library.mdx

@@ -0,0 +1,19 @@
+---
+title: Thư viện
+description: Mọi icon Lucide Beehexa được dùng. Tìm theo tên hoặc thẻ, lọc theo nhóm, đổi cỡ và bấm vào icon để sao chép tên.
+order: 1
+---
+import IconBrowser from '../../../../components/IconBrowser.astro';
+
+**Bấm vào icon để sao chép tên.** Tên viết kiểu kebab-case, như `circle-check`. Trong Vue, icon đó là `CircleCheck`.
+
+Trước khi chọn icon, xem [Thao tác thường gặp](/vi/foundations/styles/icons/usage/#thao-tác-thường-gặp): nếu nghĩa bạn cần đã có ở đó, dùng đúng icon đó. Thư viện mở sẵn nhóm **Thao tác thường gặp**, chỉ hiện các icon này; ô tìm kiếm tìm trong toàn bộ icon, chọn **Tất cả** để xem hết. Đó là icon Lucide được chọn cho các thao tác thường gặp ở Beehexa, không cái nào bị vẽ lại hay đổi tên.
+
+<IconBrowser />
+
+## Dùng thư viện
+
+- Ô tìm kiếm khớp tên icon trước, sau đó tới các thẻ Lucide gắn cho từng icon. Gõ "sync" sẽ ra `refresh-cw`.
+- Nút đổi cỡ hiện 16, 20 và 24 px. Sản phẩm mặc định dùng 16 px.
+- Dùng bàn phím: nhấn Tab để vào lưới icon, di chuyển bằng phím mũi tên, Home và End, nhấn Enter để sao chép.
+- Không thấy icon cần tìm? Tìm theo nghĩa, không chỉ theo tên. Ghép hai icon có nghĩa riêng hiếm khi thành một icon thứ ba tốt. Xem [Icon tự vẽ](/vi/foundations/styles/icons/code/#icon-tự-vẽ).