@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.8

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 (124) hide show
  1. package/dist/library-edit.d.ts +51 -2
  2. package/dist/library-edit.js +160 -8
  3. package/dist/library.d.ts +14 -1
  4. package/dist/library.js +73 -5
  5. package/dist/models.d.ts +35 -0
  6. package/dist/models.js +17 -1
  7. package/dist/packs.d.ts +57 -0
  8. package/dist/packs.js +247 -0
  9. package/dist/permissions.d.ts +3 -2
  10. package/dist/permissions.js +6 -3
  11. package/dist/profiles.js +3 -3
  12. package/dist/providers.d.ts +2 -4
  13. package/dist/providers.js +20 -4
  14. package/dist/skill-validate.d.ts +85 -0
  15. package/dist/skill-validate.js +298 -0
  16. package/dist/upgrade.d.ts +10 -0
  17. package/dist/upgrade.js +112 -6
  18. package/dist/validation.js +2 -3
  19. package/package.json +18 -2
  20. package/src/library-edit.js +170 -8
  21. package/src/library.js +96 -6
  22. package/src/models.js +24 -0
  23. package/src/packs.js +246 -0
  24. package/src/permissions.d.ts +3 -2
  25. package/src/permissions.js +13 -3
  26. package/src/profiles.js +4 -4
  27. package/src/providers.js +20 -5
  28. package/src/resolver.js +1 -1
  29. package/src/skill-validate.js +287 -0
  30. package/src/upgrade.js +54 -6
  31. package/src/validation.js +3 -4
  32. package/templates/ALP.md +52 -52
  33. package/templates/agents/lead/AGENT.md +77 -74
  34. package/templates/agents/main/AGENT.md +153 -145
  35. package/templates/agents/oracle/AGENT.md +38 -37
  36. package/templates/agents/peer/AGENT.md +56 -52
  37. package/templates/agents/reviewer/AGENT.md +63 -65
  38. package/templates/agents/supervisor/AGENT.md +63 -63
  39. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  40. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  41. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  42. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  43. package/templates/packs/architecture/pack.json +7 -0
  44. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  45. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  46. package/templates/packs/backend/pack.json +6 -0
  47. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  48. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  49. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  50. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  51. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  52. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  53. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  54. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  55. package/templates/packs/design/pack.json +6 -0
  56. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  57. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  58. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  59. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  60. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  61. package/templates/packs/frontend/pack.json +6 -0
  62. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  63. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  64. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  65. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  66. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  67. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  68. package/templates/packs/integration/pack.json +6 -0
  69. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  70. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  71. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  72. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  73. package/templates/packs/operations/pack.json +6 -0
  74. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  75. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  76. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  77. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  78. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  79. package/templates/packs/quality/pack.json +6 -0
  80. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  81. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  82. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  83. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  84. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  85. package/templates/role-skills.json +4 -4
  86. package/templates/skills/architecture-docs/SKILL.md +81 -0
  87. package/templates/skills/architecture-docs/references/adr.md +62 -0
  88. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  89. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  90. package/templates/skills/bug-loop/SKILL.md +41 -40
  91. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  92. package/templates/skills/compact/SKILL.md +2 -2
  93. package/templates/skills/curate/SKILL.md +6 -5
  94. package/templates/skills/feature-architecture/SKILL.md +90 -0
  95. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  96. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  97. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  98. package/templates/skills/goal-griller/SKILL.md +27 -27
  99. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  100. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  101. package/templates/skills/release-readiness/SKILL.md +83 -0
  102. package/templates/skills/release-readiness/references/checklist.md +40 -0
  103. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  104. package/templates/skills/safe-refactor/SKILL.md +84 -0
  105. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  106. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  107. package/templates/skills/security-review/SKILL.md +87 -0
  108. package/templates/skills/security-review/references/checklist.md +74 -0
  109. package/templates/skills/security-review/references/severity.md +61 -0
  110. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  111. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  112. package/templates/skills/skill-authoring/SKILL.md +84 -0
  113. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  114. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  115. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  116. package/templates/skills/smart-commits/SKILL.md +37 -36
  117. package/templates/skills/test-strategy/SKILL.md +83 -0
  118. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  119. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  120. package/templates/skills/xia/SKILL.md +40 -38
  121. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  122. package/templates/teams/cafe/team.json +1 -1
  123. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  124. package/templates/teams/pho/team.json +1 -1
