accessibility-compliance

Tổng quan về skill accessibility-compliance

accessibility-compliance skill làm được gì

Skill accessibility-compliance giúp agent đưa ra hướng dẫn accessibility có thể triển khai ngay cho UI web và mobile, tập trung mạnh vào WCAG 2.2, cách dùng ARIA, khả năng truy cập bằng bàn phím, hỗ trợ screen reader và accessibility trên thiết bị di động. Skill này phù hợp nhất với các nhóm đang làm giao diện thực tế, không chỉ cần một checklist accessibility chung chung.

Ai nên cài accessibility-compliance

Skill này đặc biệt phù hợp với:

• UX auditor cần accessibility-compliance for UX Audit
• frontend engineer đang sửa lỗi accessibility trong component
• team design system xây dựng pattern tương tác có khả năng truy cập tốt
• team product đang phát hành form, dialog, menu và các UI tương tác khác
• team mobile hoặc cross-platform cần hướng dẫn có tính đến VoiceOver và TalkBack

Nếu công việc của bạn là “biến màn hình hoặc component này thành thứ gì đó gần đạt chuẩn WCAG hơn bằng các cách sửa cụ thể”, thì skill này hữu ích hơn nhiều so với một prompt thiết kế tổng quát.

Vì sao skill này khác với prompt chung chung

Giá trị chính của accessibility-compliance skill nằm ở việc nó định hướng model theo các pattern triển khai accessibility thực tế thay vì chỉ dừng ở nguyên tắc mơ hồ. Repository đi kèm các tài liệu tham chiếu tập trung vào:

• references/wcag-guidelines.md
• references/aria-patterns.md
• references/mobile-accessibility.md

Nhờ đó, skill phù hợp hơn với các tác vụ như ưu tiên semantic HTML thay vì lạm dụng ARIA, cấu trúc form dễ tiếp cận, cải thiện hành vi bàn phím hoặc kiểm tra hướng dẫn về kích thước vùng chạm trên mobile.

Điều người dùng thường quan tâm trước khi cài

Phần lớn người đang cân nhắc accessibility-compliance install muốn biết:

• skill có đưa ra cách sửa cụ thể ở mức code thay vì ngôn ngữ kiểu policy hay không
• skill có bao phủ cả web lẫn mobile hay không
• skill có hỗ trợ cả audit lẫn triển khai hay không
• skill có quan điểm rõ ràng về semantic native so với ARIA hay không
• skill có giúp giảm vòng lặp trao đổi khi review UI component hay không

Ở các điểm này, skill thể hiện khá chắc tay. Điểm khác biệt mạnh nhất là độ bao phủ thực dụng: gom cả khái niệm WCAG, ARIA pattern và accessibility cho mobile trong một gói.

Trường hợp phù hợp nhất và không phù hợp

Phù hợp nhất:

• audit các component có tương tác
• sửa lỗi accessibility trong code hiện có
• lên kế hoạch hành vi dễ tiếp cận cho dialog, accordion, form và navigation
• rà soát thứ tự focus, label, announcement và hỗ trợ reduced motion

Không phù hợp:

• diễn giải yêu cầu tuân thủ pháp lý theo từng khu vực pháp lý cụ thể
• tự thân thiết lập hệ thống test tự động
• góp ý thiết kế visual ở mức pixel không liên quan đến accessibility
• xử lý API native đặc thù từng nền tảng vượt ra ngoài phạm vi tài liệu tham chiếu

Cách dùng accessibility-compliance skill

Bối cảnh cài đặt và cách gọi

SKILL.md ở nguồn upstream không cung cấp lệnh cài đặt, nên người dùng directory thường sẽ thêm skill trực tiếp từ repo:

npx skills add https://github.com/wshobson/agents --skill accessibility-compliance

Sau đó, hãy gọi skill bằng một tác vụ accessibility cụ thể, thay vì chỉ nói “check accessibility”. Skill hoạt động tốt nhất khi yêu cầu có kèm component, luồng tương tác hoặc màn hình với đủ cấu trúc để review.

Nên đọc các file này trước

