| name | mermaid-charts |
| description | Creates and standardizes Mermaid decision flowcharts in VA Design System documentation, including templates, node types, accessibility alternatives, and the standard Jekyll include pattern. |
| triggers | ["mermaid chart","decision flowchart","mermaid diagram","flowchart TD","create a chart","add a chart"] |
SKILL: Mermaid Chart Implementation
Overview
This skill enables efficient creation and standardization of Mermaid decision flowcharts in the VA Design System documentation following established patterns and best practices.
When to use this skill
- Creating new decision flowcharts for component or pattern guidance
- Converting existing text-based guidance into visual flowcharts
- Updating existing Mermaid charts to follow current standards
- Implementing charts that help users make decisions about design system usage
Key files and resources
/docs/ai-mermaid-implementation-guide.md - Complete AI implementation guide/docs/mermaid-chart-templates.md - Ready-to-use templates for common patterns/docs/mermaid-node-types.md - Standardized node types and styling reference/docs/mermaid-chart-data-driven.md - JSON-based approach for complex charts/src/assets/stylesheets/application.scss - Chart styling (lines 145-230)
Quick implementation checklist
- Choose appropriate template based on decision structure
- Replace template variables with specific content
- Use correct width class (.mermaid-width or .mermaid-width-wide)
- Apply standardized node types (:::node-start, :::node-question, etc.)
- Add specific details to answer nodes without "Example:" labels
- Ensure all primary text uses
<b> tags
- Merge duplicate result outcomes
- Include screen reader alternative text
- Add text-based decision list using va-details component
- Test build locally
Standard pattern
<div class="mermaid-width-wide">
{% include mermaid-chart.html
id="unique-chart-id"
caption="Descriptive caption for accessibility"
chart="
flowchart TD
Start[\"<b>Main question</b>\"]:::node-start --> Decision{\"<b>Decision point?</b>\"}:::node-question
Decision --> Option1([\"<b>Option 1</b><br/>Examples:<br/>Example A, Example B\"]):::node-answer-primary
Decision --> Option2([\"<b>Option 2</b><br/>Examples:<br/>Example C, Example D\"]):::node-answer-secondary
Option1 --> Result1[\"<b>Outcome A</b><br/>Additional details\"]:::node-result-button
Option2 --> Result2[\"<b>Outcome B</b><br/>Additional details\"]:::node-result-link
" %}
</div>
<va-details label="View text-based decision list for [topic]" id="chart-id-decision-list">
<h4>Main question</h4>
<ul>
<li><strong>Decision point?</strong>
<ul>
<li><strong>Option 1</strong> (Example A, Example B) → <strong>Outcome A</strong></li>
<li><strong>Option 2</strong> (Example C, Example D) → <strong>Outcome B</strong></li>
</ul>
</li>
</ul>
</va-details>
Templates available
- Simple Binary Decision: For yes/no decisions with two clear outcomes
- Platform-Specific Decision Tree: For different web vs mobile app behavior
- Multi-Step Sequential Decision: For multiple decision points in sequence
Success criteria
- Chart renders correctly without errors
- All nodes use appropriate styling classes
- Decision flow is logical and easy to follow
- Specific details make options concrete and clear
- Screen reader users can understand the decision process
- Chart width is appropriate for content complexity
- Text-based alternative provided using va-details component
- Text alternative exactly matches visual chart (same paths, questions, details, outcomes, capitalization)
- No unnecessary "Example:" labels cluttering the design
