Matrix / Quadrant diagram

About matrix diagrams

A matrix diagram places items in a two-dimensional space defined by two intersecting axes — most commonly a 2×2 quadrant grid — so that position conveys meaning at a glance. Product managers use the Eisenhower matrix to separate urgent work from important work; strategy consultants use the BCG matrix to allocate portfolio investment; HR teams use the 9-box grid to map performance against potential. The visual convention dates to the Boston Consulting Group's 1970s portfolio work and has been extended by frameworks like Ansoff, Johari, and RICE.

Schematex supports three matrix modes: quadrant (2×2 or 3×3 bubble plots with labeled axes), heatmap (N×M colored-cell grids), and correlation (N×M dot-intensity tables). Eight pre-built templates cover the most common frameworks out of the box, and all axis labels, quadrant names, and point properties are fully customizable.

1. Your first matrix

The smallest useful matrix: a custom 2×2 with two labeled axes and three points.

Four rules cover 80% of usage:

1. Start with the keyword matrix, optionally followed by a template name or a quoted title.
2. Set the axes with x-axis: and y-axis: — or use a built-in template and skip this step entirely.
3. Each point is "Label" at (x, y) where x and y are decimal fractions from 0.0 (low/left/bottom) to 1.0 (high/right/top).
4. Add optional properties — size:, category:, color:, shape:, highlight: — after the coordinates.

Comments must start with # anywhere on a line (outside quoted strings).

2. Built-in templates

A template pre-configures axes, quadrant labels, and grid size. Just use the template name as the second token on the header line.

Axes and quadrant labels from a template can be overridden with explicit x-axis: / y-axis: / quadrant directives.

3. Axes

Axis lines declare the semantic poles of each dimension.

x-axis: Low Effort → High Effort
y-axis: Low Value → High Value

The arrow separates the low label (left / bottom) from the high label (right / top). All of these separators are equivalent:

A reversed axis is for conventions where the "high" value sits at the left or bottom:

x-axis: High Market Share ← Low Market Share

4. Points

Each point is a bubble positioned by a normalized (x, y) coordinate pair.

"Label" at (x, y)
"Label" at (x, y) size: 4 category: design color: #7B1FA2 highlight: true note: "clarify spec"

Coordinates outside [0, 1] are clamped to the chart boundary and flagged with a badge — the original value is stored for tooltip display.

5. Quadrant labels

Label each quadrant with a name and an optional subtitle.

quadrant Q1 "Do First"
quadrant Q2 "Schedule"
quadrant Q3 "Delete"
quadrant Q4 "Delegate"

# With an optional subtitle:
quadrant Q1 "Do First" description: "High urgency, high importance"

Quadrant numbering follows the standard mathematical convention: Q1 = top-right, Q2 = top-left, Q3 = bottom-left, Q4 = bottom-right. The Q prefix is optional — quadrant 1 "Label" is equally valid.

6. Heatmap mode

Heatmap mode fills N×M cells with color intensity instead of plotting bubble positions.

matrix heatmap 4x3 "Skill Matrix"
rows: [Strategy, Execution, Communication, Technical]
cols: [Junior, Mid, Senior]

cell (0,0) level: weak
cell (1,0) level: medium
cell (2,0) level: strong
cell (0,1) value: 7
cell (1,2) label: "Top 10%"

• matrix heatmap COLxROW — header sets the grid dimensions.
• rows: and cols: — comma-separated or bracket-list of axis labels.
• cell (col, row) — zero-indexed, column first, row second (row 0 = bottom).
• level: — strong (3), medium (2), or weak (1) — shorthand for heat intensity.
• value: — explicit numeric value (overrides level:).
• label: — quoted text placed inside the cell.

7. Correlation mode

Correlation mode renders an N×M dot matrix where intensity represents the relationship strength between row and column variables.

matrix correlation 4x4 "Product Metrics"
rows: [DAU, Retention, Revenue, NPS]
cols: [DAU, Retention, Revenue, NPS]

cell (0,0) value: 1
cell (1,0) value: 0.82
cell (2,0) value: 0.54
cell (3,0) value: 0.71

The same cell syntax applies. level: strong | medium | weak is also accepted in correlation mode.

8. Config options

A config: block tunes visual rendering. Each option goes on its own indented line below the config: header.

config:
  quadrantBg: true
  gridLines: true
  axisArrows: true
  bubbleScale: area
  legendPosition: bottom-right

Two shorthand directives also work at the top level (not inside the config: block):

axis: off          # off | on | auto — show or hide the axis lines
margins: true      # true | false — show Score + Rank margins (correlation mode)

9. Labels & comments

• Title: matrix "My Title" or title: My Title as a standalone line.
• Point label: the quoted string before at (…).
• Axis labels: x-axis: and y-axis: directives.
• Quadrant labels: quadrant Q1 "Name" directive.
• Comments: # anywhere on a line, outside quoted strings.

