ai-developer-skill-os 2.0.1 → 3.0.0

package/skills/qk-ui-audit/SKILL.md

@@ -1,152 +1,58 @@
----
-name: qk-ui-audit
-purpose: Kiểm toán giao diện (Consistency, Accessibility, Responsive).
-mode_supported: [standard]
-input: [UI Code]
-output: [Audit Report]
-workflow: [1. Check Radius/Color -> 2. Check A11y -> 3. Check Mobile]
-allowed_tools: [read_file]
-handoff_to: [none]
----
-
-# 🛠️ qk-ui-audit - Quy Trình Vận Hành Chuẩn (SOP)
-
-> **Mô tả:** Kiểm toán giao diện (Consistency, Accessibility, Responsive).
-
-## 🎯 1. Mục Tiêu (Goal)
-- Hoàn thành thành công tác vụ được giao liên quan đến nhiệm vụ của skill.
-- Đảm bảo chất lượng mã nguồn và tính nhất quán của hệ thống.
-
-## 🔄 2. Chuỗi Hành Động (Chain of Thought / SOP)
-*(Bắt buộc AI phải suy nghĩ và làm theo đúng thứ tự)*
-1. **Phân tích (Analyze):** Thu thập ngữ cảnh và hiểu rõ yêu cầu đầu vào.
-2. **Lên kế hoạch (Plan):** Xác định các bước cần thay đổi/tạo mới dựa trên bộ luật (rules).
-3. **Thực thi (Execute):** Tiến hành sửa đổi mã nguồn hoặc tạo tài liệu.
-4. **Xác thực (Verify):** Đảm bảo đầu ra đáp ứng đúng yêu cầu và không vi phạm quy định.
-
-## 🛡️ 3. Ràng Buộc & Quy Tắc (Constraints)
-- CẤM bỏ qua việc kiểm tra `qk-engineering-standard` trước khi viết code.
-- Mọi quyết định kỹ thuật phải dựa trên nội dung tại phần Deep Knowledge (nếu có).
-
-## 🤝 4. Giao Thức Bàn Giao (Handoff Protocol)
-- Đích đến: `none`
-- Nội dung bàn giao: Chuyển toàn bộ ngữ cảnh và kết quả đã thực thi cho bước tiếp theo.
-
-## 📚 5. Kiến Thức Chuyên Sâu (Deep Knowledge)
-
-*(Nền tảng kiến thức và quy tắc chi tiết kế thừa từ kỹ sư)*
-
----
-
-
-
-# Accessibility (A11y) Audit
-
-> **Language rule:**
-> Use English for: code, identifiers, file names, architecture terms, technical decisions.
-> Use the user's language for: explanations, questions, summaries, and feedback.
-> The user may write in any language — detect and match it automatically.
-
----
-
-## Trigger
-
-Activate this skill when:
-- User asks to "make this accessible", "fix a11y", or "audit accessibility"
-- Building complex interactive components (modals, dropdowns, tabs, sliders)
-- Preparing an app for production or public release
-- Project audit flags missing semantic HTML or ARIA issues
-
----
-
-## Scope
-
-- ✅ **Keyboard Navigation:** Ensure all interactive elements are reachable via `Tab`, and operable via `Enter`/`Space`/Arrows. Focus management (trapping focus in modals).
-- ✅ **Screen Reader Support:** Add proper `aria-` attributes, `alt` text, and visually hidden text (`sr-only`).
-- ✅ **Semantic HTML:** Replace `div` soups with `<nav>`, `<main>`, `<article>`, `<button>`, etc.
-- ✅ **Color Contrast:** Verify text vs. background contrast meets WCAG AA (4.5:1 for normal text).
-- ✅ **Form Labels:** Ensure all inputs have associated `<label>`s or `aria-label`s.
-
----
-
-## Non-goals
-
-- ❌ Do NOT completely redesign the UI visually (unless fixing a severe contrast issue, and even then, ask first).
-- ❌ Do NOT overuse ARIA. The first rule of ARIA is: "No ARIA is better than bad ARIA." Use semantic HTML first.
-
----
-
-## Workflow
-
-### Phase 1 — Semantic HTML Check
-
-Scan the component for basic HTML semantics:
-- Are buttons actually `<button>` elements (not `<div onClick>`)?
-- Are links actually `<a>` elements with `href`s?
-- Do images have meaningful `alt` text (or `alt=""` if decorative)?
-- Are headings (`h1`-`h6`) in a logical, unbroken hierarchy?
-
-### Phase 2 — Keyboard & Focus Management
-
-- Can the user tab through the component logically?
-- Does every interactive element have a visible focus state (`:focus-visible`)?
-- For Modals/Dialogs: Is focus trapped inside when open? Is focus restored when closed?
-- For custom widgets (Tabs/Dropdowns): Implement correct arrow key navigation per WAI-ARIA authoring practices.
-
-### Phase 3 — Screen Reader (ARIA) Check
-
-- Do custom interactive elements have correct `role`s (e.g., `role="tablist"`)?
-- Is dynamic state communicated? (`aria-expanded`, `aria-selected`, `aria-invalid`, `aria-busy`).
-- Are icon-only buttons properly labeled? (`aria-label` or `<span className="sr-only">Label</span>`).
-- Are dynamic live regions used for important announcements (`aria-live="polite"` or `assertive`)?
-
-### Phase 4 — Contrast & Visuals
-
-- Check text colors against backgrounds.
-- Ensure form fields have visible borders or indicators.
-- Ensure information is not conveyed *only* by color (e.g., a red border for an error must also have error text).
-
----
-
-## Decision Tree
-
-```
-Is the component a native HTML element (e.g., standard `<button>`)?
-  ├── Yes → Ensure it has accessible text/labels. No ARIA roles needed.
-  └── No  → (e.g., a custom `div` acting as a checkbox)
-              ├── Can it be refactored to use native HTML?
-              │     ├── Yes → Refactor to native HTML `<input type="checkbox">`
-              │     └── No  → Apply `role="checkbox"`, `tabIndex={0}`, `aria-checked`, and keyboard event handlers.
-```
-
----
-
-## Output Format
-
-```
-♿ Accessibility Audit Report
-─────────────────────────────────────────────────
-Component:  [ComponentName]
-
-Issues Found & Fixed:
-  ✅ Semantic HTML: Replaced `<div onClick>` with `<button>`
-  ✅ Screen Readers: Added `aria-label` to icon-only close button
-  ✅ Keyboard: Added focus trap inside the Modal
-  ✅ Forms: Associated `<label htmlFor="email">` with Input
-
-⚠️ Remaining Warnings (Manual Check Required):
-  - Please verify color contrast of primary button in light mode (needs 4.5:1 ratio).
-
-🔗 Next Steps:
-  Code updated. Recommend testing with a screen reader (VoiceOver/NVDA).
-```
-
----
-
-## Validation Checklist
-
-- [ ] Semantic HTML preferred over ARIA
-- [ ] Keyboard navigation (Tab + Enter/Space) works correctly
-- [ ] Focus is visible on all interactive elements
-- [ ] Forms have proper labels
-- [ ] Icon-only buttons have accessible names
+---
+name: qk-ui-audit
+version: 3.0.0
+updated: 2026-07-02
+description: Audit UI for Consistency, Accessibility, Responsive, and Performance.
+category: validation
+priority: medium
+tags: [ui, audit, frontend, a11y, responsive]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: User asks to check the UI, review styling, or run an audit on a component.
+inputs: [Target UI component, File path]
+outputs: [UI Audit Score, Fix recommendations]
+allowed_tools: [grep_search, read_file]
+pipeline: [analyze, review, validate, complete]
+---
+
+# 🛠️ qk-ui-audit - Standard Operating Procedure
+
+> **Goal:** Kiểm toán chất lượng Giao diện Người dùng (UI QA). Tìm ra các lỗi hiển thị, sự thiếu đồng nhất và vi phạm Accessibility (a11y).
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze (Scan UI):**
+   - Read the UI component's source code.
+   - Look for inline styles (`style={{...}}`) and hardcoded magic numbers (e.g., `px`, `%` instead of standard tokens).
+2. **Review (Consistency & Responsive):**
+   - Check if standard Design System tokens (e.g., Tailwind classes like `p-4`, `text-lg`) are used.
+   - Check for mobile-first implementation (e.g., base classes for mobile, `md:` for desktop).
+3. **Validate (Accessibility - A11y):**
+   - Verify `<img>` tags have `alt` attributes.
+   - Verify `<button>` tags without text have `aria-label`.
+   - Verify interactive `<div>` elements have `role="button"` and `tabIndex`.
+4. **Complete (Report):**
+   - Calculate a rough score (0-100) based on violations.
+
+## 🛡️ 2. Constraints & Rules
+- **Audit Only:** Do not modify the code automatically unless the user explicitly requests you to apply the fixes.
+- **Evidence Based:** Point out the exact line number where the violation occurs.
+
+## 🌳 3. Decision Tree
+```text
+Does the component contain hardcoded `#hex` colors or `px` values?
+  ├── YES → Deduct Consistency score. Recommend using Design Tokens.
+  └── NO → Pass.
+
+Does the component have clickable `<div>` elements?
+  ├── YES → Deduct A11y score. Recommend using `<button>` or adding roles.
+  └── NO → Pass.
+```
+
+## 🤝 4. Handoff Pipeline
+1. `complete`: Generate the UI Audit Report.
+
+## 📝 5. Output Format
+Vui lòng trả kết quả bằng Tiếng Việt.
+- **Tóm tắt (Summary):** Chấm điểm Giao diện (Score: X/100).
+- **Chi tiết (Changes):** Liệt kê các lỗi Consistency, A11y, Responsive (ghi rõ dòng).
+- **Nguyên nhân (Reasoning):** Tại sao lại đánh lỗi điểm đó.
+- **Hành động tiếp (Next Action):** Hỏi User có muốn tự động sửa các lỗi này không.