📊 Diagrams & Charts: Mermaid + Chart.js native support

[ramsani]

🎯 Feature: Mermaid Diagrams & Chart.js Integration

Context

The current artifact ecosystem is limited to HTML/CSS tables, grids, and text. While effective, this excludes two major artifact categories that users frequently request:

• Diagrams: flowcharts, architecture maps, sequence diagrams, state machines
• Charts: bar charts, timelines, dashboards, comparison matrices with data visualization

Mermaid and Chart.js are the de facto standards for these use cases in the web ecosystem. Mermaid renders from a simple text DSL; Chart.js renders from a data-driven JSON config. Both are lightweight, dependency-free, and render reliably in any modern browser.

Problem

• Flowcharts (architecture, workflow, decision trees) are requested frequently but require external tools or manual SVG generation
• Data visualization (timelines, bar comparisons, dashboards) is not available natively
• Users who want a chart must pre-generate it or use an external service, breaking the single-command workflow

What This Resolves

Mermaid support:

• Pre-built artifact patterns that include Mermaid block rendering
• Mermaid CDN reference embedded in artifact template
• Syntax validation in audit-artifact.py to check for malformed Mermaid blocks before delivery

Chart.js support:

• Pre-built chart templates (bar, line, timeline, radar) that accept structured data
• Interactive chart artifacts with copy/export of chart data as JSON
• Chart templates validate input data shape before rendering

Both:

• Functional examples in examples/ directory
• Integration with existing audit-artifact.py quality gate
• No external dependencies beyond CDN-loaded libraries

Proposed Approach

Mermaid integration:

1. Add Mermaid CDN to the base template in templates/artifact-explorer.html
2. Create patterns/23-mermaid-flowchart.md and patterns/24-mermaid-architecture.md as new pattern examples
3. Add Mermaid validation to audit-artifact.py:
   • Check for <div class="mermaid"> blocks
   • Validate syntax by checking for mismatched brackets, invalid node IDs, missing arrows
   • Score contribution: visual_model check upgraded when Mermaid detected
4. Add examples/mermaid-architecture.example.html as a working Mermaid artifact

Chart.js integration:

1. Add Chart.js CDN to base template (Chart.js and date-fns adapter)
2. Create patterns/25-chart-dashboard.md and patterns/26-chart-timeline.md as new patterns
3. Add chart validation to audit-artifact.py:
   • Check for <canvas> elements paired with <script> data blocks
   • Validate JSON data structure for common chart types
   • Verify required fields (labels, datasets for Chart.js v4)
4. Add examples/chart-dashboard.example.html as a working Chart.js artifact

Mermaid validation in audit-artifact.py:

def mermaid_syntax_valid(html: str) -> bool:
    matches = re.findall(r'<div[^>]*class=["']mermaid["'][^>]*>(.*?)</div>', html, re.DOTALL)
    for block in matches:
        bracket_count = block.count('[') - block.count(']')
        if bracket_count != 0:
            return False
    return True

Example Mermaid artifact structure:

<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>mermaid.initialize({ startOnLoad: true });</script>
<div class="mermaid">
flowchart TD
    A[User Intent] --> B{Decision}
    B -->|Yes| C[Generate Artifact]
    B -->|No| D[Return Markdown]
</div>

Example Chart.js artifact structure:

<canvas id="myChart" width="800" height="400"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
<script>
new Chart(document.getElementById('myChart'), {
  type: 'bar',
  data: { labels: ['Option A', 'Option B'],
         datasets: [{ label: 'Score', data: [92, 78] }] }
});
</script>

Acceptance Criteria

• Mermaid renders correctly in generated artifacts (verified by visual test)
• Chart.js renders bar/line/timeline charts correctly in generated artifacts
• audit-artifact.py validates Mermaid syntax (blocks without syntax errors pass)
• audit-artifact.py validates Chart.js data structure (required fields present)
• At least 2 new pattern files: patterns/23-*.md and patterns/24-*.md
• At least 2 new example files: examples/mermaid-*.example.html and examples/chart-*.example.html
• patterns/09-architecture-diagram.md updated to reference Mermaid approach
• patterns/10-process-workflow-flowchart.md updated to reference Mermaid approach
• validate-patterns.sh passes with new patterns
• validate-examples.sh passes with new examples

Quality Verification

python scripts/audit-artifact.py examples/mermaid-architecture.example.html --json | jq '.checks[] | select(.id=="visual_model")'
# Expected: passed=true

python scripts/audit-artifact.py examples/chart-dashboard.example.html --json | jq '.checks[] | select(.id=="interaction_export")'
# Expected: passed=true

bash scripts/validate-patterns.sh
bash scripts/validate-examples.sh

Labels

enhancement, rich-visual-content, diagrams, charts

Milestone

v1.1 — Collaboration-ready artifacts