Guidelines for creating charts and diagrams in markdown files. Use ONLY when writing charts into markdown files (*.md), NOT for chat responses in agent sessions.
These rules apply only when writing charts or diagrams into markdown files. If you are responding in a chat session with an agent (OpenCode, Claude Code, etc.) and not writing to a markdown file, prefer ASCII art instead -- it renders immediately in the terminal without requiring a markdown renderer.
When creating charts or diagrams in markdown files, follow these rules:
Always use Mermaid fenced code blocks for charts and diagrams in markdown files. Do not use ASCII art in markdown files (it is not accessible and mermaid renders better in markdown viewers).
```mermaid
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Do something]
B -->|No| D[Do something else]
```
Mermaid supports many diagram types including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, pie charts, and more. Choose the type that best represents the data.
Every mermaid diagram must be accompanied by a text description that conveys the same information. This is essential for accessibility -- screen reader users cannot interpret mermaid diagrams.
The text alternative should:
```mermaid
flowchart TD
A[User submits form] --> B{Valid?}
B -->|Yes| C[Save to database]
B -->|No| D[Show errors]
C --> E[Redirect to dashboard]
D --> A
```
Form submission flow (text description):
```mermaid
pie title Build time by phase
"Compilation" : 45
"Testing" : 30
"Linting" : 15
"Packaging" : 10
```
Build time by phase (text description):
| Phase | Percentage |
|---|---|
| Compilation | 45% |
| Testing | 30% |
| Linting | 15% |
| Packaging | 10% |