Để làm quen nhanh, hãy bắt đầu với:

1. plugins/ui-design/skills/accessibility-compliance/SKILL.md
2. plugins/ui-design/skills/accessibility-compliance/references/wcag-guidelines.md
3. plugins/ui-design/skills/accessibility-compliance/references/aria-patterns.md
4. plugins/ui-design/skills/accessibility-compliance/references/mobile-accessibility.md

Thứ tự này phản ánh khá sát cách đa số team làm việc: xác định mục tiêu tuân thủ trước, xem pattern triển khai sau, rồi mới xử lý các edge case theo nền tảng.

accessibility-compliance cần đầu vào gì để hoạt động tốt

Chất lượng accessibility-compliance usage phụ thuộc rất nhiều vào độ cụ thể của đầu vào. Bạn nên cung cấp:

• loại component hoặc trang
• code hoặc markup hiện tại
• framework (React, Next.js, Vue, plain HTML, React Native)
• hành vi tương tác
• chuẩn mục tiêu, thường là WCAG 2.2 AA
• phạm vi thiết bị: desktop web, mobile web, iOS, Android
• lỗi đã biết từ công cụ audit hoặc user testing

Đầu vào yếu:

• “Make this accessible.”

Đầu vào mạnh:

• “Review this React modal for WCAG 2.2 AA. Check keyboard trap behavior, focus return, accessible name/description, escape handling, and screen reader announcements. Suggest code changes before release.”

Biến mục tiêu thô thành prompt tốt

Một prompt accessibility-compliance guide tốt thường có 5 phần:

1. UI mục tiêu
2. tương tác người dùng
3. mục tiêu tuân thủ
4. đầu ra mong muốn
5. ràng buộc

Ví dụ:

• “Use the accessibility-compliance skill to audit this checkout form for WCAG 2.2 AA. Identify failures by issue, explain user impact, and provide corrected JSX for labels, error messaging, field grouping, and keyboard flow. Keep the current visual design if possible.”

Cách này tốt hơn nhiều so với chỉ hỏi “best practices”, vì nó buộc model tạo ra đầu ra có thể sửa và áp dụng được.

Quy trình tốt nhất cho UX audit

Với accessibility-compliance for UX Audit, hãy dùng chuỗi bước sau:

1. yêu cầu phát hiện vấn đề
2. yêu cầu đánh giá mức độ nghiêm trọng và tác động với người dùng
3. yêu cầu map từng vấn đề sang cách sửa
4. yêu cầu markup hoặc code component đã chỉnh lại
5. yêu cầu checklist retest

Cách làm này tránh lỗi phổ biến là câu trả lời đầu tiên quá nặng về khái niệm. Skill phát huy giá trị rõ nhất khi bạn đẩy nó đi từ phát hiện trong audit sang chi tiết triển khai.

Dùng cho component, không chỉ cho page

Skill này đặc biệt mạnh với các pattern tương tác có thể tái sử dụng. Các mục tiêu phù hợp gồm:

• dialog và focus trap
• accordion
• menu và disclosure
• form và validation
• tabs
• carousel
• icon button
• vùng chạm trên mobile

Đây cũng chính là những chỗ mà prompt chung thường lạm dụng ARIA hoặc bỏ sót hành vi bàn phím và screen reader.

Các tài liệu tham chiếu này gợi ý gì trong thực tế

Các tài liệu tham chiếu đi kèm cho thấy 3 nguyên tắc vận hành quan trọng:

• ưu tiên semantic HTML trước khi thêm ARIA
• xem WCAG 2.2 AA là baseline mặc định
• tính đến accessibility trên mobile, không chỉ riêng thao tác bàn phím trên desktop

Điều này rất quan trọng khi áp dụng thật. Một prompt tốt nên nói rõ rằng agent cần hạn chế ARIA không cần thiết và giải thích lý do cho bất kỳ thuộc tính ARIA nào được thêm vào.

Mẫu prompt để ra kết quả tốt hơn

Hãy dùng format yêu cầu như sau:

• Context: “This is a React checkout drawer.”
• Target: “Meet WCAG 2.2 AA.”
• Review scope: “Keyboard access, focus order, visible labels, error association, live region announcements.”
• Constraints: “Do not rewrite the design system API.”
• Deliverable: “Return prioritized issues, corrected JSX, and a manual test checklist.”

Cấu trúc này gần như luôn cho accessibility-compliance usage tốt hơn so với các yêu cầu review mở, không giới hạn phạm vi.

Nên kỳ vọng gì ở đầu ra

Một câu trả lời tốt từ accessibility-compliance skill nên bao gồm:

• danh sách vấn đề gắn với tác động đến người dùng
• dẫn chiếu tới nguyên tắc hoặc tiêu chí accessibility
• thay đổi cụ thể ở mức markup hoặc code
• ghi chú về hành vi bàn phím và focus
• hướng dẫn về cách đặt tên và announcement cho screen reader
• ghi chú riêng cho mobile nếu có liên quan

Nếu đầu ra chỉ dừng ở nguyên tắc mà không đi đến chỉnh sửa ở mức code, thì prompt của bạn vẫn còn quá rộng.

Câu hỏi thường gặp về accessibility-compliance skill

accessibility-compliance có phù hợp với người mới bắt đầu không?

Có, nếu bạn đã nắm được cấu trúc UI cơ bản. Skill này mang lại nhiều giá trị hơn khi bạn có thể cung cấp markup, component hoặc kết quả audit. Người mới vẫn dùng được, nhưng nên chuẩn bị hỏi tiếp vì sao một số lựa chọn semantic hoặc ARIA lại quan trọng.

accessibility-compliance có tốt hơn prompt accessibility thông thường không?

Thường là có, nếu bạn đang làm việc ở mức triển khai. Một prompt thông thường dễ trả về các gợi ý quá chung như “add alt text” hoặc “ensure keyboard navigation.” accessibility-compliance skill có xu hướng bám sát hơn vào WCAG 2.2, ARIA pattern và các vấn đề accessibility cho mobile được nêu trong repository.

Skill này có thay thế được test accessibility tự động không?

Không. Nó nên được dùng để bổ trợ cho công cụ tự động và review thủ công. Hãy dùng skill để diễn giải vấn đề, đề xuất cách sửa và rà soát hành vi của component mà công cụ tĩnh thường bỏ sót, như quản lý focus, thời điểm announcement hoặc chi tiết tương tác trên mobile.

Khi nào không nên dùng accessibility-compliance?

Hãy bỏ qua skill này khi bạn cần:

• tư vấn pháp lý hoặc quyết định chứng nhận
• quét toàn bộ codebase hoàn toàn tự động
• chi tiết chuyên sâu của nền tảng mobile native vượt ngoài các pattern được tham chiếu
• góp ý UX không liên quan đến accessibility

Đây là skill hướng dẫn, không phải cam kết đạt compliance.

accessibility-compliance có hỗ trợ accessibility trên mobile tốt không?

Khá ổn đối với một AI skill. Tài liệu mobile-accessibility.md riêng có đề cập đến kích thước vùng chạm, khoảng cách và các vấn đề liên quan đến screen reader trên iOS và Android. Điều đó khiến skill này đáng tin hơn cho review mobile so với các prompt accessibility chỉ tập trung vào desktop web.

Có thể dùng accessibility-compliance cho design system không?

Có. Skill này rất hợp để xác định các mặc định accessible cho component tái sử dụng, đặc biệt ở những nơi semantic, xử lý bàn phím, trạng thái ARIA và quản lý focus cần nhất quán trên nhiều sản phẩm.

Cách cải thiện accessibility-compliance skill

Hãy đưa cho skill artifact thật, không chỉ tóm tắt

Cách nhanh nhất để cải thiện kết quả từ accessibility-compliance là cung cấp JSX, HTML, mã React Native, screenshot có chú thích hoặc mô tả tương tác theo từng bước. Skill không thể suy ra đáng tin cậy thứ tự focus, label hay announcement chỉ từ phần mô tả sản phẩm mơ hồ.

