ai-developer-skill-os 9.1.1 → 9.3.0

package/.agents/skills/qk-ui-system-builder/SKILL.md

@@ -1,9 +1,9 @@
----
+---
 # ── Identity ───────────────────────────────────────────────
 name: qk-ui-system-builder
-version: 9.1.0
+version: 9.2.0
 status: stable
-description: "Xây dựng Design System và token library từ DESIGN.md — không tự đặt ra token ngoài contract."
+description: "Xây dựng Design System và token library từ DESIGN.md — không tự đặt ra token ngoài contract. Dùng skill này khi user nhắc đến: design system, token, setup css, ui system, tạo design system, cấu hình token — kể cả khi chỉ nói 'tạo file tailwind tokens từ bảng màu này'."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 # ── V9: Classification ─────────────────────────────────────
@@ -21,11 +21,14 @@ complexity:
     has_external_dependency: false
     has_breaking_change: false
 
-triggers:
-  - "tạo design system"
-  - "build token"
-  - "ui system"
-  - "setup css"
+triggers:
+  - "design system"
+  - "token"
+  - "setup css"
+  - "ui system"
+  - "tạo design system"
+  - "cấu hình token"
+
 
 # ── V8: References ─────────────────────────────────────────
 workflow: feature-delivery
@@ -83,467 +86,98 @@ produces: [code, tokens]
 consumes: [design-md]
 
 token_budget:
-  max_files_read: 2
-  max_lines_per_read: 100
+  max_files_read: 3
+  max_lines_per_read: 150
   max_shell_commands: 0
   stop_early: true
 
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
 
-# qk-ui-system-builder — Design System Constructor
+# qk-ui-system-builder — Design System & Token Constructor
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
+Chịu trách nhiệm hiện thực hóa hệ thống Design Tokens (màu sắc, typography, spacing, shadows, radius) thành mã nguồn (CSS Variables, Tailwind Config, hoặc TypeScript Tokens) dựa trên tài liệu thiết kế (`DESIGN.md`). **Tuyệt đối không tự ý bịa đặt token ngoài hợp đồng thiết kế.**
+
 ---
 
-## Memory Workflow
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Architecture / Convention (vd: ánh xạ 1:1 từ contract DESIGN.md sang biến CSS).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Chuẩn quy tắc đặt tên (--color-role-shade) hoặc cơ chế scale Dark Mode.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Giá trị màu thử nghiệm ngoài hợp đồng (bị nghiêm cấm).
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Architecture / Convention (vd: ánh xạ 1:1 từ contract DESIGN.md sang biến CSS).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Chuẩn quy tắc đặt tên (--color-role-shade) hoặc cơ chế scale Dark Mode.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Giá trị màu thử nghiệm ngoài hợp đồng (bị nghiêm cấm).
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Chuẩn quy tắc đặt tên (--color-role-shade) hoặc cơ chế scale Dark Mode.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Giá trị màu thử nghiệm ngoài hợp đồng (bị nghiêm cấm).
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Chuẩn quy tắc đặt tên (--color-role-shade) hoặc cơ chế scale Dark Mode.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Giá trị màu thử nghiệm ngoài hợp đồng (bị nghiêm cấm).
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
----
----
-
 ## Preconditions
-- [ ] `DESIGN.md` exists with color, spacing, typography tokens
 
-```
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "DESIGN.md missing. Run qk-project-bootstrap to create one."
-```
+Trước khi tạo hoặc sửa đổi file token, AI BẮT BUỘC kiểm tra:
 
