Author và render diagram với ak:mermaidjs-v11

Dùng ak:mermaidjs-v11 để diễn đạt process, interaction, data model, state machine, architecture, plan hoặc dataset thành Mermaid v11 source. Skill cung cấp reference về syntax, configuration, CLI, integration và practical pattern; runtime đang hoạt động hoặc renderer được cài riêng phải parse và render kết quả.

Chọn ak:mermaidjs-v11 cho diagram dạng text

Dùng ak:mermaidjs-v11 khi

• Bạn muốn diagram được lưu thành text có thể review trong Markdown hoặc file .mmd.
• Bạn cần flowchart, sequence, class, state, ER, Gantt, journey, Git graph, timeline, mindmap, architecture, block, quadrant, requirement, packet, pie, XY, Sankey, radar, treemap hoặc diagram Mermaid v11 liên quan.
• Bạn cần output SVG, PNG hoặc PDF được tạo từ source diagram đã duyệt.
• Bạn cần Mermaid nhúng trong browser, Node application, React, Vue, MDX hoặc host khác hỗ trợ syntax được chọn.

Chọn workflow khác khi

• List hoặc table ngắn truyền đạt thông tin rõ hơn diagram.
• Bạn cần freehand positioning, complex illustration hoặc manual vector editing. Dùng visual-design hoặc diagramming tool dành cho artifact đó.
• Bạn chỉ muốn đọc Markdown hiện có chứa Mermaid. Dùng ak:markdown-novel-viewer và tôn trọng CDN cùng security boundary của nó.
• Target platform không hỗ trợ loại diagram v11 hoặc beta bắt buộc. Chọn loại được hỗ trợ hoặc pre-render image.

Chuẩn bị diagram contract và renderer

Trước khi bắt đầu:

• Hoàn tất Onboarding, rồi xác nhận Engineer Kit được cài cho runtime và scope hiện tại.
• Cung cấp purpose, intended reader, fact, tên node hoặc actor, relationship, direction, ordering, scope cùng detail không được suy diễn của diagram.
• Nêu target host và output chính xác: inline fenced source, .mmd, .svg, .png, .pdf hoặc application integration. Renderer support khác nhau theo host.
• Chọn security level, theme, background, font, accessibility title cùng description và interactive link hoặc callback có được phép hay không.
• Chuẩn bị Mermaid v11 hoặc @mermaid-js/mermaid-cli khi cần parse hoặc render evidence. Reference khai báo Node.js ^18.19 || >=20.0 cho CLI path.

Input được khai báo là [diagram-type or description]. Đây không phải parser cố định. Nêu diagram type khi bạn biết, hoặc cung cấp relationship và để Skill đề xuất một loại mà không bịa fact còn thiếu.

Yêu cầu source và rendered evidence

/ak:mermaidjs-v11 "Create a left-to-right sequence diagram for the supplied checkout events. Keep service names exact, distinguish synchronous calls from asynchronous notifications, include failure and retry branches, add accTitle and accDescr, return a fenced Mermaid block and checkout-sequence.mmd, parse it with Mermaid v11, render SVG with a pinned v11 CLI if available, and report any unverified layout."

/ak:mermaidjs-v11 "Create a left-to-right sequence diagram for the supplied checkout events. Keep service names exact, distinguish synchronous calls from asynchronous notifications, include failure and retry branches, add accTitle and accDescr, return a fenced Mermaid block and checkout-sequence.mmd, parse it with Mermaid v11, render SVG with a pinned v11 CLI if available, and report any unverified layout."

$ak:mermaidjs-v11 "Create a left-to-right sequence diagram for the supplied checkout events. Keep service names exact, distinguish synchronous calls from asynchronous notifications, include failure and retry branches, add accTitle and accDescr, return a fenced Mermaid block and checkout-sequence.mmd, parse it with Mermaid v11, render SVG with a pinned v11 CLI if available, and report any unverified layout."

Với data-driven diagram, cung cấp authoritative dataset cùng encoding dự kiến. Pie, XY, Sankey, radar hoặc treemap không nên âm thầm aggregate, normalize, reorder hay bỏ value. Hãy yêu cầu kết quả kèm mapping từ data tới mark để đối chiếu với source.

Chọn diagram nhỏ nhất phù hợp

Một số loại được tham chiếu có suffix -beta. Hãy coi chúng nhạy với renderer, test trên exact target version và cung cấp fallback đơn giản hơn khi destination không render được.

Quan sát các giai đoạn diagram

