# What Is the DP Security Matrix Diagram Type in cathrynlavery/diagram-design?

> Understand the DP security matrix diagram type in cathrynlavery/diagram-design. Visualize per-role per-component access permissions for data platforms. Learn more now.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: getting-started
- Published: 2026-08-14

---

**The DP security matrix is a parametric diagram type that visualizes per-role/per-component access permissions for data platforms, rendering a grid where rows represent platform components and columns represent roles or AD groups.**

This specialized visualization belongs to the **Diagram-Design** repository, a structured diagramming system that generates pixel-perfect SVG and HTML outputs from YAML configuration files. The DP security matrix specifically addresses the need for clear, scannable security documentation in modern data platform architectures.

## Core Architecture of the DP Security Matrix

The DP security matrix follows a strict **grid-based layout** with no connectors—information flows entirely through cell positioning, content, and deterministic styling rules.

### Row and Column Semantics

Each **row** maps to a platform component: authentication systems like Keycloak, storage layers like MinIO buckets, query engines like Trino catalogs, or compute environments like JupyterHub and NiFi. Each **column** represents an access principal—typically Active Directory groups or platform roles such as Data Administrators, Data Engineers, Data Scientists, and Data Consumers.

The intersection cells encode **permission values** (`Admin`, `R/W`, `Read`, `SELECT`, `Login`, `No access`) driven by a closed-vocabulary **level** field.

### The Level Vocabulary

The `level` attribute controls visual styling through four canonical values:

- `full` — administrative/complete access
- `rw` — read-write permissions
- `read` — read-only or limited access
- `none` — no access granted

These levels map to predetermined **fill, stroke, and text colors** that maintain consistency across diagrams. The specification in [`skills/diagram-design/references/type-dp-security-matrix.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-dp-security-matrix.md) details how each level translates to specific color tokens.

### Focal Cell Highlighting

A single cell may be designated as **focal** via `focal: true`. This override emphasizes the diagram's most critical security rule—the "signal" that defines the platform's distinguishing access pattern. Per the anti-patterns documented in the reference file, designs must contain **zero or one focal cells**; multiple focal cells dilute visual hierarchy.

## YAML Input Contract

The DP security matrix accepts a well-defined YAML structure. Below is the canonical 4×8 example from the repository's reference implementation:

```yaml
title:    "Platform Access Matrix"
subtitle: "Four canonical groups × platform components"

roles:
  - { name: "Data Administrators", code: "DL-DataAdmins" }
  - { name: "Data Engineers",      code: "DL-DataEngineers" }
  - { name: "Data Scientists",     code: "DL-DataScientists" }
  - { name: "Data Consumers",      code: "DL-DataConsumers" }

components:
  - { name: "Keycloak",          hint: "SSO" }
  - { name: "MinIO · raw bucket" }
  - { name: "MinIO · anon · staging · agg" }
  - { name: "Trino · raw catalog" }
  - { name: "Trino · anon‑staging" }
  - { name: "Trino · aggregated" }
  - { name: "JupyterHub" }
  - { name: "NiFi" }

cells:
  # Row 0 – Keycloak

  - { row: 0, col: 0, value: "Admin",  level: "full" }
  - { row: 0, col: 1, value: "Login", level: "read" }
  - { row: 0, col: 2, value: "Login", level: "read" }
  - { row: 0, col: 3, value: "Login", level: "read" }

  # Row 1 – MinIO raw

  - { row: 1, col: 0, value: "Full",   level: "full" }
  - { row: 1, col: 1, value: "R/W",    level: "rw"   }
  - { row: 1, col: 2, value: "No access", level: "none" }
  - { row: 1, col: 3, value: "No access", level: "none" }

  # … (additional rows omitted) …

  # Row 5 – Trino aggregated (focal cell)

  - { row: 5, col: 0, value: "Full",         level: "full" }
  - { row: 5, col: 1, value: "R/W",          level: "rw"   }
  - { row: 5, col: 2, value: "SELECT",       level: "read" }
  - { row: 5, col: 3, value: "SELECT only", sub: "sole consumer access", focal: true }

dark: false

```

Optional fields include `none_label` for customizing empty permission text, `dark` for theme selection, and per-cell `color` overrides for exceptional cases.

## Layout Formulas and Rendering Precision

The DP security matrix implements **deterministic geometry** through precise layout formulas documented in [`skills/diagram-design/references/type-dp-security-matrix.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-dp-security-matrix.md). These calculations ensure:

- Consistent **padding** and **column widths** regardless of content length
- Fixed **row stride** for uniform vertical rhythm
- Exact **viewBox** dimensions for scalable SVG output
- Pixel-perfect alignment across **light and dark mode** variants

The rendering engine produces self-contained HTML files with embedded SVG and CSS. Dark mode support operates through **token-based palette swaps**—design tokens like `paper`, `ink`, `muted`, and `soft` invert systematically without manual color recalculation.

## Generating DP Security Matrix Diagrams

The Diagram-Design skill exposes a `render` command for diagram generation. Usage follows this pattern:

```bash
diagram-design render --type dp-security-matrix --input my-access-matrix.yaml --output my-matrix.html

```

Post-rendering, export commands produce distributable assets:

```bash
diagram-design export my-matrix.html                             # SVG + PNG

diagram-design export my-matrix.html --svg-only                  # SVG only

diagram-design export my-matrix.html --png-only --scale=3        # 3× PNG

```

The `--scale` parameter enables high-resolution PNG output for print documentation or presentation decks.

## Reference Implementations in the Repository

The `cathrynlavery/diagram-design` repository contains three canonical examples:

| File | Description |
|------|-------------|
| [`skills/diagram-design/assets/example-dp-security-matrix.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-dp-security-matrix.html) | Light-mode 4×8 canonical matrix |
| [`skills/diagram-design/assets/example-dp-security-matrix-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-dp-security-matrix-dark.html) | Dark-mode variant |
| [`skills/diagram-design/assets/example-dp-security-matrix-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-dp-security-matrix-full.html) | Editorial version with title, subtitle, and summary cards |

These assets serve as **taste gates**—reference outputs against which generated diagrams are validated. The reproducibility checklist in the specification verifies viewBox dimensions, header placement, row stride consistency, and focal-cell uniqueness.

## Anti-Patterns to Avoid

The DP security matrix specification documents explicit **anti-patterns** that degrade diagram effectiveness:

- **Multiple focal cells** — violates the single-signal principle
- **Connector elements** — the matrix contains no edges or flows by design
- **Free-form `level` values** — breaks styling consistency and legend generation
- **Excessive color overrides** — undermines the semantic color system
- **Scale violations** — more than 6 roles or 14 components produces unreadable output

## Summary

The DP security matrix in `cathrynlavery/diagram-design` provides:

- **Grid-based visualization** of per-role, per-component data platform permissions
- **Closed-vocabulary styling** through `full`, `rw`, `read`, and `none` levels
- **Single focal cell** capability for highlighting critical security signals
- **Deterministic layout formulas** ensuring reproducible, pixel-perfect output
- **Native dark-mode support** via token-based color inversion
- **YAML-driven workflow** from configuration through SVG/PNG export

The complete specification resides in [`skills/diagram-design/references/type-dp-security-matrix.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-dp-security-matrix.md), with the diagram type registered in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) as the visual representation for "Per-role / per-component access permissions matrix."

## Frequently Asked Questions

### How does the focal cell work in a DP security matrix?

The focal cell is designated by setting `focal: true` on any single cell in the matrix. This override applies accent styling that supersedes standard level-based formatting, drawing immediate attention to the diagram's most critical permission rule. The specification enforces uniqueness—zero or one focal cells per diagram—to maintain visual hierarchy and prevent attention fragmentation.

### What permission levels does the DP security matrix support?

The DP security matrix recognizes four canonical levels: `full` for administrative access, `rw` for read-write permissions, `read` for read-only or limited access, and `none` for explicitly denied access. These values drive automatic cell styling and legend generation. Using values outside this closed vocabulary constitutes an anti-pattern and may break rendering consistency.

### Can I customize colors in a DP security matrix?

Individual cells accept an optional `color` field for exceptional tinting, though the specification discourages overuse. Systematic theming occurs through the `dark` boolean (switching between light and dark palettes) and through the underlying design token system documented in [`type-dp-security-matrix.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-dp-security-matrix.md). Direct color overrides should be reserved for edge cases that the standard level vocabulary cannot express.

### What are the practical limits for DP security matrix dimensions?

The specification recommends maximums of **6 roles (columns)** and **14 components (rows)**. Exceeding these thresholds produces matrices that sacrifice scannability—the primary virtue of this diagram type. For larger permission spaces, the documentation suggests decomposition into multiple focused matrices or alternative visualization strategies.