Business & decisions

Field contracts and worked examples for the business & decisions blocks — converted at build time from the repo's authoring-skill reference. Every example body is YAML; in a real doc the fence language is the block type (for example sequence … ). Schemas are strict — unknown fields are rejected. See the field contract for the at-a-glance shape of all 77 blocks, or the block catalog for live previews.

Access control / RBAC

matrix — a role × resource capability grid

cells is positional — one value per cols entry, in order. Cells tint by meaning: Full/Admin/Write/✓ → green, —/None/✗ → muted, anything else → amber. Use matrix (not table) for a capability grid where the columns are resources and each cell is a permission level.

anatomy — the parts of a structured string (e.g. a permission)

Renders the full string (acme:billing:invoices.read) with each segment coloured, then a labelled card per segment. Use it to explain one identifier's shape — a permission string, a resource URN, a topic name.

composition — effective access as intersected gates

Renders gate₁ ∩ gate₂ ∩ … = result. Use it when access is the AND of several independent checks (authn ∩ scope ∩ permission), not a sequence of steps (use flow/sequence for ordered steps).

Presentation cards

drivers — the forces that shaped a design

A grid of "the N drivers/requirements behind this." icon is one of a fixed set (location · shield · grid · lock · key · user · clock · check · database · bolt · flag · doc · link · eye · server · layers); accent colours the top edge + icon.

team — people cards (who owns what)

Compact cards on a 3-column grid — initials avatar, name, uppercase role, and a one-line focus. Initials derive from name; set initials to override (e.g. for a team rather than a person). Use team for ownership/contact overviews; use persona for user archetypes with goals and frustrations.

options — approaches explored, with a verdict

Use when you weighed several approaches. Each card is one option; tone: chosen highlights the winner. For one option's trade-offs alone, use proscons.

scorecard — a weighted decision matrix

Criteria are rows (an ×N chip marks weights other than 1), options are columns, and the footer TOTAL row carries the weighted sum per option — the winner's header and total are highlighted with a WINNER chip (ties highlight all). Scores are plain numbers, 0-5 by convention. Use scorecard when the decision was scored; use options for qualitative pros / cons / verdict cards and table for plain data.

spec — a labelled spec sheet

A compact "fact sheet" for one approach/component. A row with steps: renders as an arrow-joined pill flow (great for a short resolution pipeline).

envelope — back-of-envelope capacity math

The system-design "step 2" block: assumptions are the givens, each steps row is one derivation (label · calc · result), and the optional result is the highlighted bottom line. Every value is a string — write units and ≈/× freely, and quote anything containing , : or #. Use envelope for the estimate that justifies a design; use stats for measured KPIs.

Business & strategy

swot — strengths / weaknesses / opportunities / threats

Four plain string lists — the classic 2×2 draws itself (S green · W red · O blue · T amber). Omit a quadrant you have nothing for; it still draws so the shape reads as a SWOT. Use swot for a strategic position; use proscons for one option's trade-offs and quadrant to plot items on two axes. For a conversion funnel (drop-off between ordered stages), use chart with kind: funnel — see charts-overviews.md.

okr — objectives + key results

One card per objective; each key result renders a progress bar (progress is a plain number 0..1) coloured by status — done / on-track green, at-risk amber, off-track red, no status navy. Use okr for goal tracking; use slo for reliability targets and statustable for task-level work.

persona — user persona cards

A 2-column grid of cards — initials avatar (from name), role, an italic quote with an accent bar, then GOALS / FRUSTRATIONS lists and TOOLS chips (sections with no data are omitted). Use persona for user archetypes; use team for real people and ownership.