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

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 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:

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

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

Post-rendering, export commands produce distributable assets:

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	Light-mode 4×8 canonical matrix
skills/diagram-design/assets/example-dp-security-matrix-dark.html	Dark-mode variant
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, with the diagram type registered in 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}