1---2name: matrix-diagram3description: Use when the user needs to compare two dimensions, expose a portfolio or prioritization space, or show a many-to-many relationship in a grid or quadrant.4---56# Matrix diagram78## What / why910A matrix places items against two or more declared dimensions. It tells the story “how does each item compare across these axes?” Use it for prioritization, responsibility, compatibility, or traceability; choose a graph when relationships themselves are the focus.1112## How to model1314- Name each axis, direction, unit, and scale before placing items.15- Define whether cells mean intersection, score, responsibility, presence, or absence.16- Use a consistent measure and show missing/unknown values explicitly.17- Keep quadrant thresholds visible; do not let position imply precision the data does not have.18- For a responsibility matrix, define roles and accountabilities rather than generic marks.1920## Styling and customization2122Use a quiet grid, strong headers, ample cell padding, and a colorblind-safe palette. Add values or labels so meaning does not depend on color or position. For a quadrant, annotate thresholds; for traceability, use symbols with a legend and accessible text.2324## Renderer choices2526Preserve user choice. diagrams.net and custom SVG are best for precise grids; Mermaid, D2, and Graphviz can approximate matrices with tables/subgraphs, and Vega/Vega-Lite suit data-driven matrices or heatmaps. diagram.zip has no dedicated semantic matrix or quadrant type, so renderer styling cannot substitute for axis definitions.2728## Review2930Check units, axis direction, ordering, thresholds, empty cells, legend, and accessibility. Verify rankings are not inferred from an arbitrary sort. If it is a heatmap, inspect the color scale and provide numeric values.3132## Prior art and gaps3334See [references/prior-art.md](references/prior-art.md). There is no single matrix interchange standard in diagram.zip; a data-driven matrix/heatmap integration could add schema validation and accessible tabular alternatives.