@@ -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.
@@ -0,0 +1,79 @@
1
+ # Component và state
2
+
3
+ Đọc khi chia component, chọn chỗ đặt state, hoặc xử lý form.
4
+
5
+ Ví dụ dùng thuật ngữ React; cùng ý tưởng đó map sang Vue (props, emits, refs, computed,
6
+ composable) và Svelte (props, store, rune hoặc câu lệnh reactive). Hãy theo
7
+ pattern và bố trí file đang có của dự án.
8
+
9
+ ## Cấu trúc component
10
+
11
+ - Một component, một việc. Chia khi một phần có state riêng, được dùng lại, hoặc làm
12
+ component cha khó đọc; không chia chỉ để file ngắn đi.
13
+ - Tách container tải dữ liệu khỏi component trình bày khi dự án làm vậy;
14
+ component trình bày nhận props và dễ test.
15
+ - Props chảy xuống, event chảy lên. Đặt tên callback theo ý định (`onSubmit`,
16
+ `onSelect`), không theo tên event của DOM.
17
+ - Ưu tiên composition (children, slot) hơn là nhiều props boolean bật tắt layout.
18
+ - Giữ component thuần khi render: không fetch, không subscribe, không thay đổi dữ liệu trong
19
+ thân render; dùng cơ chế effect hoặc lifecycle của framework.
20
+ - Dùng key ổn định từ ID của dữ liệu trong danh sách, không bao giờ dùng chỉ số mảng cho danh sách xếp lại được.
21
+ - Chỉ bóc logic dùng lại ra thành hook hoặc composable khi đã có chỗ dùng thứ hai.
22
+
23
+ ## State nằm ở đâu
24
+
25
+ Chọn chỗ ở hẹp nhất mà vẫn chạy được:
26
+
27
+ | Loại | Chỗ ở |
28
+ | --- | --- |
29
+ | Giá trị chỉ một component dùng | state cục bộ của component |
30
+ | Giá trị dùng chung giữa các component cùng cấp | đưa lên component cha gần nhất |
31
+ | Giá trị suy ra được từ state hay props khác | tính nó ra; đừng lưu lại |
32
+ | Dữ liệu từ server | cache lấy dữ liệu của dự án, không phải state toàn cục |
33
+ | Đáng nằm trên URL (filter, tab, trang, ID đang chọn) | tham số route hoặc query string |
34
+ | Dữ liệu nhập trong form | state của form (cục bộ hoặc thư viện form của dự án) |
35
+ | Thực sự dùng toàn app (theme, session, locale) | context hoặc store của dự án |
36
+
37
+ - State bị trùng lặp sẽ lệch nhau. Nếu hai chỗ giữ cùng một sự thật, hãy giữ một nguồn và
38
+ suy ra chỗ kia.
39
+ - Tránh đồng bộ state bằng effect (`useEffect` copy props vào state); hãy suy ra
40
+ trong lúc render hoặc reset bằng key.
41
+ - Context render lại mọi consumer khi đổi; hãy tách context hoặc dùng store nếu một
42
+ giá trị đổi liên tục được dùng chung rộng khắp.
43
+ - Đặt lên URL những state đáng sống sót qua lần tải lại hoặc đáng chia sẻ được.
44
+ - Không thêm thư viện store toàn cục mà không có quyết định của chủ sở hữu.
45
+
46
+ ## Effect và lifecycle
47
+
48
+ - Dùng effect để đồng bộ với thứ gì bên ngoài (subscription, timer, DOM
49
+ API), không để tính giá trị hay phản ứng với event của người dùng.
50
+ - Mọi subscription, listener, timer, hay observer đều phải được dọn.
51
+ - Xử lý việc effect bị gọi hai lần ở strict mode khi dev: effect phải an toàn khi chạy,
52
+ dọn, rồi chạy lại.
53
+
54
+ ## Form
55
+
56
+ - Dùng cách làm form của dự án (form native, input có kiểm soát, hoặc thư viện form
57
+ của nó) một cách nhất quán.
58
+ - Mọi input đều có nhãn. Hiện lỗi validate ngay cạnh field và tóm tắt lại
59
+ khi submit; chuyển focus tới lỗi đầu tiên.
60
+ - Validate ở client để phản hồi nhanh; server vẫn là nơi có thẩm quyền.
61
+ - Vô hiệu hóa hoặc chặn hành động submit khi đang chờ để tránh submit hai lần;
62
+ hiện tiến trình.
63
+ - Giữ lại dữ liệu đã nhập khi submit thất bại.
64
+ - Coi phản hồi validate của server là nguồn của các lỗi theo field.
65
+
66
+ ## Kiểu và hợp đồng
67
+
68
+ - Khai kiểu cho props và event bằng hệ kiểu của dự án (TypeScript, PropTypes, hoặc
69
+ kiểu riêng của framework).
70
+ - Chỉ chia sẻ kiểu của phản hồi API với backend qua cơ chế đang có của dự án
71
+ (kiểu được sinh ra, package dùng chung); không copy tay những kiểu rồi sẽ lệch nhau.
72
+ - Thu hẹp dữ liệu có thể null ngay tại biên để component nhận được giá trị đầy đủ hoặc một
73
+ trạng thái rỗng tường minh.
74
+
75
+ ## Styling
76
+
77
+ - Dùng hệ thống styling của dự án (CSS module, utility class, CSS-in-JS, style có
78
+ phạm vi) và các design token. Không trộn thêm cách thứ hai.
79
+ - Tránh giá trị thần kỳ viết thẳng cho khoảng cách và màu khi đã có token.
@@ -0,0 +1,86 @@
1
+ # Lấy dữ liệu
2
+
3
+ Đọc khi tải, cache, thay đổi, hoặc làm mới dữ liệu server, hoặc khi xử lý tranh chấp.
4
+
5
+ Dùng cơ chế đang có của dự án: loader hay server component của framework, một thư viện
6
+ query-cache (TanStack Query, SWR, Apollo, RTK Query là các ví dụ), hoặc fetch thuần
7
+ gói trong một client dùng chung. Không thêm cơ chế thứ hai.
8
+
9
+ ## Mọi request đều có bốn trạng thái
10
+
11
+ - Loading: hiện skeleton hoặc spinner có kích thước như nội dung cuối để tránh dịch
12
+ layout. Với lần tải nhanh, hoãn chỉ báo một chút để nó không nháy.
13
+ - Lỗi: hiện một thông báo có ích và một hành động thử lại. Phân biệt "không tìm thấy",
14
+ "không được phép", "offline", và "lỗi server" khi API cho phép. Không hiện object
15
+ lỗi thô hay stack trace.
16
+ - Rỗng: một trạng thái riêng kèm hướng dẫn hoặc một hành động, không phải một vùng trắng.
17
+ - Thành công: render dữ liệu; giữ dữ liệu trước đó hiển thị trong lúc làm mới ở nền thay vì
18
+ nháy trở về trạng thái loading.
19
+
20
+ Cũng hãy tính tới dữ liệu một phần (một số mục bị lỗi) và dữ liệu cũ (hiện ra trong lúc
21
+ đang làm mới).
22
+
23
+ ## Fetch ở đâu
24
+
25
+ - Ưu tiên tải ở cấp route hoặc phía server khi framework hỗ trợ, để dữ liệu
26
+ bắt đầu tải cùng lúc với điều hướng và tránh được thác nước request.
27
+ - Khởi động các request độc lập song song; không xâu chúng lại trong các component lồng nhau
28
+ trừ khi cái này phụ thuộc cái kia.
29
+ - Không fetch trong lúc render. Ở client component hãy dùng thư viện cache hoặc một effect
30
+ có dọn dẹp.
31
+ - Giữ API client trong một module: base URL, header hay cookie auth, parse JSON,
32
+ và chuẩn hóa lỗi.
33
+
34
+ ## Cache
35
+
36
+ - Đặt key cho dữ liệu cache theo mọi thứ ảnh hưởng tới phản hồi (tài nguyên, ID, filter,
37
+ trang, người dùng hay tenant).
38
+ - Quyết định độ tươi cho từng tài nguyên: dữ liệu được coi là tươi trong bao lâu, và khi nào fetch lại
39
+ (khi focus, khi kết nối lại, theo chu kỳ, hoặc khi vô hiệu tường minh).
40
+ - Vô hiệu hoặc cập nhật các key bị ảnh hưởng sau một mutation; không để danh sách còn cũ
41
+ sau khi tạo hay xóa.
42
+ - Xóa cache riêng của người dùng khi logout hoặc đổi tài khoản.
43
+ - Tôn trọng các header cache HTTP mà backend đã đặt; không cache những phản hồi mang tính
44
+ cá nhân vào cache dùng chung.
45
+
46
+ ## Tranh chấp (race condition)
47
+
48
+ - Một phản hồi đến trước nhưng chậm hơn không được ghi đè lên phản hồi mới hơn. Hãy hủy request
49
+ trước đó (AbortController hoặc cơ chế hủy của thư viện) hoặc bỏ qua kết quả có key
50
+ không còn khớp với dữ liệu nhập hiện tại.
51
+ - Debounce việc tìm kiếm khi đang gõ và hủy các request đang bay khi có dữ liệu nhập mới.
52
+ - Bỏ qua kết quả sau khi unmount; dọn subscription và abort các request đang bay.
53
+ - Chặn việc submit mutation hai lần: vô hiệu hóa khi đang chờ, và gửi một
54
+ idempotency key nếu API hỗ trợ.
55
+
56
+ ## Mutation
57
+
58
+ - Hiện trạng thái đang chờ trên chính control đã khởi động mutation đó.
59
+ - Chỉ cập nhật lạc quan khi thất bại là hiếm và đảo lại được; hoàn tác khi lỗi
60
+ và nói cho người dùng biết.
61
+ - Khi server trả lỗi validate, hãy map chúng về từng field.
62
+ - Sau khi thành công, cập nhật hoặc vô hiệu cache, rồi chuyển focus hoặc thông báo
63
+ kết quả cho công nghệ trợ giúp.
64
+
65
+ ## Lỗi và thử lại
66
+
67
+ - Chỉ tự động thử lại các lần đọc idempotent, với giới hạn nhỏ và có backoff. Không
68
+ tự động thử lại mutation trừ khi chúng idempotent.
69
+ - Xử lý 401 ở một chỗ duy nhất (refresh hoặc chuyển tới trang login theo quy ước của dự án).
70
+ - Dùng error boundary hoặc route lỗi của framework cho những lỗi bất ngờ, để một
71
+ widget vỡ không làm trắng cả trang.
72
+ - Báo lỗi qua hệ thống giám sát đang có của dự án, không kèm dữ liệu cá nhân hay
73
+ token.
74
+
75
+ ## Bảo mật
76
+
77
+ - Không bao giờ nhúng secret hay API key riêng vào code client; hãy đi qua
78
+ backend.
79
+ - Chỉ gửi thông tin đăng nhập tới các origin của chính dự án.
80
+ - Không tin các kiểm tra phía client về phân quyền; server mới là nơi thực thi.
81
+
82
+ ## Ghi chú về test
83
+
84
+ - Mock mạng ở tầng HTTP (công cụ mock request của dự án) chứ không
85
+ mock phần bên trong của thư viện cache.
86
+ - Test cả bốn trạng thái và một tình huống chậm-rồi-nhanh cho các input tìm kiếm.
@@ -0,0 +1,77 @@
1
+ # Framework, render, và routing
2
+
3
+ Đọc khi chọn SSR, SSG, hay CSR, server hay client component, hoặc chỗ đặt
4
+ routing.
5
+
6
+ Quy ước của framework đổi giữa các bản major. Hãy xác định đúng framework
7
+ và phiên bản từ `package.json` và lockfile, theo quy ước của chính
8
+ phiên bản đó, và xem tài liệu chính thức của nó (hoặc tài liệu và type của package đã
9
+ cài) trước khi dựa vào một API. Nếu dự án trộn quy ước cũ và mới (ví
10
+ dụ vừa pages router vừa app router), hãy theo cái đang dùng ở vùng bạn
11
+ đang sửa và không tự ý chuyển đổi nó.
12
+
13
+ ## Các chế độ render
14
+
15
+ | Chế độ | Render ở đâu | Phù hợp cho | Cái giá |
16
+ | --- | --- | --- | --- |
17
+ | CSR (phía client) | trong browser | màn hình dạng app sau khi đăng nhập | first paint chậm hơn, SEO tùy crawler |
18
+ | SSR (mỗi request) | trên server mỗi request | nội dung cá nhân hóa hay tươi mới, SEO | tốn server, có độ trễ mỗi request |
19
+ | SSG (lúc build) | một lần khi build | nội dung ổn định, tài liệu, marketing | phải build lại hoặc revalidate để cập nhật |
20
+ | Static tăng dần / có revalidate | khi build, làm mới theo chu kỳ hay theo trigger | nội dung phần lớn tĩnh nhưng có đổi | có khoảng thời gian dữ liệu cũ |
21
+ | Streaming / một phần | server stream từng phần khi sẵn sàng | phần chậm trên bộ khung nhanh | trạng thái loading phức tạp hơn |
22
+
23
+ - Theo đúng chế độ mà các route xung quanh đang dùng, trừ khi brief yêu cầu đổi.
24
+ - Đổi chế độ render của một route ảnh hưởng tới cache, hosting, và SEO; hãy chuyển
25
+ quyết định đó lên trên.
26
+
27
+ ## Server component và client component
28
+
29
+ Áp dụng cho framework có tách server/client (React Server Component trong
30
+ app router của Next.js và tương tự; khái niệm tương đương ở Nuxt, SvelteKit, island của Astro).
31
+
32
+ - Server component: fetch dữ liệu, đọc config chỉ có ở server, render markup tĩnh,
33
+ không gửi JS của component. Chúng không dùng được state client, effect, hay API browser.
34
+ - Client component: tính tương tác, state, effect, API browser. Đánh dấu chúng theo
35
+ cách framework yêu cầu (ví dụ chỉ thị `"use client"`) ở vị trí càng thấp trong cây càng
36
+ tốt, để phần lớn markup vẫn được render ở server.
37
+ - Props truyền từ server sang client phải serialize được; không truyền hàm hay
38
+ instance của class.
39
+ - Không bao giờ import module chỉ dành cho server (client database, secret) vào code client.
40
+ Dùng cơ chế chặn server-only của framework nếu nó có.
41
+ - Server action hay form action là endpoint công khai: hãy validate dữ liệu nhập và kiểm tra
42
+ phân quyền trong chúng như với bất kỳ API nào.
43
+
44
+ ## Hydration
45
+
46
+ - Server và client phải render ra cùng một markup ban đầu. Tránh dùng khi render các thứ như
47
+ `Date.now()`, giá trị ngẫu nhiên, `window`, hay định dạng phụ thuộc locale mà không có
48
+ dữ liệu nhập ổn định.
49
+ - Đọc các giá trị chỉ có ở browser sau khi mount, hoặc chỉ render chúng ở client qua
50
+ cơ chế của framework.
51
+ - Coi cảnh báo hydration là bug.
52
+
53
+ ## Quy ước routing
54
+
55
+ - Theo hệ thống routing của dự án: dựa trên file (Next.js, Nuxt, SvelteKit, Remix
56
+ hay React Router ở chế độ framework) hoặc dựa trên config (React Router, Vue Router).
57
+ - Đặt phần tải dữ liệu ở nơi framework mong đợi (loader, server component,
58
+ hàm `load`, route guard) để tránh thác nước request ở client.
59
+ - Dùng component link của framework cho điều hướng nội bộ, để prefetch và
60
+ chuyển trang ở client hoạt động.
61
+ - Dùng cơ chế xử lý loading, lỗi, và không-tìm-thấy ở cấp route mà framework cung cấp.
62
+ - Giữ state thuộc URL (filter, phân trang, tab) trong tham số hoặc query string.
63
+ - Bảo vệ route ở server (middleware, loader) chứ không chỉ ở UI; chỉ redirect
64
+ ở client thì không bảo vệ được dữ liệu.
65
+
66
+ ## Môi trường và config
67
+
68
+ - Biến env công khai (tiền tố như `NEXT_PUBLIC_` hay `VITE_`) được nhúng vào
69
+ bundle client; không bao giờ đặt secret vào chúng.
70
+ - Tôn trọng dạng output build của dự án (static export, Node server, edge runtime);
71
+ API lúc chạy khác nhau giữa chúng.
72
+
73
+ ## Khi không chắc
74
+
75
+ - Tìm route đang có gần nhất làm cùng loại việc đó và làm theo nó.
76
+ - Nếu tài liệu của phiên bản đã cài trái với ký ức hay với ví dụ, hãy theo tài liệu
77
+ và ghi lại khác biệt đó trong handoff.
@@ -0,0 +1,78 @@
1
+ # Hiệu năng frontend
2
+
3
+ Đọc khi một màn hình chậm, bundle phình ra, hoặc ảnh và danh sách quá nặng.
4
+
5
+ Đo trước, rồi đổi một thứ, rồi đo lại trong cùng điều kiện
6
+ (cùng chế độ build, cùng thiết bị hay cấu hình giới hạn, cùng lượng dữ liệu). Bản build dev
7
+ chậm hơn và nhiễu hơn bản production; muốn khẳng định điều gì thì hãy profile bản production.
8
+
9
+ ## Đo cái gì
10
+
11
+ - Core Web Vitals cho trải nghiệm trang: Largest Contentful Paint (tải),
12
+ Interaction to Next Paint (độ đáp ứng), Cumulative Layout Shift (độ ổn định).
13
+ Dùng công cụ đang có của dự án (Lighthouse, panel performance của browser, một dashboard
14
+ RUM) và báo lại điều kiện đo.
15
+ - Chi phí render: profiler của framework (React DevTools Profiler, Vue DevTools) để
16
+ thấy component nào render, bao nhiêu lần, và mất bao lâu.
17
+ - Kích thước bundle: công cụ phân tích hoặc output thống kê của build cho các route bị ảnh hưởng.
18
+ - Mạng: biểu đồ thác nước của route; tìm những request nối tiếp nhau và payload lớn.
19
+
20
+ Dùng ngân sách mà dự án đã định ra. Đừng tự nghĩ ra một ngưỡng cố định; hãy báo
21
+ các con số trước và sau.
22
+
23
+ ## Chi phí render
24
+
25
+ - Trước hết hãy bỏ những việc không cần: state đặt quá cao làm render lại cả vùng rộng,
26
+ dữ liệu suy ra bị tính lại trong lúc render trên dữ liệu nhập lớn, effect đặt state ở
27
+ mỗi lần render, và giá trị context bị tạo lại mỗi lần render.
28
+ - Đưa state xuống đúng chỗ nó được dùng, hoặc chia component ra để state đổi nhanh
29
+ chỉ render lại một nhánh nhỏ.
30
+ - Chỉ ghi nhớ (`memo`, `useMemo`, `useCallback`, giá trị computed) ở nơi
31
+ profiler cho thấy một chi phí đo được, hoặc ở nơi compiler hay luật lint của dự án
32
+ đã xử lý giúp. Ghi nhớ mà không đo thì thêm phức tạp và có thể che bug do
33
+ phụ thuộc đã cũ.
34
+ - Virtual hóa danh sách dài (hàng trăm dòng hoặc hơn) theo cách đang có của
35
+ dự án; phân trang khi chưa đáng để virtual hóa.
36
+ - Chỉ đưa phần tính toán nặng ra khỏi luồng chính (một web worker) khi đã đo.
37
+ - Hoãn các cập nhật không gấp bằng API transition hay lập lịch của framework khi
38
+ gõ chữ thấy có cảm giác trễ.
39
+
40
+ ## Bundle và tải
41
+
42
+ - Chia theo route; lazy-load những component nặng, ít dùng (editor, biểu đồ, bản đồ)
43
+ đặt sau tương tác hoặc view thực sự cần chúng.
44
+ - Kiểm tra một phụ thuộc mới tốn bao nhiêu trước khi đề xuất nó; ưu tiên API của nền tảng và
45
+ các phụ thuộc đang có. Thêm một cái là quyết định của chủ sở hữu.
46
+ - Chỉ import những gì bạn dùng; tránh import kiểu barrel làm mất tác dụng tree shaking khi
47
+ bundler xử lý chúng không tốt.
48
+ - Đừng vô tình gửi code chỉ dành cho server, file dữ liệu lớn, hay source map
49
+ xuống client.
50
+ - Preload các tài nguyên quan trọng (ảnh LCP, font chính) khi số đo cho thấy có
51
+ độ trễ; đừng preload mọi thứ.
52
+ - Render ở server hay sinh tĩnh giúp cải thiện first paint cho các trang nội dung; xem
53
+ frameworks.md.
54
+
55
+ ## Ảnh và media
56
+
57
+ - Phục vụ ảnh đã đúng kích thước, đã nén, ở các định dạng hiện đại, qua pipeline hay
58
+ component ảnh của dự án.
59
+ - Luôn đặt width và height (hoặc tỉ lệ khung) để tránh dịch layout.
60
+ - Lazy-load các ảnh nằm dưới màn hình đầu; không lazy-load ảnh LCP.
61
+ - Dùng `srcset` và `sizes` responsive để màn hình nhỏ tải file nhỏ.
62
+ - Ưu tiên CSS hoặc SVG cho icon và hình đơn giản.
63
+
64
+ ## Độ ổn định layout và độ đáp ứng
65
+
66
+ - Dành sẵn chỗ cho nội dung bất đồng bộ, quảng cáo, và nội dung nhúng.
67
+ - Tránh chèn nội dung lên phía trên nội dung đang có sau khi tải xong.
68
+ - Tải font với một chiến lược hiển thị tránh chữ vô hình, dùng thiết lập font
69
+ của dự án.
70
+ - Giữ các handler nhập liệu ngắn gọn; chia nhỏ task dài; tránh giật layout (đọc
71
+ layout rồi ghi style trong một vòng lặp).
72
+
73
+ ## Báo cáo
74
+
75
+ - Nêu rõ chỉ số, công cụ, chế độ build, thiết bị hay cấu hình giới hạn, lượng dữ liệu, và
76
+ giá trị trước và sau.
77
+ - Nếu một thay đổi không làm chỉ số đo được nhúc nhích, hãy hoàn tác nó chứ đừng giữ lại
78
+ cho chắc.
@@ -0,0 +1,6 @@
1
+ {
2
+ "label": "Integration",
3
+ "description": "Server và client Model Context Protocol: thiết kế tool, transport, kiểm thử, và nối một server vào ALP.",
4
+ "skills": ["mcp-integration"],
5
+ "assign": { "lead": ["mcp-integration"], "peer": ["mcp-integration"] }
6
+ }