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. SIPOC mode

A SIPOC is the one-page scoping table that opens the Define phase of a Six Sigma DMAIC project. It names, in five fixed columns left to right, everyone and everything the process touches: Suppliers · Inputs · Process · Outputs · Customers. Before a team measures or improves anything, SIPOC pins down the boundary — "where does this process start, where does it end, and who hands work in and out of it."

matrix sipoc "Order fulfilment"
suppliers: "Vendor", "Warehouse"
inputs: "PO", "Stock levels"
process: "Receive order", "Pick", "Pack", "Ship"
outputs: "Shipped package", "Invoice"
customers: "End customer", "Finance"

• Start with matrix sipoc, optionally followed by a quoted title.
• Each of the five columns is its own directive: suppliers:, inputs:, process:, outputs:, customers:.
• After the colon, list the entries as comma-separated quoted strings. A column may have any number of entries; the rows simply stack top-down inside that column.
• The process: column is the high-level step sequence (typically 4–7 steps) — keep it to the major stages, not a detailed flowchart.

The five columns always render in the canonical S-I-P-O-C order regardless of the order you declare them, so the diagram reads correctly even if an LLM emits the blocks out of sequence.

9. QFD mode (House of Quality)

Quality Function Deployment (QFD) — the House of Quality, introduced by Yoji Akao — translates what customers want into the engineering characteristics that deliver it. Rows are the WHATs (customer requirements, each with an importance weight); columns are the HOWs (the measurable engineering characteristics the team controls). The body of the grid records how strongly each HOW serves each WHAT.

The differentiator: the engine computes the bottom row for you. Each HOW's technical importance is the sum down its column of weight × relationship strength — a ranked answer to "which engineering characteristic moves the most customer value, and is therefore worth the most effort." And the roof of the house — a half-matrix of diamond cells above the columns — records whether two HOWs help or fight each other.

matrix qfd "Coffee maker"
what: "Quiet operation" weight: 5
what: "Brews fast" weight: 3
what: "Energy efficient" weight: 4
how: "Fan RPM" dir: down
how: "Heater watts" dir: up
how: "Insulation" dir: up
rel (0,0): 9
rel (0,2): 3
rel (1,1): 9
rel (2,1): 3
rel (2,2): 9
roof (0,1): --
roof (1,2): +

WHATs and HOWs

Relationship cells

rel (i, j): strength records how strongly column-j HOW serves row-i WHAT. The index is (row, column), both zero-based.

This 9 / 3 / 1 scale is the QFD convention: it is deliberately non-linear so that one strong link outweighs several weak ones when the importance row is summed.

Computed technical-importance row

The engine sums each column to produce the technical-importance row at the foot of the house:

importance(j) = Σ over rows i  ( weight(i) × strength(i, j) )

For the coffee-maker example above the row computes to 45 / 39 / 51 — Insulation (51) is the highest-leverage characteristic, Heater watts (39) the lowest. This ranking is the deliverable: it tells the team where to spend engineering effort.

Add normalize: true (its own line, anywhere in the block) to show each column as a percentage of the total instead of a raw sum — for this example, 33% / 29% / 38%. Percentages make the relative priorities easier to read across very different weight scales.

The roof — HOW × HOW correlations

The roof is the triangular half-matrix sitting above the columns. roof (i, j): glyph records whether HOW i and HOW j reinforce or conflict with each other — the synergies and trade-offs a team must reconcile.

Each roof entry renders as a diamond cell in the standard QFD pitched-roof grid. In the example, roof (0,1): -- flags that pushing Fan RPM down while pushing Heater watts up is a trade-off, and roof (1,2): + flags that Heater watts and Insulation reinforce each other.

10. Punnett mode (Mendelian genetics)

A Punnett square predicts the offspring of a genetic cross. You write only the two parental genotypes; the engine does the Mendelian bookkeeping — it enumerates each parent's gametes (one allele per gene locus), fills the grid with every gamete combination, and computes the genotype and phenotype ratios. The user never fills the grid.

matrix punnett "Eye color  (Bb × Bb)"
cross: Bb x Bb
trait B: "Brown eyes" / "Blue eyes"

The cross

Allele case sets dominance — this is the standard genetics convention. An uppercase letter is the dominant allele, the matching lowercase letter is recessive. A genotype groups alleles by letter: RrYy is two loci, R/r (round/wrinkled) and Y/y (yellow/green). One gene is a monohybrid cross (2×2 grid), two genes a dihybrid (4×4), three a trihybrid (8×8).

Computed ratios (the differentiator)

The engine derives, from the genotypes alone:

• the gametes of each parent — the column and row headers — by taking one allele per locus (so a heterozygote Bb yields B and b);
• the offspring grid — every gamete pairing, written dominant-allele-first (Bb, never bB);
• the phenotype ratio — boxes grouped by which phenotype they express, reduced to lowest terms. A monohybrid Bb × Bb gives the classic 3:1; a dihybrid RrYy × RrYy gives the famous 9:3:3:1;
• the genotype ratio — e.g. 1:2:1 (1 BB, 2 Bb, 1 bb) for the monohybrid.