matrix "Prioritization"
# This is a comment
x-axis: Low Cost → High Cost   # inline comment after a directive
"Fix bug" at (0.1, 0.9) size: 3  # comment after a point

10. Reserved words & escaping

Reserved at line start: matrix (header), x-axis:, y-axis:, quadrant, config:, title:, rows:, cols:, grid:, axis:, margins:, cell.

Point lines must start with a quote character (" or '). A line that does not start with a quote is not treated as a point.

Strings with spaces in axis labels do not need quoting — the text after the colon (and after the arrow) is taken verbatim. In note: and label: point properties, use double quotes.

11. Common mistakes

12. Grammar (EBNF)

document     = header directive*

header       = "matrix" ( template-name | mode-header | title )? NEWLINE
template-name = "eisenhower"|"impact-effort"|"rice"|"bcg"|"ansoff"|"johari"|"9-box"|"risk-matrix"
mode-header  = ( "heatmap" | "correlation" ) ( number "x" number )? title?
title        = quoted-string | bare-text

directive    = x-axis | y-axis | quadrant-dir | config-block
             | point | cell | rows-dir | cols-dir | grid-dir
             | title-dir | axis-dir | margins-dir | comment | blank

x-axis       = "x-axis:" WS axis-spec NEWLINE
y-axis       = "y-axis:" WS axis-spec NEWLINE
axis-spec    = text arrow text  |  text   # plain text → high label only
arrow        = "→" | "->" | "↑" | "←" | "<-" | "<" | "↓"

quadrant-dir = "quadrant" WS "Q"? digit WS quoted-string ( WS "description:" quoted-string )? NEWLINE

config-block = "config:" NEWLINE ( INDENT key ":" WS value NEWLINE )*

point        = quoted-string WS "at" WS "(" number "," number ")" ( WS point-prop )* NEWLINE
point-prop   = "size:" number
             | "category:" bareword
             | "color:" hex-color
             | "shape:" ( "circle"|"square"|"triangle"|"diamond" )
             | "highlight:" "true"
             | "note:" quoted-string
             | "label:" quoted-string

cell         = "cell" WS "(" digit "," digit ")" ( WS cell-prop )* NEWLINE
cell-prop    = "value:" number
             | "label:" quoted-string
             | "level:" ( "strong" | "medium" | "weak" )

rows-dir     = "rows:" WS label-list NEWLINE
cols-dir     = "cols:" WS label-list NEWLINE
grid-dir     = "grid:" WS number "x" number NEWLINE
axis-dir     = "axis:" WS ( "off" | "on" | "auto" ) NEWLINE
margins-dir  = "margins:" WS ( "true" | "false" | "on" | "1" ) NEWLINE

label-list   = "[" text ("," text)* "]" | text ("," text)*
quoted-string = '"' any-char-but-quote* '"' | "'" any-char-but-quote* "'"
comment      = "#" any NEWLINE

Authoritative source: src/diagrams/matrix/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

13. Standard compliance

Schematex matrix diagrams implement the standard 2×2 quadrant convention used by the Boston Consulting Group (1970), Eisenhower decision matrix, Ansoff growth matrix, and Johari Window frameworks. The 9-box grid follows the McKinsey/GE talent review convention (3×3, performance × potential). Heatmap and correlation modes follow no named external standard but use the universal cell-intensity encoding found in tools like Excel conditional formatting and R's corrplot.

What is implemented today:

• ✅ 2×2 quadrant mode with custom axes and quadrant labels
• ✅ 3×3 quadrant mode (9-box template)
• ✅ N×M heatmap mode with level: and value: cells
• ✅ N×M correlation mode
• ✅ Eight built-in templates (eisenhower, impact-effort, rice, bcg, ansoff, johari, 9-box, risk-matrix)
• ✅ Point properties: size, category, color, shape, highlight, note
• ✅ Reversed axes (← / <-)
• ✅ Config block (quadrantBg, gridLines, axisArrows, bubbleScale, legendPosition, labelCollision, offChartPolicy)
• ⏳ label: override on points (parsed, renderer support pending)
• ⏳ Off-chart drop policy (parsed, renderer always clamp-badges today)
• ⏳ margins: correlation score/rank sidebar (parsed, not yet rendered)

References:

• Henderson, B. (1970). The Product Portfolio. Boston Consulting Group.
• Covey, S. (1989). The 7 Habits of Highly Effective People. (Eisenhower matrix popularization)
• Ansoff, H.I. (1957). "Strategies for Diversification." Harvard Business Review.

14. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• Swimlane / zone overlays — named rectangular highlight regions drawn behind the grid.
• Threshold lines — horizontal or vertical reference lines with labels (e.g. "break-even" line).
• Bubble labels inside — option to print the point label inside the bubble rather than beside it.
• Export to table — structured CSV / JSON output alongside the SVG for spreadsheet import.
• 4×4 and custom-label quadrant mode — arbitrary NxM with labeled cells in quadrant (bubble-plot) mode, not just heatmap.

Track in the GitHub issues if you need any of these sooner.