Hãy yêu cầu map vấn đề, đừng chỉ xin khuyến nghị

Một yêu cầu tốt hơn là:

• “List each issue, affected users, violated principle or criterion, and exact fix.”

Cách này buộc model tạo ra đầu ra có thể audit lại. Nếu thiếu cấu trúc đó, câu trả lời thường trôi sang lời khuyên chung chung.

Nói rõ mức thay đổi nào là chấp nhận được

Các bản sửa accessibility thường phải đánh đổi với ràng buộc của design system. Hãy nói rõ agent có được phép:

• chỉ thay đổi markup
• chỉ thêm ARIA khi thật sự cần
• cấu trúc lại hierarchy của component
• chỉnh copy để rõ nghĩa hơn
• đổi pattern tương tác nếu thiết kế hiện tại không thể truy cập tốt

Điều này ảnh hưởng đến chất lượng kết quả nhiều hơn đa số người dùng nghĩ.

Lỗi thường gặp: lạm dụng ARIA

Một vấn đề rất dễ gặp trong công việc accessibility là thêm ARIA ở những chỗ native HTML làm tốt hơn. Để cải thiện đầu ra, hãy nói rõ:

• “Prefer native semantic elements and only use ARIA when native semantics are insufficient.”

Câu chỉ dẫn này khớp với tài liệu ARIA trong repository và giúp giảm các cách sửa kém chất lượng.

Lỗi thường gặp: quên các thay đổi trạng thái

Nhiều câu trả lời ở lượt đầu bắt được label và focus nhưng lại bỏ sót hành vi động. Hãy yêu cầu cụ thể:

• focus khi vào và khi trả về
• announcement cho trạng thái expanded/collapsed
• liên kết giữa lỗi validation và trường nhập
• thông báo trạng thái bất đồng bộ bằng live region
• reduced motion và high contrast nếu có liên quan

Các chi tiết này cải thiện đáng kể giá trị thực tế của accessibility-compliance guide.

Lặp thêm sau câu trả lời đầu tiên

Sau lượt audit ban đầu, hãy nối tiếp bằng một trong các yêu cầu sau:

• “Rewrite the component with the fixes applied.”
• “Prioritize only release-blocking issues.”
• “Convert this into QA test steps.”
• “Explain what should be tested with screen readers.”
• “Separate WCAG AA requirements from nice-to-have AAA improvements.”

Cách này biến skill từ một công cụ review thành một trợ lý hỗ trợ bàn giao thực tế.

Dùng tài liệu trong repository một cách có chọn lọc

Đừng đọc toàn bộ repository ngay từ đầu. Nếu vấn đề của bạn là:

• cấu trúc semantic hoặc mục tiêu tuân thủ: bắt đầu với references/wcag-guidelines.md
• hành vi widget hoặc role: mở references/aria-patterns.md
• vùng chạm hoặc AT trên mobile: mở references/mobile-accessibility.md

Lộ trình đọc có chọn lọc này giúp accessibility-compliance install và quá trình áp dụng diễn ra nhanh hơn.

Tăng độ tin cậy bằng cách yêu cầu giải thích lý do

Hãy yêu cầu skill giải thích vì sao từng cách sửa lại quan trọng với người dùng bàn phím, người dùng screen reader, người dùng thị lực kém hoặc người nhạy cảm với chuyển động. Cách này giúp phát hiện những bản sửa hời hợt và hỗ trợ team bảo vệ quyết định triển khai trong quá trình review.

Cách tốt nhất để nhận đầu ra sẵn sàng cho production

Để có accessibility-compliance usage giá trị cao nhất, hãy yêu cầu tất cả các mục sau trong một lượt:

• phát hiện đã được ưu tiên theo mức độ
• code đã chỉnh sửa
• giải thích lý do
• checklist xác minh thủ công
• rủi ro hoặc giả định còn lại

Đó mới là gói đầu ra mà đa số team thực sự cần để đi từ “chúng ta nên cải thiện accessibility” sang “chúng ta có thể triển khai và kiểm chứng việc này ngay bây giờ.”