Ds Architect

🔒 primitives/   — Raw values. Agent KHÔNG tự thêm.
🔒 shared/       — Cross-cutting presets. Agent KHÔNG tự thêm.
🟡 modes/        — light/dark mapping. Chỉ thêm khi User đồng ý.
🟡 themes/       — Brand overrides. Chỉ thêm khi User đồng ý.
🟢 style-modes/  — Density. OK thêm, PHẢI đủ 22 keys.
🟢 styles/       — Visual overrides. OK thêm, PHẢI ref primitives.

TOKEN CHANGE LOG:
- Action     : CREATE | MODIFY | DELETE
- File       : tokens/{tier}/{file}.tokens.json
- Token      : {full.token.path}
- Value      : "{ref.path}" (→ giải thích ref tới đâu)
- Reason     : [mô tả ngắn gọn]
- Approved by: User

Lưu tại : knowledge/{client}_design_intent.md
Tạo khi  : Nhận PDR / brief chưa tồn tại trong DS
Nội dung : Phần §1 DESIGN INTENT + §3 LAYOUT MAPPING đã điền đầy đủ
Format   : DESIGN INTENT EXTRACTION template (style-scaling §1)
Consumer : style-scaling §2-5, component-lifecycle skill

Lưu tại : knowledge/ds_gap_report_{YYYY-MM-DD}.md
Tạo khi  : Có ít nhất 1 GAP-NNN trong §5 Risk Report
Nội dung : Tất cả GAP-NNN entries dùng format token-governance §8
           + severity levels (BLOCKER / WARNING / INFO)
           + workaround đang dùng (nếu có)
Consumer : User review → approve → dev-journal Audit Trail
Status   : PROPOSED | USER_APPROVED | IMPLEMENTED

Lưu tại : design-system/tokens/themes/{client}.tokens.json
Tạo khi  : User đã approve brand mới sau gap review
Nội dung : Copy vnpay.tokens.json → batch replace refs
           Phải pass: style-scaling §4 Theme Contract Checklist
Consumer : sync-tokens.js, post-change, dev-journal

Lưu tại : Inline trong response (KHÔNG tạo file riêng trừ khi User yêu cầu)
Tạo khi  : Bất kỳ khi chạy §4 Compliance Validation
Format   : token-reviewer §7 Compliance Report Template
Consumer : post-change step 3, dev-journal

Lưu tại : knowledge/ux_audit_{YYYY-MM-DD}.md
Tạo khi  : User yêu cầu UX audit / a11y audit / component UX review
Nội dung : Scoring matrix 11 domains, grade, critical/major/minor issues
Format   : ux-research skill Audit Report Template
Consumer : UX debt backlog, dev-journal, component improvement

Output có >10 tokens được map?
  YES → Tạo file knowledge/{client}_token_mapping.md
  NO  → Inline trong response

Có gaps cần User approve?
  YES → Tạo ds_gap_report_{date}.md TRƯỚC khi tiếp tục
  NO  → Tiếp tục luồng

User confirm token mới?
  YES → Tạo token JSON file + chạy /post-change
  NO  → Dừng lại, ghi rõ lý do vào response

Tạo / sửa / chỉnh component, CSS, HTML, hoặc showcase?
  YES → ĐỌC ux-research SKILL.md TRƯỚC khi code
     → Check: §6 font-size (T1 ≥14px), §7 ARIA/focus, §5 states, §2 interaction
     → Áp dụng rules TRONG LÚC code, không chờ post-change
  User yêu cầu FULL UX audit (scoring matrix)?
    YES → Chạy full audit → tạo ux_audit_{date}.md
    NO  → Vẫn PHẢI tuân thủ §5 §6 §7 inline — không optional