Practical guide

How to create a dashboard specification with AI

A dashboard specification is a decision contract, not a collection of chart ideas. It should tell a reviewer which decision the dashboard supports, where every measure comes from, how calculations behave, what users can inspect, and what must be true before release. AI can help organize requirements and challenge omissions, but the accountable author still has to verify the source data,.

By Two Prune

A dashboard specification is a decision contract, not a collection of chart ideas. It should tell a reviewer which decision the dashboard supports, where every measure comes from, how calculations behave, what users can inspect, and what must be true before release. AI can help organize requirements and challenge omissions, but the accountable author still has to verify the source data, definitions, access rules, and acceptance tests.

Start with the decision, not the display

Write one sentence that names the user, the recurring decision, and the time window. “Help the support director decide each Monday which queues need staffing intervention” is testable. “Show support performance” is not. Record the questions the dashboard will not answer, such as individual performance or causal attribution.

This focus follows the Digital.gov data visualization guidance, which starts with a clear research question and then asks authors to identify, clean, and validate the data. Treat that sequence as a specification dependency: no chart is accepted until its decision question and data route are known.

Sources: [1]

Use the FRAME specification

FRAME turns a loose request into five reviewable blocks.

The method deliberately separates arithmetic from meaning. A calculation can reconcile and still invite the wrong interpretation. A clear story can also rest on an incorrect denominator. Review both.

  • Focus: name the decision, audience, cadence, scope, and exclusions.
  • Record: define each source, owner, field, join key, refresh schedule, and permitted use.
  • Arithmetic: state the numerator, denominator, filters, time zone, rounding, missing-data rule, and reconciliation total for every metric.
  • Meaning: specify the chart, comparison, explanatory text, drill path, and accessibility alternative.
  • Exceptions: define stale-data behavior, suppressed values, access failures, alert ownership, change approval, and rollback.

Build the metric contract before the wireframe

Create one row per metric. A complete row includes a stable metric ID, business question, plain-language definition, source fields, formula, grain, inclusion and exclusion rules, refresh target, owner, quality checks, display rule, and known limitations. Link the row to a sample query or transformation rather than pasting untraceable figures into a mockup.

For a “first-response within target” rate, the contract might say: count eligible conversations whose first human response occurred within the service target; divide by all eligible conversations opened during the reporting week; exclude spam and system-generated contacts; use the queue’s configured target as it stood when the conversation opened; expose excluded and missing counts beside the rate. That is materially more useful than “SLA percentage.”

Specify the visual and accessible equivalent

For each view, state the intended comparison and why the chosen form supports it. A weekly trend may use a line; queue comparisons may use sorted bars; exact operational values may require a table. Do not ask AI to choose a chart from the metric name alone.

The U.S. Web Design System data visualization guidance recommends familiar forms, a limited central idea, careful color use, explanatory context, and accessible alternatives. Put those requirements in acceptance criteria: keyboard reachability, sufficient contrast, visible focus, non-color status cues, text summaries, and a data table or equivalent route to the values. A screenshot review is not an accessibility test.

Sources: [2]

Worked example: a support intervention dashboard

A support operations team wants a Monday dashboard for staffing decisions. The FRAME artifact records this decision: “The support director chooses up to two queues for a one-week staffing intervention using the previous four complete weeks.” It excludes employee ranking and forecasts.

The source register lists the ticket warehouse, schedule table, queue configuration history, and incident calendar. The metric contract defines backlog age at Monday 00:00 UTC, median first-human-response time, within-target rate, reopened-ticket rate, and staffed hours. Each metric has an owner and a reconciliation query.

The main view contains five queue rows with four-week sparklines and current values. A queue is highlighted only when backlog age worsens for two consecutive weeks and staffed hours are below plan. A warning appears when more than 2% of eligible tickets lack a first-response timestamp. The director can open the excluded-count table before acting.

The worked acceptance artifact is a six-case fixture:

The dashboard passes only when the displayed totals, warnings, access behavior, and text alternatives match the fixture. A polished layout is not enough.

  • a normal week that reconciles to the warehouse total;
  • a daylight-saving boundary with explicit UTC treatment;
  • a queue whose service target changed midweek;
  • missing response timestamps above the warning threshold;
  • a user without access to customer-level drill-down;
  • a stale refresh that must show the last successful time and suppress the intervention highlight.

Give AI bounded jobs

AI can convert interview notes into candidate requirements, identify undefined terms, propose edge cases, compare the metric contract with the wireframe, and draft test fixtures. Give it the approved glossary and ask it to cite the requirement behind every proposed test. Reject invented fields, inferred ownership, and formulas that have not been traced to a system of record.

Keep a decision log containing the prompt or task, the accepted or rejected suggestion, the human reviewer, and the resulting specification change. Do not place confidential source data into an unapproved model. The final metric definitions and access rules belong to accountable domain, data, security, and accessibility reviewers.

Verify with a four-way trace

Run the same fixture through four layers: source query, transformation, API or semantic model, and rendered dashboard. Compare identifiers and totals at every hop. Then test the decision path with a representative user: can they identify the intervention candidate, inspect the evidence, notice uncertainty, and decline to act when data is stale?

A release checklist should record reconciliation results, accessibility checks, permission tests, refresh monitoring, alert routing, known limitations, and approval names. Schedule re-review when a source schema, metric definition, policy, or user decision changes.

Keep the product boundary clear

This specification method is educational. It does not prove that a dashboard is accurate, accessible, secure, or effective without implementation-specific testing. Two Prune can provide task-bounded assessment evidence about how a participant frames requirements, uses sources, checks calculations, and communicates limitations. It is not a dashboard platform, does not certify compliance, and is not an automated employment decision system.

Sources

  1. 1.Digital.gov data visualization guidance · U.S. General Services Administration
  2. 2.U.S. Web Design System data visualization guidance · designsystem.digital.gov

Explore this topic