@anhlp/alp-core 0.0.0-beta.2 → 0.0.1-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (158) hide show
  1. package/dist/backup.js +106 -4
  2. package/dist/bridges.d.ts +26 -0
  3. package/dist/bridges.js +96 -0
  4. package/dist/gate-ledger.d.ts +30 -0
  5. package/dist/gate-ledger.js +99 -0
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +2 -0
  8. package/dist/library-edit.d.ts +57 -5
  9. package/dist/library-edit.js +216 -11
  10. package/dist/library.d.ts +14 -1
  11. package/dist/library.js +73 -5
  12. package/dist/migrations.js +1 -1
  13. package/dist/models.d.ts +74 -0
  14. package/dist/models.js +67 -1
  15. package/dist/packaged.d.ts +122 -0
  16. package/dist/packaged.js +125 -0
  17. package/dist/packs.d.ts +57 -0
  18. package/dist/packs.js +247 -0
  19. package/dist/permissions.d.ts +3 -2
  20. package/dist/permissions.js +6 -3
  21. package/dist/profiles.js +6 -6
  22. package/dist/providers.d.ts +4 -5
  23. package/dist/providers.js +26 -5
  24. package/dist/skill-validate.d.ts +85 -0
  25. package/dist/skill-validate.js +298 -0
  26. package/dist/task-rows.d.ts +5 -0
  27. package/dist/task-rows.js +1 -1
  28. package/dist/tasks.d.ts +23 -4
  29. package/dist/tasks.js +103 -9
  30. package/dist/types.d.ts +3 -0
  31. package/dist/upgrade.d.ts +10 -0
  32. package/dist/upgrade.js +112 -6
  33. package/dist/user-settings.d.ts +2 -0
  34. package/dist/user-settings.js +40 -1
  35. package/dist/user-worktree.d.ts +29 -0
  36. package/dist/user-worktree.js +242 -0
  37. package/dist/validation.d.ts +1 -0
  38. package/dist/validation.js +35 -13
  39. package/package.json +34 -2
  40. package/src/backup.js +106 -5
  41. package/src/bridges.js +113 -0
  42. package/src/gate-ledger.js +125 -0
  43. package/src/index.js +1 -0
  44. package/src/library-edit.js +227 -12
  45. package/src/library.js +96 -6
  46. package/src/migrations.js +1 -1
  47. package/src/models.js +87 -1
  48. package/src/packaged.js +207 -0
  49. package/src/packs.js +246 -0
  50. package/src/permissions.d.ts +3 -2
  51. package/src/permissions.js +13 -3
  52. package/src/profiles.js +7 -7
  53. package/src/providers.js +23 -7
  54. package/src/resolver.js +1 -1
  55. package/src/skill-validate.js +287 -0
  56. package/src/task-rows.js +1 -1
  57. package/src/tasks.d.ts +23 -4
  58. package/src/tasks.js +137 -10
  59. package/src/types.d.ts +3 -0
  60. package/src/upgrade.js +54 -6
  61. package/src/user-settings.d.ts +2 -0
  62. package/src/user-settings.js +51 -1
  63. package/src/user-worktree.js +259 -0
  64. package/src/validation.d.ts +1 -0
  65. package/src/validation.js +43 -14
  66. package/templates/ALP.md +52 -52
  67. package/templates/agents/lead/AGENT.md +77 -74
  68. package/templates/agents/main/AGENT.md +153 -141
  69. package/templates/agents/oracle/AGENT.md +38 -37
  70. package/templates/agents/peer/AGENT.md +56 -52
  71. package/templates/agents/reviewer/AGENT.md +63 -65
  72. package/templates/agents/supervisor/AGENT.md +63 -63
  73. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  74. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  75. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  76. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  77. package/templates/packs/architecture/pack.json +7 -0
  78. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  79. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  80. package/templates/packs/backend/pack.json +6 -0
  81. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  82. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  83. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  84. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  85. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  86. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  87. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  88. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  89. package/templates/packs/design/pack.json +6 -0
  90. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  91. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  92. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  93. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  94. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  95. package/templates/packs/frontend/pack.json +6 -0
  96. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  97. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  98. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  99. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  100. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  101. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  102. package/templates/packs/integration/pack.json +6 -0
  103. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  104. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  105. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  106. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  107. package/templates/packs/operations/pack.json +6 -0
  108. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  109. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  110. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  111. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  112. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  113. package/templates/packs/quality/pack.json +6 -0
  114. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  115. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  116. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  117. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  118. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  119. package/templates/role-skills.json +4 -4
  120. package/templates/skills/architecture-docs/SKILL.md +81 -0
  121. package/templates/skills/architecture-docs/references/adr.md +62 -0
  122. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  123. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  124. package/templates/skills/bug-loop/SKILL.md +41 -40
  125. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  126. package/templates/skills/compact/SKILL.md +34 -0
  127. package/templates/skills/curate/SKILL.md +36 -0
  128. package/templates/skills/feature-architecture/SKILL.md +90 -0
  129. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  130. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  131. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  132. package/templates/skills/goal-griller/SKILL.md +27 -27
  133. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  134. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  135. package/templates/skills/release-readiness/SKILL.md +83 -0
  136. package/templates/skills/release-readiness/references/checklist.md +40 -0
  137. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  138. package/templates/skills/safe-refactor/SKILL.md +84 -0
  139. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  140. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  141. package/templates/skills/security-review/SKILL.md +87 -0
  142. package/templates/skills/security-review/references/checklist.md +74 -0
  143. package/templates/skills/security-review/references/severity.md +61 -0
  144. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  145. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  146. package/templates/skills/skill-authoring/SKILL.md +84 -0
  147. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  148. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  149. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  150. package/templates/skills/smart-commits/SKILL.md +37 -36
  151. package/templates/skills/test-strategy/SKILL.md +83 -0
  152. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  153. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  154. package/templates/skills/xia/SKILL.md +40 -38
  155. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  156. package/templates/teams/cafe/team.json +1 -1
  157. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  158. package/templates/teams/pho/team.json +1 -1
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: ui-design
3
+ description: "Ra quyết định và review thiết kế UI/UX: layout, typography, màu và token, trạng thái tương tác, hành vi responsive và tính nhất quán với design system. Dùng khi thiết kế hình thức của một màn hình hay component, định nghĩa token, hoặc review UI theo chuẩn khả dụng và accessibility. Không dùng để viết code component (frontend-development) hay viết nội dung."
4
+ ---
5
+
6
+ # Ra quyết định và review thiết kế UI
7
+
8
+ ## Khi nào dùng
9
+
10
+ - Một màn hình, luồng hay component cần quyết định về layout, thứ bậc, khoảng cách hoặc kiểu chữ.
11
+ - Màu, khoảng cách, bán kính, đổ bóng hoặc kiểu chữ cần thành token, hoặc token cần biến thể sáng/tối.
12
+ - Một thiết kế cần đặc tả trạng thái tương tác: hover, focus, active, disabled, loading, rỗng, lỗi.
13
+ - UI đang có cần được review về khả dụng, accessibility và tính nhất quán với design system.
14
+ - Hành vi responsive theo chiều rộng, cách nhập liệu hoặc mức zoom chưa được quyết hoặc đang sai.
15
+
16
+ ## Không dùng cho
17
+
18
+ - Viết hay refactor code component, hạ tầng styling hoặc quản lý state: frontend-development.
19
+ - Nội dung marketing hoặc đặt tên sản phẩm.
20
+ - Nhận diện thương hiệu, logo hoặc sản xuất hình minh họa.
21
+ - Tối ưu hiệu năng render: dùng quy trình profiling của dự án.
22
+
23
+ ## Điều kiện tiên quyết
24
+
25
+ - Việc được giao (assignment) nêu rõ bề mặt (màn hình, component, luồng) và ai dùng nó trên thiết bị nào.
26
+ - Đọc ALP.md và design system đang có của dự án: file token, config theme, thư viện component,
27
+ style guide, ảnh chụp hoặc file thiết kế đã có trong repository.
28
+ - Biết cơ chế styling của stack (CSS variable, utility class, theme object, native style) qua
29
+ manifest và config, không phải qua tên thư mục.
30
+
31
+ ## Quy trình
32
+
33
+ 1. Kiểm kê những gì đã có. Tìm token, component và pattern hiện tại đã giải quyết được một phần
34
+ vấn đề. Ghi lại bạn đã tìm ở đâu trước khi nói là thiếu một thứ gì.
35
+ 2. Nêu tác vụ người dùng mà bề mặt này phục vụ và một hành động chính duy nhất cho mỗi view. Thiết kế
36
+ thứ bậc quanh hành động đó; hạ bậc mọi thứ còn lại.
37
+ 3. Quyết định layout và kiểu chữ từ thang đo đang có. Dùng thang khoảng cách và thang chữ của dự án;
38
+ chỉ thêm một bậc khi không bậc nào vừa, và nói rõ vì sao.
39
+ 4. Quyết định màu qua token, không bao giờ dùng giá trị thô trong component. Map token semantic (surface,
40
+ text, border, accent, danger) sang palette nguyên thủy cho cả theme sáng và tối, và kiểm tra tương phản.
41
+ 5. Đặc tả mọi trạng thái tương tác cho từng phần tử tương tác được, gồm cả focus bàn phím,
42
+ loading, rỗng và lỗi. Đặc tả chuyển động kèm một phương án giảm chuyển động.
43
+ 6. Đặc tả hành vi responsive: cái gì reflow, co lại, ẩn đi hoặc đổi thứ tự ở mỗi breakpoint,
44
+ và layout hoạt động thế nào ở zoom 200% và trên thiết bị cảm ứng.
45
+ 7. Viết quyết định thành một spec ngắn: token đã dùng hoặc thêm, layout theo từng breakpoint, bảng
46
+ trạng thái, ghi chú accessibility, và các câu hỏi còn mở. Giao phần cài đặt cho role triển khai.
47
+ 8. Khi review, dùng checklist review, xếp các phát hiện theo mức nghiêm trọng và dẫn bằng chứng
48
+ (file và dòng, ảnh chụp, tỉ lệ tương phản đo được) cho từng cái.
49
+
50
+ ## Ràng buộc
51
+
52
+ - Trước hết hãy tuân theo design system, stack và quy ước đang có của dự án. Chỉ đề xuất token,
53
+ component hay pattern mới khi cái đang có không đáp ứng được, và nêu rõ nó thay thế cái gì.
54
+ - Không thêm thư viện UI, bộ icon, dịch vụ font hoặc phụ thuộc công cụ thiết kế mà không có
55
+ quyết định của chủ sở hữu. Không tự động cài.
56
+ - Không tải dữ liệu thiết kế, font hay ảnh từ xa. Chỉ làm với những gì có trong repository và brief.
57
+ - Agent chỉ đọc (oracle, reviewer, architect) dừng ở spec hoặc các phát hiện; chúng không sửa file.
58
+ - Accessibility là yêu cầu, không phải bước làm đẹp: tương phản WCAG 2.2 AA, focus thấy được,
59
+ kích thước đích, và không có thông tin nào chỉ truyền tải bằng màu.
60
+ - Skill không cấp thẩm quyền: quyết định thiếu về sản phẩm hay thương hiệu chuyển lên main và người dùng.
61
+
62
+ ## Kiểm chứng
63
+
64
+ - Mọi cặp màu trong spec đều có tỉ lệ tương phản được nêu và đạt ngưỡng của nó ở cả hai theme.
65
+ - Mọi phần tử tương tác được đều có đủ các trạng thái áp dụng được, gồm cả focus và disabled.
66
+ - Layout được mô tả tại các breakpoint của dự án và ở zoom 200% mà nội dung chữ không bị cuộn
67
+ ngang.
68
+ - Token mới theo đúng lược đồ đặt tên đang có và có giá trị cho cả hai theme.
69
+ - Mỗi phát hiện khi review đều có mức nghiêm trọng, vị trí, bằng chứng và một cách sửa cụ thể.
70
+
71
+ ## Xử lý khi thất bại
72
+
73
+ - Chưa có design system: đề xuất một bộ token tối thiểu suy ra từ các giá trị đã dùng trong code,
74
+ và đánh dấu nó là một quyết định cho chủ sở hữu thay vì tự nghĩ ra cả một hệ thống.
75
+ - Đang dùng những pattern xung đột nhau: liệt kê kèm vị trí và khuyến nghị một cái; không
76
+ im lặng tự chọn.
77
+ - Màu thương hiệu không đạt tương phản: giữ giá trị thương hiệu cho phần trang trí và đề xuất một
78
+ biến thể đã điều chỉnh, đạt accessibility, cho chữ và control; chuyển lựa chọn lên trên.
79
+ - Chưa rõ thiết bị hay người dùng mục tiêu: nêu giả định đó trong spec và đánh dấu là còn mở.
80
+
81
+ ## Tài liệu tham chiếu
82
+
83
+ - [references/design-tokens.md](references/design-tokens.md) — đọc khi định nghĩa, đặt tên hay tạo theme cho token, hoặc kiểm tra tương phản ở bước 4.
84
+ - [references/layout-and-typography.md](references/layout-and-typography.md) — đọc khi chọn grid, khoảng cách, thang chữ hay breakpoint ở bước 3 và 6.
85
+ - [references/interaction-states.md](references/interaction-states.md) — đọc khi đặc tả trạng thái hoặc chuyển động ở bước 5.
86
+ - [references/ui-review.md](references/ui-review.md) — đọc khi review UI đang có ở bước 8.
@@ -0,0 +1,67 @@
1
+ # Design token
2
+
3
+ Đọc khi định nghĩa, đặt tên hay tạo theme cho token, hoặc khi kiểm tra tương phản màu.
4
+
5
+ ## Các tầng
6
+
7
+ 1. **Nguyên thủy** (palette và thang đo thô): `color-blue-600`, `space-4`, `radius-2`, `font-size-3`.
8
+ Đặt tên theo đúng bản chất của chúng. Không bao giờ dùng trực tiếp trong component.
9
+ 2. **Semantic** (vai trò): `color-text-primary`, `color-surface-raised`, `color-border-subtle`,
10
+ `color-accent`, `color-danger`, `space-inset-md`. Đặt tên theo việc chúng làm. Các theme map
11
+ những token này sang các giá trị nguyên thủy khác nhau.
12
+ 3. **Component** (không bắt buộc, chỉ khi một component lệch khỏi chuẩn): `button-primary-bg`,
13
+ `input-border-focus`. Trỏ vào token semantic. Thêm dè dặt; mỗi cái là một nhánh rẽ.
14
+
15
+ Component chỉ tiêu thụ token semantic hoặc token component. Đổi một theme đáng ra chỉ cần
16
+ sửa các map semantic, không phải sửa code component.
17
+
18
+ ## Đặt tên
19
+
20
+ - Theo lược đồ đã có trong dự án. Nếu chưa có: `category-role-variant-state`, chữ thường,
21
+ nối bằng gạch ngang, ví dụ `color-text-secondary`, `color-accent-hover`.
22
+ - Tên mô tả vai trò, không mô tả giá trị: `color-danger`, không phải `color-red`; `space-stack-lg`,
23
+ không phải `space-24` ở tầng semantic.
24
+ - Giữ thang đo theo thứ tự và chịu được khoảng trống (`100`..`900`, hoặc `1`..`8`) để chèn thêm bậc.
25
+ - Một nguồn chân lý duy nhất. Nếu token tồn tại ở nhiều định dạng (CSS variable, theme object, hằng
26
+ số native), hãy sinh ra hoặc đồng bộ từ một file chứ không sửa tay từng cái.
27
+
28
+ ## Sáng và tối
29
+
30
+ - Định nghĩa mọi màu semantic cho cả hai theme. Một token thiếu giá trị tối là một lỗi.
31
+ - Theme tối không phải theme sáng đảo ngược: dùng surface trung tính tối thay vì đen tuyệt đối,
32
+ nâng độ cao bằng surface sáng hơn thay vì bóng đậm hơn, và giảm độ bão hòa của những vùng
33
+ accent lớn.
34
+ - Tôn trọng tùy chọn của nền tảng (`prefers-color-scheme` hoặc tương đương native) và cho phép
35
+ ghi đè tường minh nếu sản phẩm đã có sẵn lựa chọn đó.
36
+ - Kiểm tra ảnh, hình minh họa, biểu đồ và vòng focus ở cả hai theme, không chỉ riêng chữ.
37
+
38
+ ## Ngưỡng tương phản (WCAG 2.2)
39
+
40
+ | Cặp màu | Tối thiểu AA | AAA |
41
+ |---|---|---|
42
+ | Chữ nội dung so với nền | 4.5:1 | 7:1 |
43
+ | Chữ lớn (24px+, hoặc 18.66px+ in đậm) | 3:1 | 4.5:1 |
44
+ | Đường biên component UI, icon mang nghĩa | 3:1 | - |
45
+ | Chỉ báo focus so với các màu kề nó | 3:1 | - |
46
+ | Control bị disabled, phần trang trí thuần túy | miễn | - |
47
+
48
+ - Tính tỉ lệ từ độ sáng tương đối của hai màu sRGB:
49
+ `(L1 + 0.05) / (L2 + 0.05)` với L1 là màu sáng hơn. Ghi lại con số, không ghi "trông ổn".
50
+ - Kiểm tra chữ trên mọi surface nó có thể xuất hiện (nền cơ sở, nền nổi, overlay, dòng được chọn, hover).
51
+ - Chữ placeholder vẫn là chữ: nó cần 4.5:1, hoặc nó không nên chứa hướng dẫn.
52
+ - Màu bán trong suốt: tính dựa trên nền thực tế sau khi ghép lớp.
53
+ - Không bao giờ truyền tải trạng thái chỉ bằng màu; luôn kèm chữ, icon, hình dạng hoặc vị trí.
54
+
55
+ ## Các loại token khác
56
+
57
+ - Khoảng cách: một đơn vị cơ sở (thường là 4 hoặc 8) và một thang ngắn; xem layout-and-typography.md.
58
+ - Bán kính: 3-5 bậc cộng thêm `full`. Phần tử lồng trong dùng bán kính nhỏ hơn phần tử chứa nó.
59
+ - Độ cao: vài mức có tên, map đổ bóng và màu surface cùng với nhau.
60
+ - Chuyển động: token thời lượng (`fast`, `base`, `slow`) và token easing; xem interaction-states.md.
61
+ - Z-index: một tập có tên và có thứ tự (`dropdown`, `sticky`, `overlay`, `modal`, `toast`) thay cho
62
+ các con số đặt tùy hứng.
63
+
64
+ ## Spec đầu ra cho một thay đổi token
65
+
66
+ Liệt kê từng token: tầng, tên, giá trị sáng, giá trị tối, tương phản với các surface đi kèm,
67
+ và nó thay thế những giá trị hard-code nào đang có (file và dòng).
@@ -0,0 +1,73 @@
1
+ # Trạng thái tương tác và chuyển động
2
+
3
+ Đọc khi đặc tả trạng thái cho các phần tử tương tác được hoặc cho view, hoặc khi định nghĩa chuyển động.
4
+
5
+ ## Trạng thái của control
6
+
7
+ Đặc tả từng trạng thái áp dụng được cho mọi phần tử tương tác được. Đầu ra mong đợi là một
8
+ bảng trạng thái cho mỗi component.
9
+
10
+ | Trạng thái | Mục đích | Yêu cầu |
11
+ |---|---|---|
12
+ | Default | Hình thức khi nghỉ | Nhận ra được là tương tác được mà không cần hover |
13
+ | Hover | Gợi ý cho con trỏ | Thay đổi nhẹ; không bao giờ là tín hiệu duy nhất; không cần trên cảm ứng |
14
+ | Focus-visible | Vị trí bàn phím | Chỉ báo thấy được, 3:1 so với màu kề, không bị nội dung sticky che |
15
+ | Active / được nhấn | Phản hồi khi nhấn | Tức thì; khác biệt với hover |
16
+ | Selected / checked | Lựa chọn còn lưu lại | Không chỉ bằng màu; dùng dấu check, tô nền, độ dày hoặc chữ |
17
+ | Disabled | Hiện không dùng được | Giải thích vì sao nếu có thể; cân nhắc bật kèm thông báo |
18
+ | Chỉ đọc | Thấy được, không sửa được | Vẫn focus được và copy được |
19
+ | Loading / đang xử lý | Hành động đang diễn ra | Chặn submit hai lần; giữ kích thước ổn định; thông báo cho công nghệ trợ giúp |
20
+ | Invalid / lỗi | Dữ liệu nhập bị từ chối | Thông báo cạnh field, chữ kèm icon, chỉ ra cách sửa |
21
+ | Success | Hành động đã được xác nhận | Ngắn, không chặn, có thông báo |
22
+
23
+ Ghi chú:
24
+
25
+ - Không bao giờ bỏ viền focus mà không có thứ thay thế thấy được.
26
+ - Thứ tự focus theo thứ tự đọc; modal giữ focus bên trong và trả nó lại khi đóng.
27
+ - Nút disabled không focus được trên nhiều stack, nên người dùng không thể biết vì sao nó bị
28
+ disabled. Nên giải thích yêu cầu còn thiếu ngay cạnh control.
29
+ - Giữ vùng bấm ổn định qua các trạng thái; một spinner không được làm nút đổi kích thước.
30
+
31
+ ## Trạng thái của view
32
+
33
+ Mọi view dựa trên dữ liệu đều cần thiết kế những trạng thái sau, không chỉ trạng thái có dữ liệu:
34
+
35
+ - **Loading lần đầu:** skeleton khớp layout cuối cho các chờ ngắn; spinner kèm nhãn cho những
36
+ hình dạng chưa biết. Tránh nháy loader với phản hồi rất nhanh (hoãn hiện nó một chút).
37
+ - **Rỗng (lần dùng đầu):** giải thích cái gì sẽ xuất hiện và mời hành động chính để tạo nó.
38
+ - **Rỗng (không có kết quả):** nói rõ filter hay truy vấn không ra gì; mời xóa nó đi.
39
+ - **Một phần:** một phần dữ liệu đã tải, một phần lỗi; hiện cái có và đánh dấu phần thiếu.
40
+ - **Lỗi:** nguyên nhân bằng lời thường, người dùng có thể làm gì (thử lại, kiểm tra kết nối, liên hệ),
41
+ và giữ lại dữ liệu người dùng đã nhập. Không hiện stack trace thô.
42
+ - **Offline / dữ liệu cũ:** cho biết dữ liệu cũ cỡ nào và khi nào sẽ làm mới, nếu sản phẩm hỗ trợ.
43
+ - **Bị từ chối quyền:** nói rõ là thiếu quyền truy cập và ai có thể cấp, mà không để lộ nội dung.
44
+ - **Tràn:** tên dài, nhiều mục, số lớn, ảnh bị thiếu.
45
+
46
+ ## Thời điểm phản hồi
47
+
48
+ - Dưới ~100ms: cảm giác tức thì, không cần chỉ báo.
49
+ - ~100ms đến 1s: hiện một chỉ báo nhẹ trên chính control đó.
50
+ - Trên ~1s: hiện tiến trình hoặc trạng thái loading cho cả vùng.
51
+ - Trên ~10s: hiện tiến trình xác định nếu có thể và cho phép hủy hoặc chạy nền.
52
+ - Cập nhật lạc quan cần một đường thoát khi lỗi, thấy được và đảo lại được.
53
+
54
+ ## Chuyển động
55
+
56
+ - Mục đích trước đã: chuyển động giải thích thay đổi không gian, tính liên tục hoặc phản hồi. Bỏ các
57
+ chuyển động trang trí không phục vụ điều nào trong số đó.
58
+ - Thời lượng: khoảng 100-200ms cho control nhỏ, 200-300ms cho panel và overlay, ít khi
59
+ trên 400ms. Lúc ra hơi nhanh hơn lúc vào.
60
+ - Easing: ease-out khi vào, ease-in khi ra, ease-in-out chuẩn khi di chuyển trên màn hình.
61
+ Dùng token chuyển động của dự án.
62
+ - Hoạt họa opacity và transform; tránh hoạt họa các thuộc tính layout gây reflow.
63
+ - **Giảm chuyển động:** khi người dùng yêu cầu giảm chuyển động (`prefers-reduced-motion` hoặc
64
+ thiết lập native), hãy thay chuyển động, parallax, zoom và hoạt họa tự chạy bằng một thay đổi
65
+ tức thì hoặc một crossfade ngắn. Nêu biến thể giảm đó trong spec cho từng hoạt họa.
66
+ - Không nội dung nào nháy quá ba lần mỗi giây.
67
+ - Nội dung tự chạy hoặc đang chuyển động kéo dài trên 5 giây cần có pause, stop hoặc hide.
68
+
69
+ ## Thông báo
70
+
71
+ - Thay đổi trạng thái (đã lưu, loading xong, lỗi sau khi submit) được thông báo qua cơ chế live-region
72
+ hoặc cơ chế thông báo accessibility của stack, ở mức lịch sự trừ khi gấp.
73
+ - Sau khi submit form mà có lỗi, chuyển focus tới bản tóm tắt lỗi hoặc field không hợp lệ đầu tiên.
@@ -0,0 +1,71 @@
1
+ # Layout và typography
2
+
3
+ Đọc khi chọn grid, khoảng cách, thang chữ, độ dài dòng hoặc breakpoint responsive.
4
+
5
+ ## Thang khoảng cách
6
+
7
+ - Một đơn vị cơ sở, thường là 4px hoặc 8px. Ví dụ thang: 4, 8, 12, 16, 24, 32, 48, 64, 96.
8
+ - Dùng thang đang có. Giá trị lệch thang (13px, 22px) là một phát hiện (finding) khi review, trừ khi
9
+ nó đến từ một chỉnh sửa thị giác đã được ghi lại.
10
+ - Sự gần nhau thể hiện việc nhóm: khoảng cách trong một nhóm nhỏ hơn khoảng cách giữa các nhóm.
11
+ Tỉ lệ thường dùng là 1:2 (ví dụ 8 bên trong, 16 ở giữa; 16 bên trong, 32 giữa các mục lớn).
12
+ - Ưu tiên gap của layout trên container hơn margin trên phần tử con; nó tránh khoảng cách bị gộp hay nhân đôi.
13
+
14
+ ## Grid
15
+
16
+ - Trang nội dung: một cột căn giữa có chiều rộng tối đa, hoặc grid 12 cột với gutter cố định
17
+ (16-32px) và lề ngoài co lại trên màn hình nhỏ (16px là mức tối thiểu thường dùng).
18
+ - Khung ứng dụng: thanh điều hướng rộng cố định, vùng chính linh động, pane chi tiết tùy chọn. Hãy quyết
19
+ pane nào co lại trước khi chiều rộng hẹp dần.
20
+ - Căn theo một số ít đường biên dọc. Mỗi đường biên thêm vào là thêm nhiễu thị giác.
21
+ - Dữ liệu dày (bảng, dashboard) có thể dùng thang chặt hơn, nhưng giữ nó nhất quán trong một view.
22
+
23
+ ## Thang chữ
24
+
25
+ - Dùng thang theo module (tỉ lệ khoảng 1.2-1.25 cho ứng dụng, tới 1.333 cho dạng báo chí) hoặc
26
+ các bậc đã có của dự án. 5-7 cỡ là đủ cho phần lớn sản phẩm.
27
+ - Chữ nội dung: mặc định 16px trên web; không bao giờ dưới 14px cho chữ nội dung, 12px chỉ dành cho
28
+ nhãn phụ với tương phản đủ.
29
+ - Dùng `rem` (hoặc đơn vị co giãn được của nền tảng) để chữ đi theo thiết lập cỡ chữ của người dùng.
30
+ - Chiều cao dòng: khoảng 1.4-1.6 cho nội dung, 1.1-1.3 cho tiêu đề. Chữ lớn hơn cần ít hơn.
31
+ - Độ dày: hai hoặc ba mức (regular, medium hoặc semibold, bold). Thứ bậc đến từ cỡ,
32
+ độ dày và màu cùng nhau, không phải từ nhiều độ dày.
33
+ - Giới hạn một hoặc hai họ chữ, tốt nhất là họ dự án đã tải sẵn; thêm một font
34
+ là một quyết định về phụ thuộc, thuộc về chủ sở hữu.
35
+ - Dùng chữ số dạng bảng cho các cột số và bộ đếm thời gian.
36
+
37
+ ## Độ dài dòng và tính dễ đọc
38
+
39
+ - Chiều dài dòng nội dung: khoảng 45-75 ký tự mỗi dòng; chặn container văn bản (ví dụ `max-width: 65ch`).
40
+ - Căn lề trái cho chữ nội dung ở ngôn ngữ viết trái sang phải; tránh chữ căn đều hai bên trên web.
41
+ - Khoảng cách giữa các đoạn xấp xỉ bằng chiều cao dòng.
42
+ - Tính trước việc chữ dài ra: bản dịch có thể dài hơn 30-40%; tránh nhãn có chiều rộng cố định.
43
+ - Hỗ trợ viết phải sang trái bằng các thuộc tính logic (start/end) ở nơi stack cho phép.
44
+
45
+ ## Checklist thứ bậc cho mỗi view
46
+
47
+ - Một hành động chính rõ ràng; hành động phụ yếu hơn về thị giác; hành động phá hủy để tách riêng.
48
+ - Tiêu đề trang là chữ lớn nhất trong vùng nội dung.
49
+ - Các control liên quan đặt cạnh nhau; nhãn đặt cạnh input của nó (đặt trên với form trên màn hình hẹp).
50
+ - Đường quét mắt: tiêu đề và giá trị quan trọng đọc được khi nhìn nhanh mà không đọc phần nội dung.
51
+
52
+ ## Hành vi responsive
53
+
54
+ - Dùng breakpoint của dự án. Nếu chưa có, hãy bắt đầu từ nội dung: thêm breakpoint ở nơi
55
+ layout bị vỡ, không phải ở các chiều rộng thiết bị. Các mốc tham chiếu thường gặp: ~640, ~768, ~1024, ~1280px.
56
+ - Thiết kế cho màn hình nhỏ trước; rồi nâng cấp cho màn hình rộng hơn.
57
+ - Với mỗi component hãy quyết: reflow, xếp dọc, co lại (vào menu hoặc phần mở ra), cắt bớt
58
+ (vẫn truy cập được giá trị đầy đủ), hoặc ẩn (chỉ khi không thiết yếu và có ở nơi khác).
59
+ - Ưu tiên quy tắc theo container cho những component dùng lại trong các pane rộng khác nhau, khi
60
+ stack hỗ trợ.
61
+ - Reflow: ở chiều rộng 320 CSS px (tương đương 1280px ở zoom 400%), nội dung không được cần
62
+ cuộn theo hai chiều, trừ bảng dữ liệu, bản đồ và những thứ tương tự.
63
+ - Cảm ứng: đích ít nhất 24x24 CSS px (WCAG 2.2 AA), khuyến nghị 44x44 cho hành động cảm ứng chính,
64
+ và có khoảng cách giữa các đích kề nhau.
65
+ - Không dựa vào hover cho thông tin thiết yếu trên thiết bị cảm ứng.
66
+ - Tôn trọng vùng an toàn và bàn phím trên màn hình ở mobile; giữ các hành động chính trong tầm với.
67
+
68
+ ## Spec đầu ra
69
+
70
+ Với mỗi breakpoint: grid/số cột, những vùng nào hiện ra, thay đổi thứ tự, các cỡ chữ thay đổi,
71
+ và những component đổi hình thức. Ghi chú hành vi ở zoom 200% và ở chiều rộng hẹp nhất được hỗ trợ.
@@ -0,0 +1,83 @@
1
+ # Review UI
2
+
3
+ Đọc khi review một màn hình, component hay spec thiết kế đang có về mức khả dụng,
4
+ accessibility và tính nhất quán với design system.
5
+
6
+ ## Phạm vi và cách làm
7
+
8
+ - Review bề mặt được nêu trong việc được giao (assignment). Không mở rộng ra toàn bộ ứng dụng.
9
+ - Dùng bằng chứng có sẵn: source (markup, style, token), ảnh chụp, file thiết kế trong repo,
10
+ và chạy ứng dụng cục bộ nếu lệnh chạy của dự án có sẵn và được phép.
11
+ - Kiểm tra chỉ bằng bàn phím, ở chiều rộng hẹp, ở zoom 200%, và trong từng theme được hỗ trợ khi bạn
12
+ chạy được UI. Nếu không chạy được, hãy nói rõ và review từ source; đánh dấu những mục chỉ kiểm được
13
+ khi chạy là chưa kiểm chứng.
14
+ - Reviewer chỉ đọc thì báo các phát hiện; họ không sửa file.
15
+
16
+ ## Checklist
17
+
18
+ Thứ bậc và layout
19
+ - Một hành động chính cho mỗi view; hành động phá hủy tách riêng và có xác nhận hoặc hoàn tác được.
20
+ - Khoảng cách và kích thước lấy từ thang đo của dự án; không có giá trị lệch thang lạc vào.
21
+ - Căn theo một tập nhỏ các đường biên; mật độ nhất quán trong một view.
22
+
23
+ Typography
24
+ - Chữ nội dung đọc được (cỡ, chiều cao dòng, chiều dài dòng); chữ co giãn theo thiết lập người dùng.
25
+ - Cấp tiêu đề theo cấu trúc, không chỉ theo cỡ thị giác.
26
+
27
+ Màu và token
28
+ - Component dùng token semantic, không dùng giá trị thô.
29
+ - Tương phản của chữ và UI đạt ngưỡng trong mọi theme và trên mọi surface được dùng.
30
+ - Không có ý nghĩa nào chỉ truyền tải bằng màu.
31
+
32
+ Trạng thái
33
+ - Có hover, focus-visible, active, disabled, loading, lỗi, rỗng ở nơi áp dụng được.
34
+ - Focus thấy được trên mọi phần tử tương tác được; thứ tự focus hợp lý; focus được trả lại sau overlay.
35
+
36
+ Form
37
+ - Mọi input đều có nhãn thấy được và gắn kết được bằng chương trình; placeholder không phải là nhãn.
38
+ - Lỗi phải cụ thể, nằm cạnh field, và giữ lại dữ liệu người dùng đã nhập.
39
+ - Field bắt buộc được đánh dấu; loại input và gợi ý autocomplete phù hợp với dữ liệu.
40
+
41
+ Ngữ nghĩa accessibility
42
+ - Dùng phần tử native theo đúng vai trò của chúng (button, link, input) trước khi dùng vai trò tự tạo.
43
+ - Ảnh có chữ thay thế mang nghĩa hoặc được đánh dấu là trang trí.
44
+ - Control chỉ có icon thì có tên truy cập được.
45
+ - Kích thước đích ít nhất 24x24 CSS px; nội dung dùng được ở chiều rộng 320 CSS px.
46
+ - Tùy chọn giảm chuyển động được tôn trọng.
47
+
48
+ Tính nhất quán
49
+ - Cùng một pattern cho cùng một việc trên khắp sản phẩm (dialog, toast, bảng, trạng thái rỗng).
50
+ - Dùng lại component đang có thay vì tạo bản gần giống.
51
+ - Câu chữ và thuật ngữ nhất quán với phần còn lại của sản phẩm.
52
+
53
+ ## Mức nghiêm trọng
54
+
55
+ | Mức | Nghĩa | Ví dụ |
56
+ |---|---|---|
57
+ | Blocker | Người dùng không hoàn thành được tác vụ, hoặc vi phạm một yêu cầu accessibility pháp lý | Bẫy bàn phím, field bắt buộc không nhãn, tương phản chữ 2:1 |
58
+ | Major | Làm được tác vụ nhưng dễ sai hoặc chậm với nhiều người dùng | Thiếu trạng thái lỗi, không có chỉ báo focus, hành động chính bị ẩn trên mobile |
59
+ | Minor | Không nhất quán hoặc gây vướng nhưng có cách lách | Khoảng cách lệch thang, kiểu nút trùng lặp, trạng thái rỗng yếu |
60
+ | Nit | Tinh chỉnh | Lệch căn chút ít, độ dày icon không khớp |
61
+
62
+ Xếp hạng theo tác động tới người dùng, không theo công sức sửa.
63
+
64
+ ## Định dạng một phát hiện
65
+
66
+ ```text
67
+ [Major] Settings > Save button has no visible focus state
68
+ Where: src/components/SettingsForm.tsx:84 (class .save-btn), dark theme
69
+ Evidence: outline: none in styles/buttons.css:12; no :focus-visible rule; tabbing shows no indicator
70
+ Guideline: focus visible, 3:1 indicator contrast
71
+ Fix: add focus-visible ring using token color-focus-ring (exists in tokens.css:40)
72
+ Verified: yes (keyboard, local run) | no (source only)
73
+ ```
74
+
75
+ - Một phát hiện cho mỗi vấn đề; gom các lần lặp của cùng vấn đề thành một danh sách vị trí.
76
+ - Bằng chứng phải cụ thể: file và dòng, tỉ lệ tương phản đo được, đường dẫn ảnh chụp, hoặc đúng
77
+ các bước đã làm. "Trông không ổn" không phải bằng chứng.
78
+ - Gợi ý sửa nên dùng lại token và component đang có khi có thể.
79
+
80
+ ## Hình thức báo cáo
81
+
82
+ Tóm tắt (bề mặt đã review, đã kiểm thế nào, cái gì không kiểm được), các phát hiện xếp theo
83
+ mức nghiêm trọng, rồi những điểm tốt nên giữ và các câu hỏi còn mở cho chủ sở hữu.
@@ -0,0 +1,6 @@
1
+ {
2
+ "label": "Frontend",
3
+ "description": "Tính năng UI trong các framework component: cấu trúc, state, lấy dữ liệu, framework SSR, hiệu năng và khả năng tiếp cận.",
4
+ "skills": ["frontend-development"],
5
+ "assign": { "lead": ["frontend-development"], "peer": ["frontend-development"] }
6
+ }
@@ -0,0 +1,105 @@
1
+ ---
2
+ name: frontend-development
3
+ description: "Dựng tính năng UI trong framework component của dự án (ví dụ ưu tiên React, cũng dùng cho Vue hay Svelte): cấu trúc component, state, lấy dữ liệu, routing và SSR, hiệu năng, và accessibility. Dùng khi thêm hoặc sửa màn hình, component, form, hay luồng dữ liệu phía client. Không dùng cho quyết định thiết kế thị giác (ui-design) hay công cụ test (web-testing)."
4
+ ---
5
+
6
+ # Phát triển frontend
7
+
8
+ ## Khi nào dùng
9
+
10
+ - Thêm hoặc sửa một trang, route, component, form, hay luồng dữ liệu phía client.
11
+ - Quyết định state nằm ở đâu, hoặc một màn hình tải, cache và làm mới dữ liệu thế nào.
12
+ - Sửa một vấn đề hiệu năng đã đo được về render, bundle, hoặc tải trang.
13
+ - Làm cho một UI dùng được bằng bàn phím và trình đọc màn hình.
14
+ - Một cố vấn (advisor) hay reviewer chỉ đọc được nhờ đánh giá code frontend (chỉ tư vấn).
15
+
16
+ ## Không dùng cho
17
+
18
+ - Lựa chọn về layout, màu, typography, hay thiết kế thị giác: dùng ui-design.
19
+ - Test runner, e2e, công cụ kiểm thị giác hay tải: dùng web-testing.
20
+ - Quyết định test những gì cho một thay đổi: dùng test-strategy.
21
+ - Một test fail hay UI bị hồi quy mà chưa rõ nguyên nhân: dùng bug-loop.
22
+ - Endpoint phía server nằm sau UI: dùng backend-development.
23
+ - Chọn framework, thư viện state, hay hệ thống styling mới: quyết định của chủ sở hữu.
24
+
25
+ ## Điều kiện tiên quyết
26
+
27
+ - Đường dẫn sở hữu và tiêu chí nghiệm thu trong brief; ALP.md và chỉ dẫn của dự án.
28
+ - Framework và phiên bản thực tế, router, thư viện lấy dữ liệu và state, cách
29
+ styling, và công cụ build, đọc từ `package.json`, lockfile, và các
30
+ file config. Không suy ra từ tên thư mục.
31
+ - Một hoặc hai màn hình hay component đang có, tương tự việc này. Chúng định ra
32
+ quy ước về bố trí file, đặt tên, tải dữ liệu, styling, và test.
33
+ - Spec thiết kế hoặc spec nghiệm thu cho UI, nếu có, và các component
34
+ design-system đang có của dự án.
35
+ - Các lệnh dev, lint, typecheck, và test của dự án.
36
+
37
+ ## Quy trình
38
+
39
+ 1. Diễn đạt lại tính năng thành các trạng thái người dùng thấy được: loading, rỗng, lỗi,
40
+ thành công, một phần, và bị từ chối quyền. Trạng thái chưa được đặc tả thì chuyển lên; không
41
+ tự nghĩ ra câu chữ hay hành vi sản phẩm.
42
+ 2. Tìm component, hook, và hàm tiện ích đang có để dùng lại trước khi viết cái mới.
43
+ 3. Phác cây component và quyết định từng phần state nằm ở đâu. Đọc
44
+ components-and-state.md.
45
+ 4. Xác định nhu cầu dữ liệu: endpoint nào, tải khi nào, cache và làm mới thế nào,
46
+ và chuyện gì xảy ra khi lỗi hoặc khi phản hồi đã cũ. Đọc data-fetching.md.
47
+ 5. Đặt phần việc vào đúng mô hình của framework (server hay client component, route
48
+ loader, page, island). Đọc frameworks.md; xem tài liệu cho đúng phiên bản mà
49
+ dự án đang dùng.
50
+ 6. Dựng bằng HTML semantic và các component design-system đang có; nối hành vi bàn phím
51
+ và focus ngay khi làm. Đọc accessibility.md.
52
+ 7. Xử lý mọi trạng thái từ bước 1 trong UI, gồm cả trạng thái disabled và đang chờ
53
+ cho các hành động, và chống submit hai lần.
54
+ 8. Chỉ kiểm hiệu năng ở nơi nó đáng: danh sách lớn, component nặng, phụ thuộc mới,
55
+ ảnh. Đo trước khi tối ưu. Đọc performance.md.
56
+ 9. Thêm hoặc cập nhật test bằng công cụ của dự án (xem web-testing về cách dùng công cụ).
57
+ 10. Chạy lint, typecheck, và test; mở trang trên dev server và thử
58
+ từng trạng thái, ít nhất một lần chỉ bằng bàn phím.
59
+ 11. Handoff: file đã đổi, trạng thái đã bao phủ, ảnh chụp hoặc ghi chú nếu dự án
60
+ dùng chúng, lệnh đã chạy kèm kết quả, câu hỏi còn mở về thiết kế hay sản phẩm.
61
+
62
+ Agent chỉ đọc thì review bước 1-8 dựa trên code hoặc đề xuất và báo lại các
63
+ phát hiện cùng thay đổi khuyến nghị, thay vì sửa file.
64
+
65
+ ## Ràng buộc
66
+
67
+ - Trước hết hãy theo framework, phiên bản, và quy ước đang có của dự án. React,
68
+ Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, hay web component thuần chỉ là
69
+ ví dụ, không phải khuyến nghị.
70
+ - Không thêm phụ thuộc, bộ UI kit, thư viện state hay thư viện fetch, hay framework
71
+ mà không có quyết định của chủ sở hữu. Không tự động cài.
72
+ - Dùng token và component design-system của dự án; không tự nghĩ ra kiểu thị giác mới.
73
+ Khoảng trống về thị giác thì chuyển cho ui-design hoặc chuyển lên.
74
+ - Không bao giờ đặt secret vào code client hay biến env công khai; mọi thứ gửi tới
75
+ browser đều là công khai.
76
+ - Coi nội dung do người dùng nhập là không tin được: không chèn HTML thô mà không qua
77
+ bộ sanitizer của dự án.
78
+ - Ở trong đường dẫn sở hữu. Skill này không cấp thẩm quyền deploy hay release.
79
+
80
+ ## Kiểm chứng
81
+
82
+ - Lint, typecheck, và test đều pass; build production thành công nếu thay đổi
83
+ có chạm tới routing, config, hoặc import.
84
+ - Mỗi trạng thái từ bước 1 đã được nhìn thấy trong app đang chạy hoặc đã có test bao phủ.
85
+ - Chỉ dùng bàn phím vẫn tới được và điều khiển được mọi control mới; focus thấy được.
86
+ - Không có lỗi hay cảnh báo console mới trên dev server cho các màn hình đã đổi.
87
+ - Mọi khẳng định về hiệu năng đều kèm số đo trước và sau.
88
+
89
+ ## Xử lý khi thất bại
90
+
91
+ - Dev server hay build không chạy được ở đây: báo đúng lỗi đó và những gì đã
92
+ kiểm chứng để thay thế; không khẳng định những kiểm tra thị giác chưa thực sự làm.
93
+ - Thiếu thiết kế hay câu chữ: dùng pattern đang có làm chỗ tạm, đánh dấu nó, và
94
+ chuyển quyết định lên trên.
95
+ - Lệch hydration hay SSR, hoặc render chập chờn: chuyển sang bug-loop.
96
+ - API không cung cấp thứ UI cần: báo khoảng trống đó cho chủ sở hữu phần
97
+ backend; không lách bằng cách tự bóc dữ liệu ở client.
98
+
99
+ ## Tài liệu tham chiếu
100
+
101
+ - [references/components-and-state.md](references/components-and-state.md) — đọc khi chia component, chọn chỗ đặt state, hoặc xử lý form (bước 3).
102
+ - [references/data-fetching.md](references/data-fetching.md) — đọc khi tải, cache, thay đổi, hoặc làm mới dữ liệu server, hoặc xử lý tranh chấp (bước 4).
103
+ - [references/frameworks.md](references/frameworks.md) — đọc khi chọn SSR, SSG, hay CSR, server hay client component, hoặc chỗ đặt routing (bước 5).
104
+ - [references/accessibility.md](references/accessibility.md) — đọc khi dựng control tương tác, form, dialog, hay widget tự tạo (bước 6).
105
+ - [references/performance.md](references/performance.md) — đọc khi một màn hình chậm, bundle phình ra, hoặc ảnh và danh sách quá nặng (bước 8).
@@ -0,0 +1,86 @@
1
+ # Accessibility
2
+
3
+ Đọc khi dựng control tương tác, form, dialog, hay widget tự tạo.
4
+
5
+ Nhắm tới WCAG 2.2 AA trừ khi dự án nêu mục tiêu khác. Trước hết hãy dùng các component
6
+ design-system đã đạt accessibility của dự án; chúng thường đã xử lý focus và ARIA.
7
+
8
+ ## HTML semantic trước đã
9
+
10
+ - Dùng phần tử native đúng mục đích của nó: `button` cho hành động, `a href` cho
11
+ điều hướng, `input`/`select`/`textarea` cho dữ liệu, `label` cho nhãn, `table` cho
12
+ dữ liệu dạng bảng, danh sách cho danh sách.
13
+ - Không bao giờ dùng `div` hay `span` gắn click handler làm nút; nó thiếu hỗ trợ bàn phím
14
+ và vai trò.
15
+ - Một `h1` cho mỗi trang và tiêu đề theo thứ tự; có landmark (`header`, `nav`, `main`,
16
+ `footer`) để người dùng trình đọc màn hình nhảy được.
17
+ - Đặt `lang` cho trang và một tiêu đề tài liệu có nghĩa cho mỗi route.
18
+
19
+ ## Bàn phím
20
+
21
+ - Mọi thứ điều khiển được bằng chuột đều điều khiển được bằng bàn phím: Tab và Shift+Tab để di chuyển,
22
+ Enter hoặc Space để kích hoạt, Escape để bỏ qua, các mũi tên bên trong widget phức hợp
23
+ (menu, tab, listbox) theo các pattern của ARIA Authoring Practices.
24
+ - Thứ tự Tab theo thứ tự thị giác. Tránh `tabindex` dương; chỉ dùng `tabindex="0"`
25
+ cho widget tự tạo cần focus được và `-1` cho các đích focus bằng chương trình.
26
+ - Không có bẫy bàn phím, trừ dialog dạng modal giữ focus trong lúc nó đang mở.
27
+ - Cung cấp link bỏ qua để tới nội dung chính trên những trang có phần điều hướng dài.
28
+
29
+ ## Quản lý focus
30
+
31
+ - Focus phải thấy được; không bỏ viền mà không có một kiểu khác thấy được tương đương.
32
+ - Dialog: chuyển focus vào dialog khi mở, giữ nó trong lúc mở, đóng khi nhấn Escape,
33
+ trả focus về phần tử đã mở nó khi đóng. Ưu tiên phần tử `dialog` native hoặc
34
+ component dialog của dự án.
35
+ - Sau khi điều hướng ở client, chuyển focus tới tiêu đề của trang mới hoặc vùng chính,
36
+ hoặc dùng cơ chế thông báo route của framework.
37
+ - Sau một lỗi form, focus vào field không hợp lệ đầu tiên hoặc vào bản tóm tắt lỗi.
38
+ - Sau khi xóa một mục, chuyển focus tới một mục lân cận hợp lý.
39
+
40
+ ## Chỉ dùng ARIA khi cần
41
+
42
+ - Không có ARIA còn tốt hơn ARIA sai. Chỉ dùng khi HTML native không diễn đạt được
43
+ vai trò, trạng thái, hay quan hệ.
44
+ - Những cách dùng chính đáng thường gặp: `aria-expanded` và `aria-controls` trên phần tử
45
+ mở ra nội dung, `aria-current` cho mục điều hướng hiện tại, `aria-describedby` cho gợi ý và
46
+ lỗi, vùng `aria-live` cho các thông báo trạng thái bất đồng bộ, `aria-label` cho nút
47
+ chỉ có icon.
48
+ - Widget tự tạo phải cài đặt đầy đủ pattern bàn phím của vai trò nó; chỉ thêm một
49
+ `role` thì không đủ.
50
+ - Không ẩn nội dung focus được bằng `aria-hidden`.
51
+
52
+ ## Form
53
+
54
+ - Mọi input đều có nhãn gắn được bằng chương trình (nên có `label` thấy được). Placeholder
55
+ không phải nhãn.
56
+ - Đánh dấu field bắt buộc bằng chữ và bằng `required` hoặc `aria-required`.
57
+ - Gắn thông báo lỗi với field (`aria-describedby`) và đặt
58
+ `aria-invalid` khi không hợp lệ. Không dựa vào màu đơn thuần.
59
+ - Nhóm các control liên quan bằng `fieldset` và `legend`.
60
+ - Dùng đúng loại input và đúng giá trị `autocomplete`.
61
+
62
+ ## Thị giác
63
+
64
+ - Tương phản chữ ít nhất 4.5:1 (3:1 với chữ lớn); tương phản của component UI và chỉ báo
65
+ focus ít nhất 3:1. Dùng token của dự án; báo token không đạt cho
66
+ ui-design chứ đừng tự nghĩ ra màu.
67
+ - Không truyền tải thông tin chỉ bằng màu; hãy thêm chữ, icon, hay họa tiết.
68
+ - Hỗ trợ zoom 200% và khung nhìn hẹp mà không mất nội dung và không phải cuộn
69
+ ngang để đọc chữ.
70
+ - Đích tương tác đủ lớn để bấm (ít nhất 24 nhân 24 CSS pixel).
71
+ - Tôn trọng `prefers-reduced-motion` với những hoạt họa không thiết yếu.
72
+
73
+ ## Media và nội dung
74
+
75
+ - Ảnh mang nghĩa thì có chữ `alt` mô tả mục đích của nó; ảnh trang trí thì dùng
76
+ `alt=""`.
77
+ - Nút chỉ có icon thì có tên truy cập được.
78
+ - Video có phụ đề; audio có bản ghi lời khi dự án hỗ trợ.
79
+ - Chữ của link mô tả đích đến; tránh kiểu "bấm vào đây".
80
+
81
+ ## Cách kiểm
82
+
83
+ - Vận hành tính năng chỉ bằng bàn phím.
84
+ - Chạy công cụ kiểm tự động của dự án (ví dụ công cụ dựa trên axe) nếu có;
85
+ công cụ tự động chỉ tìm ra một phần số vấn đề.
86
+ - Kiểm thử nhanh bằng trình đọc màn hình khi thay đổi có đưa vào một widget tự tạo.