Dym Diagram Design Authoring In Chat

Skill: dym-diagram-design-authoring-in-chat — Vẽ sơ đồ bằng chat (không có CLI cho việc này)

Vì sao dùng: đây là công dụng chính của tool. Không có lệnh shell nào tạo sơ đồ — việc chọn loại, chọn nội dung và viết SVG là do agent làm, dựa trên SKILL.md và các file references/type-*.md.

File này sinh ra gì: một file .html tự chứa (inline SVG + inline CSS), mở được bằng file://, không cần build, không cần server.

Toàn bộ file này là câu gõ trong chat. Đừng dán vào terminal. Phần shell nằm ở 04 và 06.

1. Câu gõ tối thiểu

Make me an architecture diagram of my app: frontend, backend, database, Redis cache.
I need a quadrant showing Q2 projects by impact vs effort.
Give me a sequence of a bearer call with token refresh on 401.

Agent sẽ: chọn loại → nạp references/type-<loại>.md tương ứng → xác nhận với bạn trước khi vẽ → dựng HTML → lưu file.

Bước xác nhận là bắt buộc theo SKILL.md §3 ("Confirm before drawing"). Nếu agent vẽ luôn không hỏi, nó đang bỏ qua skill.

2. Chọn loại — 39 lựa chọn, chọn theo thứ bạn đang thể hiện

SKILL.md §3 không hỏi "bạn muốn sơ đồ gì" mà hỏi "bạn đang cho thấy cái gì". Bảng rút gọn theo nhóm:

Cấu trúc & hệ thống

Luồng & thời gian

Dữ liệu

Định lượng

Ba quy tắc ngón tay cái, nguyên văn SKILL.md §3:

• Nếu một bảng 3 cột nói được điều tương tự, chọn bảng.
• Hai loại cùng hợp lý → chọn theo trục trội. Semantic pattern có thể thêm primitive, không thêm ngữ pháp bố cục thứ hai.
• Vượt ngân sách độ phức tạp (§7) → tách thành overview + detail.

3. Semantic pattern — chọn hành vi trước, hình dạng sau

Khi hành vi mới là thứ quan trọng, skill chọn semantic pattern trước rồi mới chọn visual type. Bảy pattern được định tuyến (references/semantic-patterns.md):

1. Hàng đợi fan-in và nút thắt cổ chai
2. Ô stage lặp lại
3. Biến đổi đầu vào phi cấu trúc
4. Vết chính sách theo cặp (paired policy trace)
5. Paved road bảo mật
6. Catalog quản trị
7. Lớp bảo mật bù trừ (compensating)

Mỗi pattern tự khai: trigger, primitive, ngân sách, anti-pattern, fallback tĩnh, và visual type gần nhất.

Ví dụ gõ:

Show the ingestion queue with its bottleneck — use the fan-in semantic pattern.
Draw the paved road for our deploy path, with the compensating controls layered on.

4. Chuyển động (motion) — mặc định TẮT

references/animation.md định nghĩa 4 mode: none (mặc định), reveal, step, loop. Luật cứng:

• Output thường là tĩnh và không script. Motion phải được yêu cầu rõ ràng.
• Mọi file có motion phải có khung tĩnh đầu tiên hoàn chỉnh và timing tất định.
• prefers-reduced-motion → hiện khung tĩnh đầy đủ, ẩn/vô hiệu nút điều khiển.
• HTML motion dùng đúng controller đã review trong template-motion.html, verbatim. Script inline tuỳ ý, asset từ xa, CSS @import, và thuộc tính HTML thực thi được đều bị từ chối (linter lint-skin.py chặn cứng — xem 06).
• ADR 0003: reveal là autoplay duy nhất được phép.

Gõ:

Make it animated with the reveal mode, respecting reduced motion.

Ví dụ tự chứa để xem trước: skills/diagram-design/assets/example-policy-trace-animated.html.

5. Bốn núm chỉnh — nói ra thì được đúng ý ngay

Bốn "dial" này áp cho cả sơ đồ mới lẫn sơ đồ import (references/output-spec.md):

audience chi phối cách dùng từ, không phải số phần tử — đây là chỗ rất hay bị hiểu nhầm.

Bảng viewBox thật (output-spec.md §2):

Gõ:

Same diagram at slide-16x9, simplified, executive audience.

6. Bắt đầu từ template thay vì từ con số 0

Ba template này copy bằng shell nhưng điền bằng chat — nên để ở đây cho liền mạch:

cp skills/diagram-design/assets/template.html        my-diagram.html  # light tối giản
cp skills/diagram-design/assets/template-full.html   my-diagram.html  # editorial + summary card
cp skills/diagram-design/assets/template-motion.html my-diagram.html  # có motion, accessible

Rồi gõ trong chat: "fill my-diagram.html with an architecture diagram of …".

7. Những gì skill sẽ TỪ CHỐI làm (và vì sao)

SKILL.md §4 "Universal Anti-patterns" và §9 "Pre-Output Checklist (Taste Gate)" chạy trước khi ghi file. Triết lý một câu, nguyên văn: "The highest-quality move is usually deletion."

Ba thứ được bảo đảm ở mọi output:

• Accessible SVG: role="img", aria-labelledby phân giải được, <title>/<desc> là con đầu tiên. ID có tiền tố theo sơ đồ và theo biến thể, để nhiều SVG inline chung một trang không giành nhau accessible name. Icon trang trí bị ẩn khỏi assistive tech.
• Một file, không phụ thuộc ngoài: không asset từ xa ngoài stylesheet Google Fonts đã duyệt, không script ngoài controller motion chính tắc, không thuộc tính thực thi được.
• Lưới 4px và ngân sách độ phức tạp cho từng loại.

Nếu bạn ép nó vượt ngân sách, nó sẽ đề xuất tách overview + detail chứ không nhồi.

8. Xong bước này khi

• Có một file .html mở bằng file:// hiển thị đúng.
• Chạy python3 <skill-dir>/scripts/self_check.py file.html được OK (xem 06).
• Màu trong file là brand của bạn, không phải atomic-tangerine.

Tiếp theo: đã có sơ đồ từ draw.io/Mermaid thì sang 04/05; muốn xuất PNG/SVG thì 05; muốn khoá chất lượng bằng CI thì 06.