Each box is tinted by its phenotype class, and the footer lists the phenotype ratio with a legend plus the genotype ratio.

11. 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)

12. 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

13. Table mode (style: table)

The default matrix rendering is a scatter / bubble chart — points float at (x, y) coordinates. For frameworks where the output is a list of items grouped by quadrant (Eisenhower, Johari, Impact-Effort, 9-box), use style: table to switch to a text-in-cell layout instead.

matrix eisenhower "This Week"
style: table
Q2: "Ship hotfix"
Q2: "Customer demo prep"
Q1: "Write Q3 OKRs"
Q1: "Refactor auth layer"
Q4: "LinkedIn updates"
Q3: "Reorganize Slack channels"

style: table applies these changes automatically:

Q1 … Q4 shorthand (2×2 only)

For 2×2 templates, use Qn: "item" instead of the longer cell (col, row) label: "item" form. Mapping:

Repeat a shorthand key to add multiple items to the same cell:

Q2: "Ship hotfix"
Q2: "Customer demo prep"

For 3×3 grids (9-box), use cell (col, row) label: "…" directly — the Q shorthand is 2×2 only.

When to use table vs scatter

14. Reserved words & escaping

Reserved at line start: matrix (header), x-axis:, y-axis:, quadrant, config:, title:, rows:, cols:, grid:, axis:, margins:, cell. In SIPOC mode: suppliers:, inputs:, process:, outputs:, customers:. In QFD mode: what:, how:, rel, roof, normalize:.

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.

15. Common mistakes

16. 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?
             | ( "sipoc" | "qfd" | "punnett" ) title?
title        = quoted-string | bare-text

directive    = x-axis | y-axis | quadrant-dir | config-block
             | point | cell | q-short | rows-dir | cols-dir | grid-dir
             | style-dir | title-dir | axis-dir | margins-dir
             | sipoc-col | qfd-what | qfd-how | qfd-rel | qfd-roof | normalize-dir
             | punnett-cross | punnett-trait
             | comment | blank

# SIPOC mode
sipoc-col    = ( "suppliers:" | "inputs:" | "process:" | "outputs:" | "customers:" )
               WS quoted-string ( "," quoted-string )* NEWLINE

# QFD / House of Quality mode
qfd-what     = "what:" WS quoted-string WS "weight:" number NEWLINE
qfd-how      = "how:" WS quoted-string ( WS "dir:" ( "up" | "down" ) )? NEWLINE
qfd-rel      = "rel" WS "(" number "," number ")" ":" WS ( "9" | "3" | "1" ) NEWLINE  # (row, col)
qfd-roof     = "roof" WS "(" number "," number ")" ":" WS ( "++" | "+" | "-" | "--" ) NEWLINE  # (how, how)
normalize-dir = "normalize:" WS "true" NEWLINE

# Punnett (Mendelian genetics) mode
punnett-cross = ( "cross:" | "parents:" ) WS genotype WS ( "x" | "×" | "*" ) WS genotype NEWLINE
punnett-trait = "trait" WS letter ":" WS quoted-string WS "/" WS quoted-string NEWLINE  # dominant / recessive
genotype     = ( letter letter )+   # allele pairs grouped by letter; case = dominance, e.g. "RrYy"

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" )

style-dir    = "style:" WS "table" NEWLINE
q-short      = "Q" ( "1" | "2" | "3" | "4" ) ":" WS quoted-string NEWLINE   # 2×2 only

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.

17. 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
• ✅ SIPOC mode — five-column Suppliers · Inputs · Process · Outputs · Customers scoping table (Six Sigma DMAIC Define)
• ✅ QFD / House of Quality mode — WHATs × HOWs grid, 9 / 3 / 1 relationship scale, computed technical-importance row (with normalize: true percentages), and the HOW × HOW correlation roof (++ / + / - / --)
• ✅ Punnett mode — Mendelian cross from two parental genotypes; the engine computes the gametes, the offspring grid, and the genotype + phenotype ratios (monohybrid 3:1, dihybrid 9:3:3:1); allele case = dominance; optional trait phenotype names; mono/di/trihybrid (2×2 / 4×4 / 8×8)
• ✅ 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)
• ✅ style: table — text-in-cell layout with Q1…Q4 shorthand (2×2) and stacked bullet lists
• ⏳ 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.
• Akao, Y. (1990). Quality Function Deployment: Integrating Customer Requirements into Product Design. Productivity Press. (House of Quality)
• Pyzdek, T. & Keller, P. (2018). The Six Sigma Handbook (5th ed.). McGraw-Hill. (SIPOC in DMAIC Define)
• Punnett, R.C. (1905). Mendelism. Macmillan. (the Punnett square); Mendel, G. (1866). "Versuche über Pflanzenhybriden."

18. 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.

Related examples

Ready-to-use scenarios from the examples gallery: