Security posture

Security state matrix

<forma-security-state-matrix>

Counts security results by explicit state (Verified, Violated, Unknown, Stale, N/A) so no state collapses into another or into a score.

Authoring tag
<forma-security-state-matrix>
Behavior owner
Aegis / application
Canonical source
patterns/security-state-matrix.html

Purpose

The security state matrix shows how many invariants or evidence records Tutela places in each state: Verified, Violated, Unknown, Stale and N/A. Each state is a labelled tile with its count as large text, and every state is always shown, including zero, so Unknown and Stale are as visible as Violated. It is a count display, not a score: the tiles are never summed into a percentage or grade. To compare several scopes, repeat the matrix once per scope with the scope named in its heading. Tutela supplies the counts; Forma never computes them.

Use when

  • A release or review page needs a quick, honest overview of evidence states for one scope.
  • Unknown and stale counts must be shown with the same weight as violations.
  • Several scopes need side-by-side overviews, each with its own labelled matrix.

Avoid when

  • You need a true two-dimensional table (for example boundary × state with row and column headers): use a native table through Data grid so header scope is announced.
  • You need the posture and its blockers: use Security posture.
  • You want a single headline score or percentage: Tutela forbids a composite score as the primary representation.
  • You need a general KPI tile: use Metric card.

Behavior to know

  • A description list: each tile's term is the state name and its value is the count, so pairs are announced together.
  • Tiles share one visual treatment (top border and secondary surface); the state name, not color, distinguishes them.
  • Tiles auto-fit columns of at least 7rem and wrap to more rows as space shrinks.
  • data-state on each tile carries the machine state name.

Basic example

The smallest correct markup: the canonical pattern from patterns/security-state-matrix.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal security state matrix

Rendered from the canonical pattern file.

Security evidence state

Verified
18
Violated
1
Unknown
3
Stale
2
N/A
4
HTML · Minimal security state matrix Raw HTML for HTML · Minimal security state matrix
<forma-security-state-matrix class="forma-component-tag">
<section class="forma-security-state-matrix" aria-labelledby="security-state-title">
<h2 id="security-state-title">Security evidence state</h2><dl class="forma-security-state-matrix__grid">
<div data-state="verified"><dt>Verified</dt><dd>18</dd></div><div data-state="violated"><dt>Violated</dt><dd>1</dd></div>
<div data-state="unknown"><dt>Unknown</dt><dd>3</dd></div><div data-state="stale"><dt>Stale</dt><dd>2</dd></div><div data-state="na"><dt>N/A</dt><dd>4</dd></div>
</dl></section>
</forma-security-state-matrix>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

New artifact with nothing verified yet

Counts for an artifact that has just been assessed. Zero counts are shown rather than omitted, so the large Unknown count is read in context.

Security evidence state for build 7f3c9a2

Verified
0
Violated
0
Unknown
26
Stale
0
N/A
2
HTML · New artifact with nothing verified yet Raw HTML for HTML · New artifact with nothing verified yet
<forma-security-state-matrix class="forma-component-tag">
  <section class="forma-security-state-matrix" aria-labelledby="security-state-matrix-new-artifact-title">
    <h2 id="security-state-matrix-new-artifact-title">Security evidence state for build 7f3c9a2</h2>
    <dl class="forma-security-state-matrix__grid">
      <div data-state="verified"><dt>Verified</dt><dd>0</dd></div>
      <div data-state="violated"><dt>Violated</dt><dd>0</dd></div>
      <div data-state="unknown"><dt>Unknown</dt><dd>26</dd></div>
      <div data-state="stale"><dt>Stale</dt><dd>0</dd></div>
      <div data-state="na"><dt>N/A</dt><dd>2</dd></div>
    </dl>
  </section>
</forma-security-state-matrix>

Click or tap the code once to select all of it, then copy.

Scenario

One matrix per assessed scope

Two scopes compared by repeating the matrix, each with the scope in its heading. The layout never implies that counts from different scopes can be added together.

Authentication boundary

Verified
9
Violated
0
Unknown
1
Stale
0
N/A
1

Network egress boundary

Verified
2
Violated
1
Unknown
2
Stale
2
N/A
0
HTML · One matrix per assessed scope Raw HTML for HTML · One matrix per assessed scope
<forma-security-state-matrix class="forma-component-tag">
  <div class="forma-stack">
    <section class="forma-security-state-matrix" aria-labelledby="security-state-matrix-per-scope-auth-title">
      <h3 id="security-state-matrix-per-scope-auth-title">Authentication boundary</h3>
      <dl class="forma-security-state-matrix__grid">
        <div data-state="verified"><dt>Verified</dt><dd>9</dd></div>
        <div data-state="violated"><dt>Violated</dt><dd>0</dd></div>
        <div data-state="unknown"><dt>Unknown</dt><dd>1</dd></div>
        <div data-state="stale"><dt>Stale</dt><dd>0</dd></div>
        <div data-state="na"><dt>N/A</dt><dd>1</dd></div>
      </dl>
    </section>
    <section class="forma-security-state-matrix" aria-labelledby="security-state-matrix-per-scope-egress-title">
      <h3 id="security-state-matrix-per-scope-egress-title">Network egress boundary</h3>
      <dl class="forma-security-state-matrix__grid">
        <div data-state="verified"><dt>Verified</dt><dd>2</dd></div>
        <div data-state="violated"><dt>Violated</dt><dd>1</dd></div>
        <div data-state="unknown"><dt>Unknown</dt><dd>2</dd></div>
        <div data-state="stale"><dt>Stale</dt><dd>2</dd></div>
        <div data-state="na"><dt>N/A</dt><dd>0</dd></div>
      </dl>
    </section>
  </div>
</forma-security-state-matrix>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

State counts on a phone

The five state tiles at phone width.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • Tiles auto-fit columns of at least 7rem, so at 320px they form two columns and wrap onto three rows; the source order Verified, Violated, Unknown, Stale, N/A reads left to right, top to bottom.
  • Counts use a fluid size (clamp(1.4rem, 4vw, 2rem)), so they shrink slightly on phones without truncation.
  • The tiles are not interactive, so there are no touch targets to size.
  • In landscape more tiles fit per row; order is unchanged.
HTML · State counts on a phone Raw HTML for HTML · State counts on a phone
<forma-security-state-matrix class="forma-component-tag">
  <section class="forma-security-state-matrix" aria-labelledby="security-state-matrix-mobile-title">
    <h2 id="security-state-matrix-mobile-title">Security evidence state</h2>
    <dl class="forma-security-state-matrix__grid">
      <div data-state="verified"><dt>Verified</dt><dd>18</dd></div>
      <div data-state="violated"><dt>Violated</dt><dd>1</dd></div>
      <div data-state="unknown"><dt>Unknown</dt><dd>3</dd></div>
      <div data-state="stale"><dt>Stale</dt><dd>2</dd></div>
      <div data-state="na"><dt>N/A</dt><dd>4</dd></div>
    </dl>
  </section>
</forma-security-state-matrix>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelledbysection.forma-security-state-matrixid of the heading—Names the region; include the scope or subject in the heading.
data-state.forma-security-state-matrix__grid > divverified | violated | unknown | stale | na—Machine state name for the tile. Not styled by Forma CSS; the dt text is the visible label.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-security-state-matrixBlock class—Root section: bordered, padded primary surface.
.forma-security-state-matrix__gridElement class—Description list laid out as an auto-fit grid of tiles at least 7rem wide. Each tile has a 0.25rem top border in the current text color (CanvasText in forced colors) and a secondary surface; dt is a small bold label and dd a large fluid count.
Keyboard interaction
KeysResult
—Not interactive. Link to detailed lists from surrounding content if readers need to drill in.
Events
EventDescription
—No events.

Form behavior

Not a form control.

States

Security state matrix states
StateHow it is expressedPresentation
Verifiedtile data-state="verified"Count of verified results.
Violatedtile data-state="violated"Count of violated results.
Unknowntile data-state="unknown"Count of results that could not be established; same visual weight as Violated.
Staletile data-state="stale"Count of results whose evidence is invalidated.
N/Atile data-state="na"Count of results not applicable to the scope.

Accessibility

Forma provides

  • Uses a description list so each state name is announced with its count.
  • Gives every state the same visual treatment, so none is hidden or de-emphasized and color is never the cue.
  • Keeps tile borders visible as CanvasText in forced-colors mode.

Your application supplies

  • Always render all five states, including zero counts.
  • Name the scope or subject in the heading.
  • Do not add a total, percentage or grade derived from the counts.
  • Use a native table with row and column headers when you truly need two dimensions.

Responsive behavior

  • The grid auto-fits tiles of at least 7rem, reflowing from one row of five to two or three rows on phones.
  • Counts use a fluid font size between 1.4rem and 2rem.
  • No breakpoints; order is preserved at every width.

Motion

  • No animation: counts change by re-rendering. Numbers do not tick or count up, which could misrepresent the supplied values.

Usage guidance

Do

  • Keep the state order consistent across pages (Verified, Violated, Unknown, Stale, N/A).
  • Pair the matrix with links to the underlying invariant or evidence lists.

Avoid

  • Coloring Violated red and Verified green as the only distinction.
  • Dropping zero-count tiles.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.