Visualize Skill Guide

Hướng dẫn cho dev viết skill prompt sử dụng hệ thống Visualize. Hệ thống hỗ trợ 3 loại: Native Components, SVG Diagrams, và HTML Widgets — mỗi loại phù hợp cho use case khác nhau.

---

Khi nào dùng loại nào

Loại	Sức mạnh	Use case	Module
Native	Nhanh, theme-consistent, dark mode sẵn	Hiển thị data có cấu trúc (giá, list, chart đơn giản)	native
SVG	Diagram tùy chỉnh, flowchart, minh họa kiến trúc	Giải thích quy trình, hệ thống, chuỗi giá trị	diagram, art
HTML	Interactive, Chart.js/D3, mọi thứ phức tạp	Dashboard, biểu đồ kỹ thuật, interactive calculator	chart, mockup, interactive

SVG — giải thích visual

Dùng khi cần vẽ diagram, flowchart, kiến trúc hệ thống, chuỗi giá trị, minh họa concept. LLM tự viết SVG code với pre-built classes (.c-blue, .box, .arr...) — tự động dark mode.

Ví dụ use cases:
- "Vẽ chuỗi giá trị HPG" → SVG flowchart
- "Kiến trúc hệ thống microservices" → SVG structural diagram
- "Giải thích cách hoạt động của margin trading" → SVG illustrative
- "So sánh mô hình kinh doanh A vs B" → SVG structural

HTML — interactive & charts phức tạp

Dùng khi cần Chart.js, D3 maps, interactive controls, calculator, dashboard layout. Render trong iframe sandboxed, hỗ trợ CDN libraries.

Ví dụ use cases:
- "Biểu đồ kỹ thuật RSI + MACD + Bollinger" → HTML + Chart.js
- "Dashboard tổng quan thị trường" → HTML + multiple charts
- "Bản đồ nhiệt ngành" → HTML + D3
- "Calculator lãi kép" → HTML interactive
- "So sánh timeline giá 5 cổ phiếu" → HTML + Chart.js multi-series

Native — data có cấu trúc

Dùng khi data khớp với 1 trong các component có sẵn. Không cần LLM viết code — chỉ truyền JSON.

Ví dụ use cases:
- "Giá HPG bao nhiêu?" → asset_card
- "Định giá HPG" → valuation_chart
- "So sánh P/E HPG với ngành" → peer_comparison
- "Tỷ trọng danh mục" → donut_chart
- "Kế hoạch giao dịch hôm nay" → list (grouped)

---

Workflow chung

Agent cần 2 bước:

1. visualize_read_me(modules=[...], components=[...]) — load design system + schema
2. visualize_show_chart(widget_code=..., title=..., loading_messages=[...], i_have_seen_read_me=true) — render

widget_code chấp nhận 3 loại content (auto-detect):

• JSON có "component" key → Native
• Bắt đầu <svg → SVG
• Còn lại → HTML

---

Viết Skill Prompt

Bước 1: Xác định module cần load

Cần vẽ gì	Modules
Native component	modules=['native']
SVG diagram	modules=['diagram']
SVG illustration	modules=['diagram'] hoặc modules=['art']
Chart.js chart	modules=['chart']
Interactive widget	modules=['interactive']
UI mockup	modules=['mockup']
Native + chart kết hợp	modules=['native', 'chart']

Bước 2: Viết reminder trong skill prompt

Dạng SVG diagram:

Visualize using SVG diagram.
Call visualize_read_me(modules=['diagram']) for design system.
Draw a flowchart/structural diagram showing the process.

Dạng HTML Chart.js:

Visualize using Chart.js.
Call visualize_read_me(modules=['chart']) for setup guide.
Create a bar/line/pie chart with the data.

Dạng Native component:

Visualize using native component 'valuation_chart'.
Call visualize_read_me(modules=['native'], components=['valuation_chart']) for schema.
Set context: "valuation".

Dạng kết hợp nhiều loại:

Visualize with multiple types:
- Native 'stat' for KPI summary
- Chart.js for price trend chart
- Native 'list' for trade recommendations
Call visualize_read_me(modules=['native', 'chart'], components=['stat', 'list']).

---

Component & Module Reference

Native Components (modules=['native'])