1. Skill xác nhận information model. Skill tách supplied fact khỏi inferred layout và hỏi về relationship còn thiếu làm thay đổi ý nghĩa.
2. Skill chọn một diagram type và direction. Lựa chọn phản ánh information shape cùng Mermaid version được destination hỗ trợ.
3. Skill author semantic source. Stable ID, label rõ, edge text có nghĩa, comment, accessible title cùng description và styling tối thiểu giúp source review được.
4. Skill áp dụng bounded configuration. Theme, look, layout, font, deterministic ID, size limit và security level được nêu rõ thay vì dùng host default khi reproducibility quan trọng.
5. Skill parse trước rendering. mermaid.parse() hoặc check v11 tương đương phân biệt syntax error với browser hoặc layout failure về sau.
6. Skill render trong target đã chọn. CLI hoặc host tạo SVG, PNG, PDF hay live HTML bằng version được pin khi có thể.
7. Skill kiểm tra visual output. Clipped label, overlap, crossing arrow, contrast, scale, font substitution, responsive behavior và accessible metadata được review.
8. Skill trả source và evidence. Report nêu version, command, output, data reconciliation, render finding và gap.

Render với tool boundary rõ ràng

CLI được tham chiếu chuyển .mmd input theo output extension:

mmdc -i checkout-sequence.mmd -o checkout-sequence.svg
mmdc -i checkout-sequence.mmd -o checkout-sequence.png -t dark -b transparent
mmdc -i checkout-sequence.mmd -o checkout-sequence.pdf --configFile mermaid-config.json

Installation có thể global, local, qua npx hoặc bằng cách pull container image đã document. Mỗi path có thể dùng network, ghi package hoặc image layer, khởi động browser-backed renderer và dùng CPU, memory cùng disk. Batch conversion ghi một artifact cho mỗi input và có thể overwrite output trùng; hãy review target trước khi chạy.

Browser integration có thể tải Mermaid từ CDN hoặc npm package đã cài. Tránh URL @latest trong reference khi reproducibility quan trọng; pin một version v11 đã review. Ví dụ Jupyter dùng mermaid.ink, editor workflow dùng mermaid.live và CDN icon pack có thể làm diagram source hoặc metadata liên quan rời khỏi máy. Xin phép trước khi dùng các external service đó.

Giữ source, link và rendering an toàn

• Ưu tiên securityLevel: 'strict', default được document, cho diagram do người dùng cung cấp hoặc được publish. loose cho phép thêm HTML cùng interaction và cần trust boundary được review riêng.
• Không đặt credential, private endpoint, customer identifier, hidden architecture, incident detail hay sensitive data vào source, exported image, link, tooltip, comment hoặc accessibility description.
• Interactive click handler và URL có thể navigate hoặc thực thi page callback. Chỉ thêm khi cần và đã review cho target host.
• Custom CSS, HTML label, icon loader và remote font thay đổi security, appearance, accessibility cùng reproducibility. Ghi nhận mỗi external asset.
• Generated SVG có thể chứa link, ID, style và metadata. Coi nó là active content khi embed và áp dụng sanitization policy của destination.
• Chỉ được ghi source hoặc rendered file khi có yêu cầu. Publish, upload, embed vào production hay thay checked-in diagram vẫn là action riêng.

Xác minh output và evidence

Kết quả đầy đủ nên gồm:

• Canonical Mermaid source trong Markdown block hoặc file .mmd được yêu cầu, với ID, label, relationship, date, value cùng comment chính xác.
• accTitle và accDescr hữu ích, cộng text alternative dễ đọc khi destination không expose đáng tin Mermaid SVG accessibility metadata.
• Version Mermaid và CLI hoặc host, security level, theme, layout, font, configuration file, custom CSS cùng command đã dùng.
• Parse result tách biệt với kết quả render SVG, PNG, PDF hoặc live host.
• Rendered artifact path cùng dimension và visual inspection cho collision, clipping, edge routing, label placement, contrast cùng scale.
• Đối chiếu với process, schema, timeline hay dataset được cung cấp, nêu rõ inferred layout và target feature không được hỗ trợ.

Skill tham chiếu guidance companion /ak:tech-graph để review universal SVG layout, nhưng capability đó không thuộc Skill directory này. Chỉ dùng khi nó thực sự được cài; nếu không, thực hiện visual check đã nêu bằng tool sẵn có và báo companion còn thiếu. Skill không chứa renderer, script hay test có scope trực tiếp. Hai release stable và beta được ghim chứa file giống hệt.

Khắc phục sự cố và hiểu giới hạn

Dùng ak:markdown-novel-viewer để đọc trusted Markdown với live Mermaid rendering hoặc Runtime adapter để xem khác biệt renderer và tool.