Add custom risk levels to the risk matrix widget

[henryhaverinen]

Summary

The risk matrix widget colours each cell by its position in the two scales. Risk methods that define their own risk table don't line up with that. In ISMS essentials, for example, 4 of the 25 cells show the wrong colour, and its five risk levels can't be shown with three colours.

This PR adds two optional parameters so a method can colour the matrix with its own table:

• levels: 2 to 5 risk levels, lowest first. Each has a name and a colour step from 1 to 5 on a fixed scale: green #0ca30c, light green #b5e68a, amber #fab219, red #d03b3b, dark red #7a1414.
• levelGrid: one row per likelihood level, lowest first, with one entry per impact level. Each entry is a 1-based position in levels.

"levels": [
  {"name": "Very Low", "colour": 1}, {"name": "Low", "colour": 2},
  {"name": "Moderate", "colour": 3}, {"name": "High", "colour": 4},
  {"name": "Very High", "colour": 5}
],
"levelGrid": [
  [1, 1, 2, 2, 3],
  [1, 2, 3, 3, 3],
  [2, 3, 3, 4, 4],
  [2, 3, 4, 4, 5],
  [3, 3, 4, 5, 5]
]

Behaviour:

• Pairing: the schema requires the two parameters to be given together.
• Legend: when levels are given, they're listed beside the matrix, highest first to match the likelihood axis.
• Count text: white on dark red, dark everywhere else.
• Grids that don't fit: the schema can't check the grid's size against the scales, or its entries against the number of levels. Cells without a valid level are drawn grey, and the widget prints a warning naming the row. This matches how cells outside the matrix are already reported.
• Default: without the new parameters, the matrix looks exactly as before. Steps 1, 3 and 4 are the existing colours.

Colour choices

The two new steps were picked with a colour-difference check (OKLab ΔE, including simulated protan, deutan and tritan vision):

• Light green stays at least 8.8 apart from amber and 22.8 from green.
• Dark red stays at least 17.5 apart from red, and white text on it has 10.8:1 contrast.

Light green has low contrast against a white page (1.40:1). Amber is already similar (1.79:1), and the gaps between cells and the legend compensate.

Test plan

• cyberismo validate passes.
• Exported the widget test card. All 10 matrices render with no macro errors, and the existing cases look unchanged.
• New test cases: a 5×5 using the ISMS essentials risk table (matches it cell for cell), a 4×4 with three levels, and a grid that doesn't fit (both warnings print and the two affected cells are grey).
• Schema checked with Ajv set up as the tool sets it up: both parameters are accepted together, each alone is rejected, and colour steps above 5 are rejected.
• Visual check in the app, in both light and dark mode.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🔵 Needs a closer look

Duplicate level names can collapse Vega-Lite color and legend categories; validation or numeric scale keys are needed.

Review effort: Lite
Findings: None

What changed in this PR

This PR adds optional custom risk levels and per-cell risk grids to the risk matrix widget while preserving default behavior.

Changes:

• Adds paired levels and levelGrid schema parameters.
• Supports custom colors, legends, contrast-aware text, and invalid-grid warnings.
• Documents and demonstrates custom configurations.

File	Summary
cardRoot/​base_h8a3eqto/​c/​base_4c0lf8u0/​c/​base_kxwagxhg/​index.adoc	Adds usage examples and validation cases.
.cards/​local/​reports/​riskMatrixWidget/​parameterSchema.json	Defines custom risk-level parameters and pairing rules.
.cards/​local/​reports/​riskMatrixWidget/​index.adoc.hbs	Renders custom grids, colors, legends, and warnings.
.cards/​local/​reports/​riskMatrixWidget.json	Updates widget metadata.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.