----
-
-## Scope
-- ✅ Extract tokens from DESIGN.md ONLY — never invent
-- ✅ Generate CSS custom properties (variables) or framework theme
-- ✅ Ensure all components are accessible (A11y)
-
-## Non-Goals
-- ❌ Invent tokens not in DESIGN.md (e.g., standard Tailwind defaults)
-- ❌ Create duplicate tokens for same visual value
-- ❌ Generate component library without token foundation
+- [ ] Tìm và đọc file đặc tả thiết kế (`DESIGN.md` hoặc styleguide document).
+- [ ] Xác định CSS framework đang sử dụng từ `.agents/DEV_PROFILE.md` (Tailwind CSS, CSS Modules, Styled Components, Vanilla CSS).
+- [ ] Kiểm tra xem đã có hệ thống tokens cũ chưa (tránh ghi đè làm vỡ giao diện đang chạy).
+- [ ] Nếu không có `DESIGN.md` và user không cung cấp giá trị màu sắc/kích thước cụ thể:
+  → **EXIT: BLOCKED**
+  → Báo cáo user yêu cầu cung cấp bảng màu (Palette) hoặc file quy chuẩn thiết kế trước.
 
 ---
 
-## Token Naming Convention
-
-```css
-/* Colors — HSL always */
---color-[role]-[shade]: hsl(H, S%, L%);
-/* Example: */
---color-primary-500: hsl(220, 80%, 55%);
---color-surface-100: hsl(220, 15%, 98%);
-
-/* Spacing — scale-based */
---space-[n]: [n * base]px;
-/* Example: */
---space-1: 4px; --space-2: 8px; --space-4: 16px;
-
-/* Typography */
---font-[family]: '[Name]', fallback;
---font-size-[scale]: [value]rem;
---font-weight-[name]: [value];
-
-/* Border Radius */
---radius-[size]: [value]px;
-
-/* Shadows */
---shadow-[level]: [value];
-
-/* Animation */
---duration-[speed]: [value]ms;
---ease-[type]: [cubic-bezier or keyword];
-
-/* Z-index */
---z-[layer]: [value];  /* dropdown=100, modal=200, toast=300 */
-```
+## Scope
 
----
+✅ Skill này làm:
+- Chuyển đổi mã màu Hex/HSL thành semantic CSS custom properties (`--color-primary`, `--color-surface-base`).
+- Cấu hình file `tailwind.config.js` / `tailwind.config.ts` khớp chính xác với Design Tokens.
+- Khai báo token cho Spacing (bội số của 4px/8px), Font sizes, Border Radius, Shadows, Transitions.
+- Tạo theme hỗ trợ Light/Dark mode qua CSS variables.
+- Xuất type definition TypeScript cho autocomplete token trong code.
 
-## Dark/Light Mode Pattern
-```css
-:root {
-  --color-background: hsl(0, 0%, 100%);
-  --color-text: hsl(220, 15%, 10%);
-}
-
-[data-theme="dark"] {
-  --color-background: hsl(220, 15%, 10%);
-  --color-text: hsl(220, 10%, 90%);
-}
-```
+❌ Skill này KHÔNG làm:
+- Dựng các màn hình hay component hoàn chỉnh (→ `qk-ui-builder`).
+- Định nghĩa chiến lược quy chuẩn thiết kế cấp cao (→ `qk-design-system-engineering`).
+- Sửa đổi business logic backend.
 
 ---
 
-## Workflow
-
-### Phase 1 — Extract from DESIGN.md
-1. Read DESIGN.md → list all defined tokens
-2. Categorize: Colors / Spacing / Typography / Radius / Shadow / Animation
-
-### Phase 2 — Generate Token File
-1. Create `src/styles/tokens.css` (or equivalent)
-2. Apply naming convention above
-3. Add dark mode variants if DESIGN.md specifies
+## Execution Steps
 
-### Phase 3 — Verify No Invented Tokens
-1. Cross-check: every generated token has source in DESIGN.md
-2. Flag any token that was "inferred" vs explicitly defined
-
-**Decision:**
+### Step 1 — Parse Design Specs & Contracts
 ```
-IF all tokens sourced from DESIGN.md → EXIT: SUCCESS
-IF some tokens inferred (MEDIUM confidence) → EXIT: PARTIAL, list them
+Inputs:  DESIGN.md, Bảng màu từ user
+Actions:
+  - Trích xuất: Primitive tokens (Brand colors, Neutrals, Font families).
+  - Trích xuất: Semantic tokens (Background, Foreground, Border, Primary, Destructive).
+  - Phân loại thang đo Spacing, Radius và Elevation (box-shadow).
+Output: Structured Token Contract
 ```
 
----
-
----
-
-## Priority Order
-
----
-
-## Output Format
-
----
-## Exit Codes
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | All tokens extracted from DESIGN.md, naming convention applied | All generated |
-| PARTIAL | Some tokens inferred (not explicitly in DESIGN.md) | Inferred values used |
-| BLOCKED | DESIGN.md missing or has no tokens | Cannot start |
-| FAILED | Token conflicts detected (duplicate values, naming collision) | Conflict |
-
----
-
-## Confidence Model
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | Token explicitly exists in DESIGN.md | Extract and map |
-| MEDIUM | Token value inferred or estimated based on related tokens | Note assumption |
-| LOW | Core scale missing entirely (e.g. no spacing definition) | EXIT: BLOCKED |
-
----
-
-## Severity
-| Level | Definition | Example |
-|-------|-----------|---------|
-| CRITICAL | Hardcoded values injected without being tokens | Missing the point of the system |
-| HIGH | Token naming convention violated | `primary-color` instead of `--color-primary` |
-| MEDIUM | Dark mode not supported | Hardcoded white background |
-| LOW | Unused token generated | Extraneous variables |
-
----
-
-## Evidence Format
+### Step 2 — CSS Variable & Theme Definition
 ```
-[SEVERITY] src/styles/tokens.css:LINE
-Issue:      [specific violation or gap]
-Confidence: HIGH
-Fix:        [specific change]
+Inputs:  Structured Token Contract
+Actions:
+  - Khởi tạo `:root` chứa biến màu Light mode.
+  - Khởi tạo `.dark` hoặc `[data-theme="dark"]` chứa biến màu Dark mode tương ứng.
+  - Bảo đảm tỉ lệ tương phản đạt chuẩn WCAG AA giữa Foreground và Background.
+Output: globals.css / theme.css
 ```
 
----
-
-## Retry Policy
+### Step 3 — Framework Config Integration
 ```
-Token generation fails
-  └─ Check if naming collision or syntax error
-       ├─ Syntax error → fix CSS/SCSS format → retry
-       └─ Collision → deduplicate → retry
-            └─ Do NOT auto-retry more than 1 time
+Inputs:  globals.css, Tailwind config (hoặc tương đương)
+Actions:
+  - Mở rộng (extend) theme của Tailwind: colors, spacing, borderRadius, fontSize.
+  - Ánh xạ trực tiếp sang `var(--...)` để tận dụng tính năng theme switching động.
+Output: tailwind.config.ts / tokens.ts
 ```
 
----
-
-## Escalation Rules
+### Step 4 — Verification & Type Generation
 ```
-BLOCKED: DESIGN.md missing or empty
-Missing:
-  - Valid DESIGN.md with token specifications
-Questions:
-  1. Bạn có file design reference nào khác không?
-Recommended Assumptions:
-  - Generate default Tailwind-like scale if requested
+Inputs:  Generated config files
+Actions:
+  - Kiểm tra cú pháp config file.
+  - Đảm bảo token types được export rõ ràng cho IDE autocomplete.
+Exit: SUCCESS
 ```
 
 ---
 
-## Handoff Contract
-### Consumes
-```json
-{
-  "from": "user or project-bootstrap",
-  "required_fields": ["design_md_path"],
-  "optional_fields": ["css_framework", "output_format"]
-}
+## Prompt Template
+
 ```
-### Produces
-```json
-{
-  "to": "user or design-to-code",
-  "output_fields": ["token_file_path", "inferred_tokens", "exit_code"]
-}
+Tài liệu thiết kế: [Đường dẫn DESIGN.md hoặc paste bảng màu]
+Framework CSS:     [Tailwind CSS / CSS Modules / Vanilla CSS]
+Dark Mode:         [Có hỗ trợ không — class / data-theme / media query]
+Yêu cầu riêng:     [Cần bổ sung font chữ mới, radius đặc biệt, ...]
 ```
-
----
-