OVP for AI agents

OVP is written for machine consumption first: controlled vocabularies, machine metadata on every object, a generated registry, and copy-paste blocks. An agent that follows this page produces deterministic, honest visuals instead of plausible ones.

The instruction grammar

Render CH-TIM-02 in DL-03 with data.json

Object code + design language + data. Nothing else is needed, because the spec and the token file determine everything else.

Resolution order

  1. Questions: match the business question; confirm its observations in the data.
  2. Decider: audience + purpose + medium resolve the design language; its constitution sets the communication contract.
  3. Patterns: what you found in the data maps to chart codes.
  4. Charts: disambiguate by message intent; honor every see_instead exit before committing.
  5. Narrative: structure the telling with the question's NR skeleton, ordered by the language's decision_style.
  6. Render the code in the language: exact px, exact hex, no adjectives, then run the object's QA checklist.

The registry

Resolve objects through REGISTRY.json rather than walking the repository. One entry per object:

{
  "id": "CH-COR-01",
  "name": "SCATTER",
  "type": "chart",
  "family": "COR",
  "ovp_version": "1.0",
  "status": "candidate",
  "intent": [
    "correlation",
    "outlier-detection"
  ],
  "relations": {
    "alternatives": [
      "CH-COR-02 (bubble, adds a size measure)",
      "CH-COR-03 (XY heatmap for dense grids)"
    ],
    "see_instead": [
      {
        "when": "a third measure matters",
        "use": "CH-COR-02"
      },
      {
        "when": "hundreds of points",
        "use": "CH-COR-03"
      }
    ],
    "implemented_by": [
      "svg",
      "pptx"
    ],
    "answers": [
      "BQ-09"
    ],
    "recommended_by": [
      "PT-02"
    ],
    "used_in": []
  },
  "source": "specs/CH-COR-01.json"
}

Controlled vocabularies

audience: executive, operations, analyst, technical, legal, field, public

purpose: decide, monitor, explain, alert, document, brief, archive, navigate, prove, celebrate

medium: screen, print, projector, wall, phone

intent: ranking, comparison, magnitude, trend, change-over-time, schedule, progress, part-to-whole, composition, share, volume, deviation, variance, flow, bridge, variance-decomposition, correlation, outlier-detection, pattern, density, status, lookup, readiness, uncertainty, distribution

narrative_style: recommendation-first, evidence-first, question-first, story-first

density: executive, operational, scientific

annotation_policy: none, minimal, guided, full

legend_policy: direct-labels-only, level-key-allowed

highlight_policy: single, dual, none

decision_style: recommendation-with-owner, options, evidence-only

reading_time: glance, minute, session

Chart specs draw meta.intent from the intent list; the validator rejects anything off-vocabulary.

The runtime contract

Three products, three audiences: the handbook (this site) is for humans; the registry is for machine lookup; the runtime is what an agent loads to execute one request, and it is deliberately tiny:

request
  -> registry lookup (one entry)
  -> one DL token block
  -> matched chart block(s), within charts_per_page
  -> the narrative skeleton the question names
  -> render

Never load the handbook into an agent context: the copy blocks are self-contained on purpose, and token efficiency is a protocol objective (PROTOCOL 2.1). Registry chart entries carry the reverse edges (answers, recommended_by, used_in) so resolution is one lookup, not a crawl.

Copy blocks: two flavors

Design-system blocks (per chart per language) resolve every color to hex: paste one into a CLAUDE.md or system prompt and the agent needs nothing else. Skill blocks (per chart) stay role-based: paste next to one language token block and re-theme by swapping that block. Both are on every chart page, generated from the canonical specs and drift-gated.