Component	Mô tả	Filter
stat	Grid KPI cards (2-4 metrics)	components=['stat']
list	List simple hoặc grouped (MUA/BÁN)	components=['list']
valuation_chart	Biểu đồ định giá (green/yellow/red)	components=['valuation_chart']
asset_card	Ticker info + mini chart	components=['asset_card']
peer_comparison	Bar chart so sánh ngành	components=['peer_comparison']
donut_chart	Pie/donut tỷ trọng	components=['donut_chart']
line_chart	Line chart + markers	components=['line_chart']
card_list	Cards slider (media/report/default)	components=['card_list']

SVG Modules

Module	Khi nào dùng	Có gì trong read_me
diagram	Flowchart, structural, illustrative	ViewBox setup, pre-built classes, arrow markers, font calibration, diagram types
art	Illustration, generative art	Canvas filling, organic shapes, color freestyle

HTML Modules

Module	Khi nào dùng	Có gì trong read_me
chart	Chart.js, D3 choropleth maps	Canvas sizing, UMD loading, legend patterns, number formatting
mockup	UI components, forms, cards	Tokens, metric cards, layout patterns
interactive	Sliders, steppers, calculators	Streaming rules, sendPrompt, stepper pattern

Context (CTA button)

Context	CTA Label	URL
stock	Xem phân tích 360 trên Simplize	/co-phieu/{ticker}/phan-tich
valuation	Xem phân tích 360 trên Simplize	/co-phieu/{ticker}/phan-tich
portfolio	Xem danh mục trên Simplize	/portfolio/{id}
nebula	Xem chi tiết Nebula	/nebula
watchlist	Xem danh sách quan sát	/watchlist
market	Xem thị trường	/market
peer	Xem so sánh ngành	/co-phieu/{ticker}/phan-tich

---

Decision Tree cho dev

Dữ liệu cần hiển thị là gì?
│
├─ Giải thích quy trình / kiến trúc / concept?
│  └─ SVG → modules=['diagram']
│
├─ Biểu đồ kỹ thuật phức tạp (multi-axis, indicators)?
│  └─ HTML + Chart.js → modules=['chart']
│
├─ Dashboard / interactive calculator?
│  └─ HTML → modules=['interactive'] hoặc modules=['chart', 'mockup']
│
├─ Bản đồ địa lý?
│  └─ HTML + D3 → modules=['chart']
│
├─ Data khớp native component?
│  ├─ Giá + chart → asset_card
│  ├─ Định giá → valuation_chart
│  ├─ So sánh ngành → peer_comparison
│  ├─ Tỷ trọng → donut_chart
│  ├─ Performance → line_chart
│  ├─ News / reports → card_list
│  ├─ List items → list
│  ├─ KPI numbers → stat
│  └─ modules=['native'], components=[...]
│
└─ Bảng dữ liệu?
   └─ Markdown table (không cần visualize)

---

Ví dụ mapping skill → visualize

Skill	Loại	Module	Component/Approach
Định giá cổ phiếu	Native	native	valuation_chart
Phân tích kỹ thuật	HTML	chart	Chart.js multi-panel (RSI, MACD, BB)
Chuỗi giá trị doanh nghiệp	SVG	diagram	Flowchart structural
So sánh cổ phiếu cùng ngành	Native	native	peer_comparison
Xây dựng danh mục Nebula	Native	native	list + donut_chart
Dashboard thị trường	HTML	chart, mockup	Chart.js + metric cards
Giải thích margin trading	SVG	diagram	Illustrative diagram
Hiệu suất portfolio	Native	native	line_chart + stat
Tin tức cổ phiếu	Native	native	card_list (media)
Báo cáo phân tích	Native	native	card_list (report)
Bản đồ nhiệt ngành	HTML	chart	D3 heatmap
Calculator lãi kép	HTML	interactive	HTML + JS interactive

Best practices

• Không cần repeat schema trong skill prompt — agent đọc từ visualize_read_me
• Chỉ nhắc module + component name + context — đủ cho agent
• SVG/HTML mạnh hơn native cho custom visualization — đừng ép native cho mọi thứ
• Thêm data mapping hint nếu field names giữa tool result và component props khác nhau
• Agent có thể kết hợp nhiều loại trong 1 response (text → SVG → text → native → text)